Querion / Reference
Architecture
How the Querion run loop works, the directive protocol, what each module does, and how the model is kept to a read-only text generator.
On this page
Querion is a small loop around the Claude Code command-line interface (CLI). The model never executes anything. It emits fenced directives, and the runner validates and executes them. How it works explains why it is built this way; this page describes what the code does.
The loop
question
-> engine.run applies the write-request firewall
-> analyst.step asks the model for read-only directives
-> the runner executes them:
run-sql -> querion.db (SELECT/WITH, read-only session, timeout)
source:NAME -> querion.sources (GET only, per-source allowlist)
chart -> querion.charts (or a spec for the client to draw)
-> results are appended to the transcript
-> repeat until the model replies with no execute fence
Details from the code:
- Each turn is stateless. The full transcript is passed to a fresh
claude -pcall, so no CLI session carries over. - Directives are found with a regular expression over fenced blocks named
run-sql,chartorsource:NAME. At mostlimits.max_directives_per_stepare run from one reply. - The loop runs at most
limits.max_stepstimes. If the model is still requesting directives, Querion asks for a final answer with no directive. - A reply with no execute fence is the final answer. Any stray execute fences are stripped from it.
- The result is a status of
done,refusedorerror, plus the answer, steps, the Structured Query Language (SQL) that ran and chart specs. - On the CLI path, charts are rendered to image files, with a text chart as fallback. On the web path, they are returned as specs and drawn in the browser by Chart.js.
Model calls per question
- A question makes at most
max_steps + 1calls: one per turn, plus the forced final answer. - Each call starts a new
claudeprocess with a fixed 200-second timeout. - The system prompt is rebuilt for every call. It holds today’s weekday, date and week number from the host’s local clock, the directive rules, the read-only rules and the knowledge block.
- A question the deterministic firewall refuses makes no calls.
The directive protocol
The model acts only by writing one of three fenced blocks. The fence name is case-insensitive.
```run-sql
SELECT ...
```
```source:NAME
GET /path?query
```
```chart
{"type": "bar", "title": "...", "x": [...], "series": [{"name": "...", "values": [...]}]}
```
run-sqlholds oneSELECTorWITHstatement. Trailing semicolons are removed before validation. The run fence isrun-sqlrather thansqlso that a plainsqlblock in the answer stays display-only and is never run.source:NAMEholds one request line.NAMEis lowercased and may contain only letters, digits,_and-.chartholds a JavaScript Object Notation (JSON) spec.typeisbar,lineorpie(defaultbar).xholds the labels, and each series hasname,valuesand an optionalcolor. A spec that is not valid JSON goes back to the model as an error, with a hint to answer in text.- A block ends at the first closing fence. Once the per-step limit is reached, later directives in the same reply are dropped.
Each executed directive feeds text back to the model:
run-sql: the row count,(capped)whenrow_capwas hit, and a text table of the first 30 rows with cells cut at 40 characters. OrSQL error:and the reason.source:NAME:HTTP <status>and the first 6000 characters of the body. OrNAME GET failed:and the reason.chart: where the image was written, a text chart, or a note that the client will draw the spec.
Charts
On the CLI path, querion/charts.py renders a spec with matplotlib to a file named querion_chart_*.png in the system temporary directory:
- Bar and line charts with more than eight series keep the seven largest by total and fold the rest into a grey “Other (N more)” series.
- Pie charts use only positive values. More than seven slices become the six largest plus “Other (N more)”.
- Without matplotlib, or when rendering fails, the model receives a text bar chart of the first series.
On the web path, the browser draws the spec with Chart.js. A pie spec is drawn as a doughnut. The web renderer does not fold series.
Modules
config.py: loadsquerion.yamland interpolates${VAR}.llm.py: the Claude Code CLI wrapper (claude -p, tools disallowed, strict Model Context Protocol (MCP) config).safety.py: SQL validation, the Hypertext Transfer Protocol (HTTP) allowlist and the write-request firewall.db.py: read-only Postgres access with a statement timeout.sources.py: generic HTTP connectors (GET and allowlist).knowledge.py: the schema, application programming interface (API) docs and optional Trove layer, assembled into the system prompt.charts.py: chart rendering with a text fallback.limits.py: the per-user daily counter. Only the web server uses it.analyst.py: the system prompt, the directive protocol and per-directive execution.engine.py: the bounded run loop shared by the CLI and the server.server.py: the FastAPI app and JSON API.cli.py:check,introspect,askandserve.web/index.html: the Alpine.js single-page user interface.
Knowledge assembly
Before answering, Querion builds one text block: the organization line, the database schema (curated file or live introspection), one section per source with its base URL and docs file, and the Trove layer if enabled. This block goes into the system prompt together with today’s date and the read-only rules. The server builds it once at startup. querion ask builds it on each run.
Why the Claude Code CLI
There is no API key to manage, and calls run under your Claude Code authentication. Querion disallows the CLI’s tools and loads no MCP servers, so the model acts as a text generator over the context Querion assembles.
The read-only session is opened with psycopg2’s set_session(readonly=True, autocommit=True). The write-request firewall is a deterministic pattern for pasted SQL and GraphQL mutations, plus a model instruction for everything else. Both are described in full in the safety model.