solvi.core.catalog¶
The catalog: Catalog, Question, Answer and the decorators that register parts (re-exported by solvi.core and solvi).
A model's Decision keeps its value when it escalates (what it would have answered) and the reason in escalate:
Decision.alone is True only for a value that was not escalated — count only those as the model's answers. In a
System, read an answer as res["question"].answer; an escalated one abstains there (res["question"].status).
solvi — a catalog of functions and checks, questions with typed answers.
A part's contract comes from its signature: argument names are the facts it reads, the function name is the fact it sets.
Part kinds: extract (pull a value from text, with a quote), fn (computation), check (test → bool), rule (answer to a question).
A part may be backed by a model (model=): its outputs are fuzzy, so they are grounded (a quote must be literally at its
offsets, a decision must be among its options) and the model's identity is recorded in the trace (see solvi.core.provenance).
Type hints are the facts' types (see solvi.core.types): checked between producers and consumers when a part is registered,
validated / coerced with pydantic at run time; untyped parts cost nothing.
Serial ¶
pydantic-backed export of solvi's data classes (see solvi.core.schema; pydantic is imported on first use):
x.model_dump(mode="python"|"json"), x.to_json(), Cls.model_validate(d), Cls.from_json(s), Cls.model_json_schema().
Traces and responses take catalog= on load to restore typed values (dates, enums, models) from the facts' types.
ExperimentalWarning ¶
Bases: UserWarning
A feature whose API and behaviour may still change (solvi.experimental: lora, changes, ...).
NotStated ¶
The type of solvi.Unknown: the answer "the text does not state it". It is a real answer — the evidence says the
input does not state the value, with a confidence — unlike an abstention (None: solvi refuses to answer). Declare it
with Maybe[T] (or T | NotStated); constraints see it as solvi.Unknown (falsy; x is Unknown).
Quote
dataclass
¶
A value extracted from text, with its location (doc[start:end] is the supporting quote). As evidence (Claim, Decision, Result.evidence) the value is the quoted text itself.
Claim
dataclass
¶
Claim(value: Any, evidence: list = list(), confidence: float = 1.0, source: str | None = None, extra: dict = dict())
A value with the quotes that support it — what a plain rule (or any part) returns to attach evidence and / or a
confidence to its answer: return Claim("billing", evidence=["charged twice"]). Evidence items are Quotes (their
offsets are checked: the text must be literally there) or strings (located in source: by default the part's only text
input, or "doc" — as whole words and numbers: "3" is not evidence when the text says "30"); an item not in its text
rejects the output (safeguard "grounding rejected"). The provenance stays the part's own (a hand-written rule:
computed). extra: details recorded in the trace with the fact (record.extra) — a check's reasons
(solvi.core.slow.refine.Fail), a generator's request (solvi.core.slow.generate.Generated).
Decision
dataclass
¶
Decision(value: Any, probs: dict = dict(), confidence: float | None = None, escalate: str | None = None, extra: dict = dict(), evidence: list = list())
A model's choice among declared options, with probabilities. Return it from a model-backed part (or rule): the value is
accepted only if it is one of the part's options (or of the probability keys), and downstream parts receive the plain
value.
alone
property
¶
Is this an answer the model gives alone — a value, and not escalated (handed over to a person)? An escalated
decision keeps value (what the model would have answered) and says why in escalate: count a decision as the
model's answer only when alone is True. In a System the same reading is res[question].status != "abstain"
(an escalated decision abstains there, with the reason in res[question].why).
AnyOf
dataclass
¶
A label with several right answers: (state, AnyOf("close", "escape")) — the dialog is closed by the button or by
Escape, and either answer is right. Calibration (solvi.build, System.guarantee, act_guard) counts an answer
right when it is any of them, so another right answer is not counted as an error. What is fitted on such a label
learns the first option (put the preferred one first). A plain label is the one right answer, as before.
AnswerType
dataclass
¶
Answer ¶
The answer types of a question: Answer.yes_no(), Answer.choice([...]), Answer.maybe(...) and the others
below — each an AnswerType.
yes_no
staticmethod
¶
A yes / no question: the options "yes" and "no" (a rule may return a bool: True is "yes").
maybe
staticmethod
¶
The same answer type, with "not stated" (solvi.Unknown) as a valid answer — distinct from "no" and from an
abstention. Maybe[T] in a type hint does the same.
span
staticmethod
¶
An exact substring of a given text fact (source), with its offsets: always grounded (the text must be literally
at the offsets), then coerced to type with pydantic (e.g. float: "12.50" → 12.5; a failure is "type rejected").
The answer is the value; result.span is the Quote (text, start, end, source). Span[float] in a type hint.
rank
staticmethod
¶
An ordering of the options, best first: the top k (all by default) as a tuple, with a score per option
(result.scores). A rule returns {option: score} (e.g. from a key function) or an ordered list; a model its
probabilities (Plackett–Luce). Rank[Literal[...], k] in a type hint.
estimate
staticmethod
¶
estimate(bins=None, *, lo=None, hi=None, step=None, coverage=0.8, unit=None, integer=None) -> AnswerType
A number with its uncertainty: a distribution over bins cut at the edges bins (ascending; or lo, hi, step) —
len(bins) + 1 bins, the first and last open: (−∞, e0), [e0, e1), …, [e_last, ∞) — whose labels are the options
("less than 0", "0–6", "7–13", "14 or more" for integer edges; integer= overrides). The value is the middle of the
median bin (an open bin: its edge), result.interval the bins holding the central coverage of the probability
((1 − c)/2 to (1 + c)/2 of the cumulative; None for an open end), and the confidence their probability mass. A rule
returns a plain number (interval [x, x], confidence 1) or a distribution ({bin label or index: p}, or a list of p per
bin); a model its probabilities over the bins as ordered options. Without bins the estimate is a plain number (rules
only). Estimate[0, 7, 14] in a type hint.
choice
staticmethod
¶
One of the options. options is a list, or a dict {option: description}.
ordinal
staticmethod
¶
One of ordered levels, lowest first (e.g. ["low", "medium", "high"]). A learned head answers with the median of its distribution instead of the most likely level, so it never jumps over the middle.
multi
staticmethod
¶
Any subset of the options (possibly empty), returned as a tuple in option order. A rule may return a list or set.
value
staticmethod
¶
Any finite JSON value, including scalars and null; null is an answer, not an abstention.
Uses the structured answer codec with an unrestricted JSON schema. Rule return annotations are still validated independently.
structured
staticmethod
¶
A rule's typed JSON object / array, with the usual trace and confidence.
Field explanations may be supplied in Claim.extra['fields'], keyed by JSON Pointer, each with why, confidence and optional evidence.
from_type
staticmethod
¶
From a Python type: bool → yes_no; Literal[...] / an Enum → choice (ordinal=True: ordinal, in declaration
order); list[Literal[...]] (or set, tuple, of an Enum) → multi. X | None is X (None = abstain).
Question
dataclass
¶
Question(name: str, text: str, answer: AnswerType | None = None, requires: list = list(), uses: list | None = None, min_confidence: float | None = None, require_evidence: bool = False)
Bases: Serial
A question the System answers: its name, text and answer type (None: from its rule's return type), the parts
that must run in its flow (requires; checkpoints= in 0.7, removed in 0.9), the facts that matter for a question without a rule (uses), and the
abstentions it asks for (min_confidence, require_evidence).
Part
dataclass
¶
Part(kind: str, name: str, inputs: list, func: Callable | None, doc: str = '', hard: bool = False, then: dict = dict(), question: str | None = None, cost: float | None = None, provides: str | None = None, validate: Callable | None = None, min_confidence: float | None = None, alternatives: list | None = None, features: Callable | None = None, model: Any = None, provenance: str | None = None, options: list | None = None, exact: bool | None = None, source: str | None = None, types: dict | None = None, returns: Any = None, timeout: float | None = None, blocking: bool = False, quotes: str = 'normalized', cites: list | None = None, family: str | None = None, shares_call_with: str | None = None, then_parts: dict | None = None, tin: dict | None = None, tout: Any = None, text: str | None = None, precedence: int | None = None, reads_from: tuple | None = None)
Catalog ¶
Everything the system can do; the strategist decides which parts each question needs.
quotes: how quotes and evidence are matched against their source text — "normalized" (default since 1.0: a
quote that differs from its text only in Unicode form, no-break spaces or hyphens, dashes, "…", whitespace
runs or curly quotes is found, and the source's own substring is kept, see solvi.core.locate) or "literal"
(0.9: the text as written, up to whitespace runs). It applies to the parts registered after it is set.
sensitive: names of given facts no part may read (age, sex, ...) — solvi check (solvi.check.lint) reports a part
that reads one, directly or through a fact computed from one, as an error; nothing changes at ask time.
combine: which of several false hard checks governing one question decides it — None (default since 1.2: as
"strictest", and when their then answers differ a warning names them and the one that decided), "strictest"
(the same, chosen: no warning) — the answer that comes last in the question's options, so list them from
mildest to strictest; a governing check with no then answer for the question abstains and is strictest of
all; with a then function among them, or no options, the first declared decides, with the warning — or
"first" (the first declared decides, no warning: the declaration order is the priority; the default before
1.2).
extract ¶
extract(f=None, *, provides=None, cost=None, validate=None, min_confidence=None, model=None, provenance=None, exact=None, source=None, timeout=None, blocking=None, cite=None, clause=None)
Extract a value from text (returns a Quote). With provides="fact" the function is one of several alternative
producers of that fact: its output is used only if it passes validate / min_confidence, otherwise the next
alternative runs. cost (ms) is a prior for scheduling until run times are measured.
model: the model behind it (recorded in the trace with its fingerprint); a model's Quote must be literally the text
at its offsets or it is rejected (exact=False turns that off, exact=True turns it on for hand-written code).
source: the given fact (text) its quotes point into. By default: "doc" if the function reads doc, else its only
argument, else its only str-typed argument; if that is ambiguous, registration raises and asks for source=. A
returned Quote that names another source (Quote(..., source="notes")) keeps it.
The function may be async def (awaited by System.aask). timeout (seconds) and blocking (a sync function that
waits on I/O or a model: aask runs it in a worker thread) apply under aask; see System.aask.
cite / clause (on every decorator): the text the part implements — a verbatim quote (or a list) and the id of
its clause (or a list as long), e.g. @cat.fn(clause="c16", cite="other_debtors is "guarantor" → −1");
recorded as Part.cites, checked against the text by solvi.check.citations (solvi check --text), listed in the
causes of solvi.core.store.diff.diff.
alias ¶
Read internal fact name from external/source fact source.
Registers one ordinary typed computation, so existing consumers and rules need no wrappers. It never replaces a declared part and refuses cycles. type defaults to the one common type existing consumers declare; provide it when declaring an alias before its consumers. description documents the source fact in input schemas and entry points. If an input_model is used, its fields must use the external names. Answers are not renamed.
answer_fact ¶
Declare a fact containing a System question's accepted answer, not its raw rule output.
The source question must belong to the System. Refused answers become missing facts; consumers retain their own checks and inherit the source confidence bound.
fn ¶
fn(f=None, *, provides=None, cost=None, validate=None, model=None, provenance=None, options=None, min_confidence=None, timeout=None, blocking=None, cite=None, clause=None)
A computation. provides, validate, cost, timeout, blocking: as for extract. A model-backed fn (model=)
with options is a model decision: it returns a Decision (or a plain value) that must be one of the options, else
it is rejected. cite, clause: as for extract.
check ¶
check(f=None, *, hard=False, then=None, cost=None, model=None, provenance=None, timeout=None, blocking=None, cite=None, clause=None, family=None, shares_call_with=None, precedence=None, reads_from=None)
A check: a function of facts that answers True or False (or solvi.core.slow.refine.Fail("why") for False with its
reasons). hard=True: when it is False it decides the questions it governs — the model cannot override it.
then: {question: answer} — the answer a question gets when this hard check is False (a question listed here is
governed by it; without then the check governs every question whose flow runs it, and they abstain). The check
is put into the flow of every question its then names (since 1.0; no requires= needed). An answer may be a
function of facts instead of a constant — then={"step": free_side} with def free_side(position, walls) ->
str — whose argument names are the facts it reads (typed like any part's); it runs only when the check is
False, its value must be one of the question's answers (else the question abstains), and it is recorded in the
trace (record kind "then") and re-checked by replay. then={"q": None} (or "abstain") names that abstention
itself: the check fails and the question abstains on purpose. When several hard checks governing a question are False,
the strictest answer by the question's option order decides (since 1.2; Catalog(combine="first"): the first
declared). precedence: an integer priority for hard checks only (None is 0). The largest priority among
proven false governing checks selects the deciding group; ties use the existing combine mode. It does not
remove mandatory checks or permit ignoring unavailable checks.
reads_from: {function_argument: actual_fact} binds this check's inputs only. Planning, types, traces and
replay name the actual facts; the function still receives its original argument names. Source names do not
certify independent data. Model-backed/shared-pass checks do not support these bindings.
cite, clause: as for extract. family: where the check's evidence comes from (a model family such as
"gpt", "code", "human", a data source); shares_call_with: the part or question whose model call the check
re-reads (a self-check in the same response). Both are metadata: nothing changes at ask time and the
fingerprint is the same; solvi check warns about a check that shares a call (it agrees with that answer
whatever it is) and about a question whose checks are all of one family (they err together).
features ¶
Cheap features of the input for choosing among a fact's alternative producers (the learned producer policy):
@cat.features("total") def total_features(doc): return {"length": len(doc), "has_total": "TOTAL" in doc}.
Arguments must be among the producers' inputs; values are numbers, booleans or short strings.
rule ¶
rule(question, *, model=None, provenance=None, timeout=None, blocking=None, cite=None, clause=None, text=None)
The answer rule of a question. With model= the rule is a model's decision: it may return a Decision with
probabilities; an answer outside the question's options abstains, as for any rule. timeout, blocking, cite,
clause: as for extract. text: a nonempty condition expression shown in the answer's why,
alongside its input values. Author-declared text is not evaluated or inferred from source;
use because(...) for the reason of the branch actually taken.
replace_rule ¶
Install a ready rule Part (System.learn_rule: a learned rule list) as its question's rule, in place of the one registered before; what the catalog recorded about the replaced rule's typed arguments is dropped with it.
contract ¶
Declare the contract of a question's answer (solvi.core.contract): returns — the type the answer must have (a Python type, a tuple of types or an answer type; None: the question's own, which a System already holds its answers to); echo — the answer must not equal a given fact it was read from (True: every given fact its rule reads, directly or through computed facts; a list of names; False: off; None, the default: by the answer's kind — checked for free text such as a span, not for a declared choice, yes / no or number); applicable — a function of the given facts → bool checked before the question is computed. A broken contract is a hard refusal: the question abstains (guard "contract", or "not_applicable" without computing it), whatever the confidence. A System raises when the catalog has a contract for a question it does not ask. applicable_inputs explicitly lists the initial given facts the callable reads (tuple/list of distinct identifier names; () means none). These are required schema inputs, not computed predicates. Arbitrary callable reads cannot be inferred safely; schema export refuses undeclared reads unless Question.uses is explicitly set as a compatibility fallback. → the Contract.
constraint ¶
A rule between answers: argument names are question names, it returns True when the answers fit together
(e.g. def unsafe_if_harm(verdict, harm): return harm == "none" or verdict == "unsafe"). When learned answers break it,
solvi picks the most probable combination that satisfies every constraint; answers from rules and hard checks stay.
unreadable_validates ¶
Producers whose validate requires an argument no producer of their fact takes as an input → [(fact, producer,
[names])]. Such a validate cannot run, so every output of that producer would be rejected. (A part that is not
an alternative producer is checked when it is declared; a fact's producers only once all of them are.)
label_options ¶
A label → the tuple of its right answers (an AnyOf's options; a plain label: itself alone).
first_label ¶
A label as a learner is fitted on it: an AnyOf's first option, a plain label itself.
because ¶
A value with the reason its part chose it — the branch taken and the numbers it rested on: return because("unknown",
"B = P ≠ D", p=0.38). Opt-in: from a rule the reason leads the answer's why ("because B = P ≠ D (p=0.38); ..."); from
a fact function it is shown after that fact's value in the why of each rule that reads it. Recorded in the trace
(record.extra["because"], ["numbers"]) and checked on replay. numbers: plain values (int, float, str, bool) → a Claim.
missing ¶
A fact with no value, and why: return missing("the program did not run") in place of a NaN stand-in. The fact is
None for the parts that read it (a rule decides what no value means) and each rule's why shows "x = missing (the
program did not run)"; the reason is recorded in the trace (record.extra["missing"]). → a Claim.
because_text ¶
A record's extra → its reason as text ("B = P (p=0.38)"; "missing (why)"), or None when it has none.
unwrap ¶
A part's output → (plain value, quote (start, end, source) or None, confidence, probs or None).
find_whole ¶
Where text is written in t as whole words and numbers → the start of its first such occurrence, or -1.
An occurrence that begins or ends inside a longer word or number is not one: "3" is not found in "30", in "3.5" or
in "1,300", "cat" not in "category" — but "30" is found in "30." and "30%", "charged twice" in "was charged twice,".
(Only the ends are held to this: what the evidence itself contains is compared literally.)
cuts_number ¶
Does t[i:j] begin or end inside a longer number written in t? A quote [26:27] of "30" is the "3" of "30", one of "3.5" or "1,300" is part of that number, and so is "7." of "7.5" (a separator at its edge, between two digits). Apostrophe groups and unsupported numeric tokens ("1_000", "1e-3") cannot supply a truncated number either. (Words are not held to this: a quote with offsets may end inside a word.)
locate ¶
A Claim's / Decision's evidence with every item as a Quote: a string is located in the output's source text —
Claim.source, else the part's source, else "doc" if the part reads it, else its only given text input, else "doc";
then the part's other text inputs (several labelled sources: "notes", "dialogues", "map" — the Quote records which
one) — at its first occurrence as whole words and numbers (find_whole: "3" does not quote "30"); a string that is
not there becomes Quote(text, -1, -1, source), which ground rejects. An item given as a Quote keeps its own offsets.
Quote matching (the part's quotes, Catalog(quotes=...)): "normalized" (default) — a quote that is not literally in
its text is looked for, and compared at its offsets, in the normalized view (solvi.core.provenance.norm_view: NFKC,
no-break spaces and hyphens, dashes, "…", whitespace runs, curly quotes); the Quote kept is then the source's own
substring at offsets into the original text, and the output carries extra["quote_match"] = {"form", "written"} —
what the part wrote — so the record says so and a replay re-checks it. A literal match never needs the view and
leaves the output as it was. "literal": as 0.9 (the text as written, up to whitespace runs at given offsets).
Outputs without evidence or quotes are returned as they are (no work).
evidence_rows ¶
Located evidence → [[start, end, source, text]] (what the trace records in extra["evidence"]).
check_evidence ¶
Every evidence Quote must lie in its (given) source text and be literally the text at its offsets → None or the rejection reason (a grounding reason: "quote outside the text" / "not grounded").
bin_labels ¶
Bin edges e0 < … < e_last → the labels of their len(edges) + 1 bins (−∞, e0), [e0, e1), …, [e_last, ∞) — exactly the
labels of the answer-primitives decider (its training code's bin_labels): "less than e0", then "a" (a one-wide integer
bin), "a–(b−1)" (integers) or "a to b", then "e_last or more"; the unit after a space.
cites_of ¶
The decorators' cite= (a verbatim quote of the text the part implements, or a list of them) and clause= (the
clause id, or a list of ids — as long as the list of quotes when both are lists) → Part.cites: [(clause, quote)],
or None when neither is given. One clause with several quotes: each quote cites it; quotes without a clause: None.
group_func ¶
The group as a plain function: alternatives in declaration order, the first accepted value wins (used by code that calls part.func directly; the executor runs groups itself, with the producer policy and the trace).
ground ¶
Is a part's output grounded? → None, or the reason it is rejected. A Quote must lie inside its source text and, for a
strict (model-backed) part, its value must be literally the text at its offsets (strings up to whitespace, numbers as
written); a Decision (or any value of a part with options) must be among the options; min_confidence is enforced.
validated ¶
Run a part's validate(value, [its inputs by name]) → None or the rejection reason.
accept ¶
Does an alternative producer's output pass its checks? → (ok, reason, plain value — coerced to its return type). None
means "not found"; otherwise the output must be grounded (see ground: a quote in the text — literally, for a model — a
decision among the options, min_confidence), pass its return type (typed parts) and validate, which gets the plain value
plus any of the producer's inputs it names.
question_data ¶
A question as plain data (its serialized form, solvi.core.schema) — without importing pydantic.
plain_json ¶
Is v JSON data as it is — str / int / bool / None, finite floats, lists and tuples, dicts with str keys — so that solvi.core.schema.jsonable would give it back unchanged (up to tuples as lists)?