6krrt/docs/data-model.md

> SQLite schema reference. Back to [README](../README.md).

## Decision Table Schema (SQLite)

Three data tables plus one observability table, `PRAGMA foreign_keys = ON`:

### `models` — one row per served model variant

| Column | Type | Notes |
|---|---|---|
| `model_id` | TEXT | Full catalog id (e.g. `glm-5.2-short-fast-flex` or `qwen2.5-coder-router:14b`) |
| `provider` | TEXT | `neuralwatt` \| `ollama-local` |
| `base_model_id` | TEXT | Model family (e.g. `glm-5.2`). Proficiency/leaderboard keys here. |
| `eligible_categories` | TEXT | Comma-joined category allowlist; `NULL` = unrestricted (cloud rows) |
| `display_name` | TEXT | Human-readable name |
| `cost_per_1m_prompt` | REAL | Listed USD per 1M input tokens |
| `cost_per_1m_completion` | REAL | Listed USD per 1M output tokens |
| `cost_per_1m_prompt_cached` | REAL | Cached prefix price (null if no cache discount) |
| `context_window` | INTEGER | Advertised max tokens |
| `effective_context_window` | INTEGER | `advertised × safety_factor − reserve` |
| `max_output_tokens` | INTEGER | |
| `tier` | INTEGER | 1–3, set by `tier.py` pass |
| `supports_tools` | INTEGER | Boolean 0/1 |
| `supports_json_mode` | INTEGER | |
| `supports_vision` | INTEGER | |
| `supports_reasoning` | INTEGER | "API accepts reasoning param" — NOT a quality signal |
| `reasoning_default_enabled` | INTEGER | The actual tier-bearing signal |
| `latency_class` | TEXT | `standard` \| `flex` (`-flex`: discounted async, held during peak) |
| `reasoning_mode` | TEXT | `default` \| `reduced` (`-fast`: reasoning capped) |
| `context_variant` | TEXT | `full` \| `short` (`-short`: 200K pool bounded budget) |
| `access_level` | TEXT | `public` \| `preview` \| `canary` |
| `pricing_tbd` | INTEGER | |
| `deprecated` | INTEGER | |
| `availability` | TEXT | `active` \| `deprecated` \| `stale` |
| `last_updated` | TEXT | ISO8601 |

**Serving class:** Neuralwatt ships ~6 base models as 19 catalog rows. The id
suffixes are three **orthogonal** dimensions (`glm-5.2-short-fast-flex`), parsed
by `poller.parse_serving_class` into columns. Rows carry identical catalog
pricing, so routing would pick between them arbitrarily without these — the
`latency_tolerance` hard filter resolves it.

**Local rows:** `provider='ollama-local'` rows come from `config.yaml`'s
`local_dispatch_models:` section and are refreshed by `poller.upsert_local_dispatch_models`
each poll. They start with the three cost columns NULL; once
`seed_local_dispatch_energy.py` has run, those columns hold measured
tariff-priced rates and re-polls never overwrite them.

**Access gating:** 6 of 19 rows are prose-gated
("Private preview (grant-gated)", "(Canary)"). `poller.parse_access_level`
parses them into `access_level` and `routing.allowed_access_levels` (default
`[public]`) excludes them, so dispatch won't earn a 403.

### `proficiency` — one row per (model, provider, category)

| Column | Type | Notes |
|---|---|---|
| `model_id` | TEXT | |
| `provider` | TEXT | |
| `category` | TEXT | See category list below |
| `leaderboard_score` | REAL | 0–1, from external benchmarks |
| `self_eval_score` | REAL | 0–1, from self-eval harness |
| `outcome_score` | REAL | Accumulated client-reported success rate on real traffic (0–1) |
| `outcome_samples` | INTEGER | Number of client-reported `succeeded`/`failed` verifications folded in |
| `self_eval_samples` | INTEGER | Evidence count for benchmark blending threshold |
| `blended_score` | REAL | Expected pass rate on real traffic after empirical-Bayes shrinkage |
| `source` | TEXT | `outcome_blended` \| `outcome_prior` \| `blended` \| `self_eval` \| `self_eval_thin` \| `leaderboard` |
| `inherited_from` | TEXT | Model this row was copied from, NULL if measured directly |
| `last_updated` | TEXT | ISO8601 |

**Category set** (9 categories, defined in `config/config.yaml`):

| Category | Example | Scoring type |
|---|---|---|
| `coding_general` | Merge intervals, parse semver, word wrap | Code (execution) |
| `coding_refactor` | Remove repetition, refactor dispatch chain | Code (execution) |
| `debugging` | Fix closure leak, fix binary search, fix regex | Code (execution) |
| `reasoning_math` | Percent trap, rate trap, counting | Exact match |
| `tool_use_agentic` | Right tool / right args / no tool when empty | Structural |
| `docs_writing` | Docstring quality, must-mention gotchas | Judge |
| `summarization` | Root-cause isolation, buried-lede identification | Judge |
| `translation` | Technical register, hedging/informal tone | Judge |
| `general_chat` | Simple explanations, measured pushback | Judge |

**Scoring kinds** (4 types, objective wherever the category admits it):
- **`code`** — runs model-generated Python in a subprocess, scores fraction of checks passing
- **`exact`** — normalizes & compares a single answer
- **`tool`** — structural: which tool was called, which args matched
- **`judge`** — a strong model scores against a rubric (prose categories only)

**Blending the benchmark signal:** Once `self_eval_samples ≥
self_eval_min_samples` (default 10): `blended = 0.3 × leaderboard + 0.7 ×
self_eval`. Before that, falls back to leaderboard alone. If neither
exists, the benchmark component is neutral.

**From benchmark to expected pass rate:** The files in
`src/proficiency.py` convert the benchmark blend into an expected client
success rate on real traffic. A category with no client outcome traffic
keeps the benchmark score verbatim. A trafficked category with no
per-model outcomes inherits a peer-rate prior. A row with its own
outcomes gets an empirical-Bayes blend of the prior and its observed
rate, with `outcome_prior_strength` pseudo-observations (default 20)
pulling thin data toward the category mean.

Source labels report provenance, not just confidence:
- `outcome_blended` — per-model has real outcome evidence
- `outcome_prior` — category is trafficked, but this row has no own outcomes
- `self_eval_thin` — benchmark measurement below the sample threshold; a
caller wanting to exclude it can

**Proficiency inheritance:** `propagate_to_variants` copies evaluated
`scores` to equivalent serving variants (same weights, same reasoning
setting, same context pool), but never over a row that was measured
directly. A `-fast` row is **not** equivalent to its `-standard` sibling.

"Measured directly" is `inherited_from IS NULL`, not `self_eval_samples > 0`
— inheritance copies the sample count too, so sample count alone cannot tell
an inherited row from a measured one, and using it meant a variant inherited
exactly once and then froze forever. `ensure_columns()` adds the column and
backfills provenance on databases that predate it.

### `energy_observations` — per-request telemetry

| Column | Type | Notes |
|---|---|---|
| `id` | INTEGER | Autoincrement |
| `model_id` / `provider` | TEXT | |
| `task_category` | TEXT | |
| `prompt_tokens` / `completion_tokens` | INTEGER | |
| `energy_kwh` | REAL | **Attributed** billed figure (noisy, 20× within-model) |
| `energy_btu` | REAL | `kwh × 3412.14`, dashboard value |
| `avg_power_watts` / `duration_seconds` | REAL | Pre-attribution product, ~1.8× within-model. `duration_seconds` is the **provider's** reported serving time — see `router_wall_seconds` below, which is a different quantity |
| `attribution_ratio` | REAL | Request's share of shared GPU pool (stable quantized: 0.001, 0.25, 0.5, 0.75) |
| `carbon_g_co2eq` | REAL | Reported by provider |
| `grid_carbon_intensity` | REAL | gCO2/kWh at call time |
| `grid_id` | TEXT | e.g. `FI` |
| `carbon_source` | TEXT | `static_fallback` (constant, excluded from routing) or live measurement |
| `cost_usd` | REAL | **Billed** figure, not tokens × list price |
| `allowance_remaining_usd` | REAL | |
| `service_tier` | TEXT | As billed |
| `cached_prompt_tokens` | INTEGER | `usage.prompt_tokens_details.cached_tokens`. NULL when the provider reported no count — never a substituted 0 |
| `cached_tokens_source` | TEXT | Why the column above is what it is: `reported` (a number arrived, 0 included), `details_no_count` (a details block with no cached count), `no_details` (no details block at all). NULL only on rows written before the column |
| `router_wall_seconds` | REAL | **Router-observed** wall clock for the request, `time.monotonic()`. Not `duration_seconds` — see below |
| `router_ttft_seconds` | REAL | Router-observed time to the first output token. Streaming only; NULL on a buffered row means not applicable |
| `observed_at` | TEXT | ISO8601 |

**Router-observed latency is a second quantity, not a backfill of the first.**
`duration_seconds` is what the provider says it spent serving; the two
`router_*` columns are what the router measured end to end, which additionally
includes connection setup, network transit, queueing ahead of the first token,
and router overhead. They are never written into each other.

The reason for the second measurement is coverage. On the live database
`duration_seconds` is present on 31,243 of 31,309 NeuralWatt rows and on **0**
of 3,850 OpenRouter rows, and no request-body opt-in will change that:
OpenRouter serves generation timing only from its separate
`/api/v1/generation?id=` endpoint, a second HTTP call per request. OpenRouter
carries ~73% of routed decisions, so a latency term in the objective needs a
number that exists for every provider. The router can always take one.

Spans, which differ by path:

| path | `router_wall_seconds` | `router_ttft_seconds` |
|---|---|---|
| streaming `/v1/chat/completions` | connection open → last byte forwarded | connection open → first delta carrying content or a `tool_calls` fragment |
| buffered `/v1/chat/completions` | just before the POST → complete response body | NULL, not applicable |
| `POST /dispatch` | just before the SDK call → response returned | NULL, not applicable |

Three things follow from those definitions. The mark is re-taken per attempt,
so a failover records only the candidate that actually answered. A role-only
opening delta does not count as a first token — it is protocol, not answer — so
TTFT is measured against output a user could see. And if a streaming client
hangs up early the `finally` still records the span up to abandonment, which
understates that request's latency rather than inflating it.

NULL on rows written before the columns existed, and on `seed_energy.py` and
`eval_proficiency.py` rows, which do not pass the timings.

**Attribution noise:** Billed `energy_kwh = avg_power_watts × duration ×
attribution_ratio`. The attribution term looks like noise up close (8 identical
calls varied 20×), but ranks 750× between models while within-model spread is
1.8× — it's a stable per-model property reflecting serving concurrency. Routing
scores on the attributed figures with a **median** over all `seed_reference`
rows, so repeated sweeps accumulate into a median-across-time.

### `provider_balance_observations` — per-provider prepaid pool snapshots

| Column | Type | Notes |
|---|---|---|
| `id` | INTEGER | Autoincrement |
| `provider` | TEXT | |
| `balance_usd` | REAL | Current prepaid pool balance |
| `total_credits_usd` | REAL | Lifetime credits purchased |
| `total_usage_usd` | REAL | Lifetime usage billed against the pool |
| `observed_at` | TEXT | ISO8601 |

Polled by `poller.py` from each provider's balance endpoint
(`provider.balance_url`). Used by `quota_accounts()` to compute per-provider
burn rate, projected runway, and stale-reading alerts.

### `local_energy_observations` — per-call local hardware draw

| Column | Type | Notes |
|---|---|---|
| `id` | INTEGER | Autoincrement |
| `model_id` | TEXT | Local Ollama tag (e.g. `mistral-nemo:12b` or `qwen2.5-coder-router:14b`), not a cloud model |
| `call_type` | TEXT | Not a closed enum. Current values include `classify`, `verify`, `local_vision`, `local_dispatch`, `file_summarization`, `diff_checking`, and `seed_local_dispatch`. |
| `request_id` | TEXT | Optional; joins to `POST /outcome` reports the same way `energy_observations.request_id` does for cloud rows |
| `session_dir` | TEXT | Optional; used for source-less `/outcome` attribution |
| `avg_power_watts` | REAL | Averaged over the call (background `nvidia-smi` sampler) |
| `duration_seconds` | REAL | Wall-clock time for the local call |
| `energy_kwh` | REAL | `avg_power_watts × duration_seconds / 3_600_000` |
| `cost_usd` | REAL | `energy_kwh × tariff_usd_per_kwh`; NULL if tariff not configured |
| `carbon_g_co2eq` | REAL | `energy_kwh × 1000 × grid_intensity_g_per_kwh`; NULL unless grid intensity configured |
| `meter` | TEXT | `nvidia_smi` (room for RAPL / smart plug later) |
| `observed_at` | TEXT | ISO8601 |

**Separate table, by design.** `quota_burn()` sums `energy_kwh` over **all**
of `energy_observations` against the NeuralWatt plan allowance. A separate
table makes it structurally impossible for local electricity to leak into that
number. `local_energy_summary()` in `metrics.py` queries this table exclusively,
over the same 30-day window. `/metrics` surfaces it as a top-level
`"local_energy"` key, and the admin dashboard has a distinct "Local compute"
card. The meter is off by default (`local_energy:` in config); config load
refuses `enabled: true` without a `tariff_usd_per_kwh`. Remote-Ollama safety:
if any Ollama base URL is non-loopback, metering skips with a log warning.
`ensure_local_energy_table()` in `src/local_energy.py` also creates the table
and index idempotently for live databases predating this schema.

### `verifications` — response quality observations

| Column | Type | Notes |
|---|---|---|
| `id` | INTEGER | Autoincrement |
| `model_id` / `provider` | TEXT | |
| `task_category` | TEXT | Optional (prose answers may lack a category) |
| `kind` | TEXT | `structural` \| `local_llm` \| `client_outcome` |
| `verdict` | TEXT | `ok` \| `truncated` \| `malformed` \| `unverifiable` \| `succeeded` \| `failed` |
| `detail` | TEXT | Human-readable reason |
| `completion_tokens` | INTEGER | Wasted answer cost, for payoff sum |
| `observed_at` | TEXT | ISO8601 |
| `applied_at` | TEXT | Set by `feedback.py` when folded into proficiency |
| `model_attributable` | INTEGER | 1 = model's fault; 0 = client caused (e.g. tight cap) |

Verifications drive the feedback loop: `feedback.py` reads unanswered failures,
applies a 0.0 sample per failure to `proficiency`, and marks them
`applied_at` for idempotency. `unverifiable` is recorded but not treated as a
failure — it means the checker had nothing to say, not that the model failed.

### `route_decisions` — routing observability

| Column | Type | Notes |
|---|---|---|
| `id` | INTEGER | Autoincrement |
| `observed_at` | TEXT | ISO8601, UTC |
| `kind` | TEXT | `route` \| `dispatch` \| `chat` \| `passthrough` \| `local_vision` \| `local_dispatch_fallback` |
| `task_category` | TEXT | |
| `task_tier` | INTEGER | 1–3 |
| `required_context_tokens` | INTEGER | |
| `confidence` | REAL | Classifier confidence |
| `classifier_ms` | INTEGER | Classification latency |
| `classification_source` | TEXT | `classifier` \| `override` \| `fallback` \| `cached` |
| `latency_tolerance` | TEXT | `interactive` \| `batch` |
| `candidates_considered` | INTEGER | How many survived hard filters |
| `selected_model` | TEXT | Null when no model was selected |
| `selected_provider` | TEXT | `neuralwatt`, `local` (vision fallback), or `ollama-local` (local dispatch) |
| `runner_up_models` | TEXT | JSON array of up to 3 runner-up candidates |
| `est_cost_usd` | REAL | Estimated cost of the selected model |
| `est_proficiency` | REAL | Estimated proficiency for the task category |
| `rejected_reason` | TEXT | Active filters when nothing was selected |
| `session_key` | TEXT | Hashed session fingerprint ONLY |
| `tools` | INTEGER | 0/1 — request carried a `tools` array |
| `images` | INTEGER | 0/1 — request carried image parts |
| `json_mode` | INTEGER | 0/1 — request required JSON mode |
| `streamed` | INTEGER | 0/1 — response was streamed |
| `pinch_original_tokens` | INTEGER | Estimated tokens before pruning (includes `extra_fixed_tokens`) |
| `pinch_final_tokens` | INTEGER | Estimated tokens after pruning |
| `request_id` | TEXT | Provider request id; joins to `energy_observations.request_id` |
| `exploration` | INTEGER | 0/1 — selected as the least-evidenced candidate for exploration |
| `prefix_divergence_index` | INTEGER | First message position whose bytes differ from the previous turn in this session |
| `prefix_tokens_after_divergence` | INTEGER | Estimated tokens at or after that position in THIS turn |
| `prefix_prev_message_count` | INTEGER | The previous turn's message count |

The three `prefix_*` columns are the prefix-stability probe
(`pinch.prefix_probe`, on by default). The provider bills the longest
byte-identical **prefix** of a prompt at the cached rate, so a divergence
early in the payload re-bills everything after it; these say how much of the
previous turn's cache this turn kept. Read them together:
`prefix_divergence_index == prefix_prev_message_count` is a healthy append,
and anything lower is rewritten history —
`prefix_tokens_after_divergence` is then what it cost.

They are **NULL together** when there was no previous turn to compare against
(first turn of a session, or first after a restart), which is deliberately
distinct from a measured `0` — a zero would read as total cache loss at
message 0. **Hashes only, and not even those**: the per-message digests that
produce these numbers live in process memory for exactly one turn and never
reach the database, so nothing here is reversible to any message. Rows written
before the columns existed are NULL and nothing may be inferred for them; the
payloads were never stored, by design.

`pinch_original_tokens` and `pinch_final_tokens` capture context-pruning
outcomes: `tokens_saved = original - final`, and `pruned = original > final`.
Both are NULL when pinch is disabled or the request predates the columns.
`request_id` is written back after the provider returns a completion id; it is
NULL on `/route` (no upstream call) until backfilled. `exploration` is 1 when
`exploration.choose` replaced the ranked winner with a least-evidenced
candidate.

Rows with `kind='local_dispatch_fallback'` record a degraded answer after the
cloud refused or was exhausted — they are **NOT evidence that local was
competitive on merit** (do not feed them into proficiency analysis). They carry
`selected_provider='ollama-local'`.

`route_decisions` stores one row per routing decision so "how is routing
performing" is answerable: which model was picked, for what category/tier,
how long classification took, and — when nothing was selected — which hard
filter shut it out. It is an observability table: nothing in routing reads it.

It stores only a hashed session fingerprint in `session_key`; `session_dir`,
prompts, and answers are deliberately excluded. A test enforces that the write
path does not store prompt or answer text. The write is gated by
`logging.log_route_decisions` and is **best-effort**: a failed write is logged
at warning and swallowed so monitoring cannot slow or fail a request.