Versions of a document and their impact: solvi.core.versions¶
A policy, a regulation or a contract changes; the catalog that implements it changes with it. solvi.core.versions
keeps the text as numbered clauses, each catalog as a version whose parts cite the clauses they implement, and says
which decisions a new version moves — and the clauses why — before it goes live. (Until 1.1 this lived in the
experimental compiler, solvi.experimental.compile, which re-exports every name for one release; the compiler itself,
an LLM writing the parts, stays experimental.)
from solvi import Answer, Question
from solvi.core.versions import CatalogVersion, Spec, Versions, decision_diff
POLICY = """# Shipping
- An order of 50 or more ships free.
- Orders to the world zone heavier than 30 kg are refused.
"""
MODULE = '''
def free_shipping(total):
return total >= 50
def small_enough(zone, weight):
return not (zone == "world" and weight > 30) or Fail(f"{weight} kg to the world zone")
def ship(free_shipping):
return "free" if free_shipping else "paid"
'''
PARTS = {"free_shipping": {"kind": "fn", "clauses": ["c1"]},
"small_enough": {"kind": "check", "hard": True, "then": {"ship": "refused"}, "clauses": ["c2"]},
"ship": {"kind": "rule", "question": "ship", "clauses": ["c1"]}}
QS = [Question("ship", "Ship free, paid or refused?", Answer.choice(["free", "paid", "refused"]))]
spec = Spec(POLICY) # c1, c2: paragraphs, list items and table rows
spec2 = spec.revise(POLICY.replace("50 or more", "80 or more")) # spec2.changes: {"changed": ["c1"], ...}
v1 = CatalogVersion(spec, QS, MODULE, PARTS)
v2 = CatalogVersion(spec2, QS, MODULE.replace(">= 50", ">= 80"), PARTS)
orders = [{"id": f"o{t}", "zone": "home", "total": t, "weight": 1} for t in (10, 60, 90)]
dd = decision_diff(v1, v2, inputs=orders, only={"o60"})
print(dd) # 1 of 3 decisions change their answer ... because of clauses c1: 1
dd.exact, dd.extraneous # True, []: the change moves only what it was meant to
versions = Versions("policy_versions") # v1/, v2/ ... each module.py + compiled.json + version.json
versions.add(v1, "first"); versions.add(v2, "free from 80") # v2's parent: v1, the version in force
versions.replay_all(store) # every stored decision against the version that made it ([] — all replay)
versions.rollback(1) # v1 in force again; every version is kept
A specification (Spec(text), or Spec(clauses={id: text})) splits Markdown-like text into clauses c1, c2,
...: paragraphs, list items and table rows (a row as header: cell; ...), headings naming the section. spec.revise(new)
aligns a changed text with the old one: an unchanged clause keeps its id, a replaced one keeps the id of the one it
replaces (changed), new ones get new ids (added), the rest are removed. spec.hash covers the clauses.
A catalog version (CatalogVersion(spec, questions, source, parts)) is a module of plain functions — a part's name is
the fact it sets, its argument names what it reads — and parts, each part's kind (fn, check, rule), for a hard
check its then, for a rule its question, and the clauses it implements. version.system(**kw) is an ordinary System;
the module is checked before it is loaded (standard-library imports only, no files, reflection or dunders) and a check
may return Fail("why"). save(folder) / CatalogVersion.load(folder) write and read module.py and compiled.json
(an edited module.py is refused); a version with accepted=False is refused unless allow_unaccepted=True.
The decisions a version moves. decision_diff(old, new, *, store=None, inputs=None, only=None) re-runs the stored
decisions (store=, decided by the old version) or inputs (each decided by the old version first) through
solvi diff and maps each cause step to the clauses its part
implements; old and new may also be plain Systems, whose parts cite their clauses with clause= / cite= (citing the
clause), and the causes then carry "cites". only= names the decisions the
change may move — stored ids, or with inputs= an input's "id" (else its position): extraneous lists the others it
moves, and exact is True when there are none and every decision re-ran. On a credit policy
(benchmarks/changes_credit.py) a second version moved 144 decisions and each was traced to its clause, and every
exception for one application was checked with only= before it was admitted.
Versions (Versions(folder)) numbers the versions it is given; each records its parent (the version in force when
it was added), its catalog fingerprint and the spec's hash. current is the version in force (get() and system()
give it), rollback(n, by=, why=) puts an earlier one back in force (recorded in history()), find(fp) the version of
a fingerprint, and replay_all(store) replays each stored decision with the version whose catalog made it, so old
decisions keep verifying after the rules changed; a decision made by a catalog that is no version here is reported.
The change pipeline (solvi.experimental.changes, VersionsTarget) promotes into a Versions and rolls it back.