Skip to content

solvi.core.runtime

Flow execution and replay: Trace, Record, Result, Replay, MISSING, the hash chain of the steps.

Flow execution: computed_state with provenance and a hash chain, answers, hard checks, independent replay.

Step dataclass

Step(part: object, reasons: list = list())

One step of a flow: the part and why the strategist took it.

Flow dataclass

Flow(steps: list, per_question: dict, skipped: dict, unresolved: dict, types: dict = dict(), batches: list = list(), answer_stages: list = list())

The parts a request runs, in order (solvi.core.plan.strategist.plan builds it).

Mismatch

Bases: tuple

One replay mismatch: the triple (step, name, reason), as replay has always returned it, plus .kind:

integrity      the hash chain, a record's hash, the input's hash or a recorded input hash does not verify: the data
               was changed after the run
recompute      a step does not give the recorded value: its code, a declaration or what it reads changed
model_changed  the step's model has another fingerprint than the recorded one
missing_part   the part (or a producer) is no longer in the catalog: renamed or removed
missing_input  a part now reads an input the trace does not hold
flow           a planned step is not in the trace
answer         a stored answer is not the one the trace gives under the same questions and catalog: the answer
               was changed after the run (replay with the System; a bare Catalog cannot check answers)
not_restored   a hash or a step does not verify because a value it rests on did not come back from storage as it
               was: its type is neither one the dump restores (date, Decimal, set, ...) nor declared (an untyped
               enum or object; an untyped date in a record stored by solvi ≤ 0.7.1) — no verdict on the data
not_kept       a compact record (TraceStorage(record="compact")) does not keep what checking this step needs: a
               model step that is not re-run on replay — no verdict on the data past the record's chain
error          the replay itself failed (the record could not be loaded, or replay raised): no verdict on the data
other_system   the record answers no question of the System(s) replay_all was given: another system's record,
               or one whose questions were edited — not an integrity verdict (its record hash and, for a full
               record, its trace's hashes are still checked; verify() checks the chain)

It compares, unpacks and serializes as the plain triple.

Record dataclass

Record(step: int, kind: str, name: str, inputs: dict, value: Any, quote: tuple | None = None, confidence: float = 1.0, error: str | None = None, prev: str = '', hash: str = '', producer: str | None = None, tried: list | None = None, provenance: str | None = None, model: dict | None = None, probs: dict | None = None, extra: dict | None = None, tried_models: dict | None = None)

Bases: Serial

origin property

origin

The provenance kind of this record's value.

body

body(h=vhash)

What the record's hash is taken over. h: the hash of a value (vhash; the executor passes its memo, so a value already hashed in this run is not hashed again).

Result dataclass

Result(answer: Any, confidence: float, why: str, status: str = 'ok', probs: dict = dict(), provenance: str | None = None, source: str | None = None, guard: str | None = None, repaired: tuple | None = None, kind: str | None = None, evidence: list = list(), extra: dict | None = None)

Bases: Serial

not_stated property

not_stated

Is the answer "the text does not state it" (solvi.Unknown)? — a real answer, unlike an abstention.

span property

span

A span answer's Quote (text, start, end, source), else None.

interval property

interval

An estimate's interval (lo, hi) holding coverage of the probability, else None.

scores property

scores

A ranking's score per option, else None.

Trace dataclass

Trace(init_hash: str, records: list, init: dict, skipped: list = list(), schedule: list = list(), timings: dict = dict(), rejected: list = list(), fingerprint: dict = dict(), early_exit: bool = True)

Bases: Serial

explain_order

explain_order()

The learned schedule as text: which hard check ran first and why.

replay

replay(catalog, flow=None, trust_models=False)

Independent replay: recompute every step from its recorded inputs, verify the value, the quote, the error and the hash chain, and that the chain starts from the hash of the recorded input. With flow (res.flow) it also checks the trace is complete: every planned step is either recorded or listed as skipped at run time.

Model-backed steps (a part with model=, a learned rule, an answer head): the recorded model fingerprint is compared with the catalog's current model — a difference is a mismatch ("model changed since this decision"). If the model is the same and deterministic, the step is re-run and compared like any other. With trust_models=True, or when the model is not available (no model on the part, model.available is False, no head), the model is not re-run: the recorded output is verified instead — a quote must be literally at its offsets, a decision among its options. Pass the System instead of the catalog to verify answer-head records too (else they are reported as unavailable).

→ {"ok", "steps", "mismatches": [(step, name, reason)], "models": [(step, name, verdict)], "catalog"} with verdicts "recomputed", "trusted", "unavailable" or "changed". "catalog": "same", "changed" (with "changed_parts": the parts of this trace whose code or declarations differ from when it was recorded) or "unrecorded" — for information: a changed part that still re-computes the recorded values is not a mismatch. Each mismatch is a Mismatch: the triple, with .kind (see Mismatch). When there are mismatches the result also has "kinds": {kind: count} and "summary": one line that tells damaged data ("data damaged: ...") from a catalog or a model that changed since ("data intact, catalog changed", "data intact, model changed", ...). A part that is no longer in the catalog (renamed or removed) is a mismatch of kind missing_part, not an exception; the steps after it are still checked. Limits: a trace rebuilt honestly from a different input is internally consistent — compare init_hash with a receipt you published elsewhere to catch that.

HashMemo

HashMemo(init_state=None, seed=None)

Bases: dict

vhash of the values of one run, by object: a value read by several steps — and then recorded, and hashed as part of the input — is canonicalised and hashed once (each entry keeps its value alive, so an id is not reused within the run). The hashes are vhash's own, byte for byte. seed: a HashSeed of values hashed before the run (the same objects asked again and again, e.g. by solvi.core.slow.search): a value found there is not hashed again.

init_hash

init_hash()

vhash(init_state), with each given value canonicalised and written as JSON once: its own hash (what the steps that read it record) is taken from the same text, and the input's JSON is put together from the values' texts — byte for byte what json.dumps writes for the whole canonical dict (sorted keys, ", " and ": ").

HashSeed

Bases: dict

Values hashed once for many runs: id → (value, hash, canonical JSON text). For values that the runs read as the same objects and that nothing changes in place (a given text asked with every candidate of a search, a fact held at its value) — a value changed in place after it was added keeps its old hash. A catalog carrying one (catalog._hash_seed) lends it to every run of its flows.

PartTimeout

Bases: Exception

A part did not finish within its timeout (aask): the step fails with this reason, like any other error.

scalar_row

scalar_row(values, keys=None)

Cheap features from a dict of facts: numbers, booleans and short strings as they are; a long string gives its length; a list / tuple / dict gives its length. Anything else is left out.

srepr

srepr(v)

repr with sets in vhash's fixed order (repr(set) depends on PYTHONHASHSEED): for text that is stored, e.g. why.

mismatch_summary

mismatch_summary(mismatches, catalog=None)

Replay mismatches → {"kinds": {kind: count}, "summary": one line}. "data damaged" when anything of kind integrity; else what the mismatches say about a trace whose data is intact: the catalog changed (parts missing, new inputs), the model changed, steps do not recompute, or the replay itself failed. catalog: the replay's catalog verdict.

trace_hash

trace_hash(resp)

The hash at the end of a response's trace (its last record's; the input's hash when nothing ran).

replay_guard

replay_guard(r, system, vals)

A recorded guard verdict (kind "guard", solvi.core.guarantees.guarantee): its inputs must be the recorded facts, the verdict must follow from the recorded signal and threshold, and with the System its guarantee must be the one the question has now.

replay_plan

replay_plan(r, catalog, init_keys)

Re-verify a plan record (kind "plan", solvi.core.plan.cost) against the catalog: every chosen producer exists and provides its fact, and its inputs are given or chosen facts → [(step, name, reason)].

narrowed

narrowed(group, tried)

A fact's producer group narrowed to the producers that ran (replay of a plan that dropped the others).

run_sync

run_sync(aw)

Wait for an awaitable from sync code (an async def part called by ask, a replay, facts_for): in a new event loop — on a worker thread when this thread already runs one (ask called from async code).

resolved

resolved(v)

A part's output: awaited when it is an awaitable (an async def part called from sync code).

is_async_func

is_async_func(f)

Is f an async def function (or an object with an async call, or a wrapper of one)?

async_parts

async_parts(catalog)

The parts (producers, rules) of a catalog that aask awaits: async def functions and parts marked blocking=True.

execute

execute(catalog, flow, init_state, workers=1, early_exit=True, order=None, costs=None, policy=None, known=None, hashes=True, memo=None, context=None)

Run the flow. Hard checks and what they depend on run first; a failed hard check settles the questions whose flow contains it, and the steps only those questions needed are skipped (early exit). Steps that do not depend on each other run in parallel when workers > 1 (threads: suits I/O-bound parts such as API calls and model inference). Records are always written in flow order, so the hash chain and replay do not depend on scheduling. An async def part is awaited in an event loop of its own (aexecute runs such catalogs concurrently).

order: None — all hard checks (and their inputs) first, together. An object with p_fail(check, row) and row(vals, init_keys) (solvi.core.plan.strategist.OrderModel, or an oracle) — hard checks one at a time, most expected saving first, stopping as soon as the failed ones settle every question they govern; answers are the same as with the default order. costs: a CostBook (ms per part) for the learned order and the producer policy. policy: a ProducerPolicy for facts with alternative producers (without one they are tried in declaration order). known: given fact → the type its value was already validated against (System(input_model=...)), so typed parts reading it with that type skip re-validation. early_exit=False: every step of the flow runs, whatever the hard checks say (the answers are the same: a failed hard check still decides); the trace records it (trace.early_exit). hashes=False: a lean run — the same steps, values and records, but nothing is hashed (no input hashes, no record hashes, an empty init hash): for answers that are never stored or replayed (the candidates of solvi.core.slow.search); such a trace does not replay. memo: a HashMemo of this very init_state whose init_hash() was taken already (System(cache=) hashes the input for its key): reused.

aexecute async

aexecute(catalog, flow, init_state, early_exit=True, order=None, costs=None, policy=None, known=None, timeout=None, speculate=False, context=None)

execute, on an event loop: async def parts are awaited, parts marked blocking run in worker threads, plain sync parts inline; steps whose inputs are ready run concurrently. timeout: seconds per call of a part without its own timeout= (None: no limit) — a step that does not finish in time fails with "timed out after ... s". speculate=False: the phases of execute (hard checks and their inputs first, then what the open questions need), so no step starts that execute would not run. speculate=True (default order only): every step starts as soon as its inputs are ready; a failed hard check cancels the pending steps that only the questions it settles needed, and steps that finished anyway are dropped. Either way the records, values and hashes are those of execute (a timeout aside).

path_confidence

path_confidence(catalog, trace, facts, cache=None)

A fact's confidence is the minimum confidence of the extractions it depends on. A fact with alternative producers depends on what the producer that was used reads (the record's producer), not on the inputs of producers that did not give the value. cache: a dict the caller keeps for one trace (the answers of one ask), so the questions share the walk; a walk that met a ring of facts (net ⇄ gross: its values depend on where it started) is not kept.

plan_batches

plan_batches(steps)

The strategist's grouping: decision parts in a flow that read the same facts with the same model, when the model can answer several questions in one forward pass → [[step name]] (chunks of at most the checkpoint's max_questions). Moved here from solvi.core.deciders in 1.0 (solvi.core.deciders re-exports it): the part says whether and with what it batches (DecisionPart._batch_group), so the planner does not import the deciders.