Skip to content
Querion

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
  1. The loop
  2. Model calls per question
  3. The directive protocol
  4. Charts
  5. Modules
  6. Knowledge assembly
  7. Why the Claude Code CLI

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 -p call, so no CLI session carries over.
  • Directives are found with a regular expression over fenced blocks named run-sql, chart or source:NAME. At most limits.max_directives_per_step are run from one reply.
  • The loop runs at most limits.max_steps times. 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, refused or error, 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 + 1 calls: one per turn, plus the forced final answer.
  • Each call starts a new claude process 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-sql holds one SELECT or WITH statement. Trailing semicolons are removed before validation. The run fence is run-sql rather than sql so that a plain sql block in the answer stays display-only and is never run.
  • source:NAME holds one request line. NAME is lowercased and may contain only letters, digits, _ and -.
  • chart holds a JavaScript Object Notation (JSON) spec. type is bar, line or pie (default bar). x holds the labels, and each series has name, values and an optional color. 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) when row_cap was hit, and a text table of the first 30 rows with cells cut at 40 characters. Or SQL error: and the reason.
  • source:NAME: HTTP <status> and the first 6000 characters of the body. Or NAME 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: loads querion.yaml and 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, ask and serve.
  • 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.