solvi.core.store¶
TraceStorage: stored responses and traces, queries and replay; JSONL, SQLite, PostgreSQL and DuckDB backends.
TraceStorage: stored responses with their traces, a hash chain across them, queries, a replay of everything stored, and provenance questions over the store (which stored decisions rest on a fact found to be wrong; what a forgotten given fact touches).
Every stored decision is one record (a dict of plain JSON):
kind "ask" the 0.5 journal line's keys — init_hash, answers {question: [answer, confidence, status]}, flow, records [[step, name, hash]] (and producers) — plus index fields (guards, safeguards, models) and the whole response (Response.to_dict(): answers, flow, trace), which get() loads back and replay_all() re-checks; kind "teach" a correction (System.teach): {"teach": question, "init": ..., "answer": ...} and, when given, its "source" ("outcome", "rule", "verified"; none: a human), "by" and "of" (the stored id of the decision it corrects; for "verified", the System 2 decision the label is); kind "update" a labelled update (solvi.experimental.changes, LearningTarget): what changed, the gates' results, the state to roll back to; kind "specialist" a specialist's run (solvi.core.specialist): the source's hash, the proposal, the check, the output's hash; kind "stream" a state change of a Dispatcher's stream certificate (promise=, audit="adaptive"): {"stream": {"event": "grid" | "certified" | "loosened" | "alarm" | "recertify", "question", "decision", "v_index", "delta_v", "threshold", "n", ...}}; a dispatch record of such a dispatcher carries "stream" too (its sample, certificate and detector state). "stream" is KEPT: a redaction leaves it; kind "pending" a ticket issued to an oracle outside the process (solvi.experimental.stream.tickets): {"pending": {"ticket", "question", "n", "created", "ttl", "kind_hidden", "rho", "probation", "sampled"}, "issue": the decision begun (Dispatcher.start: the input, System 1's response, the draws)}; its dispatch record, written when the ticket is resolved or expires, carries "pending": the ticket. kind "pending_expired": {"pending": {"ticket", "question", "n", "at", "why"}} — no verdict came. "pending" is KEPT; kind "loop" one decision of the closed learning loop (solvi.experimental.stream.versions): "question", "stream" (KEPT: the served and candidate versions, the coin, the scores, both certificates' states) and "loop" (the input, the would-be answers, the label: not kept); its freeze / promote / discard / rollback are records of kind "stream"; every record seq (0, 1, 2, ...), time (seconds since the epoch), meta (optional, yours; a decision made with solvi.experimental pieces has meta["experimental"]: their names), prev and hash.
A record is written with every dict's keys in their own order (a decider reads a dict's keys in that order, so a
stored trace gives its dicts back as they were). hash is the SHA-256 of the record's canonical JSON (keys sorted,
without id and hash) — it does not depend on the order the record was written in — which includes prev, the
hash of the record before it: editing, deleting, inserting or reordering a stored record breaks the chain at that point
(verify()). Cutting records off the end leaves a shorter chain that is still valid, so the store keeps its head — the
count and the last hash (head()) — next to the log and verify() checks it; a head you published elsewhere
(verify(anchor=head)) also catches a rewrite of the whole chain together with the stored head.
Backends: JSONLStorage (append-only file, one record per line; what System(storage="file.jsonl") writes), SQLiteStorage (stdlib sqlite3; indexed by question, answer, status, safeguard, model fingerprint and time; several processes may write), PostgresStorage (psycopg 3; the same tables, several services writing) and DuckDBStorage (duckdb; the same tables in a DuckDB file, for analytics).
UntrustedLabel ¶
Bases: ValueError
A label from a source outside TRUSTED_SOURCES (the model, the system itself, an unknown process), or a "verified" label offered to a channel that does not take it.
CompactRecord ¶
Bases: ValueError
A stored decision kept compact (record="compact"): its trace is not in the store, so it cannot be loaded as a Response. TraceStorage.rederive(id, system) re-runs it from the recorded input and checks every step against the recorded hashes; replay_all does so too.
Stored
dataclass
¶
One stored record: its id, position, time (seconds since the epoch), kind ("ask": a decision; "teach": a correction; "redaction": the mark of an erasure, see TraceStorage.redact) and the record itself.
answers
property
¶
question → the stored answer (JSON form: tuples as lists, "not stated" as "
parent
property
¶
The id of the decision this record follows from (run_context(parent=)), or None.
compact
property
¶
Was this decision stored compact (record="compact", or not drawn for a full record under "sample:N")?
input
property
¶
The given facts of a stored decision as JSON data (full or compact; None for a redacted one).
response ¶
The stored response, loaded back (typed values restored from catalog — a Catalog or a System — or from the
store's own). A compact record raises CompactRecord: re-derive it with TraceStorage.rederive(id, system).
TraceStorage ¶
Bases: ABC
A store of responses and their traces with a hash chain across the stored records (see the module docstring).
The base class of every store (an extension point: from solvi.core import TraceStorage). A backend of your own
implements five methods — _append(body) (assign seq, time, prev, hash and id atomically; → the record),
_raw(snap=None) (every chained record in stored order: (position, dict or None when unreadable)), _find(id)
(the record or None), head() ({"count", "hash"}) and _rewrite(rec) (replace the record with that seq: redact
uses it) — and may override close(), _snapshot(), _backend_problems(rows, snap), iter / query (for an
index). It gets for free: the hash chain and verify (with an anchor and a signature), save / get /
rederive (full and compact records), corrections and verified labels with their source checks, query,
report, replay_all, quarantine / where_is, redact, signature, and every reader of a store (the audit,
the system report, diff). solvi.testing.conformance.check_storage(MyStorage) checks a backend. Stability:
stable; the record format is stable (stores of 0.7 to 0.9 read and verify).
save(response, meta=None) → id; save_many(responses, metas=None) → [id]; batch() (a context: the saves inside it share one lock, one head write / one commit); get(id) → Response; record(id) → the stored dict; iter() / query(...) → [Stored]; corrections() → the teach records; head() → {"count", "hash"}; signature(); verify(anchor=None, signature=None); replay_all(system); quarantine(fact, value=...); where_is(fact, value=...).
system: the System (or a Catalog) used to restore typed values (dates, enums, models) when loading responses;
System(storage=...) sets it to that system when it is not set. clock: a function → seconds since the epoch.
record: what a decision's record holds — "full" (default: the whole response, every step's value and inputs), "compact" (for frequent decisions: the input, the answers, every check's result and reasons, the model-backed steps whole with the models' ids, fingerprints and tokens, and every step's hash; not the computed values, the planned flow or the timings — see compact_content) or "sample:N" (one decision in N, counted by this store object, in full, the others compact). A compact record is hashed into the chain like any other: verify() checks it, its kept steps' places and links in the chain of step hashes, and its answers. What it does not keep is re-computed, not read: replay_all re-runs the decision from the recorded input and compares every step's hash (rederive); a model step that is not re-run on replay (trust_models=True, a generator) leaves the decision unchecked past the chain, and the replay says so (mismatch kind "not_kept") instead of passing it. get(id) raises CompactRecord; the reports read the answers, checks, models and costs from what is kept; quarantine re-derives compact decisions when the store knows the System; diff compares their answers only (no steps are kept to say what changed them).
head
abstractmethod
¶
{"count", "hash"}: the number of chained records and the last record's hash (GENESIS when empty). Publish it somewhere else (a ticket, a log, a signed message) to later catch a rewrite of the whole store: verify(anchor=...).
save ¶
Store a response (its answers, flow and whole trace) → its id. meta: your own JSON data kept with it (a
ticket id, a user) — hashed into the chain like the rest. What the record holds follows the store's record=;
record="full" or "compact" overrides it for this response (System(cache=) stores a served decision compact).
batch ¶
A batch of writes: with store.batch(): for r in responses: store.save(r). JSONLStorage takes its locks
once and writes the head (and, with fsync=True, syncs) once at the end, not per record; the SQL stores run the
batch as one transaction — one commit, and an exception inside rolls the whole batch back (JSONL keeps the
records written before it, with their head). Other threads and processes wait for the batch to end. Inside a
batch only save, save_correction and reads that need no lock (get, iter, query, head) are for this thread;
verify and redact raise. A backend without its own batch saves one record at a time, as outside one.
save_many ¶
save() each response in one batch() → their ids. metas: None or one meta (or None) per response.
save_correction ¶
save_correction(question, init_state, answer, meta=None, *, label_source='human', by=None, of=None, note=None)
Store a correction (what System.teach records) → its id. label_source (source= in 0.7; stored as the
record's "source"): where the label comes from — "human" (a person
corrected or confirmed the answer), "outcome" (what really happened: the parcel was lost, the loan defaulted) or
"rule" (code rejected a model's proposal and decided instead), or "verified" — a System 2 answer that passed
the checks and a guarantee: of must then name that decision, stored in this store, which answered question
alone (status "ok", not escalated or abstained) under a guarantee (System.guarantee) with this very answer;
anything else raises UntrustedLabel, and the label is not stored. Anything else is refused (UntrustedLabel):
the system's own unverified answers are never labels. by: who (a user, a reviewer, a process); of: the stored id
of the decision it corrects (for "verified", the one it is); note: a line of text kept with it (what happened —
System.outcome writes it). Every record writes its "source" (since 2026-10-30 the default too); records of 0.6
have no source: they are human corrections. Storing a verified label
teaches nothing by itself: which channel may read it, see check_source.
get ¶
The stored response with this id, loaded back with system (default: the store's; see Stored.response).
rederive ¶
A stored decision as a Response — a full record loaded as get() loads it; a compact one re-run with system
(default: the store's) from its recorded input, every step checked against the recorded hashes (see the module
function rederive). Raises CompactRecord with the reasons when a compact decision cannot be rebuilt.
iter ¶
Stored records in order (kind "ask": responses; "teach": corrections; None: all) → iterator of Stored. A redacted record (see redact) has no content left and is passed over; redacted=True: it is yielded too. after: only the records stored after this sequence number (Stored.seq) — the cursor of a reader that keeps its own index over the append-only store and reads only what was appended since (JSONLStorage serves it from its parsed-lines cache without walking the whole store).
__len__ ¶
The number of chained records — decisions, corrections and redaction marks (head()["count"]); the decisions alone: len(list(store.iter())).
close ¶
Release what the store holds open (a database connection; nothing for a JSON-lines file). A store is also a
context manager: with SQLiteStorage("decisions.db") as store: ... closes it at the end.
corrections ¶
The stored corrections → [{"id", "time", "question", "init", "answer", "source", "by", "of"}] (feed them to fit / learn_rule, a CorrectionMemory or an update target of solvi.experimental.changes). source: "human" (also every record without one), "outcome", "rule", "verified" — or, for a record written around save_correction, whatever it says (solvi.core.knowledge.memory and the update target of solvi.experimental.changes refuse anything outside TRUSTED_SOURCES, "verified" included; System.guarantee takes "verified" when told to). label_source: only the corrections from this source (or these sources) — e.g. "audit", the labels of the decisions drawn at random (Dispatcher(audit=)).
query ¶
query(question=None, answer=ANY, status=None, safeguard=None, model=None, since=None, until=None, catalog_fp=None, run=None)
Stored responses that match every filter given → [Stored] in stored order. question: asked this question; answer: answered this (with question: that question's answer; None matches an abstention); status: "ok" / "forced" / "abstain" (with question: of that question); safeguard: a safeguard of this kind fired ("grounding", "hard_check", "low_confidence", ...; with question: one that concerns it); model: a model with this fingerprint, id or type produced a step; since / until: stored in [since, until) — seconds since the epoch, a datetime, a date or an ISO string; catalog_fp: decided by the catalog with this fingerprint (System.fingerprint()["catalog"]); run: written inside run_context(run) with this run id (records written outside a run_context have none). An answer is matched in its stored form: answer=True finds a yes/no "yes" (see _answer_key).
report ¶
A human-readable report of the stored decisions in [since, until) (optionally of one question): counts by
answer, status and safeguard, the escalation rate, the guarantee coverage of the answers a model took part in,
changes of the catalog's and the models' fingerprints, and examples stored ids per answer, escalation and
safeguard. format: "md", "html" (one self-contained page) or "data" (a dict); other filters as query. See
solvi.core.store.report.
redact ¶
Erase a stored record's content — a person's data that must go — and keep the chain whole.
The record keeps its place, its time, its hash and its id, so every link after it still verifies; its content
(the response with its trace and input, the meta; a correction's input and answer) is removed and it is marked
redacted with who and why and the digest of what was removed. A record of kind "redaction" is appended that
names the erased record and its hash: the erasure is itself in the chain, with its time. keep_answers=False
removes the answers too (their digest stays in the mark). The record no longer replays and is passed over by
iter / query / replay_all / reports; record(id) returns what is left. → the redaction record's id.
What is left stays verified: a record's hash is taken over its lasting fields, the digest of its answers and the digest of its content (record_body), so verify() recomputes the hash of a redacted record like any other — an answer edited in it afterwards, or a record passed off as redacted with other answers, does not verify — and a signature taken before the erasure still holds. A record written by solvi ≤ 0.7.1 (format 1) has one flat hash: redacting it leaves its kept fields unverifiable, which verify() lists under "unverified". What it cannot do: copies made before (a backup, an exported report, a published anchor's holder) are not touched, and derived state (a correction memory, a fitted head) keeps what it learned — rebuild those.
signature ¶
The signature of the chained records (solvi.core.store.signature.sign): {"alg", "count", "root"} — with the default "syndrome" code two numbers (64 bytes). Keep it where you keep the head: verify(signature=...) then names the one record that changed — even when every hash after it and the stored head were recomputed — and restores its content hash.
verify ¶
Check the chain across stored records: each record's hash, its link to the record before it, the sequence
numbers, the stored response against its own summary, and the stored head (a cut-off tail). anchor: a head()
taken earlier and kept elsewhere — the chain must still contain it (catches a rewrite of the whole store).
signature: a signature() taken earlier and kept elsewhere — the records it covers must be the ones signed; when one
changed, its seq is named and signature in the result holds solvi.core.store.signature.check's answer (the original content
hash; candidates: records, e.g. from a backup, one of which may be the original → its "match").
→ {"ok", "count", "head", "legacy", "problems": [(seq, id, reason)]} (+ "signature" when given; + "unverified":
[(seq, id, reason)] — redacted records of format 1, whose kept fields no hash covers). Records written before the
chain (0.5 journal lines) are counted in legacy and not checked.
A store that is being written to verifies as it stands at one moment: the stored head is read first and the
records are checked against it, so a record appended while verify runs is not reported as damage.
deep: True (default) also re-checks each stored response against its own summary (the answers, their
confidence, the trace's hashes and links, guards, safeguards, models, flow); False skips that re-check and
keeps every chain check (each record's hash, links, sequence, ids, redactions, the head, anchor, signature) —
an edit is still caught unless the editor recomputed the record's hash and every hash after it, which only an
anchor or a signature kept elsewhere catches.
replay_all ¶
Replay every stored trace (or those matching query filters) against system (a System or a Catalog): each
step is re-computed from its recorded inputs (see Trace.replay). → the ones that fail: [{"id", "seq", "time",
"mismatches": [(step, name, reason)], "models": [(step, name, verdict)], "catalog", "kinds", "summary"}] — empty
when all replay. Each mismatch has a .kind, and "summary" tells damaged data from a catalog or a model that
changed since (see solvi.core.runtime.Mismatch). A stored record that cannot be loaded is one mismatch (0, "load", ...),
a replay that raises is (0, "replay", ...): both of kind "error", no verdict on the data. "note" (a record of
format 1 whose model step does not recompute): it was stored with sorted dict keys, see LEGACY_ORDER.
A compact record (record="compact") is re-run from its recorded input and every step compared with its recorded
hash (rederive), then replayed like a full one; one that cannot be — a model step not re-run (kind "not_kept":
no verdict on the data past the chain), a step whose hash differs (kind "recompute": the old value is not kept)
— is listed with "record": "compact".
One store, several systems: pass them all, replay_all([system_a, system_b]) — each record is replayed against
the system that asks every question it answers (the one whose catalog fingerprint is the recorded one first). A
record that no given system asks any question of is listed with a mismatch of kind "other_system" instead of
the missing parts and inputs a foreign catalog would report — not an integrity verdict: which questions a record
answers is its own (editable) content. What does not depend on the system is still checked: a full record's
trace hashes (kind "integrity"); a compact one keeps no trace ("not_kept"), and a trace that cannot be loaded
with this system is an "error" mismatch, never passed over. Every record's own hash is checked as verify()
checks it (an edited record: kind "integrity"). question= / catalog_fp= filters replay one system's
records only.
provenance_index ¶
An index of which stored records read or hold which fact → ProvenanceIndex. Its quarantine(fact, value) and where_is(fact, value) answer as this store's do, looking only at the records that can match instead of every record; it follows records saved after it was built (it reads the new ones on the next query).
quarantine ¶
A fact (or a given input) found to be wrong: the stored decisions whose answers rest on it — through the trace's
provenance graph (each step's recorded inputs, from the answer back to the fact; a hard check that ran for the
question counts, passed or failed: the answer stood because it passed). value: only where the fact had this value (compared by its hash as the consumers recorded it).
→ [{"id", "seq", "time", "questions": {question: {"answer", "status", "path": [fact, ..., "answer:question"]}}}].
Nothing is changed: re-decide or review these.
A compact record keeps no step inputs: it is re-derived with the store's System (rederive) and its rebuilt
trace is searched; one that cannot be (no System, a model step not re-run, a step that no longer recomputes) is
not searched, and a UserWarning names how many and their ids.
where_is ¶
Where a given fact (e.g. a person's data) is held, and what removing it would touch (forget in 0.7) — a
report only: nothing is deleted (deleting a
stored record breaks the chain by design; keep the report as the record of the request, and erase the records it
lists with redact).
→ {"fact", "value", "dependent": the stored decisions whose answers rest on it (as quarantine), "stored": ids of the
stored records that hold it without an answer resting on it (responses and corrections), "deleted": 0}. A compact
record that holds it in its input is listed under "stored": it keeps no step inputs to say what rests on it
(quarantine re-derives it for that).
ProvenanceIndex ¶
Which stored records read which fact (as a step's recorded input) and which hold it as a given input — built from a store in one pass (TraceStorage.provenance_index()), so that quarantine(fact, value) and where_is(fact, value) visit only the records that can match. The answers are the store's own (the same lists, in stored order): the candidates are then checked by the store's quarantine / where_is. A compact record keeps no step inputs: it is always a candidate of quarantine (re-derived there, as the store does). Records saved after the index was built are read on the next query; a record redacted since is passed over, as the store passes it over. In memory only: {fact: {record id: value hashes}}, nothing is written to the store.
JSONLStorage ¶
JSONLStorage(path, system=None, clock=None, fsync=False, index=True, *, record='full', rotate_bytes=None, rotate_records=None)
Bases: TraceStorage
Append-only JSON lines, one record per line (the file System(storage="file.jsonl") writes). The head (count and last hash)
is kept in <path>.head. Threads of a process may write; several processes may too where the system has advisory
file locks (POSIX: an append takes an exclusive flock on the file, reads what other processes appended since it
last looked, then writes its record and the head) — on Windows keep to one writing process, or use SQLiteStorage.
Lines of a 0.5 journal at the start of the file are kept and skipped (verify reports them as legacy).
fsync=True: flush every record to disk before save returns (slower; without it a power failure can lose the last
records, which the OS had not yet written). index=False: open from the stored head (checked
against the file's last line) without reading every record — a long file opens at once, for a process that only
appends; get(id) then scans the file. A head that does not match the last line is not trusted: the file is read.
record: "full", "compact" or "sample:N" (see TraceStorage).
Rotation. rotate_bytes / rotate_records: when the file has reached that many bytes (or chained records), the next
append first moves it to a closed segment <name>.000001.jsonl (with its head; the number counts up) and starts
path again with a record of kind "segment" that names the closed segment, its record count and its last hash —
so each file verifies on its own, the first record of a file is linked to the head of the one before it, and
verify_segments() checks every segment and every link (a segment replaced, cut short or removed breaks a link).
Reads (iter, query, get, replay_all) and redact see the current file; segments() lists the closed ones, each
readable as a JSONLStorage of its own. A closed segment is not written to: redacting one of its records there would
append to it and break the link of the file after it (not supported yet). With rotation, writers of the same path
lock <path>.lock (a file that is never moved): every process writing a rotated store must open it with rotation
on.
segments ¶
The closed segments of a rotated store, oldest first → [path] (the current file, path, is not listed).
verify_segments ¶
Verify a rotated store whole: every closed segment and the current file (each as verify() checks it) and
every link — the first record of each file after the first is a "segment" record naming the file before it, its
record count and its last hash, which must be that file's. anchor: a head() of the current file kept
elsewhere; deep: as verify(). → {"ok", "files": [{"path", "ok", "count", "head"}], "count": records in all files, "problems":
[(path, seq, id, reason)]}.
batch ¶
See TraceStorage.batch: the thread lock and the file locks are taken once, the head is written (and, with fsync=True, the file synced) once at the end — also when the batch ends with an exception.
iter ¶
As TraceStorage.iter, with after served from the parsed-lines cache: only the records past that sequence
number are walked to (a bisect on the cache's seq index), so a reader that keeps its own cursor — the
process store's index over tickets, answers and segments — costs O(new), not O(store) (S267/S277).
SQLiteStorage ¶
Bases: _SQLStorage
SQLite (stdlib sqlite3): one row per record with the record's JSON, plus index tables — answers (question, answer,
status), safeguards (kind, question), models (fingerprint, id, type) — and the time. The head is kept in the meta
table. Appends run in a write transaction, so several processes may write to one file. Each record is one committed
transaction: durable once save returns (unlike JSONLStorage without fsync=True), at the cost of a disk sync.
PostgresStorage ¶
Bases: _SQLStorage
PostgreSQL (psycopg 3, pip install solvi[postgres]): the tables of SQLiteStorage, named with prefix
("solvi_records", ...), created when missing. Several processes and services may write: an append locks the head
table (LOCK TABLE ... IN SHARE ROW EXCLUSIVE MODE — readers are not blocked) for its transaction, so the chain has
no forks. conninfo: a connection string ("postgresql://user@host/db") or an open psycopg connection in autocommit
mode (the store runs its own BEGIN / COMMIT).
DuckDBStorage ¶
Bases: _SQLStorage
DuckDB (pip install solvi[duckdb]): the tables of SQLiteStorage in a DuckDB file (":memory:" for none) — for
analytics over the stored decisions next to JSONL or Parquet files (store.db.sql(...)). One writing process at a
time (DuckDB's own rule); threads of that process are fine.
check_source ¶
A label's source → itself, when it is trusted: "human", "outcome", "rule" or "audit" (a person's or an
outcome's label of a decision drawn at random for it; the store checks the decision was) — or "verified" when the channel
lists it in accept (only System.guarantee(..., sources=) does: see VERIFIED); else UntrustedLabel, with the
measured reason when a channel (channel, a key of VERIFIED_REFUSED) refuses a verified label.
record_body ¶
What a record's hash is taken over. Format 1 (solvi ≤ 0.7.1): the record without id and hash. Format 2: the
fields that stay for ever (KEPT), the digest of its answers and the digest of everything else (its content: the
response, the input, the meta) — three parts, so that redact can remove the content, or the answers too, leave their
digests in the record's mark, and the hash still recomputes: what is left of a redacted record is verified like any
other record, and a record cannot be passed off as redacted with other answers.
record_hash ¶
The hash of a stored record: SHA-256 of the canonical JSON of its body (record_body; it covers prev).
plain ¶
A value as stored: JSON data (sets sorted as vhash sorts them, dates as ISO strings, "not stated" as "
record_mode ¶
A store's record= → ("full", None), ("compact", None) or ("sample", N); ValueError for anything else.
compact_content ¶
A response's dict (Response.to_dict()) → what a compact record keeps of it (see TraceStorage, record="compact"):
the given facts (the input as read, with the types that restore it), each answer with its why / guard / source /
evidence / guarantee (not its probabilities), each check's result and reasons, the model-backed steps and the
answer heads, guarantees, plan, text and then records whole (with the models' ids, fingerprints and token usage), the
steps skipped, the catalog's and questions' fingerprints, and the time. Left out: the values of the computed facts
(they are re-computed), the other steps' records (their hashes stay in the record's records), the planned flow,
the timings and the per-part fingerprints.
entry ¶
The stored content of a response (without seq, time, prev, hash). record: "full" (the whole response) or "compact" (compact_content: the input, answers, checks and model steps — see TraceStorage).
run_context ¶
Within it, every record solvi writes to a store (decisions, corrections, knowledge, dispatch and change records —
JSONLStorage and the SQL stores, any of them) carries "run": {"id": run, "parent": parent} — hashed into the chain
like the rest — so the records of one run, written to several stores, can be put in one order (chronology).
run: the run's id (default: inherited from an enclosing run_context, else a new random one); give the same id to
the other processes of a run. parent: the id of the decision the records inside follow from (a nested
with run_context(parent=decision_id): keeps the run id). → an object with .id and .parent. Opt-in: outside a
run_context nothing is added, and readers take records without "run" as before. A store of your own sees the field
when its _append writes the body it is given. store.query(run=id) finds the decisions of one run. The run lives in
a context variable: a thread started inside does not inherit it — submit work to a pool as
pool.submit(contextvars.copy_context().run, fn, *args), or open run_context(run=id) in the thread.
chronology ¶
The records of several stores in one order → [{"store", "id", "seq", "time", "kind", "run", "parent"}] by time
(ties: the order the stores are given, then seq). stores: TraceStorage objects (or KnowledgeStore / anything with a
.storage that is one), or one dict {name: store} — "store" is then the name, else the position. run: only the
records of this run id; kinds: only these kinds. Records written outside a run_context have run None.
view ¶
A stored decision's response as a dict, for readers that do not need the whole trace (reports): the stored response, or for a compact record what it kept, shaped the same way ("results", "trace" with "init" and the kept "records", "ms", "safeguards"). None for a record without either (a redacted one).
chained ¶
Is this a record of the chain (a dict with its hash)? A JSON object without one — a line another tool appended to the file, a hand edit — is not: it is passed over by iter / query / replay_all, and verify reports it.
rederive ¶
A compact record (dict) → (Response or None, [Mismatch]): its decision rebuilt with system from the recorded
input. The flow is planned again for the recorded questions and run; a model-backed step whose model is not re-run
on replay (trust_models=True, a generator, a model not available) gives its kept output instead of calling the
model (a compact record keeps every model step whole), and a model step that is re-run and gives the kept output
takes the kept record (its latency and usage); then every step's hash is chained again and compared with the
recorded one — a hash covers the step's inputs, value, error and the link to the step before, so equal hashes mean
the step gave what it gave then — and the kept records after the flow (answer heads, guarantees, plan, text, then) are
appended. The Response is the decision as it was: replay it like a stored one. None, with the reasons, when it
cannot be rebuilt: a step whose hash differs (kind "recompute": the catalog changed since — the old value is not
kept, only its hash), a kept model output that does not give its record again or a model step of several producers
that is not re-run (kind "not_kept": no verdict past it), the input not restored.
open_storage ¶
A TraceStorage from a path: .db / .sqlite / .sqlite3 → SQLiteStorage, .duckdb → DuckDBStorage (in any case), a postgresql:// (or postgres://) URL → PostgresStorage, anything else → JSONLStorage; a TraceStorage is returned as it is.