Clarity

Text-to-SQL demos in an afternoon

Point a decent model at a schema and you'll have something working the same day.

The problems start after that. It answers from a table that died a year ago, quotes a number without running a query, or says an export is ready when nothing was written. These are worse than errors, because nobody can tell they happened.

When I read the actual user transcripts, the issue wasn't missing features. People didn't trust the answers.

So the design rule became: Clarity doesn't assert a number without showing the query behind it.

⌁clarity · chat↗

No vector store

The default move is embeddings: chunk the schema, load it into a vector database, retrieve per question. I didn't do that. A schema isn't an unbounded corpus. It's a few hundred tables you can describe directly.

A nightly job compiles a knowledge document per tenant. Business summary per table, a glossary, SQL recipes known to work. It goes into every conversation as cached context, byte-identical so the provider can cache it.

The model turns up already knowing the estate. Live discovery stays as a fallback, so a table added this morning works this morning. This is what it gets handed:

## Schema Directory
Every table you can query is listed below with a one-line description.
This is the complete set.
 
### operational
- `work_order` — jobs raised against a site, with status and due date
- `site` — every physical location, with region and commissioning date
- `asset` — equipment installed at a site, keyed to its site
- `site_daily_rollup` (no new data since 2025-03) — legacy daily aggregates
- `alarm_event_archive` (no rows) — superseded, retained for audit
 
### telemetry
- `reading` — time-series sensor readings, one row per probe per interval
- `probe` — sensor metadata: type, unit, the asset it monitors
 
## Glossary
- **overdue**: a work order past its due date and not yet closed
- **estate**: every site belonging to one tenant
 
## Verified Query Recipes
- **open work by site** — how much outstanding work does each site have?
```sql
SELECT s.name, count(*) AS open_jobs
FROM work_order w JOIN site s ON s.id = w.site_id
WHERE w.closed_at IS NULL GROUP BY s.name ORDER BY 2 DESC
```

Compiled knowledge is what lets it answer about the whole estate at once rather than one table at a time:

⌁clarity · estate briefing↗

The bug that changed the design

Someone asked which sites were running hottest. Clarity said there was no data. There was loads of data. It had found a promisingly named table, dead for months, while the live telemetry sat somewhere less obvious.

A wrong "no data" is the worst failure mode, because it never gets escalated. People just stop using the tool, and no metric tells you why.

Now the compile probes each table for its newest timestamp and marks the directory: (no rows), (no new data since …). The model routes around dead tables because it can see they're dead.

The compile only rewrites a table's summary when the table itself has changed, which it works out by hashing the structure. Freshness timestamps are deliberately left out of that hash. A clock ticking forward every night would otherwise rebuild the whole estate to tell us nothing had changed.

Try to get something past it

Generated SQL is untrusted input that happens to be executable. The system prompt says read-only, but a prompt isn't enforcement, so the restriction lives in the database.

Queries run as a dedicated read-only role, provisioned on every tenant database at startup. It fails closed: no pool, no query. There is no code path that falls back to the admin connection.

Validation lexes SQL to canonical tokens before checking anything. String matching loses to quoting and comments, so FROM/**/pg_tables would walk straight past it. Failures return as data, not exceptions, so the model reads its own error and corrects itself.

I won't use a model to grade a model

LLM-as-judge is the obvious approach; I didn't use it. A grader that hallucinates can't certify a system whose defining failure is hallucination. Two models can agree in the same wrong direction.

So the evals are canary questions instead. Canned questions replay after every deploy, asserted against the audit record rather than the prose. Answer contains a number, SQL must have run. Fabricated-names list must be empty. Export claimed, report row must have completed.

Where each guarantee is enforced

A system prompt is a request. Everything below is a property of the system, and each entry names the place it holds.

⌁clarity · exports↗

An honest answer

The questions that used to become a ticket now get asked directly. Some of those conversations end as a dashboard the tenant keeps rather than a one-off answer.

⌁clarity · a dashboard the AI built↗

One claim I can't back yet: the trust layer is built and running, but I haven't re-run the transcript analysis against the current build, so I can't show that fabrication is at zero. I'm not claiming it until I can.