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
¶
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)
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)
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
replay ¶
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 ¶
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 ¶
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 ¶
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 ¶
repr with sets in vhash's fixed order (repr(set) depends on PYTHONHASHSEED): for text that is stored, e.g. why.
mismatch_summary ¶
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 ¶
The hash at the end of a response's trace (its last record's; the input's hash when nothing ran).
replay_guard ¶
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 ¶
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 ¶
A fact's producer group narrowed to the producers that ran (replay of a plan that dropped the others).
run_sync ¶
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 ¶
A part's output: awaited when it is an awaitable (an async def part called from sync code).
is_async_func ¶
Is f an async def function (or an object with an async call, or a wrapper of one)?
async_parts ¶
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 ¶
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 ¶
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.