Skip to content

solvi.core.provenance

Provenance of facts and answers, model identity and fingerprints, grounding of quotes (matches).

Provenance of facts and answers, model identity, and grounding.

Principle: fuzzy proposes, deterministic decides, everything is in the trace. Every fact and answer carries a provenance kind:

given — a key of init_state (the input) computed — a plain function (fn, check, hand-written rule) quoted — an extract part returning a Quote: the value is grounded at offsets in the source text decided — a model's choice among declared options, with probabilities (a Decision) learned — a fit answer head, a learn_rule list, or another trained function proposed — a model that writes: a strategist's plan, a generator's text or JSON (solvi.core.slow.generate); the deterministic layer verifies what it proposes

A part backed by a model (an extractor, a head, a rule list, any object) records the model's identity in the trace: {"type", "id", "fp"} — the fingerprint is a stable hash of the model's configuration and weights, so a replay can tell whether the model that made the decision is still the one in the catalog.

classify

classify(reason)

A rejection reason → the safeguard that fired (grounding, type_rejected, outside_options, low_confidence, escalated, validator, timeout, no_answer, instruction, memory) or None. A remote model whose server did not answer (a timeout, 5xx, 429 after the retries) is "no_answer", not "escalated": the model gave no answer, neither a wrong one nor a doubt.

fingerprint

fingerprint(model)

A stable hash of a model: its own fingerprint() if it has one; parameters for solvi heads and rule lists; otherwise a version attribute, or "unversioned:" (then a changed model cannot be detected).

model_info

model_info(model)

→ {"type", "id", "fp"} recorded in the trace for a model-backed step (None without a model).

torch_fingerprint

torch_fingerprint(modules, files_dir=None, samples=256)

Weights of torch modules, cheaply: every parameter's shape plus samples evenly spaced values (and the full tensor when it is small), plus the names and sizes of the weight files when the model was loaded from a directory.

code_fingerprint

code_fingerprint(f, _seen=None)

A stable hash of a function's code: its definition's AST (without decorators, docstring, comments, formatting; the bytecode when there is no source), the simple values it closes over or reads as module globals (THRESHOLD = 30), and the code of the module's own functions it calls. A callable object (a model-backed part such as a decision) is identified by its type: its weights are the model's fingerprint. Cached per function: a module constant rebound after the first fingerprint is not noticed within the process; a mutable module-level container (dict, list, set) is hashed by its content as first seen in the process (see _global_container). Within one call (and one catalog_fingerprint) a function the code calls is hashed once and reused wherever the result cannot depend on the path that reached it, so a helper shared by many rules costs one hash.

code_callees

code_callees(f)

The functions a function's code fingerprint takes in directly — the functions it closes over and those of its own module it reads as globals — → {qualified name: code_fingerprint(callee)} ({} for none, or for a callable object). A callee's own fingerprint holds its callees in turn, so a change deep down shows as the direct callee that leads to it. What diff uses to tell "a function it calls changed" from a change of the part's own code.

catalog_fingerprint

catalog_fingerprint(catalog)

→ {"fp": the catalog's fingerprint, "parts": {name: fingerprint}, "calls": {name: {callee: fingerprint}} (the parts that call functions of their own module, see code_callees)} over every part, answer rule ("answer:") and constraint ("constraint:"). Cached on the catalog while its parts are the same objects (a part edited in place after that is not noticed: register a new one). A helper that many parts call is hashed once per call (see code_fingerprint).

matches

matches(value, snippet)

Is value literally the quoted text? Strings: equal up to whitespace. Numbers (int, float, Decimal, Fraction, numpy scalars): a number in the snippet equals it (thousands separators allowed; a Decimal or a Fraction exactly, a float up to rounding). A date: the snippet reads as that date (solvi.core.textin.parse_date) or holds it in ISO form; a snippet with no date in it is not the date, one whose date needs a year or "today" to be read is not compared (None). A bool (also numpy's): the snippet is one of its words (BOOL_WORDS: "yes" / "true" / "1" / "да" ... for True, "no" / "false" / "0" / "нет" ... for False, any case) — any other text is not that bool. Other types (datetimes, lists) cannot be compared → None (not checked).

quote_mode

quote_mode(mode)

A quote-matching mode, checked: "normalized" (default) or "literal" (0.9: the text as written, up to whitespace).

norm_view

norm_view(s)

A text in the normalized view → (view, starts, ends): view[i] comes from s[starts[i]:ends[i]]. Each character with the combining marks after it is NFKC-normalized as a unit; dashes and hyphens become "-", curly and angle quotes straight ones, zero-width characters and soft hyphens go, and every run of whitespace is one space.

normalized

normalized(s)

The normalized view of a text, without the offsets and without leading / trailing space.

find_normalized

find_normalized(text, quote, whole=True)

Where quote is in text in the normalized view → (start, end) in the ORIGINAL text — text[start:end] is the source's own substring — or None. whole: as whole words and numbers (solvi.core.find_whole).

matches_normalized

matches_normalized(value, snippet)

Is the string value the text snippet in the normalized view?

quote_match_problem

quote_match_problem(extra, value=None, rows=())

A record's quote_match note (what a part wrote, matched in the normalized view) re-checked on replay → None, or why it does not hold: the form must be one this version knows, and each written text must be, in that view, the quote the record keeps (value: the record's quoted value; rows: its evidence rows [start, end, source, text]).

snippet

snippet(init, quote, width=60)

The quoted text doc[start:end] for a record's (start, end, source), shortened for display.