Why Verdict?

The problem it solves

Agents may use frontier, hosted, or local providers, but Verdict does not assume that a catalog entry is reachable or qualified.

Verdict is the decision layer between your task and those providers:

1. Understand the task's difficulty, risk, context, and tool needs.
2. Remove models that cannot safely or reliably handle it.
3. Send routine work to the least expensive capable option.
4. Escalate difficult or sensitive work to a frontier model when justified.
5. Record why the route was chosen and what happened.

The goal is not “always use the cheapest model.” The goal is use the cheapest model that is good enough—and keep premium capacity available for the work that needs it.

Most AI tooling starts with: "which model should I use?"

Verdict starts earlier: "should this action happen, which choices are allowed, and can we prove what happened?"

In plain English: Verdict helps you use more of the models you already pay for—free, low-cost, and frontier—without sending every task to the most expensive option. It blocks choices that violate your rules, budget, privacy, or safety requirements.

It's the difference between a recommendation engine and a control plane:

An optional orchestrator can do the expensive research. The gate (deterministic Python, no LLM in the enforcement path) does the enforcing. Neither can do the other's job — by design, codified in 20+ ADRs.

Verdict Core is a deterministic execution-policy control plane that sits between your agents and model providers:

┌─────────────────────────────────────────────────────────────────┐
│                        YOUR AGENTS                              │
└─────────────────────────┬───────────────────────────────────────┘
                          ▼
┌─────────────────────────────────────────────────────────────────┐
│                    VERDICT CORE (Control Plane)                 │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐            │
│  │  Eligibility │ │  Adaptive    │ │  Evidence    │            │
│  │  Gate        │ │  Ranking     │ │  Chain       │            │
│  └──────────────┘ └──────────────┘ └──────────────┘            │
└─────────────────────────┬───────────────────────────────────────┘
                          ▼
┌─────────────────────────────────────────────────────────────────┐
│              EXPLICIT PROVIDER / ROUTE ADAPTERS                │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐            │
│  │  19 Strategies│ │  Quota Guard │ │  Cost/Quality│            │
│  └──────────────┘ └──────────────┘ └──────────────┘            │
└─────────────────────────┬───────────────────────────────────────┘
                          ▼
┌─────────────────────────────────────────────────────────────────┐
│              MODEL PROVIDERS (operator-configured)              │
│  Anthropic • OpenAI • OpenRouter • Local • Custom              │
└─────────────────────────────────────────────────────────────────┘

Key Features

30-Second Demo

No API keys. No config. Deterministic, offline, auditable. This is a local fixture demo—not a live provider call or production-readiness proof:

verdict quickstart --non-interactive --dry-run

Verdict credential-free quickstart
===================================
Task: Add structured output to the invoice parser
Required capabilities: structured_output, tools
Selected route: demo/frontier-tools
Excluded candidates: 3
Status: PASS
- demo/no-tools: missing capability: tools
- demo/quota-empty: quota exhausted
- demo/unverified: health unknown

Every exclusion carries a machine-readable reason and state (capability_mismatch, quota_exhausted, unknown). That's the gate working.

Install → provider → route → mission → failover → replay

Follow the full user journey for the commands, evidence, and maturity limits. In short:

uv sync --extra dev
verdict --help
verdict detect --offline --json         # no-probe offline status; no prompt sent
verdict quickstart --non-interactive --dry-run --json  # offline route proof

The mission, failover, and replay stages are also available as bounded offline proofs. They do not imply live provider availability or generated-output quality. Run the forced failover proof and reload the persisted session:

verdict failover-proof --memory-path /tmp/failover.db --json
VERDICT_MEMORY_DB=/tmp/failover.db verdict replay <session-id> --json

Use route only as a local policy decision preview after configuring provider metadata; it does not send the prompt to a model:

verdict route "summarize this change" --criticality low --terse

Install

# Recommended: transparent source install (uv)
# Requires Python 3.10+ and uv.
git clone https://github.com/mrnicholasbcarter-code/verdict-core.git
cd verdict-core
uv sync --extra dev --extra server --extra dashboard

# Optional convenience installer (review release assets first; Linux/macOS)
curl -fsSL https://raw.githubusercontent.com/mrnicholasbcarter-code/verdict-core/main/install.sh | bash

Then:

verdict setup            # interactive setup wizard (supports --dry-run --json)
verdict doctor --fix     # scan & repair config / connectivity issues
verdict detect           # discover available LLM providers on this machine

Cost Demo

# Run a fixture simulation; its numbers are not live-provider evidence
python scripts/demo-routing.py

# Output shows:
# - Always Opus:      $12.47
# - Always Haiku:     $0.18
# - Verdict Routed:   $1.23
# - SAVINGS vs Opus:  $11.24 (90.1%)
# - Quality gates:    Reasoning→Frontier 88%, Simple→Cheap 92%

How It Works

                    ┌──────────────────────────────────────────────┐
                    │           ORCHESTRATOR (frontier model)       │
                    │  1. Research the task                         │
                    │  2. Review the OmniRoute catalog              │
                    │  3. Pick right-sized candidates per slice     │
                    │  4. Dispatch workers (Ruflo swarms / agents)  │
                    └──────────────────┬───────────────────────────┘
                                       │ candidate set
                                       ▼
                    ┌──────────────────────────────────────────────┐
                    │        ELIGIBILITY GATE (deterministic)       │
                    │  ✓ Capability passports  ✓ Budget floors     │
                    │  ✓ Privacy policy        ✓ Probe-verified     │
                    │    availability (TTL + stale-while-revalidate)│
                    │                                               │
                    │  PROTECTED WORK: fail-closed when fresh truth │
                    │  is absent. Intelligence is advisory — it can │
                    │  NEVER re-admit an excluded candidate.        │
                    └──────────────────┬───────────────────────────┘
                                       │ admitted set
                                       ▼
                    Workers execute → outcomes → SONA / RuVector
                    (learning loop improves advice, not authorization)

The gate has no selection logic. The orchestrator has no enforcement power. That separation is the whole point — see ADR-002 and the Routing Policy.

Hard guarantees (test-enforced)

• Intelligence cannot re-admit an excluded candidate — test_ranker_cannot_reintroduce_excluded_candidate
• Protected work fails closed when fresh truth is absent — test_protected_work_fails_closed_when_truth_absent
• Gate filters before any ranking — test_intelligence_route_filters_before_ranking
• Explain surface carries per-model eligibility and exclusions — test_explain_surfaces_eligible_set_and_exclusions
• Budget, concurrency, and timeout limits enforced — over-budget plans and replan increases rejected (tests/test_planner.py, tests/test_ruflo_verification.py)
• Every claim maps to acceptance criteria in ACCEPTANCE_GATES.md — CI fails if any gate lacks evidence

Evidence-backed public claims

Every public claim carries a status in the claims ledger — verified, observed, partial, self-reported, or unsupported — indexed in the proof matrix. Catalog counts are historical observations, not proof that every advertised route is live. The portfolio proof matrix maps each audience story to reproducible evidence and states its limits.

CLI Reference

verdict setup          Interactive setup wizard (plan / --dry-run / --json)
verdict route          Route a task: --criticality {critical,high,medium,low} --terse
verdict quickstart     Credential-free deterministic flagship demo
verdict detect         Discover local LLM providers (--config emits suggested config)
verdict probe          1-token liveness probe (--allow-live-probe for explicit consent)
verdict catalog        Qualify an OmniRoute catalog snapshot (bounded sample probes)
verdict benchmark      Reproducible local benchmark harness (--fixture, --output-json)
verdict stats          Routing analytics
verdict suggest        Review intelligence suggestions from past outcomes
verdict serve          Launch the FastAPI microservice
verdict ui             Launch the Streamlit analytics dashboard
verdict doctor         Scan & repair configuration (--fix, --json)
verdict runtime        Inspect/reconcile global Ruflo/RuVector ownership
verdict memory         Local-first unified memory plane (put/search/export/import/...)
verdict check          Validate config syntax and sanity
verdict uninstall      Reversibly remove hooks and MCP registrations

Full flags and examples: docs/CLI_REFERENCE.md

Configuration

Layered — project overrides global:

1. Global: ~/.verdict/config.toml
2. Project: .verdict/config.toml

[gateway]
primary_model = "anthropic/claude-3-opus-20240229"   # frontier floor for protected work
providers = {}

[intelligence]
profile = "balanced"        # fast | balanced | thorough
timeout_ms = 8000
allow_client_model_override = false

[availability]
ttl_seconds = 60            # availability cache TTL
stale_window_seconds = 30   # stale-while-revalidate window
omniroute_base_url = "http://localhost:20128"   # optional live catalog

Full reference: docs/CONFIGURATION.md

Architecture

Design decisions live in docs/adr/ — 26 numbered records covering the evidence ledger, orchestrator boundary, fail-closed capability passports, consented probes, catalog qualification, gateway adapter contracts, and more. The ADR index lists every record with its decision and current status.

Ecosystem-stories ADR trail (verdict-ecosystem tracks the source stories):

TypeScript ecosystem

TypeScript packages are published under the current @bodanglin/* namespace. Check each package README and release metadata before integrating:

Python ↔ TypeScript field-level parity is verified in CI — see CONTRACT_PARITY.md.

Ecosystem repos

Security

• Fail-closed protected work: protected actions halt when required fresh truth is unavailable — no silent fallback
• Consent-gated probes: network liveness checks require explicit --allow-live-probe
• Privacy: privacy-safe receipt ledger (THREAT_MODEL_RECEIPTS.md); logs and evidence must not contain PII
• Supply chain: CI runs dependency/security checks on protected-branch pushes, pull requests, and scheduled runs; see security workflow for scope and documented exceptions
• Installer trust: source/uv installation is the most transparent path; review install.sh and release assets before using curl | bash
• Report vulnerabilities: see SECURITY.md

Documentation

Development

# Tests (81 test files — unit + integration)
uv run pytest -q

# Lint & format
uv run --extra dev --extra server --extra dashboard ruff check .
uv run --extra dev --extra server --extra dashboard ruff format --check .

# Type check (strict)
uv run --extra dev --extra server --extra dashboard mypy verdict --strict

# Build
uv run python -m build

Contributing guide: CONTRIBUTING.md · Versioning: VERSIONING.md · Release process: RELEASE_CHECKLIST.md

License

MIT — © Verdict contributors

Built by Nicholas Carter — 25 years shipping systems at GM OnStar, Deloitte, BCBS Michigan, Mad Mobile/Stäubli, and now AI orchestration.