postrule 1.1.0__py3-none-any.whl

postrule/__init__.py

@@ -0,0 +1,212 @@
+# Copyright (c) 2026 B-Tree Labs
+# SPDX-License-Identifier: Apache-2.0
+
+"""Postrule — graduated-autonomy classification primitive.
+
+Six-phase lifecycle from hand-written rule to learned classifier,
+with a statistical transition gate at every phase, a safety-critical
+cap that refuses construction in the highest-autonomy phase for
+authorization-class decisions, a circuit breaker that reverts to the
+rule on ML failure, and shadow-path isolation that keeps observational
+classifiers from affecting user-visible output.
+
+Core public API: :class:`LearnedSwitch`, :func:`ml_switch` decorator,
+:class:`Phase`, :class:`SwitchConfig`, :class:`ClassificationRecord`,
+:class:`FileStorage`, and the language model/ML protocol interfaces.
+
+Tooling (analyzer, ROI reporter, AST-based `wrap_function`, viz,
+research runners) ships in submodules — import directly:
+``from postrule.analyzer import analyze``, ``from postrule.roi import
+compute_switch_roi``, etc.
+
+See README.md and https://postrule.ai.
+"""
+
+__version__ = "1.1.0"
+
+from postrule.autoresearch import (
+    CandidateHarness,
+    CandidateReport,
+    Tournament,
+    TournamentReport,
+)
+from postrule.core import (
+    BulkVerdict,
+    BulkVerdictSummary,
+    ClassificationRecord,
+    ClassificationResult,
+    Label,
+    LearnedSwitch,
+    Phase,
+    SwitchConfig,
+    SwitchStatus,
+    Verdict,
+)
+from postrule.decorator import ml_switch
+from postrule.gates import (
+    AccuracyMarginGate,
+    CompositeGate,
+    Gate,
+    GateDecision,
+    ManualGate,
+    McNemarGate,
+    MinVolumeGate,
+    next_phase,
+    prev_phase,
+)
+from postrule.ml import (
+    ImagePixelLogRegHead,
+    MLHead,
+    MLHeadFactory,
+    MLPrediction,
+    SklearnTextHead,
+    TfidfGradientBoostingHead,
+    TfidfHeadBase,
+    TfidfLinearSVCHead,
+    TfidfMultinomialNBHead,
+    available_ml_heads,
+    make_ml_head,
+    register_ml_head,
+)
+from postrule.ml_strategy import (
+    CardinalityMLHeadStrategy,
+    FixedMLHeadStrategy,
+    MLHeadStrategy,
+)
+from postrule.models import (
+    AnthropicAdapter,
+    AnthropicAsyncAdapter,
+    LlamafileAdapter,
+    LlamafileAsyncAdapter,
+    ModelClassifier,
+    ModelPrediction,
+    OllamaAdapter,
+    OllamaAsyncAdapter,
+    OpenAIAdapter,
+    OpenAIAsyncAdapter,
+)
+from postrule.storage import (
+    BoundedInMemoryStorage,
+    FileStorage,
+    InMemoryStorage,
+    ResilientStorage,
+    SqliteStorage,
+    Storage,
+    StorageBase,
+    deserialize_record,
+    flock_supported,
+    serialize_record,
+)
+from postrule.switch_class import Switch
+from postrule.telemetry import (
+    ListEmitter,
+    NullEmitter,
+    StdoutEmitter,
+    TelemetryEmitter,
+)
+from postrule.verdicts import (
+    CallableVerdictSource,
+    HumanReviewerSource,
+    JudgeCommittee,
+    JudgeSource,
+    NoVerifierAvailableError,
+    VerdictSource,
+    WebhookVerdictSource,
+    default_verifier,
+)
+
+# Default-on hosted-API verdict telemetry. Best-effort, fails silent.
+# Auto-installs the cloud emitter as the process-wide default iff the
+# user is signed in (``~/.postrule/credentials`` exists) AND has not
+# opted out via ``$POSTRULE_NO_TELEMETRY``. The decision happens in
+# ``maybe_install`` itself; this block just triggers the check.
+#
+# The import + call is wrapped so a missing optional dependency, a
+# broken credentials file, or a malformed env override never aborts
+# ``import postrule``. The decision path is observability-unaware: if
+# anything here misfires, the user gets a NullEmitter and life goes
+# on. Out of scope for this block (handled by other agents): the
+# sign-up flow's consent banner that announces the default-on
+# decision to the user.
+try:  # pragma: no cover — observability hook; intentionally fails silent
+    from postrule.cloud import verdict_telemetry as _verdict_telemetry  # pragma: no cover
+
+    _verdict_telemetry.maybe_install()  # pragma: no cover
+except BaseException:  # noqa: BLE001 — observability hook, fails silent  # pragma: no cover
+    pass  # pragma: no cover
+
+__all__ = [
+    "AccuracyMarginGate",
+    "AnthropicAdapter",
+    "AnthropicAsyncAdapter",
+    "BoundedInMemoryStorage",
+    "BulkVerdict",
+    "BulkVerdictSummary",
+    "CandidateHarness",
+    "CandidateReport",
+    "CardinalityMLHeadStrategy",
+    "CompositeGate",
+    "ClassificationRecord",
+    "ClassificationResult",
+    "FileStorage",
+    "FixedMLHeadStrategy",
+    "Gate",
+    "GateDecision",
+    "ImagePixelLogRegHead",
+    "InMemoryStorage",
+    "Label",
+    "LearnedSwitch",
+    "ListEmitter",
+    "LlamafileAdapter",
+    "LlamafileAsyncAdapter",
+    "MLHead",
+    "MLHeadFactory",
+    "MLHeadStrategy",
+    "MLPrediction",
+    "ManualGate",
+    "McNemarGate",
+    "MinVolumeGate",
+    "ModelClassifier",
+    "ModelPrediction",
+    "NullEmitter",
+    "OllamaAdapter",
+    "OllamaAsyncAdapter",
+    "OpenAIAdapter",
+    "OpenAIAsyncAdapter",
+    "Phase",
+    "ResilientStorage",
+    "SklearnTextHead",
+    "SqliteStorage",
+    "TfidfGradientBoostingHead",
+    "TfidfHeadBase",
+    "TfidfLinearSVCHead",
+    "TfidfMultinomialNBHead",
+    "StdoutEmitter",
+    "Storage",
+    "StorageBase",
+    "Switch",
+    "SwitchConfig",
+    "SwitchStatus",
+    "CallableVerdictSource",
+    "HumanReviewerSource",
+    "JudgeCommittee",
+    "JudgeSource",
+    "TelemetryEmitter",
+    "Tournament",
+    "TournamentReport",
+    "Verdict",
+    "VerdictSource",
+    "NoVerifierAvailableError",
+    "WebhookVerdictSource",
+    "__version__",
+    "available_ml_heads",
+    "default_verifier",
+    "deserialize_record",
+    "flock_supported",
+    "make_ml_head",
+    "ml_switch",
+    "next_phase",
+    "prev_phase",
+    "register_ml_head",
+    "serialize_record",
+]

postrule/_examples/01_hello_world.py

@@ -0,0 +1,59 @@
+# Copyright (c) 2026 B-Tree Labs
+# SPDX-License-Identifier: Apache-2.0
+"""Postrule hello-world — rule + dispatch in the smallest form.
+
+Run: `python examples/01_hello_world.py`
+
+Pass ``labels=`` as a dict mapping label → action, call
+``rule.dispatch(input)``, done. Each dict entry is a
+**label-based conditional expression** — "when the classifier's
+output equals this label, evaluate this action."
+"""
+
+from __future__ import annotations
+
+from postrule import ml_switch
+
+
+def send_to_engineering(ticket: dict) -> str:
+    """Action fired when the classifier returns ``label="bug"``."""
+    return f"engineering ← {ticket['title']}"
+
+
+def send_to_product(ticket: dict) -> str:
+    """Action fired when the classifier returns ``label="feature_request"``."""
+    return f"product ← {ticket['title']}"
+
+
+def send_to_support(ticket: dict) -> str:
+    """Action fired when the classifier returns ``label="question"``."""
+    return f"support ← {ticket['title']}"
+
+
+@ml_switch(
+    labels={
+        "bug": send_to_engineering,
+        "feature_request": send_to_product,
+        "question": send_to_support,
+    },
+    # `author` omitted — auto-derives to "@__main__:triage_rule".
+)
+def triage_rule(ticket: dict) -> str:
+    """Classify one ticket into exactly one of the declared labels."""
+    title = (ticket.get("title") or "").lower()
+    if "crash" in title or "error" in title:
+        return "bug"
+    if title.endswith("?"):
+        return "question"
+    return "feature_request"
+
+
+if __name__ == "__main__":
+    samples = [
+        {"title": "app crashes on login"},
+        {"title": "how do I reset my password?"},
+        {"title": "add dark mode"},
+    ]
+    for sample in samples:
+        c = triage_rule.dispatch(sample)
+        print(f"{sample['title']:40s}  →  label={c.label:18s}  →  action={c.action_result}")

postrule/_examples/17_exception_handling.py

@@ -0,0 +1,180 @@
+# Copyright (c) 2026 B-Tree Labs
+# SPDX-License-Identifier: Apache-2.0
+"""Using a Postrule switch as an exception-handling dispatcher.
+
+Run: `python examples/17_exception_handling.py`
+
+A try/except tree that picks among retry, fallback, escalate,
+and drop is a classifier — input is ``(exception, context)``,
+output is one of a fixed strategy set. Wrapping the dispatch in
+a :class:`LearnedSwitch` records every decision on the outcome
+log and lets a learned policy graduate against the hand-written
+rule once enough outcomes accumulate.
+
+Day 0 (RULE)
+    Hand-written dispatch on exception type + HTTP status.
+    Conservative defaults — always retry on 5xx, never retry on
+    4xx, escalate ``RuntimeError`` to the queue.
+
+Day N (MODEL_SHADOW → ML_PRIMARY)
+    As outcomes accumulate (did the retry succeed? did the
+    fallback produce an acceptable answer?), the ML head learns
+    endpoint-specific patterns the rule can't see:
+    "endpoint X's 503s clear in 2 s; endpoint Y's are permanent"
+    or "this auth error on tenant Z is actually a billing
+    suspension, route to CS." The rule remains the floor (paper
+    §7.1) — a buggy learned policy cannot remove the
+    "503 → retry" baseline.
+"""
+
+from __future__ import annotations
+
+import random
+from dataclasses import dataclass
+
+from postrule import LearnedSwitch, Verdict
+
+
+@dataclass
+class FailureContext:
+    """Everything a classifier sees about a failure."""
+
+    exception_type: str
+    http_status: int | None = None
+    endpoint: str = ""
+    attempt: int = 1
+    elapsed_ms: float = 0.0
+
+
+# The four strategies the classifier chooses between. Each is a
+# distinct post-failure action. "retry" means loop + backoff;
+# "fallback" means route to cache/default; "escalate" means push
+# onto the ops queue; "drop" means log and continue (non-critical).
+STRATEGIES = ["retry", "fallback", "escalate", "drop"]
+
+
+def handling_rule(ctx: FailureContext) -> str:
+    """Day-0 exception-handling dispatch.
+
+    Keyword-matched on exception type + HTTP status. Conservative
+    by design — anything ambiguous escalates.
+    """
+    # Transient server-side — retry bounded.
+    if ctx.http_status in (502, 503, 504) and ctx.attempt < 3:
+        return "retry"
+    # Client-side auth / permission — not retryable; needs a human.
+    if ctx.http_status in (401, 403):
+        return "escalate"
+    # Validation errors on submitted data — the caller's problem.
+    if ctx.exception_type == "ValueError":
+        return "drop"
+    # Anything timing-out — fall back to a cached answer rather than
+    # burning more budget.
+    if ctx.exception_type == "TimeoutError":
+        return "fallback"
+    # Runtime / programmer errors — don't retry; a human should look.
+    if ctx.exception_type in ("RuntimeError", "KeyError", "AttributeError"):
+        return "escalate"
+    # Default: one-shot retry then give up.
+    return "retry" if ctx.attempt < 2 else "escalate"
+
+
+def main() -> None:
+    # Dispatch table: each strategy has a real action. In production
+    # these would call your retry loop, cache lookup, pager queue, etc.
+    def do_retry(ctx: FailureContext) -> str:
+        return f"requeued {ctx.endpoint} (attempt {ctx.attempt + 1})"
+
+    def do_fallback(ctx: FailureContext) -> str:
+        return f"served cached response for {ctx.endpoint}"
+
+    def do_escalate(ctx: FailureContext) -> str:
+        return f"pushed {ctx.endpoint} + {ctx.exception_type} to ops queue"
+
+    def do_drop(ctx: FailureContext) -> str:
+        return f"logged {ctx.exception_type} and continued"
+
+    sw = LearnedSwitch(
+        rule=handling_rule,
+        labels={
+            "retry": do_retry,
+            "fallback": do_fallback,
+            "escalate": do_escalate,
+            "drop": do_drop,
+        },
+        auto_advance=False,  # deterministic example output
+    )
+
+    # Simulated failure stream. In production this feeds off your
+    # real exception traffic — a decorator on your HTTP client, a
+    # middleware on your message handler, an ``except`` block that
+    # calls ``sw.dispatch(ctx)`` instead of inlining its own ladder.
+    failures = [
+        FailureContext("HTTPError", http_status=503, endpoint="/api/v1/users", attempt=1),
+        FailureContext("HTTPError", http_status=401, endpoint="/api/v1/billing", attempt=1),
+        FailureContext("TimeoutError", endpoint="/api/v1/search", attempt=1, elapsed_ms=5000),
+        FailureContext("ValueError", endpoint="/api/v1/parse", attempt=1),
+        FailureContext("RuntimeError", endpoint="/api/v1/internal", attempt=1),
+        FailureContext("HTTPError", http_status=504, endpoint="/api/v1/export", attempt=3),
+    ]
+
+    print("Day 0: rule-based exception handling")
+    print("-" * 78)
+    for ctx in failures:
+        result = sw.dispatch(ctx)
+        print(
+            f"  {ctx.exception_type:14s} "
+            f"status={str(ctx.http_status or '-'):>4s}  "
+            f"attempt={ctx.attempt} "
+            f"-> {result.label:9s}  {result.action_result}"
+        )
+
+    # As outcomes accumulate, reviewers label whether each strategy
+    # actually worked. Simulated here; in production, a downstream
+    # signal (did the retry succeed? did the escalated ticket get
+    # resolved as a real bug?) feeds record_verdict.
+    print("\nLabeling outcomes (simulated downstream signal)...")
+    records = sw.storage.load_records(sw.name)
+    for r in records:
+        # Toy oracle: retries on 5xx worked; escalations on 4xx worked;
+        # fallbacks on timeouts worked; drops on ValueError worked.
+        # Everything else is "incorrect" — the rule overreached.
+        ctx = r.input
+        rule_pick = r.label
+        ok = (
+            (rule_pick == "retry" and ctx.http_status in (502, 503, 504))
+            or (rule_pick == "escalate" and ctx.http_status in (401, 403))
+            or (rule_pick == "fallback" and ctx.exception_type == "TimeoutError")
+            or (rule_pick == "drop" and ctx.exception_type == "ValueError")
+            or (
+                rule_pick == "escalate"
+                and ctx.exception_type in ("RuntimeError", "KeyError", "AttributeError")
+            )
+        )
+        sw.record_verdict(
+            input=ctx,
+            label=rule_pick,
+            outcome=Verdict.CORRECT.value if ok else Verdict.INCORRECT.value,
+            source="downstream-signal",
+        )
+
+    status = sw.status()
+    print(
+        f"outcome log: total={status.outcomes_total}, "
+        f"correct={status.outcomes_correct}, "
+        f"incorrect={status.outcomes_incorrect}"
+    )
+    print(
+        "\nNext step (not shown here): as the log grows, an ML head "
+        "trained on (ctx → correct_strategy) pairs graduates into\n"
+        "MODEL_SHADOW / MODEL_PRIMARY. The rule stays as the safety "
+        "floor; the learned policy fires only when the evidence gate\n"
+        "confirms it beats the rule head-to-head with p < 0.05. See "
+        "examples/06_ml_primary.py for the full lifecycle."
+    )
+
+
+if __name__ == "__main__":
+    # Seed for reproducible output.
+    random.seed(0)
+    main()