{"id":50596182,"url":"https://github.com/duke-of-beans/assertion-router","last_synced_at":"2026-06-05T14:30:29.526Z","repository":{"id":362164757,"uuid":"1257627302","full_name":"duke-of-beans/assertion-router","owner":"duke-of-beans","description":"4-mode confidence routing for AI systems. Routes outputs through ASSERT, PROBABILISTIC, INVESTIGATIVE, or REFUSE based on epistemic certainty.","archived":false,"fork":false,"pushed_at":"2026-06-02T23:02:34.000Z","size":5,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-03T01:06:19.830Z","etag":null,"topics":["ai-routing","confidence","decision-theory","epistemic","llm","reasoning-engine"],"latest_commit_sha":null,"homepage":"https://davidkirsch.me/builds","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/duke-of-beans.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-02T21:26:05.000Z","updated_at":"2026-06-02T23:02:38.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/duke-of-beans/assertion-router","commit_stats":null,"previous_names":["duke-of-beans/assertion-router"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/duke-of-beans/assertion-router","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/duke-of-beans%2Fassertion-router","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/duke-of-beans%2Fassertion-router/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/duke-of-beans%2Fassertion-router/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/duke-of-beans%2Fassertion-router/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/duke-of-beans","download_url":"https://codeload.github.com/duke-of-beans/assertion-router/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/duke-of-beans%2Fassertion-router/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33946818,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-05T02:00:06.157Z","response_time":120,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-routing","confidence","decision-theory","epistemic","llm","reasoning-engine"],"created_at":"2026-06-05T14:30:28.411Z","updated_at":"2026-06-05T14:30:29.519Z","avatar_url":"https://github.com/duke-of-beans.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Assertion Router\n\n**4-mode confidence routing for AI systems.**\n\n![Status](https://img.shields.io/badge/status-production-brightgreen)\n![License](https://img.shields.io/badge/license-MIT-green)\n\n---\n\n## The problem\n\nAI systems produce outputs at wildly different confidence levels but ship them all the same way. A factual lookup (\"What year was the Eiffel Tower built?\") and a speculative inference (\"Will interest rates drop next quarter?\") get the same treatment — same formatting, same certainty signals, same downstream handling. This destroys calibration at the system level.\n\n## The pattern\n\nThe Assertion Router classifies every output into one of four epistemic modes before it reaches the consumer:\n\n```\n                    ┌──────────────────┐\n                    │   Input Query    │\n                    └────────┬─────────┘\n                             │\n                    ┌────────▼─────────┐\n                    │  Confidence      │\n                    │  Assessment      │\n                    │  (CCS ≥ 7 axes) │\n                    └────────┬─────────┘\n                             │\n              ┌──────────────┼──────────────┐\n              │              │              │\n     ┌────────▼───┐  ┌──────▼─────┐ ┌──────▼──────┐\n     │  CCS ≥ 0.9 │  │ 0.5 ≤ CCS │ │  CCS \u003c 0.5  │\n     │            │  │   \u003c 0.9    │ │             │\n     └────────┬───┘  └──────┬─────┘ └──────┬──────┘\n              │              │              │\n     ┌────────▼───┐  ┌──────▼─────┐ ┌──────▼──────┐\n     │   ASSERT   │  │PROBABILISTIC│ │INVESTIGATIVE│\n     │            │  │            │ │             │\n     │ State as   │  │ State with │ │ Flag as     │\n     │ fact.      │  │ confidence │ │ requiring   │\n     │ No hedge.  │  │ bands and  │ │ further     │\n     │            │  │ caveats.   │ │ research.   │\n     └────────────┘  └────────────┘ └─────────────┘\n\n                    ┌──────────────────┐\n                    │     REFUSE       │\n                    │                  │\n                    │ Decline to       │\n                    │ answer. Veto     │\n                    │ Authority        │\n                    │ triggered or     │\n                    │ domain outside   │\n                    │ competence.      │\n                    └──────────────────┘\n```\n\n### Mode definitions\n\n| Mode | Trigger | Output behavior | Downstream signal |\n|------|---------|-----------------|-------------------|\n| **ASSERT** | CCS ≥ 0.9, all 7 axes above floor | State as fact. No hedging, no qualifiers. | High trust. Cache aggressively. |\n| **PROBABILISTIC** | 0.5 ≤ CCS \u003c 0.9 | State with confidence band, note which axes are weak. | Medium trust. Verify before acting. |\n| **INVESTIGATIVE** | CCS \u003c 0.5, or 2+ axes below floor | Flag as open question. Suggest research paths. | Low trust. Do not act without follow-up. |\n| **REFUSE** | Veto Authority triggered, domain mismatch, or ethical boundary | Decline to produce output. Explain why. | No trust. Route to human or specialist. |\n\n### Cascade integration\n\nWhen the router hits REFUSE, it doesn't just stop — it falls back through a **Cascade** chain: try a narrower interpretation, try a related domain expert, try to decompose the question into sub-questions that individually route to ASSERT or PROBABILISTIC. Only if the full Cascade exhausts does the system return REFUSE to the consumer.\n\n## The math\n\nThe router depends on a **Composite Confidence Score (CCS)** — a 7-axis weighted confidence function:\n\n```\nCCS = Σ(w_i × c_i)  where i ∈ {evidence, reasoning, calibration, source, domain, coherence, meta}\n```\n\nEach component `c_i ∈ [0, 1]` and weights `w_i` sum to 1. The mode thresholds (0.9, 0.5) and per-axis floors are tunable. See the [Composite Confidence Score](https://github.com/duke-of-beans/composite-confidence-score) repo for the full formula and component definitions.\n\n## TypeScript interfaces\n\n```typescript\nexport type AssertionMode = 'ASSERT' | 'PROBABILISTIC' | 'INVESTIGATIVE' | 'REFUSE';\n\nexport interface ConfidenceAxes {\n  evidence: number;      // 0-1: strength of supporting evidence\n  reasoning: number;     // 0-1: logical coherence of inference chain\n  calibration: number;   // 0-1: historical accuracy in this domain\n  source: number;        // 0-1: reliability of information sources\n  domain: number;        // 0-1: system competence in this topic\n  coherence: number;     // 0-1: internal consistency of output\n  meta: number;          // 0-1: confidence in the confidence assessment itself\n}\n\nexport interface AssertionResult {\n  mode: AssertionMode;\n  ccs: number;                    // composite confidence score\n  axes: ConfidenceAxes;           // per-axis breakdown\n  weakAxes: (keyof ConfidenceAxes)[];  // axes below floor\n  cascadeDepth: number;           // 0 if no cascade, N if fell back N times\n  reasoning: string;              // human-readable explanation of routing decision\n}\n\nexport interface RouterConfig {\n  assertFloor: number;            // CCS threshold for ASSERT (default: 0.9)\n  probabilisticFloor: number;     // CCS threshold for PROBABILISTIC (default: 0.5)\n  axisFloors: Partial\u003cRecord\u003ckeyof ConfidenceAxes, number\u003e\u003e;  // per-axis minimums\n  weights: Record\u003ckeyof ConfidenceAxes, number\u003e;               // axis weights (sum to 1)\n  cascadeEnabled: boolean;        // enable Cascade fallback on REFUSE\n  maxCascadeDepth: number;        // max fallback attempts (default: 3)\n}\n```\n\n## Reference implementation\n\n```typescript\nexport function route(axes: ConfidenceAxes, config: RouterConfig): AssertionResult {\n  const ccs = Object.entries(config.weights).reduce(\n    (sum, [axis, weight]) =\u003e sum + weight * axes[axis as keyof ConfidenceAxes], 0\n  );\n\n  const weakAxes = Object.entries(config.axisFloors)\n    .filter(([axis, floor]) =\u003e axes[axis as keyof ConfidenceAxes] \u003c (floor ?? 0))\n    .map(([axis]) =\u003e axis as keyof ConfidenceAxes);\n\n  let mode: AssertionMode;\n\n  if (weakAxes.length \u003e= 2 || ccs \u003c config.probabilisticFloor) {\n    mode = 'INVESTIGATIVE';\n  } else if (ccs \u003e= config.assertFloor \u0026\u0026 weakAxes.length === 0) {\n    mode = 'ASSERT';\n  } else if (ccs \u003e= config.probabilisticFloor) {\n    mode = 'PROBABILISTIC';\n  } else {\n    mode = 'REFUSE';\n  }\n\n  return { mode, ccs, axes, weakAxes, cascadeDepth: 0, reasoning: explainRouting(mode, ccs, weakAxes) };\n}\n\nfunction explainRouting(mode: AssertionMode, ccs: number, weakAxes: string[]): string {\n  switch (mode) {\n    case 'ASSERT': return `CCS ${ccs.toFixed(2)} above assert floor. All axes above minimum.`;\n    case 'PROBABILISTIC': return `CCS ${ccs.toFixed(2)} in probabilistic range.${weakAxes.length ? ` Weak: ${weakAxes.join(', ')}.` : ''}`;\n    case 'INVESTIGATIVE': return `CCS ${ccs.toFixed(2)} below threshold.${weakAxes.length \u003e= 2 ? ` ${weakAxes.length} axes below floor: ${weakAxes.join(', ')}.` : ''}`;\n    case 'REFUSE': return `Output vetoed. CCS ${ccs.toFixed(2)} insufficient for any assertion mode.`;\n  }\n}\n```\n\n## Production status\n\nIn production since March 2026 across a 38-project portfolio. The production implementation includes full Cascade integration, domain-specific weight profiles, and adaptive threshold tuning based on IMPRINT session reflections.\n\n## Prior art\n\n- **Epistemic logic** — modal logic frameworks for knowledge vs. belief (Hintikka 1962)\n- **Calibration in ML** — Guo et al. (2017), \"On Calibration of Modern Neural Networks\"\n- **Selective prediction** — Geifman \u0026 El-Yaniv (2017), reject option for classifiers\n- **Conformal prediction** — Vovk et al. (2005), distribution-free confidence sets\n\n## Part of the cognitive stack\n\nThis engine is one component of a [10-system cognitive architecture](https://github.com/duke-of-beans/cognitive-stack) for persistent AI development. Related engines:\n\n- [Composite Confidence Score](https://github.com/duke-of-beans/composite-confidence-score) — the 7-axis confidence function this router depends on\n- [Veto Authority](https://github.com/duke-of-beans/veto-authority) — the quality-floor veto that triggers REFUSE mode\n- [Tribunal](https://github.com/duke-of-beans/tribunal) — multi-perspective deliberation for INVESTIGATIVE-mode outputs\n- [ORACLE Router](https://github.com/duke-of-beans/oracle-router) — entropy-minimizing dispatch for follow-up actions\n\n---\n\n*Built by [David Kirsch](https://github.com/duke-of-beans). MIT License.*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fduke-of-beans%2Fassertion-router","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fduke-of-beans%2Fassertion-router","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fduke-of-beans%2Fassertion-router/lists"}