Skip to content

solvi.core.versions

Versions of a document and their impact: a specification as numbered clauses, a catalog version citing them, versions with parents and rollback, and the decisions a new version moves (stable since 1.1; until then in solvi.experimental.compile).

Versions of a document and their impact (stable since 1.1; until then in solvi.experimental.compile): a specification as numbered clauses, a catalog that implements it as a version citing those clauses, a folder of versions with their parents and the version in force, and the decisions a new version moves — with the clauses why.

from solvi.core.versions import CatalogVersion, Spec, Versions, decision_diff

spec = Spec(policy_text)                       # clauses c1, c2, ... (paragraphs, list items, table rows)
spec2 = spec.revise(new_text)                  # unchanged clauses keep their ids; spec2.changes
v1 = CatalogVersion(spec, questions, module_source, parts)    # parts: {name: {"kind", "clauses", ...}}
versions = Versions("policy_versions")         # v1/, v2/ ... each module.py + compiled.json + version.json
versions.add(v1, "first"); versions.add(v2, "after the change")     # each with its parent: the version in force
print(decision_diff(v1, v2, store=store))      # which stored decisions change, and the clauses of their causes
versions.replay_all(store)                     # every stored decision against the version that made it
versions.rollback(1)                           # the version in force goes back (every version is kept)

decision_diff also takes plain Systems (hand-written catalogs whose parts cite their clauses with clause= / cite=), and only= names the decisions a change may move: extraneous lists the others it moves, exact says there were none and every decision re-ran. A version's module is pure functions, checked before it is loaded (_sandbox: standard-library imports only, no files, reflection or dunders) — the compiler that writes such modules with an LLM stays experimental (solvi.experimental.compile, whose Compiled is a CatalogVersion and which re-exports every name here for one release).

Rejected

Rejected(reason)

Bases: RuntimeError

A compilation that was not accepted was asked for its catalog. .reason says why it was not accepted.

Spec

Spec(text: str | None = None, *, clauses=None, name: str = 'specification')

A specification as numbered clauses (c1, c2, ...). Spec(text) splits a text (Markdown-like: paragraphs, list items and table rows are clauses, headings are sections); Spec(clauses={id: text}) takes them as given. spec.revise(new_text) aligns a changed text with this one: unchanged clauses keep their ids, and changes says which clauses changed, were added or removed.

hash property

hash: str

sha256 of the clauses (ids, sections, texts).

render

render(marks: dict | None = None) -> str

The clauses as the writer reads them: [c3] (section) text, with marks ({id: "changed"}) in front.

revise

revise(text: str | None = None, *, clauses=None) -> 'Spec'

A new version of this specification, aligned with it: a clause whose text (and section) did not change keeps its id; a replaced clause keeps the id of the one it replaces (changed); new clauses get new ids (added); the others are removed. new.changes = {"unchanged", "changed", "added", "removed"} (lists of ids).

CatalogVersion dataclass

CatalogVersion(spec: Spec, questions: list, source: str, parts: dict, not_normative: dict = dict(), accepted: bool = True, reason: str = '', record: dict = dict(), changes: dict | None = None, _ns: dict | None = None)

A version of a catalog that implements a document: the module's source (pure functions — a part's name is the fact it sets, its argument names what it reads), parts ({name: {"kind": "fn" | "check" | "rule", "clauses": [...], for a hard check "hard" and "then", for a rule "question"}}), the questions, and the specification whose clauses the parts cite. not_normative lists clauses no part implements, with why; accepted / reason say whether the version may be loaded (a draft that was not accepted is refused); record and changes are free for whoever made it (the compiler keeps its prompts, tests and rounds there). catalog() / system() load the module in this process — checked first: standard-library imports only, no files, reflection or dunders (solvi.core.versions._sandbox) — and refuse an unaccepted version unless allow_unaccepted=True. solvi.experimental.compile.Compiled is a CatalogVersion.

fingerprint property

fingerprint: str

The catalog's fingerprint (what a stored decision records as the catalog that decided).

clauses_of

clauses_of(part: str) -> list

The clauses a part implements (a rule may be named answer:<question>).

part_of

part_of(step: str) -> str | None

The PARTS name of a trace step (answer:<question> → its rule's function).

catalog

catalog(allow_unaccepted: bool = False) -> tuple[Catalog, list]

→ (Catalog, questions): the module loaded in this process (sandbox.load), each hard check required by the questions it names. Raises Rejected for a compilation that was not accepted.

system

system(allow_unaccepted: bool = False, **kw)

An ordinary System over the compiled catalog (kw: System's own — storage, ...).

save

save(path) -> Path

Write module.py (the code, as accepted) and compiled.json (everything) into a folder.

DecisionDiff dataclass

DecisionDiff(changed: list, report: Any, total: int, extraneous: list = list(), exact: bool = False)

The decisions a new compilation changes: changed = [{"id", "question", "old", "new", "causes": [{"step", "part", "clauses", "why"}]}] (with inputs=, also "input": the input's id); report is solvi.core.store.diff's own report. With only=: extraneous, the ids of the decisions whose answer moves (moved) that are not in it, and exact, True when there are none and every decision re-ran (report.errors empty).

moved property

moved: list

The changes whose answer moves (the others keep their answer and are decided another way: by another check, or forced where a rule answered).

Versions

Versions(path)

Catalog versions as numbered folders (v1/, v2/, ... each module.py + compiled.json + version.json). Each version records its parent — the version in force when it was added — and the folder keeps which version is in force (current: the last one added, unless rolled back; in_force.json). get() / system() give the version in force, get(n) / system(n) any one; replay_all(store) replays every stored decision with the version whose catalog fingerprint it recorded — an old decision is checked against the rules it was made with.

current property

current: int | None

The version in force (None: no version yet).

add

add(version: CatalogVersion, label: str | None = None, *, parent: int | None = None) -> int

Store an accepted version as the next number, in force from now on → its number. parent: the version it changes (default: the one in force).

get

get(n: int | None = None) -> CatalogVersion

Version n (the one in force when None).

info

info(n: int) -> dict

{"version", "label", "fingerprint", "spec_hash", "parent", "time"} of version n.

system

system(n: int | None = None, **kw)

The System of version n (the one in force when None); kw: System's own (storage, ...).

find

find(fingerprint: str) -> int | None

The version whose catalog has this fingerprint.

rollback

rollback(n: int, *, by=None, why=None) -> int

Put version n back in force (every version stays; a later add takes n as its parent); recorded in history() → n.

history

history() -> list

The rollbacks, in order: [{"to", "from", "by", "why", "time"}].

replay_all

replay_all(store, **filters) -> list

Replay every stored decision against the version that made it (by the recorded catalog fingerprint) → the ones that do not replay (as TraceStorage.replay_all), plus decisions whose catalog is no version here.

split_clauses

split_clauses(text: str) -> list[tuple[str, str]]

A text → [(section, clause text)]: each paragraph, list item and table row is a clause (a table row is written as header: cell; ...); headings name the section and are not clauses themselves.

build_catalog

build_catalog(ns: dict, parts: dict, questions) -> tuple[Catalog, list]

The catalog of a loaded module (in PARTS order) and the questions, each requiring the hard checks that name it.

decision_diff

decision_diff(old, new, *, store=None, inputs=None, only=None, **filters) -> DecisionDiff

Which decisions new would change: the stored ones (store, decided by old's catalog — filters as for solvi.core.store.diff.diff) or inputs (each decided by old first, in a temporary store). old / new: a CatalogVersion (a Compiled too), or a plain System (a hand-written catalog). Each change's causes are the steps solvi.core.store.diff names, with the clauses their parts implement — a version's parts (in the new compilation, else the old one), for a plain catalog the clause ids its parts cite (clause= on the decorators) — and "cites", the parts' citations [{"clause", "quote"}] when they have them.

only: the decisions the change is allowed to move — stored decision ids, or with inputs= the inputs' ids: an input's "id" key when it has one, else its position in inputs (0, 1, ...); each change then carries "input". extraneous lists the moved decisions outside it (by those ids), exact is True when there are none and every decision re-ran (a decision that could not be re-run makes it False).

serve_head

serve_head(system, question, head) -> dict

Install head as the answer head of question — the hook through which a learned version is served (the closed learning loop, solvi.experimental.stream.versions, installs each promoted or rolled-back frozen version here). The head is system.heads[question], so the System's fingerprint ("models": "answer:") changes with it and every trace records which model answered, as for any fitted head. head: the Head protocol (options, features, predict, contributions, fingerprint); a question a rule answers is refused (the rule would answer and the head would never be asked) → {"question", "from": the previous head's fingerprint or None, "to": the new one}. Experimental (1.4): the loop that calls it is unmeasured.