solvi.experimental.process¶
A process of several solvi systems (stages 0 to 4 of solvi.Process): nodes, edges with predicates written as data,
merges, loops with a mandatory max_iter and the declared process promise, as a JSON spec with a hash, a structural
diff and a drawing; run / explain through the node runners (DecisionNode, SystemNode, GuardNode), one run
chained across the node stores and a "process" index record; questions to a person through a queue — the abstract
HumanChannel (check your own with check_human_channel), the built-ins MemoryQueue and
CallbackChannel, HumanRequest / HumanAnswer, a node of kind "human" and the hand-off, pending / resume /
cancel with each segment of a run a "process" record and each answer a "human" record; replay / replay_all
of a run from its records across its segments, a person's answer a leaf recorded and not recomputed, the first
divergence named by node and step; the path promise — guarantee() in the modes union (split "equal",
{node: r_i} or a function, Σ r_i ≤ r, each node's own promise at its share, loops counted), per_node ("the end
error is not bounded") and end_to_end (calibrate on end-labelled runs, learn then test over a ThresholdFamily:
the built-ins SharedRank — "shared_rank", the default — and PerNodeFixed — "per_node_fixed" —, or your own;
the threshold applied at run time and re-checked by replay), ProcessResult.automatic / risk, and PathWatch on
the mix of paths (monitor) (see
experimental).
Process.node(..., input_contracts=..., output_contracts=...) optionally declares
versioned boundaries for facts named in reads/writes. Each mapping value is
{"version": "quote/1", "schema": {...}, "invariants": [...]}. Versions are opaque
nonempty strings compared exactly. Declarations are copied and included in the
process spec/hash; normal strict System fingerprint checks still apply.
Schemas support an explicit type at every level: object, array, string, number,
integer, boolean or null. Supported keywords are enum; object properties,
required, boolean additionalProperties; array items, minItems, maxItems;
string minLength, maxLength; numeric minimum, maximum. Unsupported keywords
and incompatible keyword/type combinations are rejected. This is a bounded subset,
not a full JSON Schema implementation. Payloads are finite JSON with string object
keys, without coercion; booleans are not numbers. Nesting is limited to 32 levels.
enum uses canonical JSON representation equality recursively: object key order
does not matter, while true, 1 and 1.0 are distinct, including inside arrays
and objects. This stricter numeric equality is part of this subset's semantics.
Object payload invariants use the existing predicate forms answer with one of
eq/in/lt/gt, combined by and/or/not; answer names a payload field.
No arbitrary callbacks or runtime metadata predicates are accepted. An absent
field satisfies no comparison. Schema validation precedes invariants.
Output validation runs before the produced facts are published. Input validation
checks the exact producer version, schema and invariants before invoking the
consumer. Failures raise ProcessRunError; the producer may already have run and
saved its decision. Unversioned initial facts cannot satisfy an opted-in input
contract. Nodes without these declarations retain their existing behavior. Run
and replay use the same boundary checks; no compatibility negotiation is implied.
A process of several solvi systems (experimental, stages 0 to 4): the nodes, the edges with predicates written as data, merges, loops with a mandatory iteration limit and the declared promise — a JSON specification with a hash, a structural diff and a drawing (stage 0) — and running it: each node's decision in its own store, chained into one run, with an index record of the path (stage 1a), and questions put to a person through a queue, a run waiting for the answer and going on when it comes (stage 1b) — replaying a run from its records (stage 2) — and the path promise in the modes union and per_node, with a watch on the mix of paths (stage 3), and end_to_end, calibrated on end-labelled runs over a threshold family (stage 4). Retraction comes in a later stage.
from solvi.experimental.process import Process, MemoryQueue
queue = MemoryQueue() # or your own: class MyChannel(HumanChannel): ...
p = Process("claim", storage="st/process.jsonl", human=queue)
p.node("triage", triage, reads=["claim"], writes={"kind": "answer"}) # triage = solvi.build(...)
p.node("fraud", fraud, reads=["claim", "kind"], writes={"fraud_risk": "answer"})
p.node("payout", payout, reads=["claim", "kind", "fraud_risk"], writes={"payout": "answer"}, end=True)
p.node("review", kind="human", question="fraud_risk", writes={"fraud_risk": "answer"})
p.edge("triage", "fraud", when={"answer": "kind", "in": ["auto", "property"]})
p.edge("triage", "payout", when={"answer": "kind", "eq": "glass"})
p.edge("fraud", "payout", when={"status": "ok"})
p.edge("fraud", "review", when={"status": "abstain"}); p.edge("review", "payout")
p.edge("fraud", "triage", when={"drift": True}, loop=True, max_iter=2) # a cycle without max_iter: ValueError
p.promise(mode="union", risk=0.05) # split="equal": r / Σ m_i per node
spec = p.spec() # a JSON-ready dict; spec["hash"]: SHA-256 of its canonical JSON without "hash"
canonical(spec) # the canonical JSON text (sort_keys, compact separators, as docs/trace_spec.md §1)
q = Process.from_spec(spec, systems={"triage": triage, "fraud": fraud, "payout": payout})
p.diff(q) # [] — or one entry per change: {"path", "change", "before", "after", "say"}
p.render("mermaid") # or "text"
r = p.run({"claim": claim}) # ProcessResult: status ("decided" | "abstain" | "pending" | "cancelled"),
# answer, path, nodes, facts, provenance, run, stored_id, ticket (pending),
# node and question (the node that holds the waiting question)
queue.answer(r.ticket, "low", reviewer="anna") # the built-in queue; your channel answers its own way
p.pending() # the waiting questions: [{run, node, ticket, question, asked_at, stored_id}]
r2 = p.resume(r.run) # polls the channel: an answer → the run goes on (a new segment), else pending
print(p.explain(r2)) # the path in words: who answered at each node, which edge was taken
chronology(stores, run=r.run) # solvi.core.store.chronology: the node decisions and the records, in order
The format ("solvi_process": "1.0"). A node has a kind ∈ {decision, system, guard, human}: a solvi.build result,
a bare System, a Guard, or a question put to a person; reads (the facts it reads), writes ({fact: what of the
node's result}: "answer", "answer:question, the system's fingerprint,
optionally its store and its own promise record. An edge is {"from", "to", "when"} (when null: always), and
{"loop": true, "max_iter": n} on an edge that goes back: every cycle of the graph has to pass through such an edge, so
a process cannot cycle without a limit. merge says per node whether it waits for all its inputs or any; start is the
one node without an incoming edge (or the one given); end lists the nodes marked end=True. promise is the declared
process promise (mode, risk, split, family, delta; the thresholds and the calibration are null until a later stage
calibrates them). Keys are sorted when hashed, so the hash does not depend on the order of keys; the order of edges is
kept (it is the order in which they are tried) and is part of the hash.
The predicate language is closed and is data, not Python: {"answer": fact, "eq" | "in" | "lt" | "gt": value} (a fact
written upstream or given), {"status": "ok" | "abstain" | "forced" | "human"}, {"by": "s1" | "s2" | "human"},
{"confidence_below": c} (holds for a decision that went to a person, which has no confidence to compare),
{"budget_over": bool}, {"drift": bool}, {"and": [p, ...]}, {"or": [p, ...]}, {"not": p}.
check_predicate validates one, holds(when, outcome) evaluates it on an outcome {"facts", "status", "by",
"confidence", "budget_over", "drift"}, describe says it in words.
from_spec checks the hash and the format's major version, and the fingerprint of every system it is given against
the recorded one: a different system is an error (ProcessSpecError), or with strict=False is loaded and listed in
p.mismatched ({node: {"recorded", "actual"}}; the spec then carries the actual fingerprint). A node given no system
stays unbound (p.unbound): its spec is kept as recorded, so a process can be diffed and drawn without its systems.
A system's fingerprint: System.fingerprint() for a System; that and Dispatcher.config() for a solvi.build result;
the tools and the code of the policies for a Guard (stage 0: the adapters of stage 1 may refine it); an object with its
own fingerprint() otherwise (a Guard's is Guard.fingerprint()).
Running (stage 1a). run(facts) starts at the start node and follows one path: a node is given the facts it reads
(plain values: what the caller gave and what upstream nodes wrote — a fact not yet written is left out), its decision
is made by its own system and stored in its own store, and the first edge out of it whose predicate holds on its outcome
(in the order the edges were added; a loop edge until it has been taken max_iter times) leads to the next node. A node
is run through a NodeRunner — DecisionNode (a solvi.build result: ask → Dispatched, a "dispatch" record), SystemNode
(a System: ask → Response, an "ask" record), GuardNode (a Guard: call(facts["call"], context=facts["context"],
facts=the rest) → GuardDecision; an escalation has status "human") — so the decisions are exactly the ones calling the
systems by hand in the same order makes. Every fact a node writes carries a provenance label {"from": node, "decision":
stored_id, "by", "confidence", "trace_hash"} (result.provenance); a node that reads the fact "provenance" is given the
labels of the facts it reads as that given fact, and is otherwise given plain values only. Shared facts go through a
solvi.Knowledge the systems were built with (build(knowledge=)); the process passes nothing through it, and records the
hash of the snapshot a node was given. The run opens run_context(run=id) and each node runs inside
run_context(parent=the previous node's stored id), so its record carries the run and the decision it follows from, and
chronology(stores, run=id) puts the run in order without the process. With storage= the process appends one record of
kind "process" to its own store: {"process", "spec_hash", "input_hash", "mode", "promise", "path": [{node, kind, store,
stored_id, trace_hash, by, status, answers_hash, facts_in_hash, facts_out_hash, knowledge, cost, edge: {to, when,
loop}}], "outcome": {status, at, answer_hash}} — an index of hashes and ids; the decisions are in the node stores.
The run ends "decided" at an end node that answered, or "abstain" where it stopped (why). A node that abstains, or
whose decision goes to a person, with no edge for it: on_abstain / on_human = "abstain" stops the run there;
"handoff" (the default) puts the node's question to a person. A node that merges "all" of several inputs is refused
at spec() — waiting for several branches is not implemented at this stage (a recorded spec of an earlier release
still loads, and refuses at run time). Not yet: retract.
The channel to a person (stage 1b) is a queue: the process does not know when the person answers. HumanChannel is an
abstract class — submit(HumanRequest) → ticket, poll(ticket) → HumanAnswer | None, cancel(ticket, why),
fingerprint() — that you subclass with your own way to ask (check it with
check_human_channel in this module); built in: MemoryQueue (queue.answer(ticket, value, reviewer=),
queue.open()) and CallbackChannel(fn) (fn(request) → HumanAnswer or None, called at submit and at each poll). A
question is put by a node of kind "human" (an edge to it is an explicit hand-over; it is given the facts it reads, or
every fact when it reads none) or by the hand-off of a node. The process submits it and polls once: an answer is
recorded and the run goes on; none → the run ends "pending" with its ticket, as a "process" record (a segment) with
status "pending", the ticket, the channel's fingerprint, the request, and what the run needs to go on (the facts, their
labels, the loop counts — the one record that holds fact values). p.pending() lists the waiting questions;
p.resume(run) polls again: no answer → "pending" (nothing written); an answer → a record of kind "human" in the
process store ({ticket, node, question, reason, value, declined, reviewer, note, verified, asked_at, answered_at,
request_hash, channel}, run parent: the pending segment) and the run goes on from the node that asked as a new segment
("continues": the pending segment's id); a process loaded afresh from the same spec and stores resumes it. The person's
answer is the node's answer: its writes take the value, its outcome is status "ok", by "human" (so an edge for "ok"
holds, {"by": "human"} tells it apart), and the facts carry the label {"from", "decision": the human record,
"by": "human", "reviewer"}. One ticket, one answer: an answer already recorded stands (a run that broke after
recording it resumes from it). HumanAnswer(declined=True) — the person or the channel's own deadline gives no
answer — stops the run "abstain"; p.cancel(run, why) withdraws the question (the channel's cancel, a "human" record
{cancelled, why}, a segment "cancelled"). Process(user_verifier=fn(answer, request) → identity) binds an answer to
who gave it (answer.token is checked, not recorded). A run that asks a person needs storage=.
Replay (stage 2). p.replay(run) re-checks one run from the records alone → {"ok", "run", "status", "segments",
"steps", "at", "kind", "reason", "unchecked"} (+ "pending": ticket, + "cancelled": ticket). It walks the segments by
continues and each recorded path as run walks it, each node's result loaded from its store instead of asked:
"record" (the record intact in its store, of this run, after the decision before it, agreeing with the step),
"trace_hash", "replay" (the decision re-checked by its own means: Dispatcher.replay, Trace.replay, Guard.replay),
"facts" (the facts given are those the recorded answers upstream and the input give, in the step and in the node's
own record), "edge" (the first edge that holds on the recorded answers is the recorded one), "promise" (the
calibrated end_to_end rule recomputed on the node's recorded confidence). A person's answer is a leaf, "recorded, not recomputed": its "human" record must
be intact, follow from the pending segment, be the ticket's only answer, come through the same channel and answer the
request asked. "at" is the first divergence {"node", "step", "segment", "position"}; "kind" is "integrity" (records
disagree), "recompute" (a decision does not recompute, or the spec changed) or "missing_part" (a node without its
system or store). A pending run replays up to its question: {"ok": True, "pending": ticket}. p.replay_all() replays
every run and verify()s every store it reads. What the records do not keep is listed in "unchecked" (a guard's tool
result is stored as its hash).
The path promise (stage 3). p.guarantee() says what the declared promise gives → {"mode", "risk", "in_force",
"bound", "statement", "assumptions", "nodes", "problems", "warnings", "delta"}; each run that ends carries
automatic (decided with no person's answer on its path) and risk (the process risk while the union promise is in
force, else None), and explain ends with the promise. A run ends automatically when an end node answered and no
person answered on its path; E is "it ends automatically and its end answer is wrong". mode "union" (the default):
P(E) ≤ Σ_i r_i·m_i ≤ risk, summed over every automatic node of the graph (not over the path a run took), m_i an upper
bound on the times node i can run in one process run (1 plus the max_iter of each loop edge that can bring a run back
to it). split="equal" gives r_i = risk / Σ_j m_j — the risk split equally over the runs the nodes can make, so
Σ r_i·m_i = risk by construction and an equal split is in force on a process with a loop too; {node: r_i} or
callable(spec) → {node: r_i} gives your own (e.g. by the cost of a node's error), with Σ r_i ≤ risk checked when the
spec is made. Why it holds: if the end is wrong, the
first wrong node of the path was given right inputs, so it is wrong on its own question, and it answered alone (else
the end is not automatic); E lies in the union of "node i answered alone and was wrong", each of probability ≤ r_i·m_i.
No independence between nodes is assumed (correlated errors make the bound looser, not wrong). It is in force when
every automatic node keeps a promise at its share — its own CRC risk ≤ r_i (node(promise=), else the dispatcher's
calibrated policy, else System 1's guarantee: build(max_risk=r_i)); an LTT node counts at its error level and the
promise then holds with probability ≥ 1 − Σ δ_i (Bonferroni, a warning) —, Σ r_i·m_i ≤ risk (an equal split meets it
exactly; a given split can be pushed over by a loop), no node was loaded against another fingerprint (strict=False),
and the path watch has not flagged. It
assumes (A2) that each node was calibrated on what reaches it in the process — in place, on upstream's answers with
their errors and the routing of the edges; a node calibrated on clean inputs breaks it. mode "per_node": each node
keeps its own promise, and the statement says the end error is not bounded.
The end_to_end promise (stage 4). The process is one decider with thresholds on its nodes' signals (their
confidence): p.promise(mode="end_to_end", risk=r, delta=δ, family=..., examples=[(input, end_label)]) then
p.calibrate() (or calibrate(examples)). It promises P(a run ends automatically and its end answer is wrong) ≤ r with
probability ≥ 1 − δ over the n end-labelled runs. The loss is not monotone in a threshold vector in general (routing),
so the calibration is learn then test (a binomial test per threshold of a finite grid), not CRC. Each example runs
once with no threshold (each node asked, its decision stored; no person asked: a node that does not answer alone makes
the example not automatic); the loss at a threshold t is recomputed from the recorded signals, as a node held back
by t goes to a person and the run is not automatic. The family is the user's choice (ThresholdFamily: grid(spec,
signals), automatic(node, signal, t), fingerprint(), procedure "bonferroni" | "fixed"); built in: "shared_rank" (the
default — one rank threshold shared by every node, 64 values, Bonferroni) and "per_node_fixed" (a rank threshold per
node, nodes opened one at a time in the declared order, by default from the end back to the start, as a fixed
sequence). A family of your own is valid when its grid and order did not look at the labels. The chosen threshold
and what it was calibrated on (n, the examples' hash, the process's hash without its promise, the family's
fingerprint) are kept in the promise (thresholds, calibrated_on). At run time a node that answered alone with a
signal t does not let through is turned into "a person decides" (status "human", by "human", its question handed
over as when its own guard does it), and each step of a decision node records {"signal", "automatic"} (+ "held");
replay step 6 recomputes it. guarantee() is in force when calibrated, the process (spec, nodes' fingerprints) and the
family are the ones it was calibrated with, and the path watch has not flagged; it assumes (A3) that the
end-labelled runs are exchangeable with the stream (with noisy end labels the promise is about the noisy label).
Nothing certified: every node's answer goes to a person.
PathWatch watches the mix of paths: p.monitor(PathWatch(alpha=, horizon=), reference=runs of the calibration
stream); every run that ends is observed (result.path_drift: {"drift", "why", "edge", "S", "h", "seen"}). Each
edge's share of runs is followed by two Bernoulli CUSUMs (its odds up and down by odds), h simulated by resampling
the reference runs with the reference's own error, so an unchanged mix is flagged within horizon runs with chance
at most alpha. A flag is latched until watch.reset() and puts the union promise out of force.
ProcessSpecError ¶
Bases: ValueError
A process specification that is not valid (the message names the place), or one whose systems, channel or hash are not the recorded ones.
NodeResult
dataclass
¶
NodeResult(answer: Any, answers: dict, by: str, status: str, confidence: float | None = None, stored_id: str | None = None, trace_hash: str | None = None, cost: dict | None = None, drift: bool = False, budget_over: bool = False, raw: Any = None, store: Any = None)
What one node decided. answer: its main answer (the node's question's; for a System without one question, the
dict of its answers; for a Guard, the outcome allow / deny / escalate); answers: {question: answer} ("answer:"
writes read them; a Guard's are "verdict" and "result", the tool's return value); by: "s1" | "s2" | "human";
status: "ok" | "forced" | "abstain" | "human" (a person has to decide: a solvi.build result that sent it to a
person, a Guard that escalated); confidence: the answer's (None when the slow path or nobody answered);
stored_id / trace_hash: where the decision is in its store and the hash at the end of its trace; cost: {"s1",
"s2", "total"} as dicts (a solvi.build result) or None; drift, budget_over: the dispatcher's flags; raw: the
system's own result (a Dispatched, a Response or a GuardDecision); store: the TraceStorage it was written to.
value ¶
What a writes entry takes from this result: "answer", "answer:
ProcessRunError ¶
Bases: RuntimeError
A process that cannot go on: a node given no system, a node result that lacks what the node writes, a guard node without the fact "call".
NodeRunner ¶
The protocol of a node: run(facts) → NodeResult, where facts are the node's given facts ({name: plain value}, the
ones it reads); the decision is written to the system's own store (inside the process's run_context, so the record
carries the run and the decision it follows from). A runner of your own subclasses it (and sets kind);
runner_for picks the built-in one for a node.
DecisionNode ¶
Bases: NodeRunner
A solvi.build result (a DecisionSystem): ask(facts) → Dispatched; stored as a "dispatch" record.
SystemNode ¶
Bases: NodeRunner
A bare System: ask(facts) → Response; stored as an "ask" record when the System has storage. The main answer is the node's question's (question=, or the System's one question); without one, the dict of every answer.
GuardNode ¶
Bases: NodeRunner
A Guard: call(facts["call"], context=facts["context"], facts=the other facts) → GuardDecision (the tool runs when allowed, as Guard.call does); the answer is the outcome, status "human" for an escalation; answers "verdict" and "result" (the tool's return value).
HumanNode ¶
Bases: NodeRunner
A question put to a person: the process asks it through its HumanChannel (Process(human=)), so a human node has no runner of its own to call; run() says so.
ProcessResult
dataclass
¶
ProcessResult(status: str, answer: Any, path: list, nodes: dict, facts: dict, provenance: dict, run: str, stored_id: str | None = None, spec_hash: str | None = None, why: str | None = None, ticket: str | None = None, continues: str | None = None, automatic: bool | None = None, risk: float | None = None, path_drift: dict | None = None, node: str | None = None, question: str | None = None)
One run of a process (one segment of it). status: "decided" (an end node answered), "abstain" (it stopped
before an end node answered: why says where), "pending" (a question waits for a person: ticket; resume(run)
goes on), "cancelled" (the question was withdrawn: cancel(run, why)); answer: the end node's answer (None unless decided); path: the steps as recorded
([{node, kind, store, stored_id, trace_hash, by, status, answers_hash, facts_in_hash, facts_out_hash, knowledge,
cost, edge}]; a person's answer is a step of kind "human" with its "ticket" and "handoff") — a resumed run's path
is its whole run, the steps of its earlier segments first (S268), so explain() and monitor(reference=) see every
node and edge it took, as the live path watch does; nodes: {node: NodeResult} (the last result of each node on the
last segment); facts: every fact at the end; provenance:
{fact: {"from", "decision", "by", "confidence", "trace_hash"}} for the facts nodes wrote; run: the run id;
stored_id: the "process" record (None without storage=); spec_hash; why: why it stopped (abstain);
ticket: the question waiting for a person (status "pending"); continues: the pending segment this run goes on
from (a resumed run); automatic: decided with no person's answer on this segment's path (a resumed run starts
with the person's answer, so it is never automatic), None while pending; risk: the process risk the promise puts
on an automatic end when it is in force (Process.guarantee()), else None; path_drift: the path watch's report
(Process.monitor) when one watches the process; node: the node that holds the question (status "pending" and
"cancelled": the run waits there for the person), question: the question it asks — the two fields p.pending()
lists, without its store scan.
HumanRequest
dataclass
¶
HumanRequest(process: str, run: str, node: str, question: str, reason: str, facts: dict, provenance: dict = dict(), path: list = list(), answer: dict | None = None, deadline: float | None = None, asked_at: float | None = None)
A question put to a person. process, run, node: who asks; question: what (a human node's question, or the question of the node that handed its decision over); reason: "node" (a human node), "abstain" or "human" (a node that abstained or sent its decision to a person, on_abstain / on_human="handoff"); facts: what the node was given (plain values); provenance: the labels of those facts written upstream ({fact: {"from", "decision", "by", ...}}); path: the nodes run so far in this segment; answer: the answer type ({"kind", "options"}) when the node's system names one, else None; deadline: a hint for the channel (the library has no timeouts: a channel that gives up answers HumanAnswer(declined=True)); asked_at: seconds since the epoch.
HumanAnswer
dataclass
¶
HumanAnswer(value: Any, reviewer: str, note: str | None = None, at: float | None = None, token: Any = None, declined: bool = False, ticket: str | None = None)
A person's answer to one ticket: value (JSON data: what the node writes as its answer), reviewer (who answered: required), note, at (seconds since the epoch; default: when the process records it), token (a proof of who answered, checked by Process(user_verifier=); not recorded), declined=True: the person (or the channel, on its own deadline) gives no answer — the run stops "abstain" there. ticket: filled in by the process.
HumanChannel ¶
Bases: ABC
How a process asks a person — a queue: submit a question, get a ticket, poll the ticket later. Subclass it with your own way to ask (a ticket system, a review UI, a chat) and check it with check_human_channel(make) (in this module). The protocol:
submit(request: HumanRequest) → ticket (a non-empty string, new for every question) poll(ticket) → HumanAnswer, or None while there is no answer (KeyError for a ticket it never gave); once a ticket has an answer, every later poll gives the same answer (one ticket, one answer) cancel(ticket, why) → None: withdraw the question; a later poll gives None fingerprint() → str: the class and its configuration (recorded in the spec and in every record of a question; the same for two channels that ask the same way)
MemoryQueue ¶
Bases: HumanChannel
A queue in memory: questions wait until answer(ticket, value, reviewer=) (or decline(ticket, why));
open() lists the waiting requests. For tests, a CLI, a stand. Thread-safe; lost with the process that holds it
(the process store keeps every question and answer).
CallbackChannel ¶
Bases: HumanChannel
A function asks the person: fn(request) → a HumanAnswer, or None (no answer yet). submit calls it, and so does
every poll until it answers (a wrapper for manual input, a web hook, a synchronous review service). A plain value
instead of a HumanAnswer is an answer by reviewer (required then). The fingerprint is the function's code.
Process ¶
Process(name, storage=None, human=None, start=None, on_abstain='handoff', on_human='handoff', user_verifier=None)
A process of solvi systems (see the module docs). name: the process's name; storage: a path or a TraceStorage where each run's "process" record is appended (not part of the spec; None: no record, the node stores still hold every decision; a run that asks a person needs it); human: the channel to a person (a HumanChannel: MemoryQueue, CallbackChannel or your own; recorded in the spec by its fingerprint); start: the start node (default: the one node without an incoming edge); on_abstain, on_human: "handoff" (to the channel) or "abstain"; user_verifier: fn(answer: HumanAnswer, request: HumanRequest) → the verified identity of who answered (from answer.token), or None to refuse it (PermissionError; the identity must be the answer's reviewer), as Guard(user_verifier=).
participants ¶
Atomically add named Systems using their participate() declarations.
Mapping order determines outgoing edge priority. Existing graph validators still reject ambiguous entries, unreachable nodes and unbounded cycles. The declaration and compiled graph are frozen in spec/hash/replay.
node ¶
node(name, system=None, *, kind=None, reads=(), writes=None, question=None, end=False, merge=None, store=None, promise=None, fingerprint=None, input_contracts=None, output_contracts=None)
Add a node. system: a solvi.build result, a System or a Guard (kind inferred), or None for kind="human" (a
question put to a person: question= is required). reads: fact names; writes: {fact: "answer" | "answer:" |
"confidence" | "by" | "status"}; end: an end node; merge: "all" | "any" (for a node with several inputs);
store: where its decisions are stored (default: the system's storage path); promise: the node's own promise
record (Promise.record()); fingerprint: overrides the computed one. → self.
merge ¶
Say whether node waits for all its inputs ("all") or the first ("any"). "all" of several inputs is
refused at spec() (S272: waiting for several branches is not implemented — a spec that can never run is
refused where it is written); on a node with one input it is the same as "any". → self.
edge ¶
Add an edge src → dst taken when the predicate when holds on src's outcome (None: always). An edge that
goes back (closes a cycle) is loop=True with max_iter ≥ 1; a cycle without such an edge is a ProcessSpecError
(a ValueError). → self.
promise ¶
Declare the process promise (its configuration is recorded and checked; end_to_end is then calibrated by calibrate()). mode: "union" (risk r split over the automatic nodes: split="equal" — r / Σ m_i each, the risk shared equally over the runs the nodes can make —, {node: r_i} with Σ r_i ≤ r, or callable(spec) → {node: r_i}), "end_to_end" (risk, delta, examples=[(input, end_label)], family="shared_rank" (the default) | "per_node_fixed" | {"kind": "per_node_fixed", "order": [...]} | a ThresholdFamily object of your own) or "per_node" (each node keeps its own promise). → self.
spec ¶
The process as data (see the module docs), validated, with its "hash". → a JSON-ready dict.
from_spec
classmethod
¶
from_spec(spec, systems=None, human=None, storage=None, strict=True, user_verifier=None, family=None)
A process from its spec (a dict or JSON text). systems: {node: system} to bind (each checked against its
recorded fingerprint); human: the channel (checked likewise); storage, user_verifier: as Process() — a process
loaded with the store of the one that asked resumes its pending runs. strict=False loads a mismatch and lists it in
mismatched instead of raising. A node given no system is listed in unbound. family: the ThresholdFamily
object of an end_to_end promise with a family of your own (checked against its recorded fingerprint).
run ¶
Run the process once on the given facts ({name: value}) → ProcessResult (see the module docs). run: the run
id (default: the enclosing run_context's, else a new one). Every node's decision is written to its own store
inside run_context(run=..., parent=the previous node's stored id); with storage= the process writes one record
of kind "process" (the index of the path: hashes, ids, the edges taken) whose parent is the last node's
decision. A question put to a person that is not answered at once ends the run "pending" with its ticket:
resume(run) goes on when the person has answered.
calibrate ¶
Calibrate the end_to_end promise on end-labelled runs: examples [(input facts, end label)] (default: the ones given to promise(examples=)). Each example runs through the process once with no threshold — each node asked by its own system and its decision stored in its own store, under a run of its own; no "process" record; a node that does not answer alone (sends its decision to a person, or abstains) makes the example "not automatic" at every threshold and no person is asked. The family's grid is built from the signals the nodes gave (never from the labels); at each threshold t of it, the loss of an example is 1 when the run would end automatically (an end node answered and every node on its path answered alone with a signal the family lets through at t) and its end answer differs from the label. Learn then test: each t is the null "P(loss)
risk", rejected by a binomial test on the n examples — Bonferroni over the grid (procedure "bonferroni"; of the certified thresholds the one that lets most examples through) or a fixed sequence in the grid's order at the full delta, stopping at the first that fails (procedure "fixed"; the last certified one). Nothing certified: every node's answer goes to a person. The chosen threshold, the counts and what it was calibrated on (n, the examples' hash, the process without its promise, the family's fingerprint) go into the promise, so the spec's hash changes. → the promise's "thresholds" record.
pending ¶
The questions waiting for a person: the pending segments with no continuation → [{"run", "node", "ticket", "question", "asked_at", "stored_id"}] in the order they were asked.
resume ¶
Go on with a pending run (its id or its ProcessResult): poll the channel for the ticket; no answer yet → a ProcessResult "pending" again (nothing is written); an answer → it is recorded (kind "human", parent: the pending segment) and the run goes on from the node that asked, as a new segment ("continues": the pending segment's id) → its ProcessResult. A process loaded afresh from the same spec and stores resumes it.
cancel ¶
Withdraw a pending run's question (a retracted fact, the case closed): the channel's cancel, a "human" record {"cancelled": true, "why"} and a "process" segment with status "cancelled" → its ProcessResult.
guarantee ¶
What the declared promise says about this process now (stage 3) → {"mode", "risk", "in_force", "bound", "statement", "assumptions", "nodes", "problems", "warnings", "delta"}.
union: P(a run ends automatically and its end answer is wrong) ≤ Σ_i r_i·m_i ≤ risk — a union bound over every automatic node of the graph (not over the path a run took), m_i the most runs node i can make in one process run (1, plus each loop's max_iter that can bring the run back to it). It is in force when every automatic node keeps a promise at its share (a CRC risk ≤ r_i; an LTT node's error level ≤ r_i, with the process promise then holding with probability ≥ 1 − Σ δ_i, Bonferroni, and a warning), Σ r_i·m_i ≤ risk, no system was loaded against another fingerprint, and the path watch (monitor()) has not flagged. per_node: every node keeps its own promise, and the end error is not bounded. nodes: {node: {"r_i", "visits", "promise", "ok", "why"}}. end_to_end: the calibrated promise (see calibrate()): bound = risk with probability ≥ 1 − delta; in force when calibrated on this very process (its spec without the promise, the nodes' fingerprints) with this family, and the path watch has not flagged.
monitor ¶
Watch the mix of paths: watch is a PathWatch; reference: runs (ProcessResults, or lists of the edges each took) from the stream the nodes were calibrated on, to set its reference (else set it yourself). Every run that ends is then observed (result.path_drift); a flag puts the union promise out of force until watch.reset(). → self.
records ¶
The "process" records of this process's store → [Stored] (stage 1: the index of each run; read through the process's index over the store — see _index — not a scan per call).
explain ¶
A run in words: each node, who answered and how, the edge taken; then how the run ended.
replay ¶
Re-check one run (its id or its ProcessResult) from the records alone, across all its segments → {"ok",
"run", "status", "segments", "steps", "at", "kind", "reason", "unchecked"} (+ "pending": the ticket of a run
that waits for a person — ok True, replayed up to the question; + "cancelled": the withdrawn ticket). Each step
of the recorded path, in order: (1) "record": the node's record is in its store, intact (its hash and id), of
this run, after the decision before it, and says what the path says (who, status, answers, knowledge, cost);
(2) "trace_hash": the hash at the end of its trace is the recorded one; (3) "replay": the node's decision
re-checked by its own means (Dispatcher.replay, Trace.replay, Guard.replay; trust_models as there);
(4) "facts": the facts it was given are the ones the recorded answers upstream and the input give, in the path
and in its own record; (5) "edge": the first edge that holds on the recorded answers is the recorded one;
(6) "promise": the calibrated end_to_end rule recomputed on the node's recorded confidence. A person's answer is a leaf, recorded
and not recomputed ("human"): its "human" record is intact, in this run, after the pending segment that asked
(or the decision before it), the ticket's only answer, through the same channel, to the request asked; its
value is what the next facts carry. The segments are checked as a chain ("segment": continues, the same
spec and input, the pending segment's question and the facts it kept). "at": the first divergence {"node",
"step", "segment", "position"} (None when ok); "kind": "integrity" (the records disagree: data changed after
the run), "recompute" (a decision does not recompute: its system or the spec changed) or "missing_part" (a
node without its system or store). "steps": per checked step {"segment", "node", "kind", "stored_id",
"checked"} (+ "human": "recorded, not recomputed"). "unchecked": what the records do not let it check (a
guard's tool result is kept as a hash; an input fact no node read).
replay_all ¶
Replay every run in this process's store and verify() every store it reads → {"ok", "runs", "failed": [the reports of the runs that do not replay], "pending": [the run ids that wait for a person], "verify": {store: {"ok", "problems"}}} — ok when every run replays and every chain verifies (publish the process store's head() elsewhere to catch a rewrite of the whole store: verify(anchor=)).
shadow ¶
Compare complete native-System processes, serving this process's result.
Each side gets a private copy of the original input. Bindings, guards and journals must be disjoint; candidate human handoff is disabled. External callback/model effects are not sandboxed. See docs/process-shadow.md.
PathWatch ¶
A watch on the mix of paths of a process (stage 3): which edges the runs take. The union promise assumes each
node is calibrated on the stream that reaches it (A2); a shift in the share of runs that take an edge is a shift in
that stream. Each edge's share is followed by two Bernoulli CUSUMs (a rise and a fall of its odds by odds), the
reference shares from runs of the calibration stream, the threshold h simulated by resampling those runs (their
dependence kept: the edges out of a node exclude each other) with the reference's own sampling error, so that an
unchanged mix is flagged within horizon runs with chance at most alpha. A flag is latched until reset(); it puts
the union promise out of force (Process.guarantee()). What it reports is "the paths changed", not why.
watch = PathWatch(alpha=0.01, horizon=1000)
p.monitor(watch, reference=calibration_runs) # ProcessResults (or lists of edges) of the calibration stream
r = p.run(facts); r.path_drift # {"drift", "why", "edge", "S", "h", "seen"}
The same CUSUM as AuditWatch and DriftMonitor (solvi.core.guarantees.drift.Cusum).
canonical ¶
The canonical JSON text of a spec (or any JSON value): sort_keys, compact separators, UTF-8 as is.
spec_hash ¶
SHA-256 (64 hex digits) of the canonical JSON of a spec without its "hash" — and, a process spec, without the nodes' "store" paths (S271: moving a node's store to another directory does not change what the process is, so it does not change the hash either; rewriting the path in a recorded spec keeps its hash valid). Behaviour change over 1.4.0: hashes of specs whose nodes carry a store differ from the recorded ones.
check_predicate ¶
Validate the shared closed predicate language; None means always.
holds ¶
Whether predicate p holds for a node's outcome {"facts": {name: value}, "status", "by", "confidence", "budget_over", "drift"} (missing keys: None / False). A fact that is absent satisfies no comparison. {"confidence_below": c} holds for an outcome whose decision went to a person (status "human", by "human"): a hand-over has no confidence to compare, and the unsure answers are exactly what the predicate routes to one.
fingerprint_of ¶
What a node's system is, as JSON-ready data (see the module docs). kind: the node's kind when known.
runner_for ¶
The built-in NodeRunner of a node kind for its system (a NodeRunner given as the system is used as is).
diff ¶
The structural changes from spec a to spec b, by node and edge id: one entry per change {"path" (e.g. "nodes.fraud.fingerprint.system.parts.score", "edges.triage -> fraud.when", "promise.risk"), "change" ∈ {added, removed, changed, reordered}, "before", "after", "say" (in words)}. A node or an edge added or removed is one entry; a change inside one is named at the deepest key that differs. [] when the specs describe the same process.
render ¶
A spec drawn: "mermaid" (flowchart; a person's node as a hexagon, an end node with a double border, a loop edge dotted with its limit) or "text" (one line per node and per edge).
check_human_channel ¶
make: () → a fresh channel (a HumanChannel subclass); answer: (channel, ticket,
request) → the value the person answers, after making them answer it your channel's way (default: a MemoryQueue-
style channel.answer(ticket, value, reviewer=); a channel that answers by itself returns the value it will give).
Checks the protocol — fingerprint stable and equal for two channels made alike; a new non-empty ticket per
question; KeyError for a ticket never given; n questions answered, none lost, each poll after the answer gives the
same answer with a reviewer; a cancelled ticket polls None — then a process run through it: a question to a person
is pending (or answered at once), listed by pending(), resumed by a process loaded afresh from the same spec and
store, recorded as a "human" record (ticket, reviewer, the channel's fingerprint, parent: the pending segment), the
store verifies. → what was checked.
System participation declarations¶
A bare System can declare its role before it is assembled into a process:
triage.participate(writes={"kind": "answer"})
payout.participate(after="triage", when={"answer": "kind", "eq": "glass"}, end=True)
p = Process("claims", storage="process.jsonl").participants({"triage": triage, "payout": payout})
System.participate returns the System. after=None declares an entry; otherwise
after names exactly one predecessor. when uses the existing closed Process
predicate language and observes that predecessor's outcome. An entry cannot have
when or max_iter. reads, writes, question and end have the same meaning
as on Process.node. Node names belong to the process mapping, so one System's
declaration can be used in different processes with the same names.
max_iter=n marks the incoming edge as a loop with at most n traversals per
run. It is a positive integer (bool and float are refused). It is not a bound
on total System invocations. For example, a self-loop with max_iter=2 can run
its node three times: the initial entry plus two loop traversals. A graph with
such a loop still needs a reachable end node and may need an explicit
Process(start=...). Mapping order sets outgoing edge priority. Existing graph,
loop and merge validation applies; no unbounded cycle or multi-input scheduler
is introduced. For multiple predecessors or more involved routing use the
existing explicit node/edge API on nodes without participation declarations.
participants validates and installs the batch atomically. It snapshots detached
JSON declarations and compiles them to existing nodes and edges; declarations
are included in the process specification and hash. Editing returned specs or
caller predicate dictionaries cannot change the process. from_spec validates
that declarations agree with compiled nodes and incoming edges; when binding a
System it requires the same declaration, including with strict=False (that
option relaxes fingerprints, not participation). Redeclaring a bound System does
not edit the frozen process: its next run fails before invoking any node. Build
a new process to adopt the changed declaration. Replay follows the recorded
specification and existing loop counters. The existing trace replay may recompute
catalog parts; it does not assemble a new graph from live declarations.
This experimental contract describes one sequential path. It does not implement runtime negotiation, parallel joins, time triggers or distributed participation.