solvi 0.2.2__tar.gz → 0.3.0__tar.gz

{solvi-0.2.2 → solvi-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: solvi
-Version: 0.2.2
+Version: 0.3.0
 Summary: Decision systems from a catalog of Python functions and checks: a strategist plans the flow, every answer comes with a quote or formula and a verifiable trace
 Keywords: decision systems,rules,document extraction,ModernBERT,explainability,verification,audit trail
 Author: mxkuzn
@@ -54,8 +54,13 @@ script that computes everything, and 152 ms when an expired policy settles the c
 
 - [solvi playground](https://huggingface.co/spaces/solvi-ai/playground): write a decision task in Python and run it, watch the
   strategist's plan, tamper with a trace and see the replay catch it, learn rules from examples.
-- [solvi arcade](https://huggingface.co/spaces/solvi-ai/arcade): game agents built from small functions that explain every move.
-- Both run **entirely in your browser** (Pyodide): no server, no GPU, nothing you type leaves the page.
+- [solvi documents](https://huggingface.co/spaces/solvi-ai/documents): cited, typed answers from contracts, invoices, receipts,
+  leases and more — the ModernBERT extractor (ONNX) and the decisions both run in your browser; add a field by describing it.
+- [solvi arcade](https://huggingface.co/spaces/solvi-ai/arcade): game agents that explain every move — tic-tac-toe, maze,
+  minesweeper, 20 questions, Mafia detective, a bot arena, and "hack the trace".
+- [solvi realms](https://huggingface.co/spaces/solvi-ai/realms): an endless strategy game whose factions are solvi systems —
+  tested for 100 000 turns: flat decision time (~0.3–0.6 ms), bounded memory and state, every sampled trace replay OK.
+- All run **entirely in your browser** (Pyodide): no server, no GPU, nothing you type leaves the page.
 - Models: [solvi-ai/extract-base](https://huggingface.co/solvi-ai/extract-base) (fields by description) and
   [solvi-ai/extract-receipts](https://huggingface.co/solvi-ai/extract-receipts).
 
@@ -236,6 +241,7 @@ receipt with the one-pass extractor on an A100).
 | [examples/06_learned_rules.py](examples/06_learned_rules.py) | `learn_rule`: route parcels to delivery zones from free-form addresses with a readable if-then list learned from labels |
 | [examples/09_strategy_at_scale.py](examples/09_strategy_at_scale.py) | Insurance claim desk: the strategist generates a different plan per question set, hard checks first with early exit, slow services in parallel; timed |
 | [examples/10_learn_in_milliseconds.py](examples/10_learn_in_milliseconds.py) | `fit_fast`: a new question learned in milliseconds, then corrected one example at a time (each correction ~0.2 ms, nothing retrained) |
+| [examples/11_answer_types_and_constraints.py](examples/11_answer_types_and_constraints.py) | Multi-label and ordinal answers tied by constraints between answers; contradictions in learned answers are repaired by joint decoding |
 | [examples/07_receipts_model.py](examples/07_receipts_model.py) | Expense check on a scanned receipt: a receipts-tuned extractor cites each field, rules and a hard check decide (needs `solvi[model]`) |
 | [examples/08_contracts_by_description.py](examples/08_contracts_by_description.py) | Contract review with fields defined only in words: the general extractor reads the whole contract, cites clauses or says "absent" (needs `solvi[model]`) |
 

{solvi-0.2.2 → solvi-0.3.0}/README.md

@@ -27,8 +27,13 @@ script that computes everything, and 152 ms when an expired policy settles the c
 
 - [solvi playground](https://huggingface.co/spaces/solvi-ai/playground): write a decision task in Python and run it, watch the
   strategist's plan, tamper with a trace and see the replay catch it, learn rules from examples.
-- [solvi arcade](https://huggingface.co/spaces/solvi-ai/arcade): game agents built from small functions that explain every move.
-- Both run **entirely in your browser** (Pyodide): no server, no GPU, nothing you type leaves the page.
+- [solvi documents](https://huggingface.co/spaces/solvi-ai/documents): cited, typed answers from contracts, invoices, receipts,
+  leases and more — the ModernBERT extractor (ONNX) and the decisions both run in your browser; add a field by describing it.
+- [solvi arcade](https://huggingface.co/spaces/solvi-ai/arcade): game agents that explain every move — tic-tac-toe, maze,
+  minesweeper, 20 questions, Mafia detective, a bot arena, and "hack the trace".
+- [solvi realms](https://huggingface.co/spaces/solvi-ai/realms): an endless strategy game whose factions are solvi systems —
+  tested for 100 000 turns: flat decision time (~0.3–0.6 ms), bounded memory and state, every sampled trace replay OK.
+- All run **entirely in your browser** (Pyodide): no server, no GPU, nothing you type leaves the page.
 - Models: [solvi-ai/extract-base](https://huggingface.co/solvi-ai/extract-base) (fields by description) and
   [solvi-ai/extract-receipts](https://huggingface.co/solvi-ai/extract-receipts).
 
@@ -209,6 +214,7 @@ receipt with the one-pass extractor on an A100).
 | [examples/06_learned_rules.py](examples/06_learned_rules.py) | `learn_rule`: route parcels to delivery zones from free-form addresses with a readable if-then list learned from labels |
 | [examples/09_strategy_at_scale.py](examples/09_strategy_at_scale.py) | Insurance claim desk: the strategist generates a different plan per question set, hard checks first with early exit, slow services in parallel; timed |
 | [examples/10_learn_in_milliseconds.py](examples/10_learn_in_milliseconds.py) | `fit_fast`: a new question learned in milliseconds, then corrected one example at a time (each correction ~0.2 ms, nothing retrained) |
+| [examples/11_answer_types_and_constraints.py](examples/11_answer_types_and_constraints.py) | Multi-label and ordinal answers tied by constraints between answers; contradictions in learned answers are repaired by joint decoding |
 | [examples/07_receipts_model.py](examples/07_receipts_model.py) | Expense check on a scanned receipt: a receipts-tuned extractor cites each field, rules and a hard check decide (needs `solvi[model]`) |
 | [examples/08_contracts_by_description.py](examples/08_contracts_by_description.py) | Contract review with fields defined only in words: the general extractor reads the whole contract, cites clauses or says "absent" (needs `solvi[model]`) |
 

{solvi-0.2.2 → solvi-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "solvi"
-version = "0.2.2"
+version = "0.3.0"
 description = "Decision systems from a catalog of Python functions and checks: a strategist plans the flow, every answer comes with a quote or formula and a verifiable trace"
 readme = "README.md"
 license = "Apache-2.0"

{solvi-0.2.2 → solvi-0.3.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "solvi"
-version = "0.2.2"
+version = "0.3.0"
 description = "Decision systems from a catalog of Python functions and checks: a strategist plans the flow, every answer comes with a quote or formula and a verifiable trace"
 readme = "README.md"
 license = "Apache-2.0"

{solvi-0.2.2 → solvi-0.3.0}/src/solvi/core.py

@@ -21,16 +21,33 @@ class Quote:
 
 @dataclass
 class AnswerType:
-    kind: str                       # yes_no | choice
+    kind: str                       # yes_no | choice | ordinal | multi
     options: list
+    descriptions: dict = field(default_factory=dict)   # option -> what it means (for people and for zero-shot scoring)
 
     def normalize(self, v):
+        if self.kind == "multi":
+            vals = [v] if isinstance(v, str) else list(v or [])
+            bad = [x for x in vals if x not in self.options]
+            if bad:
+                raise ValueError(f"answer {bad!r} not among {self.options}")
+            return tuple(o for o in self.options if o in set(vals))      # canonical: in option order, no duplicates
         if self.kind == "yes_no" and isinstance(v, bool):
             return "yes" if v else "no"
         if v not in self.options:
             raise ValueError(f"answer {v!r} is not one of {self.options}")
         return v
 
+    def rank(self, v):
+        """Position of an ordinal (or choice) answer: 0 for the first option."""
+        return self.options.index(v)
+
+
+def _opts(options):
+    if isinstance(options, dict):
+        return list(options), dict(options)
+    return list(options), {}
+
 
 class Answer:
     @staticmethod
@@ -39,7 +56,19 @@ class Answer:
 
     @staticmethod
     def choice(options) -> AnswerType:
-        return AnswerType("choice", list(options))
+        """One of the options. `options` is a list, or a dict {option: description}."""
+        return AnswerType("choice", *_opts(options))
+
+    @staticmethod
+    def ordinal(levels) -> AnswerType:
+        """One of ordered levels, lowest first (e.g. ["low", "medium", "high"]). A learned head answers with the median of its
+        distribution instead of the most likely level, so it never jumps over the middle."""
+        return AnswerType("ordinal", *_opts(levels))
+
+    @staticmethod
+    def multi(options) -> AnswerType:
+        """Any subset of the options (possibly empty), returned as a tuple in option order. A rule may return a list or set."""
+        return AnswerType("multi", *_opts(options))
 
 
 @dataclass
@@ -69,6 +98,7 @@ class Catalog:
     def __init__(self):
         self.parts: dict[str, Part] = {}
         self.rules: dict[str, Part] = {}
+        self.constraints: dict[str, Part] = {}     # rules between answers of different questions
 
     def _add(self, kind, f, **kw):
         sig = inspect.signature(f)
@@ -76,6 +106,8 @@ class Catalog:
         if kind == "rule":
             p.name = "answer:" + p.question
             self.rules[p.question] = p
+        elif kind == "constraint":
+            self.constraints[p.name] = p
         else:
             if p.name in self.parts:
                 raise ValueError(f"part {p.name} is already in the catalog")
@@ -96,5 +128,11 @@ class Catalog:
     def rule(self, question):
         return lambda f: self._add("rule", f, question=question)
 
+    def constraint(self, f):
+        """A rule between answers: argument names are question names, it returns True when the answers fit together
+        (e.g. `def unsafe_if_harm(verdict, harm): return harm == "none" or verdict == "unsafe"`). When learned answers break it,
+        solvi picks the most probable combination that satisfies every constraint; answers from rules and hard checks stay."""
+        return self._add("constraint", f)
+
     def producer(self, fact):
         return self.parts.get(fact)

{solvi-0.2.2 → solvi-0.3.0}/src/solvi/system.py

@@ -18,6 +18,8 @@ class Response:
     trace: object
     values: dict
     ms: float
+    feasible: bool = True               # do the answers satisfy every applicable constraint?
+    violations: list = None             # names of the constraints still broken (fixed answers that conflict)
 
     def __getitem__(self, q):
         return self.results[q]
@@ -61,7 +63,8 @@ class System:
             if q.name in self.calib and r.status == "ok":
                 r.confidence = _platt(r.confidence, *self.calib[q.name])
             results[q.name] = r
-        resp = Response(results, flow, trace, vals, now_ms() - t0)
+        feasible, violations = self._joint(results)
+        resp = Response(results, flow, trace, vals, now_ms() - t0, feasible, violations)
         if self.journal:
             self._log(init_state, resp)
         return resp
@@ -109,14 +112,86 @@ class System:
         if lost:                                      # a head never guesses from facts that could not be computed
             return Result(None, 0.0, "head features not computed: " + ", ".join(lost), "abstain")
         p = head.predict(vals)
-        a = max(p, key=p.get)
+        if q.answer.kind == "multi":                  # p: option -> probability it applies
+            a = tuple(o for o in q.answer.options if p[o] >= 0.5)
+            base = min(max(v, 1 - v) for v in p.values())
+        elif q.answer.kind == "ordinal":              # median of the distribution over ordered levels
+            acc = 0.0
+            for a in q.answer.options:
+                acc += p[a]
+                if acc >= 0.5:
+                    break
+            base = p[a]
+        else:
+            a = max(p, key=p.get)
+            base = p[a]
         contrib = head.contributions(vals)
         why = ", ".join(f"{f} = {vals.get(f)!r} ({c:+.2f})" for f, c in sorted(contrib.items(), key=lambda t: -abs(t[1]))[:4])
         if soft_failed:
             why += "; failed checks: " + ", ".join(soft_failed)
-        conf = p[a] * path_confidence(self.catalog, trace, head.features)
+        conf = base * path_confidence(self.catalog, trace, head.features)
         return Result(a, conf, why, probs=p)
 
+    # --- constraints between answers: joint decoding
+    def _joint(self, results, max_combos=50_000):
+        import itertools
+        import math
+        cons = [c for c in self.catalog.constraints.values() if all(q in results for q in c.inputs)]
+        if not cons:
+            return True, []
+
+        def ok(assign, c):
+            if any(assign.get(q) is None for q in c.inputs):
+                return True                           # an abstained answer: nothing to check
+            try:
+                return bool(c.func(**{q: assign[q] for q in c.inputs}))
+            except Exception:  # noqa: BLE001
+                return False
+        current = {q: r.answer for q, r in results.items()}
+        if all(ok(current, c) for c in cons):
+            return True, []
+        # candidates: learned answers may change (their distribution), rule / forced / abstained answers are fixed
+        qs = sorted({q for c in cons for q in c.inputs})
+        cands = {}
+        for q in qs:
+            r, at = results[q], self.questions[q].answer
+            if r.status == "ok" and r.probs:
+                if at.kind == "multi":
+                    opts = []
+                    for bits in itertools.product([0, 1], repeat=len(at.options)):
+                        combo = tuple(o for o, b in zip(at.options, bits) if b)
+                        lp = sum(math.log(max(1e-9, r.probs[o] if b else 1 - r.probs[o])) for o, b in zip(at.options, bits))
+                        opts.append((combo, lp))
+                else:
+                    opts = [(o, math.log(max(1e-9, pr))) for o, pr in r.probs.items()]
+                cands[q] = sorted(opts, key=lambda t: -t[1])
+            else:
+                cands[q] = [(r.answer, 0.0)]
+        k = max(len(v) for v in cands.values())
+        while k > 1 and math.prod(min(len(v), k) for v in cands.values()) > max_combos:
+            k -= 1
+        best = None
+        for combo in itertools.product(*[cands[q][:k] for q in qs]):
+            assign = dict(current)
+            assign.update({q: a for q, (a, _) in zip(qs, combo)})
+            if all(ok(assign, c) for c in cons):
+                score = sum(lp for _, lp in combo)
+                if best is None or score > best[0]:
+                    best = (score, assign)
+        if best is None:
+            return False, [c.name for c in cons if not ok(current, c)]
+        for q in qs:
+            r = results[q]
+            if best[1][q] != r.answer:
+                was = r.answer
+                r.answer = best[1][q]
+                if r.probs:
+                    r.confidence = (math.exp(dict(cands[q])[r.answer]) if self.questions[q].answer.kind == "multi"
+                                    else r.probs.get(r.answer, r.confidence))
+                broken = [c.name for c in cons if q in c.inputs and not ok({**current}, c)]
+                r.why += f"; changed from {was!r} to satisfy {', '.join(broken)}"
+        return True, []
+
     # --- task-specific training
     def facts_for(self, init_state):
         """All computable facts (for head training): a "compute everything" flow without rules."""
@@ -135,7 +210,11 @@ class System:
         ans = [q.answer.normalize(a) for _, a in examples]
         keys = set(examples[0][0].keys())
         cands = sorted(f for f in computable(self.catalog, keys) - keys)
-        self.heads[question] = Head(q.answer.options).fit(rows, ans, cands)
+        if q.answer.kind == "multi":
+            self.heads[question] = MultiHead(q.answer.options, lambda: Head(["yes", "no"]),
+                                             lambda h, ys: h.fit(rows, ys, cands)).fit(ans)
+        else:
+            self.heads[question] = Head(q.answer.options).fit(rows, ans, cands)
         return self.heads[question]
 
     def fit_fast(self, question, examples, features=None, lam=None):
@@ -150,7 +229,12 @@ class System:
         if features is None:
             keys = set(examples[0][0].keys())
             features = sorted(f for f in computable(self.catalog, keys) - keys)
-        head = FastHead(q.answer.options, lam=lam).fit(rows, [q.answer.normalize(a) for _, a in examples], list(features))
+        ans = [q.answer.normalize(a) for _, a in examples]
+        if q.answer.kind == "multi":
+            head = MultiHead(q.answer.options, lambda: FastHead(["yes", "no"], lam=lam),
+                             lambda h, ys: h.fit(rows, ys, list(features))).fit(ans)
+        else:
+            head = FastHead(q.answer.options, lam=lam).fit(rows, ans, list(features))
         head.fit_ms = (time.perf_counter() - t0) * 1000
         self.heads[question] = head
         return head
@@ -201,7 +285,7 @@ class System:
         from .fast import FastHead
         ms = None
         head = self.heads.get(question)
-        if isinstance(head, FastHead):
+        if isinstance(head, (FastHead, MultiHead)) and getattr(head, "online", True):
             ms = head.update(self.facts_for(init_state), self.questions[question].answer.normalize(correct))
         if self.journal:
             with open(self.journal, "a") as fh:
@@ -216,6 +300,40 @@ class System:
                                  "records": [[r.step, r.name, r.hash] for r in resp.trace.records]}, ensure_ascii=False) + "\n")
 
 
+class MultiHead:
+    """A multi-label answer as one yes/no head per option (each learned with fit or fit_fast)."""
+
+    def __init__(self, options, make, train):
+        self.options, self.make, self.train = list(options), make, train
+        self.heads = {}
+
+    def fit(self, answers):
+        for o in self.options:
+            self.heads[o] = self.train(self.make(), ["yes" if o in a else "no" for a in answers])
+        h = next(iter(self.heads.values()))
+        self.features = sorted({f for hh in self.heads.values() for f in hh.features})
+        self.online = hasattr(h, "update")
+        self.loo_acc = getattr(h, "loo_acc", None)
+        return self
+
+    @property
+    def cv_acc(self):
+        return self.loo_acc
+
+    def predict(self, row):
+        return {o: h.predict(row)["yes"] for o, h in self.heads.items()}
+
+    def contributions(self, row):
+        out = {}
+        for h in self.heads.values():
+            for f, c in h.contributions(row).items():
+                out[f] = out.get(f, 0.0) + c
+        return out
+
+    def update(self, row, answer):
+        return sum(h.update(row, "yes" if o in answer else "no") for o, h in self.heads.items())
+
+
 def governs(part, question):
     """Does a failed hard check decide this question? Yes if the question is in its `then`, names it as a checkpoint, or the
     check has no `then` at all."""