AI analytics assistants can state numbers confidently that no query ever produced. GroundedBI shows the guardrails that prevent that: fixed validated tools, read-only SQL, and an answer withheld unless every number matches a query result.
You ask a question about a synthetic electronics retailer's sales, such as "Why did revenue drop in March compared with February?". A planner picks from six predefined, read-only tools; their arguments are validated and their SQL is fixed and parameterized. The answer is written only from the values those queries return, and then checked: every number in it must exactly match a query result, or the answer is withheld. An unclear question gets a clarifying question back, and a question the data can't answer (profit, forecasts, "delete the data") is declined before any query runs.
How it works
flowchart TD
Q([Question]) --> V{"Validate<br/>1-500 characters, plain text"}
V -- invalid --> E422[["422 validation error"]]
V -- valid --> S{"Within scope?"}
S -- "profit, forecasts, commands, creative requests" --> OOS[["Out of scope: declined"]]
S -- yes --> O["Data overview<br/>months, products, regions, categories"]
O --> P{"Plan"}
P -- "unknown name, vague period, no clear intent" --> C[["Clarifying question"]]
P -- "unrelated to sales data" --> OOS
P -- "tool calls" --> T["Validated tool call<br/>strict Pydantic arguments"]
T --> SQL[("Read-only, parameterized SQL<br/>SQLite, mode=ro")]
SQL --> W["Answer template<br/>quotes the query's display strings"]
W --> G{"Grounding check<br/>every number matches a result?"}
G -- yes --> A[["Answered, with evidence and trace"]]
G -- no --> X[["Withheld: grounding_failed"]]
Every /ask response carries a trace of each tool call and a request ID that matches the server's structured JSON logs. Answered questions also include the evidence tables the numbers came from.
Five layers of protection. Each works on its own, so one layer's mistake doesn't become a wrong answer or a changed database.
- Fixed tools with validated arguments. The planner can only name one of six tools. Unknown fields, wrong types and invalid months are rejected before anything runs.
- Parameterized, read-only SQL. Queries are written in advance with placeholders; the only text ever inserted into SQL is a column expression picked from a fixed list. The connection is opened read-only.
- Limits on every question. A maximum number of planning steps and tool calls, a deadline per question and a time budget per query. A run that hits a limit stops; it never returns a made-up answer.
- A grounding check on every answer. Every number in the answer text must exactly match a value the queries returned. If one doesn't, no answer is shown.
- Ask instead of guess. Unknown names ("Europe"), vague periods ("last month") and unclear requests get a clarifying question, not an assumption.
Evaluation
The planner is measured on question sets with labelled expectations: which tools should run, with which arguments, which status the response should have, and whether the answer passes the grounding check.
- Dev set: used to find and fix problems. CI requires 100% on it.
- Held-out sets: written and labelled before any run, then only measured, never used to tune the planner. A test fails if any four consecutive words of a held-out question appear anywhere in the app's source code. Once a held-out set has been inspected, it is marked seen in
evals/datasets.json and its score is no longer an unbiased estimate.
- Expected numbers in the question files are recomputed from the analytics service on a fresh database by
evals/check_expectations.py, so the labels themselves are checked.
A confident wrong answer is an answered, grounded response to a question that still failed: the worst outcome, because it looks trustworthy.
After two fix rounds all 71 questions pass with no confident wrong answers, but every set has now been seen. The last unbiased number is 7/10 on the fresh held-out v2 set, with one confident wrong answer. Each row links to the report committed at that point.
Security
Before public deployment the app was audited and hardened. What is in place:
This is the beginning of the README. Read the rest at the original. Read the full README ↗
