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)    │

1. The client sends a message via useChat({ transport: DefaultChatTransport }).
2. The route handler checks per-IP rate limit. If allowed, it calls streamText with the 3 tools and the Groq model.
3. 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.
4. The model can make further tool calls in subsequent steps (stopWhen: stepCountIs(5)) or write the final answer.
5. 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 ↗