dendra 1.0.0rc1__py3-none-any.whl

dendra/__init__.py

@@ -0,0 +1,192 @@
+# Copyright (c) 2026 B-Tree Labs
+# SPDX-License-Identifier: Apache-2.0
+
+"""Dendra — 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 dendra.analyzer import analyze``, ``from dendra.roi import
+compute_switch_roi``, etc.
+
+See README.md and https://dendra.run.
+"""
+
+__version__ = "1.0.0rc1"
+
+from dendra.autoresearch import (
+    CandidateHarness,
+    CandidateReport,
+    Tournament,
+    TournamentReport,
+)
+from dendra.core import (
+    BulkVerdict,
+    BulkVerdictSummary,
+    ClassificationRecord,
+    ClassificationResult,
+    Label,
+    LearnedSwitch,
+    Phase,
+    SwitchConfig,
+    SwitchStatus,
+    Verdict,
+)
+from dendra.decorator import ml_switch
+from dendra.gates import (
+    AccuracyMarginGate,
+    CompositeGate,
+    Gate,
+    GateDecision,
+    ManualGate,
+    McNemarGate,
+    MinVolumeGate,
+    next_phase,
+    prev_phase,
+)
+from dendra.ml import (
+    ImagePixelLogRegHead,
+    MLHead,
+    MLHeadFactory,
+    MLPrediction,
+    SklearnTextHead,
+    TfidfGradientBoostingHead,
+    TfidfHeadBase,
+    TfidfLinearSVCHead,
+    TfidfMultinomialNBHead,
+    available_ml_heads,
+    make_ml_head,
+    register_ml_head,
+)
+from dendra.ml_strategy import (
+    CardinalityMLHeadStrategy,
+    FixedMLHeadStrategy,
+    MLHeadStrategy,
+)
+from dendra.models import (
+    AnthropicAdapter,
+    AnthropicAsyncAdapter,
+    LlamafileAdapter,
+    LlamafileAsyncAdapter,
+    ModelClassifier,
+    ModelPrediction,
+    OllamaAdapter,
+    OllamaAsyncAdapter,
+    OpenAIAdapter,
+    OpenAIAsyncAdapter,
+)
+from dendra.storage import (
+    BoundedInMemoryStorage,
+    FileStorage,
+    InMemoryStorage,
+    ResilientStorage,
+    SqliteStorage,
+    Storage,
+    StorageBase,
+    deserialize_record,
+    flock_supported,
+    serialize_record,
+)
+from dendra.switch_class import Switch
+from dendra.telemetry import (
+    ListEmitter,
+    NullEmitter,
+    StdoutEmitter,
+    TelemetryEmitter,
+)
+from dendra.verdicts import (
+    CallableVerdictSource,
+    HumanReviewerSource,
+    JudgeCommittee,
+    JudgeSource,
+    NoVerifierAvailableError,
+    VerdictSource,
+    WebhookVerdictSource,
+    default_verifier,
+)
+
+__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",
+]

dendra/_examples/01_hello_world.py

@@ -0,0 +1,59 @@
+# Copyright (c) 2026 B-Tree Labs
+# SPDX-License-Identifier: Apache-2.0
+"""Dendra 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 dendra 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}")

dendra/_examples/17_exception_handling.py

@@ -0,0 +1,180 @@
+# Copyright (c) 2026 B-Tree Labs
+# SPDX-License-Identifier: Apache-2.0
+"""Using a Dendra 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 dendra 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()

dendra/_examples/19_autoresearch_loop.py

@@ -0,0 +1,269 @@
+# Copyright (c) 2026 B-Tree Labs
+# SPDX-License-Identifier: Apache-2.0
+"""Karpathy-style autoresearch loop, gated by ``CandidateHarness``.
+
+Run: `python examples/19_autoresearch_loop.py`
+
+The autoresearch loop pattern (popularised by Andrej Karpathy):
+
+    +------------+      +------------+      +------------+
+    |  PROPOSE   | ---> |  EVALUATE  | ---> |  REFLECT   | ---+
+    +------------+      +------------+      +------------+    |
+          ^                                                   |
+          +---------------------- next iter ------------------+
+
+A language-model agent reads recent results (REFLECT), proposes a fresh
+candidate classifier (PROPOSE), the candidate runs against a
+truth oracle (EVALUATE), and the loop repeats. The agent decides
+when to stop.
+
+This example wires that loop. ``CandidateHarness`` is the
+EVALUATE rung — it shadows each candidate against the production
+switch on the same inputs, runs a head-to-head significance
+test, and returns a ``CandidateReport``. The loop's ``REFLECT``
+step reads that report; the loop's ``PROPOSE`` step is the place
+a language-model agent plugs in.
+
+The propose-step here is a deterministic stand-in (a hardcoded
+ratchet through known keyword expansions) so the example runs
+offline with no API keys. Replace ``propose_next_candidate`` with
+a language-model-backed function and the rest of the loop is unchanged.
+
+What the harness gives your loop, in one line each:
+
+- *Bounded false-promotion rate.* False promotions are
+  capped at the ``alpha`` you pass (default ``0.05``), not
+  by the candidate generator's appetite.
+- *Faster convergence per paired sample.* Head-to-head
+  testing on the same inputs is statistically tighter than
+  independent-samples testing — 1.7–6× faster on the four
+  NLU benchmarks shipped here.
+- *Reproducible promotion decisions.* Every recommendation
+  carries a p-value and the discordant-pair counts
+  (``b``, ``c``) that drove it.
+
+For the situations where each of these matters most — and
+the situations where they don't — see ``docs/scenarios.md``.
+That doc opens with an at-a-glance table of high-volume,
+high-stakes industries (card fraud, AML, SOC, prior-auth,
+brand safety, returns fraud, customs) where the autoresearch
+loop's promotion gate carries direct financial weight.
+"""
+
+from __future__ import annotations
+
+import random
+from collections.abc import Callable
+
+from dendra import (
+    CandidateHarness,
+    CandidateReport,
+    LearnedSwitch,
+)
+
+# ---------------------------------------------------------------------------
+# The loop
+# ---------------------------------------------------------------------------
+
+
+def main() -> None:
+    sw = LearnedSwitch(rule=production_rule)
+    harness = CandidateHarness(switch=sw, truth_oracle=truth_oracle, alpha=0.05)
+
+    print("Production rule misses bugs phrased as 'error'/'down'/'stuck'/'broken'.")
+    print("Loop will propose keyword expansions; harness gates each.\n")
+
+    history: list[CandidateReport] = []
+    for iter_num in range(1, MAX_ITERS + 1):
+        # 1. PROPOSE — the agent reads history and produces a new candidate.
+        #    Swap this for a model call: read history, decide what to try next.
+        proposal = propose_next_candidate(history)
+        if proposal is None:
+            print("Agent says: nothing left to try. Stopping.")
+            break
+        name, candidate = proposal
+
+        # 2. EVALUATE — harness shadows the candidate, head-to-head vs production.
+        harness.register(name, candidate)
+        harness.observe_batch(_TICKETS)
+        report = harness.evaluate(name)
+
+        # 3. REFLECT — the agent reads the report. Stop on convergence or
+        #    diminishing returns; otherwise feed it into the next propose.
+        history.append(report)
+        _print_report(iter_num, report)
+        if should_stop(report):
+            print("Agent says: candidate accuracy at ceiling. Stopping.")
+            break
+
+    promoted = [r.candidate_name for r in history if r.recommend_promote]
+    print(f"\nLoop complete after {len(history)} iteration(s).")
+    print(f"Recommended for promotion: {promoted}")
+    print(
+        "\nIn production, the loop reads ``report.recommend_promote`` "
+        "and acts on it: swap the candidate into the switch's rule, "
+        "ml_head, or model and ship through your normal deployment "
+        "process. The rule floor stays in place throughout — even a "
+        "bad promotion can't remove the day-zero safety net."
+    )
+
+
+# ---------------------------------------------------------------------------
+# The three loop steps (PROPOSE / EVALUATE / REFLECT)
+# ---------------------------------------------------------------------------
+#
+# EVALUATE is implemented by ``CandidateHarness.evaluate`` directly;
+# the other two are below. The PROPOSE step is the language-model agent hook.
+
+
+# Deterministic stand-in for the language model proposer. Real loops use an
+# agent that reads ``history`` (the prior CandidateReports + the
+# ground-truth misses each surface) and proposes the next refinement.
+_PROGRESSION = [
+    ("v1_kw2", ("crash", "error")),
+    ("v2_kw3", ("crash", "error", "down")),
+    ("v3_kw4", ("crash", "error", "down", "stuck")),
+    ("v4_kw5", ("crash", "error", "down", "stuck", "broken")),
+]
+
+
+def propose_next_candidate(
+    history: list[CandidateReport],
+) -> tuple[str, Callable[[dict], str]] | None:
+    """PROPOSE step. Returns ``(name, candidate_classifier)`` or None to stop.
+
+    Production swap-in: a language-model agent that reads ``history`` (the
+    prior reports), inspects which inputs the production rule got
+    wrong, and emits the next refinement to try.
+    """
+    idx = len(history)
+    if idx >= len(_PROGRESSION):
+        return None
+    name, keywords = _PROGRESSION[idx]
+    return name, _make_keyword_rule(keywords)
+
+
+def should_stop(report: CandidateReport) -> bool:
+    """REFLECT step's stop-decision. Real loops layer in plateau detection,
+    cost ceilings, or agent-controlled halt. Here: stop on perfect
+    accuracy."""
+    return report.candidate_accuracy >= 1.0
+
+
+# ---------------------------------------------------------------------------
+# World setup — production rule, truth oracle, evaluation traffic.
+# Below the loop because the loop is the point of the file.
+# ---------------------------------------------------------------------------
+#
+# Ground-truth labeling rule (what we WISH the classifier knew):
+#   - "crash"/"error"/"down"/"stuck"/"broken" → bug
+#   - "?" at end → question
+#   - everything else → feature_request
+#
+# Production rule (what was hand-written six months ago):
+#   - "crash" only → bug
+#   - "?" at end → question
+#   - everything else → feature_request
+#
+# The production rule misses bugs phrased as "error"/"down"/
+# "stuck"/"broken". Day zero, the team didn't think of those
+# keywords. The autoresearch loop's job is to discover them — and
+# the harness's job is to gate the discovery.
+
+_BUG_KEYWORDS_TRUTH = ("crash", "error", "down", "stuck", "broken")
+
+# Stop after this many propose-evaluate cycles even if the agent
+# keeps proposing. Cost ceiling on a real loop.
+MAX_ITERS = 10
+
+
+def production_rule(ticket: dict) -> str:
+    """Six-month-old hand-written rule. Only catches 'crash' for bugs."""
+    title = (ticket.get("title") or "").lower()
+    if "crash" in title:
+        return "bug"
+    if title.endswith("?"):
+        return "question"
+    return "feature_request"
+
+
+def truth_oracle(ticket: dict) -> str:
+    """Ground truth — what a perfect classifier would return.
+
+    In production: a labeled validation set, a downstream signal
+    (with a wrapper that waits for it), a reviewer-pool aggregator,
+    or a language-model judge committee with bias guardrails.
+    """
+    title = (ticket.get("title") or "").lower()
+    if any(kw in title for kw in _BUG_KEYWORDS_TRUTH):
+        return "bug"
+    if title.endswith("?"):
+        return "question"
+    return "feature_request"
+
+
+def _make_keyword_rule(keywords: tuple[str, ...]) -> Callable[[dict], str]:
+    """Factory: build a classifier that flags 'bug' on any of these keywords."""
+
+    def rule(ticket: dict) -> str:
+        title = (ticket.get("title") or "").lower()
+        if any(kw in title for kw in keywords):
+            return "bug"
+        if title.endswith("?"):
+            return "question"
+        return "feature_request"
+
+    return rule
+
+
+# Sample tickets the loop evaluates against. In production this is
+# live traffic; for the example we hard-code a representative mix.
+_TICKETS = [
+    # Bugs the production rule catches:
+    {"title": "app crashes on startup"},
+    {"title": "page crashes when I scroll"},
+    # Bugs the production rule MISSES (no "crash" keyword):
+    {"title": "got an error trying to log in"},
+    {"title": "the search index is down"},
+    {"title": "checkout is stuck on step 3"},
+    {"title": "broken: cannot upload files"},
+    {"title": "error 500 on dashboard refresh"},
+    {"title": "service is down for our team"},
+    # Real questions:
+    {"title": "how do I export data?"},
+    {"title": "is dark mode coming?"},
+    # Real feature requests:
+    {"title": "please add SAML support"},
+    {"title": "add a CSV export option"},
+    {"title": "i would love a dark theme"},
+    {"title": "support for keyboard shortcuts"},
+    # More bugs (mixed keywords):
+    {"title": "checkout error during payment"},
+    {"title": "page is broken after the update"},
+    {"title": "crash report attached"},
+    {"title": "everything is down right now"},
+    # More features:
+    {"title": "feature: bulk-upload UI"},
+    {"title": "add a setting for default view"},
+] * 5  # repeat to give the harness statistical power
+
+
+# ---------------------------------------------------------------------------
+# Reporting
+# ---------------------------------------------------------------------------
+
+
+def _print_report(iter_num: int, report: CandidateReport) -> None:
+    verdict = "PROMOTE" if report.recommend_promote else "HOLD  "
+    print(
+        f"iter {iter_num}: {report.candidate_name:14s}  "
+        f"prod_acc={report.prod_accuracy:.1%}  "
+        f"cand_acc={report.candidate_accuracy:.1%}  "
+        f"b={report.b}  c={report.c}  p={report.p_value:.2e}  "
+        f"-> {verdict}"
+    )
+
+
+if __name__ == "__main__":
+    random.seed(0)
+    main()