Skip to content

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.