harsh.kedia / work
02:50:33 IST view .md
← all work
● ship · 2026 · Creator · Solo build

Supermarket Ops Agent

Run an Indian kirana store from a Telegram chat: stock, GST bills, khata, invoices.
Supermarket Ops Agent cover
tools
30 over MCP
guards
oversell + idempotency in SQL
tests
51, no API key needed
Python Claude Agent SDK Sonnet 5 MCP · 30 in-process tools filesystem skills SQLite · WAL reportlab · python-pptx Telegram Bot API

Run an entire Indian kirana store end to end from a Telegram chat: receive stock, cut GST-correct bills, run khata (credit), close the day, and pull invoice PDFs and analysis decks, all in plain Hindi, Hinglish, or English. The chat is the product; the model orchestrates real tools over a consistent set of books.

The chat is the product #

A kirana owner should not have to learn software to run their shop. So there is no menu and no intent router here. Every message goes straight through the model, which reasons over messy real input, asks a clarifying question only when something is genuinely ambiguous, and chains tool calls until the job is done. One message in Hindi, Hinglish, or English becomes one agent turn that may fire many tools.

a real exchange · text
1
2
3
4
5
owner: 50 packets maggi aaye, cost 12, MRP 14
agent: Added 50 × Maggi (cost ₹12, MRP ₹14). Stock now 50.

owner: bill banao: 2kg sugar, 4 maggi, 1 amul butter, UPI
agent: Bill #1042 · ₹236 (incl. GST ₹18). Paid via UPI. Send as PDF?

It is built on the Claude Agent SDK, with 30 in-process tools exposed over MCP, filesystem skills that pull in the right domain playbook on demand, and sessions that survive a restart mid-bill.

Skills route, tools stay thin, the store owns the rules #

The layering is the whole discipline of the project. A skill decides what to do; a tool is a thin adapter that parses arguments and calls exactly one method; and the repository owns every business rule and every invariant. A tool never does GST math or checks stock on its own.

Layers from Telegram chat down through skill, tool, repository, to SQLite, each a thin pass to the next.
Fig 1 · skills route, tools are thin adapters, the repository owns the rules, SQLite holds the books.

The hard parts live in SQL, not the prompt #

Anything a jailbroken model could break, I pushed down into the database where the prompt cannot reach it. The clearest example is the oversell guard: finalizing a bill runs a single conditional decrement, so stock can never go negative no matter what the model is talked into.

THE OVERSELL GUARD IS IN SQL, NOT THE PROMPT
stock left
10
succeeded
0
rejected
0
Fig 2 · 25 buyers race for 10 packets. The conditional UPDATE ... WHERE stock >= q lets exactly 10 through, whatever the order.

Everything a real shop actually needs #

Beyond billing, it does the unglamorous work that makes a tool worth opening every day.

  • ▸Branded GST invoice PDFs with HSN, per-slab tax, and amount-in-words.
  • ▸An eight-slide analysis deck with native, editable charts and computed insights.
  • ▸Khata (credit) with running balances, statements, and confirm-or-refuse guards.
  • ▸Batch tracking with FEFO, earliest-expiry-first consumption, and expiry alerts.
  • ▸Memory across sessions so default payment, brand, and GSTIN persist through a fresh chat.
  • ▸Scheduled reminders: a weekly deck and daily outstanding-credit nudges, no LLM cost.

Proven, not promised #

51 tests prove every invariant deterministically without touching an API: GST reconciliation, the oversell guard under 25 concurrent buyers, idempotent finalizes, khata math, and the artifact generators. The chat is the interface, but the books underneath are the part I would stake money on.
← PREVIOUS
D2C AI Employee
NEXT →
Pattern engine