Supermarket Ops Agent

A shopkeeper should not have to learn software to run a shop. This is an agent you talk to the way you would talk to an assistant behind the counter — receive stock, build a bill across several messages, put it on someone’s khata, ask what sold last week — and it does the work against a real database with real guardrails.

The problem

The obvious way to build this is an intent router: match the message against a list of patterns, dispatch to a handler. That approach breaks the moment a sentence carries two intents, or an item is named loosely, or the owner changes their mind halfway through a bill. It was also an explicit fail condition for this build.

The approach

The Claude Agent SDK supplies the control loop — observe, reason, act, feed the result back — so the model chooses tools from their descriptions rather than a regex choosing them from the text. Store functions are exposed as in-process MCP tools, so there is no separate tool server to run, and a PreToolUse hook gives one choke point to sandbox the agent to store-only tools and tag the destructive ones for confirmation.

Eighteen tools across six categories: inventory, billing, khata, reporting, preferences, documents. Two conventions do most of the work:

• Every tool returns {"ok": bool, ...}. Expected failures — no match, oversell, overpayment, below-cost, ambiguity — come back as data rather than exceptions, so the agent can relay or reason about them instead of crashing.
• Business logic lives in the tools, never in the prompt. The oversell guard, GST maths, CGST/SGST split, idempotency and below-cost refusal are enforced at the database layer, so a misbehaving prompt cannot bypass them.

Fuzzy matching is asymmetric on purpose. Reads resolve loosely (exact → substring → difflib) and return the candidate list when a name is ambiguous, so the agent asks instead of guessing. khata_charge is deliberately conservative — exact and substring only — because it can create an account, and loose similarity there risks crediting the wrong person or opening a duplicate.

The war story

Two concurrent stock-ins, +5 and +7 onto 10, landed at 15 instead of 22 in about a quarter of runs. Genuine, silent corruption.

add_stock was doing a read-modify-write in Python — product.qty_on_hand += qty. Python’s sqlite3 driver runs the preceding SELECT outside the write transaction, so both threads read 10 and one increment was simply lost. The fix was to express the change as an atomic SQL UPDATE as the first statement of the transaction, mirroring what finalize_bill already did:

SET qty_on_hand = qty_on_hand - :q WHERE qty_on_hand >= :q

That single pattern turns out to be the whole oversell guard as well: the losing writer’s UPDATE matches zero rows, raises, and rolls the entire finalize back — so stock can never go negative or partially commit. khata_charge and khata_pay had the identical Python-side flaw and were hardened the same way, with khata_pay taking a WHERE balance >= :amount guard against overpayment. A unique(name) constraint backstops the first-time-creation race, and the losing insert retries as a charge on the existing account.

The more interesting half of the conclusion is where the fix should not be applied. set_preference needs none of it: it is a plain upsert that sets a value rather than doing arithmetic on the existing one, so two concurrent writes resolving last-writer-wins is the correct semantics. There is no sum to lose. Applying the pattern everywhere would have been cargo cult.

The rule that came out of it: never read-then-write a contended numeric field in Python — express the change as an atomic SQL UPDATE. SQLite in WAL mode with a busy timeout is genuinely sufficient for a single-instance shop, but only under that discipline. Multiple app instances would mean moving to Postgres and row-level locking.

The rest of the hard parts

• Grounding. Prices, GST slabs and stock always come from the database via tools; the system prompt forbids inventing a product or a price.
• GST correctness. Each line’s slab is snapshotted at add-time, tax is halved into CGST and SGST so the two always sum to the line tax, and everything is integer paise, so subtotal + CGST + SGST is exactly the grand total.
• Multi-turn bills. A draft builds across messages and only finalize_bill touches stock, so edits are free until the moment of commit.
• Idempotency. Telegram redelivers updates, so every update_id is recorded and repeats ignored; finalize_bill and khata_pay carry idempotency keys, so a replayed money-move is a no-op.
• Documents. A GST-correct tax invoice with per-line HSN codes and a six-slide analysis deck with matplotlib charts. Noto Sans is vendored and registered explicitly so the ₹ glyph renders identically on the deployed host rather than depending on whatever fonts happen to be installed there.

The outcome

Deployed on Railway as a polling Telegram bot. The concurrency guarantees are held by threaded tests — two bills finalising at once, two stock-ins, two khata charges on a new customer, two payments that would together overpay — run under stress rather than as sequential calls.

Outstanding: the demo recording.