Rai: what I am building, and which decisions were load-bearing

I have spent the last few months writing the specification for a product called Rai, and last week the v1 scope was locked. This is the article I would have wanted to read before starting: what it is, what is in v1, and - more usefully - which decisions were load-bearing and which were arbitrary.

Rai is Swahili for advice or counsel. It is an in-product AI agent that lets a shop owner ask any question about their business in plain language and get back an accurate report, or grounded advice, drawn entirely from their own data.

The positioning, in one line

Ask anything. Get any report. Get advice you can act on - grounded in your own numbers, never guessed.

Every word in that sentence is doing work, and the last four are doing the most. There is no shortage of chatbots bolted onto dashboards. What there is a shortage of is a thing that answers with correct numbers and can show you where they came from.

Who it is for, and why that narrows well

v1 targets owners of electronics, hardware and spare-parts shops - commodity and serialised-goods traders - in Kenya first, then across Africa.

That is a deliberately narrow beachhead and the narrowness is the point. These businesses live and die on inventory accuracy, thin margins and multi-supplier procurement. Serial numbers matter. Warranty windows matter. A single defective batch can quietly consume a month's profit. It is the hardest segment to run on instinct, which makes it the segment where grounded answers are worth the most money.

It also means the metric catalog can be finite. "An AI analyst for any business" is a catalog you never finish. "An AI analyst for hardware shops" is about two dozen metrics, and you can actually get them right.

What is in v1

All of the following ships, with write-safety in from the start rather than promised for v2.

• Natural-language reports. Table plus chart, exportable to PDF or Excel, saveable as a reusable report the owner can rerun. Every one backed by the metric catalog.
• Grounded advice. Reorder decisions, pricing moves, dead-stock cleanup, supplier consolidation - each citing the figures it rests on. "Clear these 12 SKUs - KES 340,000 tied up, zero sales in 90 days."
• The owner brief. A scheduled daily or weekly digest: what moved, what is at risk, three concrete actions.
• Event-driven alerts. Threshold-based, firing the moment something breaks - a fast-mover about to stock out, margin sliding on a category, a supplier's price jumping, a till mismatch.
• WhatsApp channel. Questions, briefs and alerts over WhatsApp, with SMS fallback.
• Swahili and Sheng. Ask and receive in the language the owner actually uses.
• Anomaly and leakage detection. Unusual voids, odd discounts, after-hours sales, recurring cash shortfalls.
• Warranty, returns and defective-batch intelligence. Units still under warranty; returns clustering around one supplier batch.
• Demand forecasting. Predicted stock-out dates and suggested reorder quantities from the shop's own history.
• Write paths, gated. Draft-and-approve purchase orders, and photo-to-draft invoice capture.

The anchor feature is the boring one

If you asked me which item on that list justifies the subscription, I would not pick the natural-language reports. I would pick the owner brief.

Everything else requires the owner to have a question. The brief requires nothing. It arrives, it is short, and after a few weeks it stops being a notification and becomes a routine. Routines are what change how a business is run; individually impressive answers are not.

Which is why the brief is bundled into the base add-on rather than being an upsell. It is the habit that makes the rest of the product get used at all.

The decisions that were actually load-bearing

The metric catalog, not text-to-SQL. ERPNext's schema is non-obvious - real revenue lives in the general ledger, stock valuation in the stock ledger, and gross margin has to be reconstructed from COGS. A naive agent will hand an owner a confidently wrong number, which is strictly worse than no AI at all. So the agent maps questions to defined metrics and is only permitted a guarded read-only fallback when it can state that no metric applies.

The two-piece split. A hosted brain holding the reasoning, and a thin Frappe connector holding none of it. Raw rows stay on the shop's server; only aggregates travel. That protects the client's data and our IP with the same seam, which is why I expect it to survive commercial pressure.

The adapter boundary. Frappe is the only source in v1, but the agent never calls Frappe. One thin data-access module sits between them and is the only code that knows what a doctype is. Going standalone later becomes new adapters, not a rewrite.

Raw SDK, no framework. FastAPI plus the raw Anthropic SDK, no LangChain or LangGraph. This has to embed cleanly and stay dependable for years, and every abstraction between us and the model API is one we would eventually debug through. Two-tier model routing - cheap and fast for routine reports, stronger for advice - is where the token margin lives, and that is much easier to reason about unmediated.

The non-goals, written down on purpose

Scope locks are only useful if the exclusions are as explicit as the inclusions.

• No LangChain or LangGraph in v1.
• No silent writes - every write is approval-gated and audited.
• No raw business rows leaving the shop's server - aggregates only.
• No self-hosted observability at launch - cloud free tiers first.
• The agent core never calls Frappe directly - always through the adapter seam.
• No "POS" in user-facing copy.

That last one looks like a marketing footnote sitting among architecture constraints, and it is there deliberately. Constraints that live only in someone's head get violated by the third contributor. Constraints in the spec get reviewed.

What I expect to get wrong

Two things, and I would rather name them now than discover them in a retro.

The first is catalog coverage. Two dozen metrics will cover most questions and the tail will be longer and weirder than my estimate. The mitigation is that the fallback exists and shows its working, so an uncovered question degrades into a less-confident answer rather than a refusal.

The second is alert tuning. Thresholds that fire on real problems and not on noise are not something you can specify in advance; you tune them against real shops for a month, and if you get it wrong people mute the thread in a fortnight and never come back. I have budgeted for that tuning and I still think the budget is optimistic.

The next few articles go into the pieces one at a time - the semantic layer, the split architecture, the write path, and the metering. This one exists so there is something to hang them on.