English · Español
Invoice Chat
Conversational agent that answers in natural language about Peruvian receipts and invoices. Showcases real tool use: the LLM decides which SQL tool to call (list_receipts, query_aggregates, get_receipt_detail), executes it against Neon Postgres, and responds with verifiable data. Reuses the same database as Invoice Extractor — extract first, then analyze.
Author: sebpost2
Live demo · No sign-up · 27 demo receipts preloaded
Highlights
- Multi-step reasoning agent: the model can chain up to 5 steps. For "details of the most expensive receipt" it calls
list_receipts({orderBy: "total_desc"}) → grabs the first id → get_receipt_detail({id}) → writes the answer.
- Zod-typed tools: each tool declares its schema (
z.enum, z.string), the AI SDK validates inputs before execution, and TypeScript infers the types on the server.
- Token-by-token streaming of the final answer via Vercel AI SDK v6 (
streamText + useChat).
- Agent transparency: every tool call is a collapsible
<details> component showing the exact input and output JSON. Visitors see what the model queried, not just what it said.
- Data-driven citations: if the answer comes from a specific
get_receipt_detail, the receipt id is shown. If it comes from a list/aggregate, the scope is shown ("Based on N receipts"). No fabricated references.
- Real Markdown in answers (bullets, tables, emphasis) rendered with
react-markdown + GFM.
- Per-IP rate limit (in-memory token bucket, 10 messages/hour) — protects the free Groq quota from casual bots and shows a friendly message on limit hit.
- Synthetic demo data: 24 receipts seeded via
npm run seed (Tottus, Pardos, Sodimac, Inkafarma, etc.) plus the 3 real ones from the extractor — 27 receipts total for substantial questions.
- Tool-selection evals with Promptfoo: 22 cases under
evals/ lock down the agent's behavior — single-step routing (ES + EN), multi-step list → detail chains, and no-tool refusal for greetings/off-topic. Run with npm run eval. A pre-eval guard verifies the duplicated prompt copy hasn't drifted from src/lib/chat-prompts.ts.
Stack
| Layer | Technology |
|---|
| Framework | Next.js 16 (App Router, Turbopack) |
| Language | TypeScript |
| Styling | Tailwind CSS v4 (dark-first) |
| LLM SDK | Vercel AI SDK v6 (ai, @ai-sdk/groq, @ai-sdk/react) |
| Model | OpenAI gpt-oss-120b via Groq |
| Database | PostgreSQL (Neon, serverless) — shared with the extractor |
| ORM | Prisma 7 with @prisma/adapter-pg |
| Validation | Zod 4 |
| Markdown | react-markdown + remark-gfm |
| Rate limit | In-memory token bucket |
| LLM evals | Promptfoo (OSS) — 22 tool-selection cases under evals/ |
| Deploy | Vercel |
How it works
┌──────────┐ sendMessage ┌────────────────┐ streamText ┌──────┐
│ Client │ ─────────────> │ /api/chat │ ───────────────> │ Groq │
│ useChat │ │ (route handler)│ + tools (Zod) │ LLM │
└────┬─────┘ └────────┬───────┘ └───┬──┘
│ │ │
│ UIMessageStream │ │
│ <─────────────────────────────┤ ┌────────┐ tool call │
│ • text-delta │ │ Neon │ <────────────────┤
│ • tool-input-streaming │ │ DB │ │
│ • tool-output-available │ └────────┘ tool result ────┤
│ • text-end │ │
│ │ ... until stepCountIs(5) │
- The client sends a message via
useChat({ transport: DefaultChatTransport }).
- The route handler checks per-IP rate limit. If allowed, it calls
streamText with the 3 tools and the Groq model.
- The model picks a tool and emits tool-call parts. The AI SDK runs the matching
execute (Prisma query) and feeds the result back to the model.
- The model can make further tool calls in subsequent steps (
stopWhen: stepCountIs(5)) or write the final answer.
- The entire conversation reaches the client as a stream of typed parts rendered in order.
The three tools
| Tool | Input | Output | When the model picks it |
|---|
list_receipts | orderBy: "date_desc" | "date_asc" | "total_desc" | "total_asc" | Array of receipts with summary fields | "Show me my receipts", "which was the most expensive?" |
query_aggregates | metric: "total_spent" | "total_igv" | "total_subtotal" | "count" | "all" | Per-currency aggregates | "How much did I spend?", "How many receipts?", "How much VAT?" |
get_receipt_detail | id: string | Full receipt with items | "Give me the details of [id]", final step after identifying a receipt via a list |
This is the beginning of the README. Read the rest at the original. Read the full README ↗
