Skip to content

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

Quote(value: Any, start: int, end: int, source: str = 'doc', confidence: float = 1.0)

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.

act property

act

Does the model act on this decision (False: it escalates)?

alone property

alone

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

AnyOf(*options)

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.

first property

first

The preferred right answer: what a learner is fitted on.

AnswerType dataclass

AnswerType(kind: str, options: list, descriptions: dict = dict(), unknown: bool = False, k: int | None = None, bins: list | None = None, coverage: float | None = None, unit: str | None = None, source: str | None = None, type: Any = None)

Bases: Serial

primitive property

primitive

Is this answer resolved with details (a span, a ranking, an estimate, or one that may be "not stated")?

Answer

The answer types of a question: Answer.yes_no(), Answer.choice([...]), Answer.maybe(...) and the others below — each an AnswerType.

yes_no staticmethod

yes_no() -> AnswerType

A yes / no question: the options "yes" and "no" (a rule may return a bool: True is "yes").

maybe staticmethod

maybe(answer_type) -> AnswerType

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

span(source='doc', type=None) -> AnswerType

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

rank(options, k=None) -> AnswerType

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

choice(options) -> AnswerType

One of the options. options is a list, or a dict {option: description}.

ordinal staticmethod

ordinal(levels) -> AnswerType

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

multi(options) -> AnswerType

Any subset of the options (possibly empty), returned as a tuple in option order. A rule may return a list or set.

value staticmethod

value() -> AnswerType

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

structured(type=dict) -> AnswerType

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_type(t, ordinal=False) -> AnswerType

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)

call_args

call_args(values)

Translate already-validated actual fact values to the original check's argument names.

strict

strict()

Must a Quote from this part be literally at its offsets? Yes for model-backed parts (unless exact=False).

Catalog

Catalog(*, quotes='normalized', sensitive=(), combine=None)

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

alias(name, source, *, type=None, description=None)

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

answer_fact(question, *, name=None)

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

features(fact)

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

replace_rule(part)

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

contract(question, *, returns=None, echo=None, applicable=None, applicable_inputs=None)

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

constraint(f)

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

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.)

alternative

alternative(fact, name)

One alternative producer of a fact, by its function name.

unknown_key

unknown_key(k)

A probability key read back from JSON: "" → Unknown.

label_options

label_options(y)

A label → the tuple of its right answers (an AnyOf's options; a plain label: itself alone).

first_label

first_label(y)

A label as a learner is fitted on it: an AnyOf's first option, a plain label itself.

because

because(value, text, **numbers)

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

missing(reason)

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

because_text(extra)

A record's extra → its reason as text ("B = P (p=0.38)"; "missing (why)"), or None when it has none.

unwrap

unwrap(v)

A part's output → (plain value, quote (start, end, source) or None, confidence, probs or None).

find_whole

find_whole(text, t)

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

cuts_number(t, i, j)

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

locate(part, v, init_state)

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

evidence_rows(v)

Located evidence → [[start, end, source, text]] (what the trace records in extra["evidence"]).

check_evidence

check_evidence(evidence, init_state)

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_labels(edges, integer=True, unit=None)

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

cites_of(cite=None, clause=None)

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

group_func(group)

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

ground(part, v, init_state=None)

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

validated(part, value, args)

Run a part's validate(value, [its inputs by name]) → None or the rejection reason.

accept

accept(alt, v, args, init_state=None)

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.

accepts

accepts(alt, v, args, init_state=None)

accept() without the value → (ok, reason).

question_data

question_data(q)

A question as plain data (its serialized form, solvi.core.schema) — without importing pydantic.

plain_json

plain_json(v)

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)?