Portfolio project · TypeScript · Agentic LLM systems

Daily sales KPIs by code, narrative by AI.

An agentic TypeScript pipeline. Math lives in a pure module; Claude or Groq writes a strict-JSON readout; Telegram, Slack and Email get the report at 9 AM. Built to demonstrate production patterns for LLM apps — tool-use, prompt caching, zod validation, graceful fallback, idempotent fan-out.

View on GitHub Read the case study

TypeScript 5.6 Node 20 Anthropic SDK Groq zod GitHub Actions

pulse report

bot · 09:00

📊 Daily Sales Pulse (Tue, Jun 9, 2026) Revenue at $1,606.76 drops 20.47% from yesterday but stays 24.42% above last week 💰 Revenue: $1,606.76 (-20.47% vs prev day, +24.42% vs last week) 🛍️ Orders: 17 🧾 Avg order: $94.52 🔝 Top product: Nimbus Sneakers ($493.19) Today's revenue is $1,606.76, a 20.47% decline versus the previous day, while still 24.42% higher than the same day last week. Highlights: • Orders fell to 17, pulling the average order value to $94.52 • Nimbus Sneakers generated $493.19, the largest single-product contribution • Weekly momentum is positive, with revenue up 24.42% compared to last week 👉 Launch a limited-time discount on Nimbus Sneakers tomorrow to capitalize on its strong performance.

Problem

Existing AI-report templates hallucinate numbers

Off-the-shelf solutions in Zapier / Make / n8n hand raw data to the LLM and ask it to summarize. The model casually re-derives totals and percentages — and gets them wrong often enough to destroy trust. Once the owner spots one wrong number, the whole report becomes noise.

Solution

Separate math and narrative

A small TypeScript pipeline computes every figure in a pure metrics.ts module. The LLM receives finished metrics through a strict JSON schema and is explicitly forbidden from re-deriving anything. The numbers are auditable, the prose stays human-readable, and the system fails gracefully if the LLM call breaks.

Pipeline

Seven typed steps. One direction. Deterministic where it matters; AI where it doesn't.

fetchOrders

Sheets / CSV via adapter

computeMetrics

Pure, deterministic math

writeSummary

Claude tool-use / Groq json

zod validate

Strict schema or fallback

formatReport

en-US, emojis, branding

fan-out

Promise.all · TG/Slack/Email

saveSnapshot

Idempotent audit JSON

Orchestrator

export async function runDailyReport(flags) {
  const cfg     = loadConfig();
  const orders  = await fetchOrders(cfg);
  const metrics = computeMetrics(orders, flags.date);

  if (!flags.force && await hasReportFor(cfg.SNAPSHOT_PATH, metrics.date)) return;

  let summary;
  try {
    assertLLMReady(cfg);
    summary = await writeSummary(cfg, metrics);   // Claude tool-use or Groq json
  } catch (err) {
    summary = fallbackSummary(metrics);            // never silently break
  }

  const text = formatReport(metrics, summary, cfg.BRAND_NAME);
  if (flags.dry) return console.log(text);

  const [tg, slack, email] = await Promise.all([   // fan-out
    enabled.telegram ? sendTelegram(cfg, text) : null,
    enabled.slack    ? sendSlack(cfg, text)    : null,
    enabled.email    ? sendEmail(cfg, subject, text) : null,
  ]);
  if (![tg, slack, email].some(r => r?.ok)) throw new Error("all channels failed");

  await saveSnapshot(cfg.SNAPSHOT_PATH, { date: metrics.date, metrics, summary, ... });
}

Stack & Patterns

🔢

Deterministic numbers

All KPI math in a single pure metrics.ts. LLM receives finished figures and is forbidden from re-deriving anything in the system prompt.

🛠️

Strict structured output

Claude path uses tools + tool_choice + input_schema; Groq path uses response_format: json_object. One zod schema validates both.

⚡

Prompt caching

System prompt marked cache_control: ephemeral on Anthropic — typical re-run reuses the prefix, cutting input tokens significantly.

🛡️

Graceful fallback

LLM down or returns invalid JSON? fallbackSummary emits a templated readout from the same metrics so the pipeline never silently breaks.

📡

Multi-channel fan-out

Telegram + Slack + Email in parallel via Promise.all. Pipeline succeeds if at least one channel delivers; per-channel error logged.

🔁

Idempotent runs

Snapshot store keyed by report date. Re-run for the same day no-ops; --force overrides. Audit trail in data/reports.json.

🔌

Adapter pattern

Single OrdersSource interface. Adding Stripe / Shopify / Postgres = ~30 LOC, no downstream changes.

🧪

Typed env

zod parses process.env once at boot. Invalid configuration fails fast with a clear message — no silent misbehavior.

⏰

GitHub Actions cron

Free hosted scheduling via .github/workflows/daily.yml. Swap to node-cron on a VPS for sub-minute timing — same entry point.

What this project demonstrates

✓ Agentic pipeline design with a single strict LLM call instead of an open-ended tool-use loop — predictable, debuggable, cheap.

✓ Production patterns for LLM apps: structured output, schema validation, prompt caching, graceful fallback.

✓ Multi-provider abstraction over Anthropic and Groq with a one-env-var switch.

✓ Clean adapter interface for plug-and-play data sources.

✓ Multi-channel delivery with partial-failure tolerance via Promise.all.

✓ Idempotency + audit-trail design for one-shot scheduled jobs.

✓ End-to-end type safety: env → AI response → file IO. tsc --noEmit clean.

✓ Zero-runtime-bundler setup — direct tsx execution. Ships in 794 lines of code across 9 modules.