Skip to content

The catalog

from solvi import Catalog, Quote

cat = Catalog()
Decorator Kind Returns Sets fact
@cat.fn computation any value function name
@cat.check soft check bool function name
@cat.check(hard=True, then={"question": "answer"}) hard check bool function name
@cat.extract extraction from text Quote(value, start, end, source="doc", confidence=1.0) function name
@cat.rule("question") answer rule one of the question's options (a bool is accepted for yes/no) the answer

A part's contract is its signature. You do not write a separate schema:

  • argument names are the inputs: keys of init_state or facts produced by other parts;
  • the function name is the output fact.

Part names must be unique in a catalog (a duplicate raises ValueError). A rule is registered per question; registering a second rule for the same question replaces the first. The decorators return the original function, so parts stay ordinary, testable Python. A part and a key of init_state cannot share a name: ask raises ValueError for an input key named like a part (the given value would replace the part — a hard check included), and System(input_model=Model) refuses a model with such a field when it is built. Name a part after what it computes (savings_points), not after the input it reads (def savings(savings) reads its own name).

A part may be an async def function (a database or HTTP lookup): system.aask awaits it, concurrently with the other steps; timeout= (seconds) and blocking=True (a sync function that waits: run in a worker thread) on any decorator apply under aask (see Async execution).

@cat.fn
def total(items):                           # reads "items", sets "total"
    return sum(q * p for q, p in items)

@cat.check
def big_order(total):                       # soft check: a fact like any other
    return total > 1000

@cat.check(hard=True, then={"ship": "no"})  # hard check: if False, the answer to "ship" is forced to "no"
def paid(payment_status):
    return payment_status == "paid"

@cat.rule("ship")
def ship_rule(big_order):
    return not big_order                    # bool is normalized to "yes"/"no" for yes/no questions

Citing the clause a rule implements

A hand-written part can say which text it implements: cite= a verbatim quote (or a list) and clause= the clause's id (or a list as long). They are kept as Part.cites and checked against the text by solvi.check.citations(system, text, spec=None, require=False) — or solvi check module:system --text POLICY.md: a quote not in the text is the error cite_not_found (matched as quotes are, across Unicode forms, dashes and curly quotes), with a Spec a clause that does not exist or does not hold the quote is an error, require=True warns on an uncited part; a correction can be cited as clause="person:k07". --spec POLICY.md splits the text into clauses c1, c2, ... as solvi.core.versions.Spec does (and is the text, unless --text names another file); --require-cites warns on an uncited part. The causes of solvi diff carry the citations: clause → rule → decision.

@cat.fn(clause="c16", cite='new rule `guarantor`: other_debtors is "guarantor" → −1')
def guarantor_points(other_debtors):
    return -1 if other_debtors == "guarantor" else 0

Soft and hard checks

  • A soft check is a boolean fact. Rules can use it, answer heads can learn from it, and failed soft checks are listed in the reason of a learned answer.
  • A hard check decides the answers it governs whenever it is in the question's flow and evaluates to False:
  • if then names the question, the answer is set to that value with status="forced" and confidence 1.0;
  • if the question lists the check in its requires (or the check has no then at all) but then does not name it, the question abstains;
  • otherwise — the check has a then for other questions and only reads this question's facts — it is an ordinary failed check for this question and is listed in the reason.

A check can say why it is False: return Fail("Harold is busy 13:30 - 15:30") — see A check that says why.

A check returns True or False (numpy's bools count: amount <= limit over numpy numbers gives one), typed -> bool or not. Anything else — 1, "yes", "true", 0, None, a list — rejects the step: the check's status is "error" and the questions it governs abstain (guard hard_check); it never passes, and 0 or "no" does not force the then answer either. A check declared with another return type (-> Literal[True, False]) is validated by that type.

No rule and no model confidence can override a failed hard check. A hard check whose then names a question is put into that question's flow by the strategist (since 1.0; the step's reason says hard check for <question> (then)), so then= alone wires it — no requires= needed, and the other questions' flows stay as they were. A strategist of your own that leaves such a check out is refused when the System is built. To make sure a hard check without then is always in a question's flow, list it in the question's requires. When several hard checks governing a question fail with different then answers, the strictest decides — 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 it abstains, strictest of all) — and a warning names them; Catalog(combine="strictest") chooses this without the warning. Changed in 1.2: before, the first one declared in the catalog decided; Catalog(combine="first") keeps that (declare the most important first). Where the options give no order (a then function among them, or a question without options) the first declared decides, with the warning. A question's flow does not depend on which other questions are asked in the same request, and neither does its answer — except through a constraint between answers, which applies only when all its questions are asked.

A hard check that could not be evaluated (it raised, or a fact it reads is missing) never counts as passed: the questions it governs abstain. The reason names the check and, when the check could not run for lack of an input, the part further up that failed: hard check day_allowed could not be evaluated: missing inputs: violations; caused by spec: ValueError: no slot in the plan. A rule that could not run says the same (rule not computed: ...; caused by ...).

The answer then sets may be a function of facts instead of a constant: its argument names are the facts it reads (given or computed; type hints validate them as for any part), and it runs only when the check is False.

def free_side(free_sides: list, facing: str) -> str:      # the step to take instead
    return next((s for s in free_sides if s != facing), free_sides[0])

@cat.check(hard=True, then={"step": free_side})
def not_looping(history: list) -> bool:
    return Fail("the same room three times") if len(history) > 2 and len(set(history[-3:])) == 1 else True

The facts it reads are planned into the question's flow and computed even when the failed check closes the question early. Its value must be one of the question's answers — else the question abstains (guard="hard_check", the reason names the value). The value is recorded in the trace (a record of kind "then", named then:<question>, with the hashes of the facts it read), stored with the decision and re-run by replay; the function's code is in the check's fingerprint.

Extractors and Quote

An extractor reads text from init_state and returns a Quote:

import re

@cat.extract
def amount(doc):
    "the total amount to pay"
    m = re.search(r"Total due:\s*([0-9,]+\.[0-9]{2})", doc)
    if not m:
        raise ValueError("no total")        # a failed part becomes a missing fact; dependent answers abstain
    return Quote(float(m.group(1).replace(",", "")), m.start(1), m.end(1))
  • doc[start:end] is the supporting quote. source names the init_state key holding the text. When the Quote does not name it, it is the extractor's text: "doc" if the function reads doc, else its only argument (def refund_word(message) quotes message), else its only str-typed argument; if that is ambiguous, registration raises and asks for @cat.extract(source="..."). A Quote that names another source keeps it.
  • A quote whose offsets fall outside the source text is rejected: the fact is missing (dependent answers abstain) and the error is recorded. A quote from a model-backed part must also be literally the text at its offsets — see Grounded decisions. Hand-written code may return a value derived from the quoted text (a label, a parsed number, a date); @cat.extract(exact=True) makes it literal too.
  • "Literally" is measured on a normalized view of both texts (since 1.0, Catalog(quotes="normalized"), the default): Unicode NFKC (ligatures, full-width letters), no-break spaces, no-break and other hyphens and dashes (‑ – — − as -), … as ..., runs of whitespace as one space, curly and angle quotes (’ “ ” « ») as straight ones, zero-width characters and soft hyphens dropped. Models type these differently from the source; an honest quote is no longer rejected for it. The quote that is kept is always the source's own substring, at offsets into the original text (never into the normalized view), and a record whose quote needed the view says so: record.extra["quote_match"] = {"form": "nfkc-ws-dash-quote/1", "written": {"value" | "evidence <i>": what the part wrote}} — hashed, stored, and re-checked by replay under that form. A literal match is preferred and leaves the record exactly as in 0.9. Catalog(quotes="literal") keeps 0.9's rule (the text as written, up to whitespace runs at given offsets); the setting is in each part's fingerprint when it is not the default. Letter case is never normalized.
  • solvi.core.find_quote(quote, sources) does the same lookup for your own checks: sources is a text or {"notes": ..., "dialogues": ..., "map": ...}, searched in order; it returns Quote(the source's substring, start, end, label) — the label says which source the quote came from — or None.
  • confidence (default 1.0) is propagated to every answer that depends on this value (see Confidence).
  • Downstream parts receive the plain value, not the Quote.

You can write extractors by hand (regular expressions, parsers) or get them from a trained model (Extracting fields from documents).

Several producers of one fact (fallback chain)

A fact can have alternative producers — a cheap regular expression and a slower model, say. Give each its own function name and say which fact it provides:

@cat.fn(provides="total", cost=0.1, validate=lambda v: v > 0)
def total_regex(doc):
    m = re.search(r"TOTAL\s*:?\s*(\d+\.\d\d)", doc)
    return None if m is None else float(m.group(1))           # None = "not found": rejected, the next producer runs

@cat.extract(provides="total", cost=50, min_confidence=0.8)
def total_model(doc):
    return extractor.field("total", "the total amount paid")(doc)

@cat.features("total")                                      # optional: cheap features for the producer policy
def total_features(doc):
    return {"lines": doc.count("\n"), "has_total": "TOTAL" in doc.upper()}
  • The producers form a group in the catalog under the fact's name; the strategist plans it like one part (its inputs are the union of the producers' inputs). Catalogs without provides behave exactly as before.
  • A producer's output is accepted only if it is not None, a Quote lies inside its text (literally, for a model-backed producer), a Decision is among its options, it reaches min_confidence, and validate(value, [any of the producer's inputs by name]) returns true. An exception counts as a rejection. The first accepted output is used; if none is accepted the fact is missing and dependent answers abstain.
  • Order: declaration order by default. System(cat, questions, producers="learned") lets a policy choose the order per input: producers predicted to agree with the reference producer (the last declared, normally the most trusted) at least system.producer_policy.quality of the time (0.9) go first, cheapest expected cost first (cost ÷ P(accepted)). The policy learns from every run: acceptance of each producer that ran, and — when two producers ran on the same input — whether the cheaper one agreed with the reference. With probability producer_policy.explore (0.1) the remaining producers also run as a shadow (never used, only compared) so the policy keeps getting agreement labels. The policy only orders; acceptance is always the producer's own deterministic check.
  • The record of the fact says which producer was used (record.producer) and every producer that ran with its outcome (record.tried, e.g. [["total_regex", "no value"], ["total_model", "accepted"]]). Both are hashed into the chain. replay recomputes the value with the producer that was used, checks it still passes its validator, and checks that the producers tried before it are still rejected (shadow runs are not re-checked).
  • cost= (ms) is what the cost-optimal planner plans with (system.cost_book measures run times for reports only).