decision-circuits 0.1.0__tar.gz

decision_circuits-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+dist/
+__pycache__/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/

decision_circuits-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 James Barney
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

decision_circuits-0.1.0/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.5
+Name: decision-circuits
+Version: 0.1.0
+Summary: Deterministic decision gates over calibrated model answers: a small DSL that compiles to System One requests, evaluates AND/OR/NOT/threshold/argmax/majority/verify/order gates with explicit uncertainty, and renders the circuit.
+Project-URL: Homepage, https://github.com/Barneyjm/decision-circuits
+Project-URL: Article, https://towardsdatascience.com/attaining-llm-certainty-with-ai-decision-circuits/
+Author: James Barney
+License-Expression: MIT
+License-File: LICENSE
+Keywords: calibration,decision-circuits,gates,guardrails,llm,system-one,typesafe
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: pydantic>=2.0
+Provides-Extra: http
+Requires-Dist: httpx>=0.25; extra == 'http'
+Description-Content-Type: text/markdown
+
+# decision-circuits
+
+Deterministic decision gates over calibrated model answers.
+
+A System One style model (TypeSafe's Jev, or an open model that speaks
+the same contract) answers typed questions about a piece of state and
+returns probabilities, not prose. A **decision circuit** is a set of
+questions plus a set of **gates**: code that combines those
+probabilities into decisions with thresholds, boolean logic, votes,
+verification, and ordinal buckets, and that says out loud when it is
+uncertain instead of guessing.
+
+The model never sees the gates. That makes a circuit versionable,
+testable offline, and auditable per item: every result carries its
+probability, its outcome (`decided`, `abstain`, `escalate`, `default`),
+and a trace of every input that fed it.
+
+Background: [Attaining LLM Certainty with AI Decision Circuits](https://towardsdatascience.com/attaining-llm-certainty-with-ai-decision-circuits/).
+
+```bash
+pip install decision-circuits
+```
+
+## Example
+
+```python
+import httpx
+from decision_circuits import Circuit, Q, G, argmax, order
+
+c = Circuit()
+c.noul(
+    "pii",
+    "Does this text contain PII about a private individual?",
+    true="Email, phone, home address, ID, or card number",
+    false="No PII, or business-only details",
+)
+c.noul("business", "Are all identifying details about a business rather than a person?")
+c.noul("angry", "Is the customer angry?")
+c.choice("dept", "Which team should handle this?", {"billing": "Charges, refunds, invoices", "technical": "Bugs, outages, API", "other": "Anything else"})
+c.score("urgency", "How urgent is this?", ["Low", "Medium", "High", "Critical"])
+
+c.gate("redact", ((Q("pii") >= 0.7) & ~Q("business")) >= 0.6, on_uncertain="escalate")
+c.gate("route", argmax("dept", min_confidence=0.35))
+c.gate("tier", order("urgency", [1.0, 2.0, 2.6]))
+c.gate("human", (Q("angry") | Q("urgency")[3]) >= 0.6, on_uncertain="escalate")
+c.gate("bill_hot", (G("route")["billing"] & G("tier")[3]).at(0.5))
+
+out = c.run(
+    httpx.Client(),
+    "Card charged twice, refund NOW, my card ends in 4412.",
+    url="https://api.typesafe.ai/v1/systemone",
+    headers={"Authorization": f"Bearer {TYPESAFE_API_KEY}"},
+)
+
+out["gates"]["redact"]
+# {"value": True, "p": 0.88, "outcome": "decided", "trace": [...]}
+out["gates"]["route"]
+# {"value": "billing", "p": 0.81, "outcome": "decided", ...}
+```
+
+`run` posts the circuit as a normal System One request. If the server
+evaluates gates itself, its results are used. If it returns answers
+only (TypeSafe today), the gates are evaluated on the client from the
+returned probabilities. `out["gates_evaluated_by"]` says which.
+
+## The expression language
+
+| form | meaning |
+|---|---|
+| `Q("noul_id")` | P(yes) for a yes/no question |
+| `Q("choice_id")["option"]` | probability of one option |
+| `Q("score_id")[level]` | probability of one score level |
+| `G("gate_id")`, `G("gate_id")["value"]` | an earlier gate's probability, or one value of a categorical gate |
+| `~e` | NOT: `1 - p` |
+| `a & b & c` | AND: product (independence assumed and recorded in the trace) |
+| `a \| b` | OR: `1 - prod(1 - p)` |
+| `e >= tau`, `e.at(tau)` | threshold: boolean at `tau` with an uncertainty band around it |
+| `argmax("choice_id", min_confidence=...)` | pick the top option; abstain below the confidence floor |
+| `majority("c1", "c2", "c3")` | vote across paraphrased questions over the same options |
+| `verify("choice_id", check=Q("supported"), tau=...)` | a negative checker: escalate when the check does not support the pick |
+| `order("score_id", [c1, c2, ...])` | bucket the expected score by cutpoints |
+
+An expression used as a gate without a threshold thresholds at 0.5.
+`e >= tau` builds a node and does not compare; `bool(Q("x") >= 0.7)` is
+always true, so use `.at(tau)` anywhere an operator would read as a
+runtime comparison.
+
+Every gate takes `on_uncertain="abstain" | "escalate" | "default"`
+(with `default=value`) and `band=width`. A gate is uncertain when the
+probability it acts on lies within `band` of its threshold, or when a
+confidence floor fails. Uncertainty is surfaced, never silently
+resolved.
+
+## Without a server
+
+`c.compile()` returns the flat `gates` map (the wire format).
+`c.evaluate(answers)` runs the gates against answers you already have,
+in the response format of any System One server. `evaluate_gates` is
+the underlying function if you build the map by hand.
+
+## Diagram
+
+`c.to_mermaid()` renders the circuit as a Mermaid flowchart with three
+columns, inputs, logic, and decisions; pass the results of a run to
+color each node by outcome. Paste it into a README or render it with
+`mmdc`.
+
+```python
+print(c.to_mermaid(results=out["gates"], answers=out["answers"]))
+```
+
+## Status
+
+Alpha. The wire format is TypeSafe's `POST /v1/systemone` request with
+an added `gates` block; the reference server that evaluates gates is
+[s1proto](https://github.com/Barneyjm/s1-proto). The gate semantics
+(`and` as a product, `or` as noisy-or) assume independent questions;
+the trace records that assumption on every result so a reviewer can
+see it.

decision_circuits-0.1.0/README.md

@@ -0,0 +1,119 @@
+# decision-circuits
+
+Deterministic decision gates over calibrated model answers.
+
+A System One style model (TypeSafe's Jev, or an open model that speaks
+the same contract) answers typed questions about a piece of state and
+returns probabilities, not prose. A **decision circuit** is a set of
+questions plus a set of **gates**: code that combines those
+probabilities into decisions with thresholds, boolean logic, votes,
+verification, and ordinal buckets, and that says out loud when it is
+uncertain instead of guessing.
+
+The model never sees the gates. That makes a circuit versionable,
+testable offline, and auditable per item: every result carries its
+probability, its outcome (`decided`, `abstain`, `escalate`, `default`),
+and a trace of every input that fed it.
+
+Background: [Attaining LLM Certainty with AI Decision Circuits](https://towardsdatascience.com/attaining-llm-certainty-with-ai-decision-circuits/).
+
+```bash
+pip install decision-circuits
+```
+
+## Example
+
+```python
+import httpx
+from decision_circuits import Circuit, Q, G, argmax, order
+
+c = Circuit()
+c.noul(
+    "pii",
+    "Does this text contain PII about a private individual?",
+    true="Email, phone, home address, ID, or card number",
+    false="No PII, or business-only details",
+)
+c.noul("business", "Are all identifying details about a business rather than a person?")
+c.noul("angry", "Is the customer angry?")
+c.choice("dept", "Which team should handle this?", {"billing": "Charges, refunds, invoices", "technical": "Bugs, outages, API", "other": "Anything else"})
+c.score("urgency", "How urgent is this?", ["Low", "Medium", "High", "Critical"])
+
+c.gate("redact", ((Q("pii") >= 0.7) & ~Q("business")) >= 0.6, on_uncertain="escalate")
+c.gate("route", argmax("dept", min_confidence=0.35))
+c.gate("tier", order("urgency", [1.0, 2.0, 2.6]))
+c.gate("human", (Q("angry") | Q("urgency")[3]) >= 0.6, on_uncertain="escalate")
+c.gate("bill_hot", (G("route")["billing"] & G("tier")[3]).at(0.5))
+
+out = c.run(
+    httpx.Client(),
+    "Card charged twice, refund NOW, my card ends in 4412.",
+    url="https://api.typesafe.ai/v1/systemone",
+    headers={"Authorization": f"Bearer {TYPESAFE_API_KEY}"},
+)
+
+out["gates"]["redact"]
+# {"value": True, "p": 0.88, "outcome": "decided", "trace": [...]}
+out["gates"]["route"]
+# {"value": "billing", "p": 0.81, "outcome": "decided", ...}
+```
+
+`run` posts the circuit as a normal System One request. If the server
+evaluates gates itself, its results are used. If it returns answers
+only (TypeSafe today), the gates are evaluated on the client from the
+returned probabilities. `out["gates_evaluated_by"]` says which.
+
+## The expression language
+
+| form | meaning |
+|---|---|
+| `Q("noul_id")` | P(yes) for a yes/no question |
+| `Q("choice_id")["option"]` | probability of one option |
+| `Q("score_id")[level]` | probability of one score level |
+| `G("gate_id")`, `G("gate_id")["value"]` | an earlier gate's probability, or one value of a categorical gate |
+| `~e` | NOT: `1 - p` |
+| `a & b & c` | AND: product (independence assumed and recorded in the trace) |
+| `a \| b` | OR: `1 - prod(1 - p)` |
+| `e >= tau`, `e.at(tau)` | threshold: boolean at `tau` with an uncertainty band around it |
+| `argmax("choice_id", min_confidence=...)` | pick the top option; abstain below the confidence floor |
+| `majority("c1", "c2", "c3")` | vote across paraphrased questions over the same options |
+| `verify("choice_id", check=Q("supported"), tau=...)` | a negative checker: escalate when the check does not support the pick |
+| `order("score_id", [c1, c2, ...])` | bucket the expected score by cutpoints |
+
+An expression used as a gate without a threshold thresholds at 0.5.
+`e >= tau` builds a node and does not compare; `bool(Q("x") >= 0.7)` is
+always true, so use `.at(tau)` anywhere an operator would read as a
+runtime comparison.
+
+Every gate takes `on_uncertain="abstain" | "escalate" | "default"`
+(with `default=value`) and `band=width`. A gate is uncertain when the
+probability it acts on lies within `band` of its threshold, or when a
+confidence floor fails. Uncertainty is surfaced, never silently
+resolved.
+
+## Without a server
+
+`c.compile()` returns the flat `gates` map (the wire format).
+`c.evaluate(answers)` runs the gates against answers you already have,
+in the response format of any System One server. `evaluate_gates` is
+the underlying function if you build the map by hand.
+
+## Diagram
+
+`c.to_mermaid()` renders the circuit as a Mermaid flowchart with three
+columns, inputs, logic, and decisions; pass the results of a run to
+color each node by outcome. Paste it into a README or render it with
+`mmdc`.
+
+```python
+print(c.to_mermaid(results=out["gates"], answers=out["answers"]))
+```
+
+## Status
+
+Alpha. The wire format is TypeSafe's `POST /v1/systemone` request with
+an added `gates` block; the reference server that evaluates gates is
+[s1proto](https://github.com/Barneyjm/s1-proto). The gate semantics
+(`and` as a product, `or` as noisy-or) assume independent questions;
+the trace records that assumption on every result so a reviewer can
+see it.

decision_circuits-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[project]
+name = "decision-circuits"
+version = "0.1.0"
+description = "Deterministic decision gates over calibrated model answers: a small DSL that compiles to System One requests, evaluates AND/OR/NOT/threshold/argmax/majority/verify/order gates with explicit uncertainty, and renders the circuit."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "James Barney" }]
+keywords = ["decision-circuits", "system-one", "typesafe", "calibration", "gates", "llm", "guardrails"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Typing :: Typed",
+]
+dependencies = ["pydantic>=2.0"]
+
+[project.optional-dependencies]
+http = ["httpx>=0.25"]
+
+[project.urls]
+Homepage = "https://github.com/Barneyjm/decision-circuits"
+Article = "https://towardsdatascience.com/attaining-llm-certainty-with-ai-decision-circuits/"
+
+[dependency-groups]
+dev = ["pytest>=8", "ruff>=0.6", "httpx>=0.25"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/decision_circuits"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/decision_circuits", "tests", "README.md", "LICENSE"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 160
+target-version = "py310"

decision_circuits-0.1.0/src/decision_circuits/__init__.py

@@ -0,0 +1,66 @@
+"""Decision circuits: deterministic gates over calibrated model answers.
+
+Build a circuit with the DSL, send it to any System One style server
+(TypeSafe's Jev, or an open model speaking the same contract), and get
+back typed decisions with probabilities, traces, and explicit
+uncertainty handling. Gates are evaluated by the server when it
+supports them and here on the client otherwise, so the result is the
+same either way.
+
+    from decision_circuits import Circuit, Q, argmax
+
+    c = Circuit()
+    c.noul("pii", "Does this text contain PII about a private individual?")
+    c.choice("dept", "Which team?", {"billing": None, "technical": None, "other": None})
+    c.gate("redact", Q("pii") >= 0.7, on_uncertain="escalate")
+    c.gate("route", argmax("dept", min_confidence=0.35))
+
+    out = c.run(httpx.Client(), state, url="https://api.typesafe.ai/v1/systemone",
+                headers={"Authorization": f"Bearer {key}"})
+    out["gates"]["redact"]   # {"value": True, "p": 0.91, "outcome": "decided", "trace": [...]}
+"""
+
+from decision_circuits.dsl import (
+    And,
+    Categorical,
+    Circuit,
+    Expr,
+    G,
+    GateDef,
+    Not,
+    Or,
+    Q,
+    Threshold,
+    argmax,
+    majority,
+    order,
+    render_mermaid,
+    to_mermaid,
+    verify,
+)
+from decision_circuits.gates import Gate, GateResult, evaluate_gates
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "And",
+    "Categorical",
+    "Circuit",
+    "Expr",
+    "G",
+    "Gate",
+    "GateDef",
+    "GateResult",
+    "Not",
+    "Or",
+    "Q",
+    "Threshold",
+    "__version__",
+    "argmax",
+    "evaluate_gates",
+    "majority",
+    "order",
+    "render_mermaid",
+    "to_mermaid",
+    "verify",
+]

decision_circuits-0.1.0/src/decision_circuits/dsl.py

@@ -0,0 +1,507 @@
+"""A small expression language for decision circuits.
+
+Symbolic references combine with Python operators and compile to the
+`gates` block the server evaluates. Same idiom as Django `Q` objects
+or Polars expressions: build an expression, hand it to the request.
+
+    from decision_circuits import Circuit, Q, G, argmax, majority, verify, order
+
+    c = Circuit()
+    c.noul("pii", "Does this text contain PII about a private individual?",
+           true="Email, phone, home address, ID, card number", false="No PII or business-only")
+    c.noul("business", "Are all identifying details about a business, not a person?")
+    c.choice("dept", "Which team?", {"billing": "...", "technical": "...", "other": "..."})
+    c.score("urgency", "How urgent?", ["Low", "Medium", "High", "Critical"])
+
+    c.gate("redact", ((Q("pii") >= 0.7) & ~Q("business")) >= 0.6, on_uncertain="escalate")
+    c.gate("route", argmax("dept", min_confidence=0.35))
+    c.gate("tier", order("urgency", [1.0, 2.0, 2.6]))
+    c.gate("human", (Q("angry") | Q("urgency")[3]) >= 0.6, on_uncertain="escalate")
+    c.gate("bill_hot", (G("route")["billing"] & G("tier")[3]).at(0.5))
+
+    body = c.request(state)          # JSON body for POST /v1/systemone
+    out = c.run(client, state)       # or evaluate through a TestClient / httpx client
+
+Semantics, in one paragraph. `Q("x")` is the probability behind a
+question: a noul's P(yes), `Q("choice")["option"]` or `Q("score")[level]`
+for one outcome (the `"choice:option"` string form also works), or
+`G("name")` for an earlier gate, indexed the same way for categorical
+gates. `~` flips it (a `not`
+gate), `&` multiplies (an `and` gate, independence assumed and printed
+in the trace), `|` is 1 - prod(1 - p) (an `or` gate). `>= tau` turns a
+probability into a boolean at that threshold with an uncertainty band
+around it; an expression used as a gate without `>=` thresholds at 0.5.
+`argmax`, `majority`, `verify`, `order` are the categorical/ordinal
+gates. Every gate carries `.on_uncertain("abstain" | "escalate" | "default", default=...)`
+and `.band(width)`.
+"""
+
+from __future__ import annotations
+
+import itertools
+from dataclasses import dataclass, field
+from typing import Any
+
+from decision_circuits.gates import Gate, evaluate_gates
+
+# ---------------------------------------------------------------- expressions
+
+
+class Expr:
+    """Base for probability-valued expressions."""
+
+    def __and__(self, other: Expr) -> And:
+        return And([self, _as_expr(other)])
+
+    def __or__(self, other: Expr) -> Or:
+        return Or([self, _as_expr(other)])
+
+    def __invert__(self) -> Not:
+        return Not(self)
+
+    def __ge__(self, tau: float) -> Threshold:
+        """`expr >= tau` builds a Threshold node; it does not compare.
+        `bool(Q("pii") >= 0.7)` is always True. Use `.at(tau)` where an
+        operator would read as a runtime comparison."""
+        return Threshold(self, float(tau))
+
+    def at(self, tau: float) -> Threshold:
+        """Named form of `>=`: `Q("pii").at(0.7)`."""
+        return Threshold(self, float(tau))
+
+
+def _as_expr(x: Any) -> Expr:
+    if isinstance(x, Expr):
+        return x
+    if isinstance(x, str):
+        return Q(x)
+    raise TypeError(f"cannot use {x!r} in a circuit expression")
+
+
+@dataclass(frozen=True)
+class Q(Expr):
+    """A question reference. A noul id is a probability on its own;
+    index a choice or score to get one option's probability:
+    `Q("dept")["billing"]`, `Q("urgency")[3]` (the `"dept:billing"`
+    string form is accepted too)."""
+
+    ref: str
+
+    def __getitem__(self, key: Any) -> Q:
+        if ":" in self.ref:
+            raise KeyError(f"{self.ref!r} already names an option")
+        return Q(f"{self.ref}:{key}")
+
+
+@dataclass(frozen=True)
+class G(Expr):
+    """A reference to an earlier gate. A boolean gate is a probability on
+    its own; index a categorical gate for one value: `G("route")["billing"]`."""
+
+    ref: str
+
+    def __getitem__(self, key: Any) -> G:
+        if ":" in self.ref:
+            raise KeyError(f"{self.ref!r} already names a value")
+        return G(f"{self.ref}:{key}")
+
+
+@dataclass(frozen=True)
+class Not(Expr):
+    inner: Expr
+
+
+@dataclass(frozen=True)
+class And(Expr):
+    parts: list[Expr]
+
+    def __and__(self, other: Expr) -> And:  # flatten chains
+        return And([*self.parts, _as_expr(other)])
+
+
+@dataclass(frozen=True)
+class Or(Expr):
+    parts: list[Expr]
+
+    def __or__(self, other: Expr) -> Or:
+        return Or([*self.parts, _as_expr(other)])
+
+
+@dataclass(frozen=True)
+class Threshold(Expr):
+    inner: Expr
+    tau: float
+
+
+# categorical / ordinal gate constructors ----------------------------------
+
+
+@dataclass(frozen=True)
+class Categorical:
+    op: str
+    input: str | None = None
+    inputs: list[str] | None = None
+    check: Expr | None = None
+    tau: float = 0.5
+    min_confidence: float = 0.0
+    cutpoints: list[float] | None = None
+
+
+def argmax(choice_id: str, min_confidence: float = 0.0) -> Categorical:
+    return Categorical("argmax", input=choice_id, min_confidence=min_confidence)
+
+
+def majority(*choice_ids: str, min_confidence: float = 0.0) -> Categorical:
+    return Categorical("majority", inputs=list(choice_ids), min_confidence=min_confidence)
+
+
+def verify(choice_id: str, check: Expr | str, tau: float = 0.6, min_confidence: float = 0.0) -> Categorical:
+    return Categorical("verify", input=choice_id, check=_as_expr(check), tau=tau, min_confidence=min_confidence)
+
+
+def order(score_id: str, cutpoints: list[float]) -> Categorical:
+    return Categorical("order", input=score_id, cutpoints=list(cutpoints))
+
+
+# ---------------------------------------------------------------- circuit
+
+
+@dataclass
+class GateDef:
+    name: str
+    body: Expr | Categorical
+    on_uncertain_: str = "abstain"
+    default_: Any = None
+    band_: float = 0.1
+
+    def on_uncertain(self, policy: str, default: Any = None) -> GateDef:
+        self.on_uncertain_ = policy
+        self.default_ = default
+        return self
+
+    def band(self, width: float) -> GateDef:
+        self.band_ = width
+        return self
+
+
+@dataclass
+class Circuit:
+    questions: dict[str, dict[str, Any]] = field(default_factory=dict)
+    gates: list[GateDef] = field(default_factory=list)
+    model: str = "s1-proto"
+    _server_gates: bool | None = field(default=None, repr=False, compare=False)
+
+    # questions ---------------------------------------------------------
+    def noul(self, qid: str, instructions: Any, true: str | None = None, false: str | None = None) -> Circuit:
+        q: dict[str, Any] = {"type": "noul", "instructions": instructions}
+        if true or false:
+            q["criteria"] = {"true": true, "false": false}
+        self.questions[qid] = q
+        return self
+
+    def choice(self, qid: str, instructions: Any, criteria: dict[str, Any]) -> Circuit:
+        self.questions[qid] = {"type": "choice", "instructions": instructions, "criteria": criteria}
+        return self
+
+    def score(self, qid: str, instructions: Any, levels: list[Any]) -> Circuit:
+        self.questions[qid] = {"type": "score", "instructions": instructions, "criteria": levels}
+        return self
+
+    # gates -------------------------------------------------------------
+    def gate(
+        self,
+        name: str,
+        body: Expr | Categorical | str,
+        *,
+        on_uncertain: str | None = None,
+        default: Any = None,
+        band: float | None = None,
+    ) -> GateDef:
+        """Add a gate. Policy can be given as keywords here or chained on
+        the returned GateDef (`.on_uncertain(...)`, `.band(...)`)."""
+        g = GateDef(name, _as_expr(body) if isinstance(body, str) else body)
+        if on_uncertain is not None:
+            g.on_uncertain(on_uncertain, default)
+        if band is not None:
+            g.band(band)
+        self.gates.append(g)
+        return g
+
+    # rendering ---------------------------------------------------------
+    def to_mermaid(self, results: dict[str, Any] | None = None, answers: dict[str, Any] | None = None, direction: str = "LR", plain: bool = False) -> str:
+        """Schematic of the compiled circuit; see `render_mermaid`."""
+        return render_mermaid(self, results, answers, direction, plain)
+
+    # compile -----------------------------------------------------------
+    def compile(self) -> dict[str, dict[str, Any]]:
+        """Lower the expression trees to the server's flat `gates` map.
+        Sub-expressions become auto-named helper gates (`_name_N`) so
+        every intermediate probability shows up in the trace."""
+        out: dict[str, dict[str, Any]] = {}
+        counter = itertools.count(1)
+
+        def helper(prefix: str, spec: dict[str, Any]) -> str:
+            name = f"_{prefix}_{next(counter)}"
+            out[name] = spec
+            return name
+
+        def ref_of(e: Expr, prefix: str) -> str:
+            """A string reference the server accepts for this expression,
+            emitting helper gates where needed."""
+            if isinstance(e, Q | G):
+                return e.ref
+            if isinstance(e, Not):
+                return helper(prefix, {"op": "not", "input": ref_of(e.inner, prefix), "tau": 0.5, "band": 0.0})
+            if isinstance(e, And | Or):
+                return helper(prefix, {"op": "and" if isinstance(e, And) else "or", "inputs": [ref_of(p, prefix) for p in e.parts], "tau": 0.5, "band": 0.0})
+            if isinstance(e, Threshold):
+                return helper(prefix, {"op": "threshold", "input": ref_of(e.inner, prefix), "tau": e.tau, "band": 0.0})
+            raise TypeError(f"unsupported expression {e!r}")
+
+        for g in self.gates:
+            common = {"on_uncertain": g.on_uncertain_, "band": g.band_}
+            if g.on_uncertain_ == "default":
+                common["default"] = g.default_
+            b = g.body
+            if isinstance(b, Categorical):
+                spec: dict[str, Any] = {"op": b.op, "tau": b.tau, "min_confidence": b.min_confidence}
+                if b.input is not None:
+                    spec["input"] = b.input
+                if b.inputs is not None:
+                    spec["inputs"] = b.inputs
+                if b.check is not None:
+                    spec["check"] = ref_of(b.check, g.name)
+                if b.cutpoints is not None:
+                    spec["cutpoints"] = b.cutpoints
+                out[g.name] = {**spec, **common}
+                continue
+            # boolean expression: the top node becomes the named gate
+            tau = 0.5
+            e = b
+            if isinstance(e, Threshold):
+                tau, e = e.tau, e.inner
+            if isinstance(e, Q | G):
+                out[g.name] = {"op": "threshold", "input": e.ref, "tau": tau, **common}
+            elif isinstance(e, Not):
+                out[g.name] = {"op": "not", "input": ref_of(e.inner, g.name), "tau": tau, **common}
+            elif isinstance(e, And | Or):
+                out[g.name] = {"op": "and" if isinstance(e, And) else "or", "inputs": [ref_of(p, g.name) for p in e.parts], "tau": tau, **common}
+            else:
+                raise TypeError(f"unsupported gate body {b!r}")
+        return out
+
+    def request(self, state: Any) -> dict[str, Any]:
+        return {"state": state, "model": self.model, "questions": dict(self.questions), "gates": self.compile()}
+
+    def evaluate(self, answers: dict[str, Any]) -> dict[str, Any]:
+        """Evaluate the compiled gates locally against answers already in hand."""
+        res = evaluate_gates({k: Gate.model_validate(v) for k, v in self.compile().items()}, answers)
+        return {k: v.model_dump() for k, v in res.items() if not k.startswith("_")}
+
+    def run(self, client: Any, state: Any, url: str = "/v1/systemone", headers: dict[str, str] | None = None, gates: str = "auto") -> dict[str, Any]:
+        """POST through any client with `.post(url, json=..., headers=...)`
+        returning `.json()` (httpx, requests, FastAPI TestClient).
+
+        `gates="auto"` sends the compiled gates and lets the server
+        evaluate them if it can; a server that rejects the extra field
+        (TypeSafe today) or returns answers only gets a second request
+        without gates, and they are evaluated here. The outcome is cached
+        per Circuit so later calls make one request. `"server"` requires
+        server evaluation; `"client"` never sends gates."""
+        if gates not in ("auto", "server", "client"):
+            raise ValueError("gates must be 'auto', 'server', or 'client'")
+        body: dict[str, Any] | None = None
+        try_server = gates == "server" or (gates == "auto" and self._server_gates is not False)
+        if try_server:
+            r = client.post(url, json=self.request(state), headers=headers)
+            body = r.json()
+            ok = getattr(r, "status_code", 200) < 400 and "gates" in body
+            if ok:
+                self._server_gates = True
+                body["gates"] = {k: v for k, v in body["gates"].items() if not k.startswith("_")}
+                body["gates_evaluated_by"] = "server"
+                return body
+            if gates == "server":
+                raise RuntimeError(f"server did not evaluate gates: {str(body)[:200]}")
+            self._server_gates = False
+        req = {k: v for k, v in self.request(state).items() if k != "gates"}
+        r = client.post(url, json=req, headers=headers)
+        body = r.json()
+        if "answers" not in body:
+            raise RuntimeError(f"unexpected response: {str(body)[:200]}")
+        body["gates"] = self.evaluate(body["answers"])
+        body["gates_evaluated_by"] = "client"
+        return body
+
+
+# ---------------------------------------------------------------- rendering
+
+
+def _short(s: str, n: int = 38) -> str:
+    s = " ".join(str(s).split())
+    return s if len(s) <= n else s[: n - 1] + "…"
+
+
+def render_mermaid(
+    circuit: Circuit, results: dict[str, Any] | None = None, answers: dict[str, Any] | None = None, direction: str = "LR", plain: bool = False
+) -> str:
+    """Render the compiled circuit as a schematic. `plain=True` omits the
+    init directive and inline HTML styling for stricter renderers (some
+    hosted Mermaid builds reject them); layout is the same.
+
+    Schematic: an input column of
+    questions, a logic column of gates, and a decisions column for the
+    gates nothing else consumes. Threshold and NOT helpers are folded
+    into edge labels rather than drawn as nodes. Only decisions are
+    coloured: green yes / grey no / amber abstained or escalated."""
+    compiled = circuit.compile()
+
+    # which gates feed other gates (their base name before ':')
+    consumers: dict[str, set[str]] = {g: set() for g in compiled}
+    for gid, spec in compiled.items():
+        refs = ([spec["input"]] if spec.get("input") else []) + list(spec.get("inputs", [])) + ([spec["check"]] if spec.get("check") else [])
+        for ref in refs:
+            base = ref.partition(":")[0]
+            if base in consumers:
+                consumers[base].add(gid)
+
+    # helpers that fold into an edge: threshold/not with one consumer
+    folded: dict[str, tuple[str, str]] = {}  # helper -> (source ref, label)
+    for gid, spec in compiled.items():
+        if gid.startswith("_") and spec["op"] in ("threshold", "not") and len(consumers[gid]) == 1:
+            src_ref = spec["input"]
+            lab = "NOT" if spec["op"] == "not" else f"≥ {spec['tau']:g}"
+            # chain: a folded helper feeding a folded helper
+            while src_ref in folded:
+                inner_src, inner_lab = folded[src_ref]
+                lab = f"{inner_lab} · {lab}"
+                src_ref = inner_src
+            folded[gid] = (src_ref, lab)
+
+    def qnode(qid: str) -> str:
+        return f"q_{qid}"
+
+    def gnode(gid: str) -> str:
+        return "g_" + gid.replace("-", "_")
+
+    init = (
+        "%%{init: {'theme': 'base', 'flowchart': {'nodeSpacing': 40, 'rankSpacing': 120, 'curve': 'basis', 'useMaxWidth': false, 'htmlLabels': true}, "
+        "'themeVariables': {'fontFamily': 'IBM Plex Sans, system-ui, sans-serif', 'fontSize': '13px', 'lineColor': '#5F6B78'}}}%%"
+    )
+    L = [
+        *([] if plain else [init]),
+        f"flowchart {direction}",
+        "  classDef q fill:#FFFFFF,stroke:#1264A3,stroke-width:1.5px,color:#1B1F24;",
+        "  classDef logic fill:#F7F8F6,stroke:#5F6B78,stroke-width:1.5px,color:#1B1F24;",
+        "  classDef yes fill:#DDF3E4,stroke:#2E7D4F,stroke-width:2.5px,color:#0F3D22;",
+        "  classDef no fill:#EEF0F2,stroke:#98A2AD,stroke-width:2px,color:#3B4550;",
+        "  classDef hold fill:#FFF1CC,stroke:#9A6B00,stroke-width:2.5px,color:#4A3300;",
+        "  classDef col fill:none,stroke:#D9DEE3,stroke-dasharray:3 3,color:#5F6B78;",
+    ]
+
+    # --- inputs
+    L.append('  subgraph IN["Inputs"]')
+    L.append("    direction TB")
+    for qid, q in circuit.questions.items():
+        kind = q["type"]
+        if answers and qid in answers:
+            a = answers[qid]
+            if kind == "noul":
+                val = f"yes {a['noul']:.0%}"
+            elif kind == "choice":
+                val = f"{a['choice']} {a['probabilities'][a['choice']]:.0%}"
+            else:
+                val = f"{a['score']:.1f} / {len(q['criteria']) - 1}"
+            label = f"<b>{qid}</b><br/>{val}"
+        else:
+            label = f"<b>{qid}</b><br/>{kind}" if plain else f"<b>{qid}</b><br/><span style='color:#5F6B78'>{kind}</span>"
+        L.append(f'    {qnode(qid)}["{label}"]:::q')
+    L.append("  end")
+    L.append("  class IN col")
+
+    # --- logic and decisions
+    OP_LABEL = {"and": "AND", "or": "OR", "not": "NOT", "threshold": "≥", "argmax": "PICK", "majority": "VOTE", "verify": "VERIFY", "order": "BUCKET"}
+    SHAPES = {"and": ("{{", "}}"), "or": (">", "]"), "not": ("((", "))"), "threshold": ("{", "}")}
+    logic, decisions = [], []
+    for gid, spec in compiled.items():
+        if gid in folded:
+            continue
+        terminal = not gid.startswith("_") and not consumers[gid]
+        (decisions if terminal else logic).append(gid)
+
+    def edge_lines(gid: str, spec: dict[str, Any]) -> list[str]:
+        out = []
+        refs = ([spec["input"]] if spec.get("input") else []) + list(spec.get("inputs", [])) + ([spec["check"]] if spec.get("check") else [])
+        for ref in refs:
+            lab = "check" if spec.get("check") == ref else ""
+            base, _, opt = ref.partition(":")
+            if base in folded:
+                base, flab = folded[base]
+                base, _, opt = base.partition(":")
+                lab = flab + (" · " + lab if lab else "")
+            if opt:
+                q = circuit.questions.get(base)
+                shown = f"level {opt}" if (q and q["type"] == "score") else opt
+                lab = (f"{shown} " + lab).strip()
+            node = gnode(base) if base in compiled else qnode(base)
+            out.append(f"  {node} --{'>' if not lab else f'>|{lab}|'} {gnode(gid)}")
+        return out
+
+    def node_line(gid: str, spec: dict[str, Any], terminal: bool) -> str:
+        op = spec["op"]
+        head = OP_LABEL[op]
+        if op == "order":
+            head += " " + " | ".join(f"{c:g}" for c in spec.get("cutpoints", []))
+        if op in ("argmax", "majority", "verify") and spec.get("min_confidence"):
+            head += f"<br/>conf ≥ {spec['min_confidence']:g}" if plain else f"<br/><span style='color:#5F6B78'>conf ≥ {spec['min_confidence']:g}</span>"
+        if op in ("and", "or") and not terminal and spec.get("tau", 0.5) != 0.5:
+            head += f" ≥ {spec['tau']:g}"
+        if terminal:
+            label = f"<b>{gid.replace('_', ' ').title()}</b><br/>{head}"
+            if op in ("and", "or", "threshold", "not"):
+                label += f" ≥ {spec.get('tau', 0.5):g}"
+            cls = "logic"
+            if results and gid in results:
+                r = results[gid]
+                val, pr, outc = r.get("value"), r.get("p"), r.get("outcome", "decided")
+                if outc != "decided":
+                    verdict, cls = f"⚠ {outc.upper()}", "hold"
+                elif val is True:
+                    verdict, cls = "✓ YES", "yes"
+                elif val is False:
+                    verdict, cls = "✗ NO", "no"
+                else:
+                    verdict, cls = f"✓ {val}", "yes"
+                label += f"<br/><b>{verdict}</b>" + (f" · {pr:.0%}" if pr is not None else "")
+            return f'  {gnode(gid)}["{label}"]:::{cls}'
+        label = f"<b>{gid.replace('_', ' ')}</b><br/>{head}" if not gid.startswith("_") else head
+        if results and gid in results:
+            r = results[gid]
+            if r.get("outcome", "decided") != "decided":
+                label += f"<br/>⚠ {r['outcome']}"
+            elif op in ("argmax", "majority", "verify", "order"):
+                label += f"<br/>→ <b>{r.get('value')}</b>" + (f" · {r['p']:.0%}" if r.get("p") is not None else "")
+            elif r.get("p") is not None:
+                label += f"<br/>{r['p']:.0%}"
+        lo, hi = SHAPES.get(op, ("[", "]"))
+        return f'  {gnode(gid)}{lo}"{label}"{hi}:::logic'
+
+    if logic:
+        L.append('  subgraph LOGIC["Logic"]')
+        L.append("    direction TB")
+        for gid in logic:
+            L.append("  " + node_line(gid, compiled[gid], False))
+        L.append("  end")
+        L.append("  class LOGIC col")
+    L.append('  subgraph OUT["Decisions"]')
+    L.append("    direction TB")
+    for gid in decisions:
+        L.append("  " + node_line(gid, compiled[gid], True))
+    L.append("  end")
+    L.append("  class OUT col")
+    for gid in logic + decisions:
+        L += edge_lines(gid, compiled[gid])
+    return "\n".join(L)
+
+
+to_mermaid = render_mermaid  # module-level alias

decision_circuits-0.1.0/src/decision_circuits/gates.py

@@ -0,0 +1,181 @@
+"""Decision circuits: deterministic gates over calibrated answers.
+
+A circuit is the `questions` map of a normal request plus a `gates`
+map. Each gate reads one or more answers (or earlier gates) and emits a
+typed value with a probability and a trace. The model never sees the
+gates; code evaluates them, so a circuit is versionable and testable
+offline, and each item's path is auditable.
+
+Gate ops (inputs may reference question ids or earlier gate ids):
+
+  threshold  input: noul id, "choice_id:option", "score_id:level",
+             or "gate_id:value" for a categorical gate   value: bool
+             p = P(input); passes if p >= tau
+  not        input: noul or gate                       value: bool, p = 1 - p_in
+  and / or   inputs: k nouls/gates                     value: bool
+             p = product / 1 - product(1-p) (independence assumption; reported as such)
+  majority   inputs: k choice ids over the same option set   value: option
+             votes by argmax; p = mean probability of the winner; margin reported
+  argmax     input: choice id                           value: option or abstain
+             abstains when confidence < min_confidence
+  verify     input: choice id, check: noul id           value: option or escalate
+             the check asks "is <that answer> supported?"; escalates when
+             P(check) < tau or the choice is below min_confidence
+  order      input: score id, cutpoints: [c1, c2, ...]  value: bucket index (0..len)
+             bucket = number of cutpoints <= expected score
+
+Every gate has `on_uncertain`: "abstain" | "escalate" | "default" (with
+`default` value). A gate is uncertain when the probability it acts on
+falls inside [tau - band, tau + band] (band defaults to 0.1), or when an
+argmax/verify confidence check fails. Uncertainty is surfaced, never
+silently resolved.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+
+class Gate(BaseModel):
+    op: Literal["threshold", "not", "and", "or", "majority", "argmax", "verify", "order"]
+    input: str | None = None
+    inputs: list[str] | None = None
+    check: str | None = None
+    tau: float = 0.5
+    band: float = 0.1
+    min_confidence: float = 0.0
+    cutpoints: list[float] | None = None
+    on_uncertain: Literal["abstain", "escalate", "default"] = "abstain"
+    default: Any = None
+
+
+class GateResult(BaseModel):
+    value: Any
+    p: float | None = None
+    confidence: float | None = None
+    uncertain: bool = False
+    outcome: Literal["decided", "abstain", "escalate", "default"] = "decided"
+    trace: list[str] = Field(default_factory=list)
+
+
+def _noul_p(answers: dict[str, Any], results: dict[str, GateResult], ref: str) -> tuple[float, str, bool]:
+    """(probability, trace, upstream_uncertain) behind a reference.
+
+    A reference is a noul id; 'choice_id:option'; 'score_id:level'; an
+    earlier boolean gate (contributes P(its condition), whatever its
+    value); or 'gate_id:value' for a categorical gate. If the upstream
+    gate was uncertain, the flag propagates so the consumer's
+    on_uncertain policy applies."""
+    if ref in results:
+        r = results[ref]
+        if r.p is None:
+            raise ValueError(f"gate {ref!r} carries no probability; use '{ref}:<value>'")
+        note = " (uncertain)" if r.uncertain else ""
+        return float(r.p), f"gate {ref} p={r.p:.2f}{note}", r.uncertain
+    if ":" in ref:
+        qid, opt = ref.split(":", 1)
+        if qid in results:
+            r = results[qid]
+            p = float(r.p if r.p is not None else 1.0)
+            match = str(r.value) == opt
+            pm = p if match else max(0.0, 1.0 - p)
+            note = " (uncertain)" if r.uncertain else ""
+            return pm, f"gate {qid}={r.value} -> P({opt})={pm:.2f}{note}", r.uncertain
+        a = answers[qid]
+        if a["type"] in ("choice", "score"):
+            p = float(a["probabilities"][opt])
+            return p, f"{qid}[{opt}] p={p:.2f}", False
+        raise ValueError(f"{qid!r} is not a choice or score")
+    a = answers[ref]
+    if a["type"] != "noul":
+        raise ValueError(f"{ref!r} is not a noul; use 'choice_id:option' for a choice option")
+    return float(a["noul"]), f"{ref} p={a['noul']:.2f}", False
+
+
+def _settle(g: Gate, value: Any, p: float | None, uncertain: bool, trace: list[str], confidence: float | None = None) -> GateResult:
+    if not uncertain:
+        return GateResult(value=value, p=p, confidence=confidence, trace=trace)
+    if g.on_uncertain == "default":
+        trace.append(f"uncertain -> default {g.default!r}")
+        return GateResult(value=g.default, p=p, confidence=confidence, uncertain=True, outcome="default", trace=trace)
+    trace.append(f"uncertain -> {g.on_uncertain}")
+    return GateResult(value=None, p=p, confidence=confidence, uncertain=True, outcome=g.on_uncertain, trace=trace)
+
+
+def evaluate_gates(gates: dict[str, Gate], answers: dict[str, Any]) -> dict[str, GateResult]:
+    """Evaluate gates in dependency order (declaration order must respect
+    dependencies; a forward reference raises)."""
+    results: dict[str, GateResult] = {}
+    for gid, g in gates.items():
+        trace: list[str] = []
+        if g.op == "threshold":
+            p, t, unc = _noul_p(answers, results, g.input)
+            trace.append(t)
+            results[gid] = _settle(g, p >= g.tau, p, unc or abs(p - g.tau) < g.band, trace)
+        elif g.op == "not":
+            p, t, unc = _noul_p(answers, results, g.input)
+            trace += [t, f"not -> p={1 - p:.2f}"]
+            results[gid] = _settle(g, (1 - p) >= g.tau, 1 - p, unc or abs((1 - p) - g.tau) < g.band, trace)
+        elif g.op in ("and", "or"):
+            ps = []
+            unc = False
+            for ref in g.inputs or []:
+                p, t, u = _noul_p(answers, results, ref)
+                ps.append(p)
+                unc = unc or u
+                trace.append(t)
+            if g.op == "and":
+                p = 1.0
+                for x in ps:
+                    p *= x
+            else:
+                q = 1.0
+                for x in ps:
+                    q *= 1 - x
+                p = 1 - q
+            trace.append(f"{g.op} under independence -> p={p:.2f}")
+            results[gid] = _settle(g, p >= g.tau, p, unc or abs(p - g.tau) < g.band, trace)
+        elif g.op == "majority":
+            votes: dict[str, list[float]] = {}
+            for ref in g.inputs or []:
+                a = answers[ref]
+                if a["type"] != "choice":
+                    raise ValueError(f"majority input {ref!r} must be a choice")
+                votes.setdefault(a["choice"], []).append(float(a["probabilities"][a["choice"]]))
+                trace.append(f"{ref} -> {a['choice']} ({a['probabilities'][a['choice']]:.2f})")
+            n = len(g.inputs or [])
+            winner, ps = max(votes.items(), key=lambda kv: (len(kv[1]), sum(kv[1])))
+            margin = len(ps) / n
+            p = sum(ps) / len(ps)
+            trace.append(f"majority {winner} {len(ps)}/{n}, mean p={p:.2f}")
+            results[gid] = _settle(g, winner, p, margin <= 0.5 or p < g.min_confidence, trace, confidence=margin)
+        elif g.op == "argmax":
+            a = answers[g.input]
+            if a["type"] != "choice":
+                raise ValueError(f"argmax input {g.input!r} must be a choice")
+            conf = float(a["confidence"])
+            p = float(a["probabilities"][a["choice"]])
+            trace.append(f"{g.input} -> {a['choice']} p={p:.2f} conf={conf:.2f} (min {g.min_confidence})")
+            results[gid] = _settle(g, a["choice"], p, conf < g.min_confidence, trace, confidence=conf)
+        elif g.op == "verify":
+            a = answers[g.input]
+            if a["type"] != "choice":
+                raise ValueError(f"verify input {g.input!r} must be a choice")
+            conf = float(a["confidence"])
+            p_check, t, u = _noul_p(answers, results, g.check)
+            trace += [f"{g.input} -> {a['choice']} conf={conf:.2f}", f"check {t} (tau {g.tau})"]
+            unc = u or conf < g.min_confidence or p_check < g.tau
+            results[gid] = _settle(g, a["choice"], p_check, unc, trace, confidence=conf)
+        elif g.op == "order":
+            a = answers[g.input]
+            if a["type"] != "score":
+                raise ValueError(f"order input {g.input!r} must be a score")
+            s = float(a["score"])
+            cuts = g.cutpoints or []
+            bucket = sum(1 for c in cuts if s >= c)
+            near = any(abs(s - c) < g.band for c in cuts)
+            trace.append(f"{g.input} score={s:.2f} cutpoints={cuts} -> bucket {bucket}" + (" (near a cutpoint)" if near else ""))
+            results[gid] = _settle(g, bucket, None, near, trace, confidence=float(a["confidence"]))
+    return results

decision_circuits-0.1.0/tests/test_dsl.py

@@ -0,0 +1,133 @@
+import pytest
+
+from decision_circuits import Circuit, G, Q, argmax, majority, order, verify
+
+ANSWERS = {
+    "pii": {"type": "noul", "noul": 0.92},
+    "business": {"type": "noul", "noul": 0.10},
+    "angry": {"type": "noul", "noul": 0.93},
+    "dept": {"type": "choice", "choice": "billing", "probabilities": {"billing": 0.7, "technical": 0.2, "other": 0.1}, "confidence": 0.55},
+    "dept2": {"type": "choice", "choice": "billing", "probabilities": {"billing": 0.6, "technical": 0.3, "other": 0.1}, "confidence": 0.4},
+    "supported": {"type": "noul", "noul": 0.85},
+    "urgency": {"type": "score", "score": 2.88, "legend": {}, "probabilities": {"0": 0.0, "1": 0.02, "2": 0.08, "3": 0.90}, "confidence": 0.73},
+}
+
+
+def test_operators_compile_and_evaluate():
+    c = Circuit()
+    c.gate("redact", ((Q("pii") >= 0.7) & ~Q("business")) >= 0.6).on_uncertain("escalate")
+    c.gate("human", (Q("angry") | Q("urgency:3")) >= 0.6)
+    c.gate("route", argmax("dept", min_confidence=0.35))
+    c.gate("vote", majority("dept", "dept2"))
+    c.gate("checked", verify("dept", Q("supported"), tau=0.8)).on_uncertain("escalate")
+    c.gate("tier", order("urgency", [1.0, 2.0, 2.6]))
+    c.gate("bill_and_hot", (G("route:billing") & G("tier:3")) >= 0.5)
+
+    compiled = c.compile()
+    assert compiled["redact"]["op"] == "and" and compiled["redact"]["tau"] == 0.6 and compiled["redact"]["on_uncertain"] == "escalate"
+    # helpers exist for the threshold and the not
+    helper_ops = sorted(v["op"] for k, v in compiled.items() if k.startswith("_"))
+    assert helper_ops == ["not", "threshold"]
+
+    r = c.evaluate(ANSWERS)
+    assert set(r) == {"redact", "human", "route", "vote", "checked", "tier", "bill_and_hot"}  # helpers hidden
+    assert r["redact"]["value"] is True and r["redact"]["p"] == pytest.approx(0.92 * 0.90, abs=1e-6)
+    assert r["human"]["value"] is True and r["human"]["p"] > 0.99
+    assert r["route"]["value"] == "billing"
+    assert r["vote"]["value"] == "billing"
+    assert r["checked"]["value"] == "billing" and r["checked"]["outcome"] == "decided"
+    assert r["tier"]["value"] == 3
+    assert r["bill_and_hot"]["value"] is True
+
+
+def test_chained_and_flattens():
+    c = Circuit()
+    c.gate("all3", (Q("pii") & Q("angry") & Q("supported")) >= 0.5)
+    spec = c.compile()["all3"]
+    assert spec["op"] == "and" and spec["inputs"] == ["pii", "angry", "supported"]
+
+
+def test_bare_reference_thresholds_at_half():
+    c = Circuit()
+    c.gate("is_pii", Q("pii"))
+    assert c.compile()["is_pii"] == {"op": "threshold", "input": "pii", "tau": 0.5, "on_uncertain": "abstain", "band": 0.1}
+
+
+def test_default_policy_carries_value():
+    c = Circuit()
+    c.gate("tier", order("urgency", [2.85])).on_uncertain("default", default=2).band(0.1)
+    r = c.evaluate(ANSWERS)["tier"]
+    assert r["outcome"] == "default" and r["value"] == 2
+
+
+class _FakeClient:
+    """Looks like httpx/requests: .post(url, json=..., headers=...) -> .json()."""
+
+    def __init__(self, answers, with_gates: bool):
+        self.answers = answers
+        self.with_gates = with_gates
+        self.calls = []
+
+    def post(self, url, json=None, headers=None):
+        self.calls.append((url, json, headers))
+        status = 200
+        body = {"answers": self.answers}
+        if "gates" in json:
+            if self.with_gates:  # a server that evaluates gates itself (s1proto)
+                body["gates"] = {"_h_1": {"value": True}, "rush": {"value": True, "p": 0.9, "outcome": "decided"}}
+            else:  # TypeSafe rejects unknown fields
+                status, body = 400, {"detail": {"error_type": "api_usage_error", "message": "Invalid request."}}
+
+        class R:
+            status_code = status
+
+            def json(self):
+                return body
+
+        return R()
+
+
+def _circuit():
+    c = Circuit()
+    c.noul("urgent", "Is this urgent?", true="Needs action today", false="Can wait")
+    c.choice("dept", "Which team?", {"billing": None, "technical": None, "other": None})
+    c.gate("rush", Q("urgent") >= 0.5)
+    c.gate("route", argmax("dept"))
+    return c
+
+
+def test_run_sends_gates_and_uses_server_evaluation_when_present():
+    client = _FakeClient({"urgent": {"type": "noul", "noul": 0.9}, "dept": ANSWERS["dept"]}, with_gates=True)
+    out = _circuit().run(client, "Card charged twice, please refund today.", headers={"Authorization": "Bearer k"})
+    url, body, headers = client.calls[0]
+    assert url == "/v1/systemone" and headers == {"Authorization": "Bearer k"}
+    assert set(body["questions"]) == {"urgent", "dept"} and set(body["gates"]) == {"rush", "route"}
+    assert set(out["gates"]) == {"rush"}  # helper gates hidden; server's result kept as-is
+
+
+def test_run_evaluates_gates_locally_when_server_returns_answers_only():
+    client = _FakeClient({"urgent": {"type": "noul", "noul": 0.9}, "dept": ANSWERS["dept"]}, with_gates=False)
+    c = _circuit()
+    out = c.run(client, "Card charged twice.", url="https://api.typesafe.ai/v1/systemone", headers={"Authorization": "Bearer k"})
+    assert out["gates"]["rush"]["value"] is True and out["gates"]["route"]["value"] == "billing"
+    assert out["gates_evaluated_by"] == "client"
+    assert len(client.calls) == 2 and "gates" not in client.calls[1][1]
+    c.run(client, "Again.", url="https://api.typesafe.ai/v1/systemone")
+    assert len(client.calls) == 3  # remembered: one request the second time
+
+
+def test_indexing_and_keyword_policy_match_string_forms():
+    a = Circuit()
+    a.gate("hot", (Q("urgency:3") | G("route:billing")) >= 0.5).on_uncertain("escalate").band(0.05)
+    b = Circuit()
+    b.gate("hot", (Q("urgency")[3] | G("route")["billing"]).at(0.5), on_uncertain="escalate", band=0.05)
+    assert a.compile() == b.compile()
+    with pytest.raises(KeyError):
+        Q("urgency:3")["x"]
+
+
+def test_to_mermaid_is_a_method():
+    c = Circuit()
+    c.noul("pii", "PII?")
+    c.gate("redact", Q("pii") >= 0.7)
+    assert "redact" in c.to_mermaid(plain=True)

decision_circuits-0.1.0/tests/test_gates.py

@@ -0,0 +1,82 @@
+import pytest
+
+from decision_circuits.gates import Gate, evaluate_gates
+
+ANSWERS = {
+    "pii": {"type": "noul", "noul": 0.92},
+    "business": {"type": "noul", "noul": 0.10},
+    "dept": {"type": "choice", "choice": "billing", "probabilities": {"billing": 0.7, "technical": 0.2, "sales": 0.1}, "confidence": 0.55},
+    "dept2": {"type": "choice", "choice": "billing", "probabilities": {"billing": 0.6, "technical": 0.3, "sales": 0.1}, "confidence": 0.4},
+    "dept3": {"type": "choice", "choice": "technical", "probabilities": {"billing": 0.4, "technical": 0.5, "sales": 0.1}, "confidence": 0.3},
+    "supported": {"type": "noul", "noul": 0.85},
+    "urgency": {
+        "type": "score",
+        "score": 2.4,
+        "legend": {"0": "low", "1": "med", "2": "high", "3": "critical"},
+        "probabilities": {"0": 0.0, "1": 0.1, "2": 0.4, "3": 0.5},
+        "confidence": 0.6,
+    },
+}
+
+
+def g(**kw):
+    return Gate.model_validate(kw)
+
+
+def test_threshold_and_not_and_and():
+    r = evaluate_gates(
+        {
+            "has_pii": g(op="threshold", input="pii", tau=0.8),
+            "private": g(op="not", input="business", tau=0.8, band=0.05),
+            "redact": g(op="and", inputs=["has_pii", "private"], tau=0.7, on_uncertain="escalate"),
+        },
+        ANSWERS,
+    )
+    assert r["has_pii"].value is True and r["has_pii"].p == pytest.approx(0.92)
+    assert r["private"].value is True and r["private"].p == pytest.approx(0.90)
+    assert r["redact"].value is True and r["redact"].p == pytest.approx(0.92 * 0.90)
+    assert "independence" in " ".join(r["redact"].trace)
+
+
+def test_uncertain_band_escalates():
+    r = evaluate_gates({"x": g(op="threshold", input="pii", tau=0.9, band=0.05, on_uncertain="escalate")}, ANSWERS)
+    assert r["x"].outcome == "escalate" and r["x"].value is None and r["x"].uncertain
+
+
+def test_uncertain_default():
+    r = evaluate_gates({"x": g(op="threshold", input="pii", tau=0.9, band=0.05, on_uncertain="default", default=False)}, ANSWERS)
+    assert r["x"].outcome == "default" and r["x"].value is False
+
+
+def test_argmax_confidence_gate():
+    ok = evaluate_gates({"route": g(op="argmax", input="dept", min_confidence=0.5)}, ANSWERS)["route"]
+    assert ok.value == "billing" and ok.outcome == "decided"
+    ab = evaluate_gates({"route": g(op="argmax", input="dept", min_confidence=0.6)}, ANSWERS)["route"]
+    assert ab.outcome == "abstain" and ab.value is None
+
+
+def test_majority_over_paraphrases():
+    r = evaluate_gates({"vote": g(op="majority", inputs=["dept", "dept2", "dept3"])}, ANSWERS)["vote"]
+    assert r.value == "billing" and r.confidence == pytest.approx(2 / 3) and r.outcome == "decided"
+    tie = evaluate_gates({"vote": g(op="majority", inputs=["dept", "dept3"])}, ANSWERS)["vote"]
+    assert tie.outcome == "abstain"
+
+
+def test_verify_with_negative_checker():
+    ok = evaluate_gates({"v": g(op="verify", input="dept", check="supported", tau=0.8, on_uncertain="escalate")}, ANSWERS)["v"]
+    assert ok.value == "billing" and ok.outcome == "decided"
+    weak = dict(ANSWERS, supported={"type": "noul", "noul": 0.4})
+    esc = evaluate_gates({"v": g(op="verify", input="dept", check="supported", tau=0.8, on_uncertain="escalate")}, weak)["v"]
+    assert esc.outcome == "escalate"
+
+
+def test_order_buckets_and_cutpoint_band():
+    r = evaluate_gates({"tier": g(op="order", input="urgency", cutpoints=[1.0, 2.0, 2.8])}, ANSWERS)["tier"]
+    assert r.value == 2 and r.outcome == "decided"
+    near = evaluate_gates({"tier": g(op="order", input="urgency", cutpoints=[2.45], band=0.1, on_uncertain="escalate")}, ANSWERS)["tier"]
+    assert near.outcome == "escalate"
+
+
+def test_forward_reference_is_an_error():
+    with pytest.raises(KeyError):
+        evaluate_gates({"a": g(op="and", inputs=["b"]), "b": g(op="threshold", input="pii")}, ANSWERS)