Skip to content

Grounded decisions: provenance, audit and safeguards

The principle: fuzzy proposes, deterministic decides, everything is in the trace. A model may extract a value, pick a category or learn an answer, but its output is checked by deterministic code before anything uses it, and every step records where its value came from. A model's hallucination is either caught or visible in the audit — never silently an answer. A decision without any model and one with models are the same system; they differ only in the provenance of the facts.

Provenance

Every fact and answer has a provenance kind (record.origin, result.provenance, solvi.core.provenance.KINDS):

Kind Where the value comes from How it is kept honest
given a key of init_state hashed into init_hash; the chain starts from it
computed a plain function: fn, check, a hand-written rule replay re-runs it and compares
quoted an extract part returning a Quote the offsets must lie in the source text; for a model, doc[start:end] must be the value
decided a model's choice among declared options, with probabilities (Decision) the value must be one of the options; probabilities recorded
learned a fit head, a learn_rule list, another trained function the head type and a fingerprint of its parameters are recorded
proposed a model that writes: a strategist's plan, a generator's text or JSON (solvi.core.slow.generate) the deterministic layer verifies what it proposes; replay re-reads a recorded reply through its parser and schema

The default comes from what a part returns (a Quote → quoted, a Decision → decided) and whether a model is behind it. Declare it explicitly with provenance= on any decorator. A part is model-backed when you pass model=:

cat.extract(extractor.field("total", "the total amount paid"))    # field() functions bring their model along

@cat.extract(model=span_extractor)                                  # any function that calls a model
def vendor(doc): ...

@cat.fn(model=classifier, options=["travel", "meals", "equipment"])
def category(doc):
    p = classifier.predict(doc)                                    # {option: probability}
    return Decision(max(p, key=p.get), p)                           # downstream parts get the plain value

@cat.rule("risk", model=risk_model)                                 # a model answers the question directly
def risk(amount, country): ...

LongSpanExtractor.field and LongSpanExtractor.embedder mark their functions (the attributes __solvi_model__ and __solvi_provenance__), so registering them is enough. For any other model, pass model=.

Model identity in the trace

A model-backed record stores record.model = {"type", "id", "fp"}: the class, the model id (the Hugging Face id or path it was loaded from, model.model_id), and a fingerprint (solvi.core.provenance.fingerprint):

  • extractors: settings, thresholds / temperatures, the span head, evenly sampled encoder weights, and the names and sizes of the weight files — computed once, then cached until fit / save;
  • FastHead (fit; Head, the logistic head before 0.8): a hash of their parameters — it changes with every teach;
  • RuleList (learn_rule): a hash of its rules;
  • any other object: its own fingerprint() method, or a version attribute, or "unversioned:<type>" (then a changed model cannot be detected — give your models a version).

res.trace.replay(catalog) handles model-backed steps as follows:

  • the fingerprint differs from the catalog's current model → a mismatch, "model changed since this decision"; the recorded output is still checked for grounding;
  • same model, deterministic (the default; set model.deterministic = False otherwise) → the step is re-run and compared;
  • replay(catalog, trust_models=True), or the model is not available (no model on the part, model.available = False) → the model is not re-run; the recorded output is verified instead: the quote is literally at its offsets in the recorded input, the decision is among the options.

Pass the System instead of the catalog (res.trace.replay(system)) to verify answer-head records too: their fingerprint, and (unless trusted) their probabilities recomputed from the recorded facts. rep["models"] lists every model-backed step with its verdict: recomputed, trusted, unavailable or changed.

Hashes: a record hashes its provenance only when it differs from the default (quoted for a record with a quote, else computed), and its model and probabilities only when present — so traces of catalogs without models hash exactly as before.

Safeguards

Safeguard Fires when Effect
grounding a quote lies outside its text, or a model's quote is not literally doc[start:end] (strings in the normalized view, see Extractors and Quote; numbers as written, e.g. 1250.0 ↔ "1,250.00" — int, float, Decimal, Fraction and numpy scalars; a date when the text reads as that date; a bool when the quoted words say it — "yes", "true", "1", "да" for True, "no", "false", "0", "нет" for False; a datetime or a list cannot be compared and is not checked); an evidence quote or a span is not literally in its text the output is rejected: the fact is missing, the claim stays in the error; the next alternative producer runs, else dependent answers abstain
closed set a Decision (or a value of a part with options=) is not one of the options; a rule's answer is not one of the question's options rejected / the question abstains
low confidence a Quote / Decision is below the part's min_confidence (a decision part's too); an answer is below the question's min_confidence rejected / the question abstains, saying what it would have answered
model escalated a decider's act / escalate signal is below its threshold (see the output) rejected: the fact is missing, next producer, else the question abstains, saying what it would have answered
validate a producer's validate(value, ...) returns false rejected, next producer
type rejected a typed part's argument or output fails its type annotation, or a field fails System(input_model=...) rejected: the fact is missing, next producer, else dependent answers abstain
hard check a hard check governing the question is false the answer is forced by then, or the question abstains
constraint repair learned or model answers break a constraint between answers the most probable consistent combination is chosen
fallback an alternative producer was rejected and a later one was used recorded in tried
evidence missing a question with require_evidence=True got an answer without a supporting quote the question abstains, saying what it would have answered
instruction a decision part with perturb=k answered differently without an instruction-like sentence of its input ("ignore the rules and answer X") rejected like an escalation: the fact is missing, next producer, else the question abstains, naming the sentence (system.stats["instruction_flips"])

Hand-written extractors (no model) may return a value derived from the quoted text; the audit then shows the value next to the text it was derived from. Numbers, dates and other non-string values from a model are checked when they can be compared (numbers) and shown next to the quoted text otherwise.

The audit

print(res.audit())            # every answer
a = res.audit("approve")      # one answer: an AnswerAudit
a.to_dict()                   # the same as data

For each answer: the given inputs → computed facts → quotes (offsets, the quoted text, whether the value is literally that text, the model) → model decisions (the model, probabilities) → learned parts (head type and fingerprint) → checks (hard or soft, which one decided) → the rule → constraints → the answer; the parts skipped at run time; the safeguards that fired; and a summary of the support: how many items are deterministic (given, computed, quoted by plain code) and how many come from models (a.share_deterministic, a.counts).

approve = 'yes'  [ok]  confidence 0.60  ← computed by approve
  given       doc = 'Expense claim #2291\nVendor: C…; limit = {'travel': 100, 'meals': 60, 'e…
  computed    amount = 48.6
  quoted      total = '48.60'  doc[100:105] literal '48.60'
  decided     category = 'travel'  (travel 0.60, meals 0.20, equipment 0.20)  [StandInClassifier demo/expense-category #bb3352d4]
  check       amount_positive = True (hard)
  rule        approve (computed)
  → answer    'yes' — amount = 48.6; category = 'travel'; limit = {'travel': 100, 'meals': 60, 'equipment': 800}
  support     7 items (2 given, 3 computed, 1 quoted, 1 decided): 86% deterministic, 1 from models
  guarantee   none for some decisions: their thresholds were not calibrated on your data (see act_guard)
  safeguards  grounding rejected ×1, fallback producer ×1
              · grounding rejected: total — total_model: not grounded: '488.60' is not the text at [100:105] ('48.60')
              · fallback producer: total — total_regex used after total_model rejected

Reports for people: res.report, store.report, solvi report

The audit is for developers; a report is for an auditor or a customer — one page per decision or per period, as Markdown, one self-contained HTML file (no external assets, scripts or fonts; every value escaped) or data (format="data").

print(res.report())                          # Markdown
open("decision.html", "w").write(res.report(format="html"))
res.report(format="data")                    # the same as a dict (answers, documents, models, trace, replay)

A decision report shows, per answer: the answer, status and confidence, the reason; what it rests on (given inputs, computed facts, quotes with their offsets, model decisions with probabilities and the model, learned parts, checks — which one decided —, the rule, evidence, constraints, parts not run); the safeguards that fired; and the guarantee line — the promise of the calibrated thresholds of the model decisions behind it (act_guard, calibrate_for), "none" when a model decided without one, or that no model decided the answer. Then the source texts with every quote highlighted (the offsets on hover; a quote that is not the text at its offsets in red; a text over 20 000 characters as excerpts around the quotes), every model that ran with its fingerprint (also the ones whose output was rejected), the trace's input and last hashes, the catalog's fingerprint and the replay status. replay="trusted" (the default) re-runs the deterministic steps and verifies the models' recorded outputs without calling them; replay="full" re-runs the models too, replay=False skips it. A response loaded from a store with its System (store.get(id) when the store belongs to a System) reports like the original.

print(store.report(since="2026-09-01", until="2026-10-01"))            # every question
store.report(question="refund", format="html", examples=5)               # one question

A period report counts per question: the answers, the statuses, the escalation rate (abstentions — handed to a person — by the safeguard that caused them), the safeguards that fired, and the guarantee coverage: of the answers a model decided or took part in, how many rest only on calibrated thresholds (answers from code alone are counted apart). It lists the catalog and model fingerprints in use, how many decisions of the period were erased (store.redact: they are not in the counts) and how many corrections were recorded in it ("erased" and "corrections" in the data; store-wide for the period, whatever the other filters), and every change of the fingerprints over the period (from which stored decision on), and up to examples stored ids per answer, escalation reason and safeguard — res = store.get(id) and res.report() give the page of one. From the shell:

solvi report decisions.db --since 2026-09-01 --question refund          # Markdown to stdout
solvi report decisions.db --html september.html                          # a self-contained page
solvi report decisions.db --id 3f9a0c1d2e4b5a67 --system app.py:system   # one decision, replayed against the system

The system report: System.report, solvi report --overview

A period report lists decisions; the system report answers the owner's questions about a System over a period — who answered, how often each part answered and handed over, what it cost, whether the promise held on the labels you have, and whether the stream moved. It reads the store alone: no model is called, no catalog is needed, so it runs on a copy of the store on another machine.

rep = system.report(since="2026-09-01", until="2026-10-01")    # the System's storage; or report(store=...)
print(rep)                                                       # plain text
rep.to_dict()                                                    # the same as data

from solvi.core.store.sysreport import system_report
rep = system_report(SQLiteStorage("decisions.db"), question="intent", price=(0.15, 0.60), drift_window=100)
solvi report decisions.db --overview --since 2026-09-01          # text
solvi report decisions.db --overview --json                      # data

What it shows, per question:

  • Who answered. The answers given alone and what gave them — a rule (its name), a model decision (the model's id), a learned head, or a hard check that forced the answer — and the inputs handed over, by the safeguard that held them back. A forced answer is credited to its check whether or not the check changed it, so the forced ones are split (forced_split): the check changed the answer (the question's own answer in the trace differs), the answer would have been the same, or not known — under early_exit=True (the default) a failed hard check skips the question's own answer and the record holds no value to compare; build the System with early_exit=False to count them. With a dispatcher (solvi.core.dispatch, storage=), who gave the final answer: System 1, the slow path or a person, by action (accept, think, check) and by the slice System 1 handed over.
  • What it cost. The time of every decision, the model calls and tokens the traces record, and dollars where they are known (the dispatcher records them, and so does a generator built with price=; for other model calls pass price=). The dispatcher's spend is split between System 1 and the slow path. Refinement loops (solvi.core.slow.refine with a System that has a storage) are counted in cost["refine"]: how many, accepted, escalated, stopped by their budget and over it, their rounds, the whole loops' cost and their proposals' model calls (which no System trace holds). Compact records are read as full ones for all of this: they keep the answers, the guarantees, the models and every model call.
  • The promise against the labels. Every guarantee the decisions were gated by (System.guarantee, an open-set gate: its method, level and text, how many decisions it let through) and every calibrated dispatch policy (Dispatcher.calibrate: who answers each slice, at what threshold), next to the error measured on the decisions that have a label in the store. A correction labels the decision it names (of=), else the latest decision before it on the same input; corrections stored after the period still count. Labels from a person, an outcome or a rule are measured; System 2's verified answers (label_source="verified") are counted but not measured — they are the system's own answers. The verdict says "within the promise", "above the promised level, not significantly", or "above the promise" with the binomial p-value. When only some decisions are labelled, the report says the measured error is that of the labelled ones: corrections are usually made where an answer looked wrong.
  • How often a person was wrong. A person is not an oracle. Where a decision has a person's label (a correction, label_source="human", or an audit label) and also an outcome label (System.outcome, label_source="outcome") — both naming it with of=, or on its input — the person's last answer given before the first outcome label is compared with the last outcome (a label given after the outcome was known is not a judgement: decisions with only such labels are counted in after_outcome, not paired): corrections["people"] gives the pairs, the wrong ones, the error with a two-sided 95% Clopper–Pearson interval, and the same per person (by=) and per question; the text report adds a "People:" line. A person's answer to a decision handed over by a dispatcher is such a label too: teach(..., of=<the dispatched decision's id>, by=...). The pairs are the decisions whose outcome happened to be recorded, not a random sample of the person's decisions; read the interval with that in mind. Before 1.4 solvi stored both labels but never paired them.
  • Drift. The flags the decisions recorded (an open-set gate's change point, the dispatcher's drift flag), and a DriftMonitor run over the period's decisions in order, with the stored labels where there are some: the first decision at which it flagged and what moved. drift_window= sets its window (default 100; None or --no-drift: not run); a period shorter than the window and half of it again is not tested, and the report says so.

The period header also lists the catalog fingerprints in use (a change of the catalog shows as two of them, with the dates of each) and the models that ran.

On the banking stand task (2,000 requests, a promise of at most 5% wrong among the answers given alone, new kinds of request from request 1,000 on), with the true intents stored as outcome labels, the report gives 713 answers given alone by the model, 1,287 handed over, 5 of the 713 wrong (0.70%: within the promise) — the numbers the task's own scorer gives — the open-set gate's own flag at request 1,068, and a DriftMonitor flag on the share answered alone at request 1,046. On the credit task (rules only, two versions of the catalog) it gives 998 answers by the rule, 2 forced by a hard check, and 600 and 400 decisions under the two catalog fingerprints.

Lifetime stats

system.stats counts, over the system's lifetime: asks, answers, abstained, model_outputs (outputs of model-backed parts, answer heads and learned rules), grounding_rejected, type_rejected, outside_options, rule_abstained, low_confidence, validator_rejected, forced_by_hard_check, constraint_repairs, fallbacks, model_escalated, evidence_missing, timeouts, no_answer (a remote model's server did not answer after its retries — the question abstains, as for an escalation, but it is not the model's doubt), instruction_flips, memory_disagreements, contract_refused (answers that broke their question's contract: a wrong type or an echo of the input, see Catalog.contract) and not_applicable (questions whose contract's precondition did not hold, so they were not computed). system.safeguard_summary() prints them (evidence missing, timeouts, no_answer, contract_refused and not_applicable once they have fired). examples/12_grounded_audit.py runs one catalog with and without models, with a hallucinating extractor and a classifier answering outside its options.