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 ¶
Bases: RuntimeError
A compilation that was not accepted was asked for its catalog. .reason says why it was not accepted.
Spec ¶
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.
render ¶
The clauses as the writer reads them: [c3] (section) text, with marks ({id: "changed"}) in front.
revise ¶
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
¶
The catalog's fingerprint (what a stored decision records as the catalog that decided).
clauses_of ¶
The clauses a part implements (a rule may be named answer:<question>).
part_of ¶
The PARTS name of a trace step (answer:<question> → its rule's function).
catalog ¶
→ (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 ¶
An ordinary System over the compiled catalog (kw: System's own — storage, ...).
save ¶
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
¶
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 ¶
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.
add ¶
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).
info ¶
{"version", "label", "fingerprint", "spec_hash", "parent", "time"} of version n.
system ¶
The System of version n (the one in force when None); kw: System's own (storage, ...).
rollback ¶
Put version n back in force (every version stays; a later add takes n as its parent); recorded in
history() → n.
replay_all ¶
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 ¶
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 ¶
The catalog of a loaded module (in PARTS order) and the questions, each requiring the hard checks that name it.
decision_diff ¶
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 ¶
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: