https://github.com/duke-of-beans/assertion-router
4-mode confidence routing for AI systems. Routes outputs through ASSERT, PROBABILISTIC, INVESTIGATIVE, or REFUSE based on epistemic certainty.
https://github.com/duke-of-beans/assertion-router
ai-routing confidence decision-theory epistemic llm reasoning-engine
Last synced: 8 days ago
JSON representation
4-mode confidence routing for AI systems. Routes outputs through ASSERT, PROBABILISTIC, INVESTIGATIVE, or REFUSE based on epistemic certainty.
- Host: GitHub
- URL: https://github.com/duke-of-beans/assertion-router
- Owner: duke-of-beans
- Created: 2026-06-02T21:26:05.000Z (10 days ago)
- Default Branch: main
- Last Pushed: 2026-06-02T23:02:34.000Z (10 days ago)
- Last Synced: 2026-06-03T01:06:19.830Z (10 days ago)
- Topics: ai-routing, confidence, decision-theory, epistemic, llm, reasoning-engine
- Language: TypeScript
- Homepage: https://davidkirsch.me/builds
- Size: 4.88 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Assertion Router
**4-mode confidence routing for AI systems.**
---
## The problem
AI 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.
## The pattern
The Assertion Router classifies every output into one of four epistemic modes before it reaches the consumer:
```
┌──────────────────┐
│ Input Query │
└────────┬─────────┘
│
┌────────▼─────────┐
│ Confidence │
│ Assessment │
│ (CCS ≥ 7 axes) │
└────────┬─────────┘
│
┌──────────────┼──────────────┐
│ │ │
┌────────▼───┐ ┌──────▼─────┐ ┌──────▼──────┐
│ CCS ≥ 0.9 │ │ 0.5 ≤ CCS │ │ CCS < 0.5 │
│ │ │ < 0.9 │ │ │
└────────┬───┘ └──────┬─────┘ └──────┬──────┘
│ │ │
┌────────▼───┐ ┌──────▼─────┐ ┌──────▼──────┐
│ ASSERT │ │PROBABILISTIC│ │INVESTIGATIVE│
│ │ │ │ │ │
│ State as │ │ State with │ │ Flag as │
│ fact. │ │ confidence │ │ requiring │
│ No hedge. │ │ bands and │ │ further │
│ │ │ caveats. │ │ research. │
└────────────┘ └────────────┘ └─────────────┘
┌──────────────────┐
│ REFUSE │
│ │
│ Decline to │
│ answer. Veto │
│ Authority │
│ triggered or │
│ domain outside │
│ competence. │
└──────────────────┘
```
### Mode definitions
| Mode | Trigger | Output behavior | Downstream signal |
|------|---------|-----------------|-------------------|
| **ASSERT** | CCS ≥ 0.9, all 7 axes above floor | State as fact. No hedging, no qualifiers. | High trust. Cache aggressively. |
| **PROBABILISTIC** | 0.5 ≤ CCS < 0.9 | State with confidence band, note which axes are weak. | Medium trust. Verify before acting. |
| **INVESTIGATIVE** | CCS < 0.5, or 2+ axes below floor | Flag as open question. Suggest research paths. | Low trust. Do not act without follow-up. |
| **REFUSE** | Veto Authority triggered, domain mismatch, or ethical boundary | Decline to produce output. Explain why. | No trust. Route to human or specialist. |
### Cascade integration
When 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.
## The math
The router depends on a **Composite Confidence Score (CCS)** — a 7-axis weighted confidence function:
```
CCS = Σ(w_i × c_i) where i ∈ {evidence, reasoning, calibration, source, domain, coherence, meta}
```
Each 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.
## TypeScript interfaces
```typescript
export type AssertionMode = 'ASSERT' | 'PROBABILISTIC' | 'INVESTIGATIVE' | 'REFUSE';
export interface ConfidenceAxes {
evidence: number; // 0-1: strength of supporting evidence
reasoning: number; // 0-1: logical coherence of inference chain
calibration: number; // 0-1: historical accuracy in this domain
source: number; // 0-1: reliability of information sources
domain: number; // 0-1: system competence in this topic
coherence: number; // 0-1: internal consistency of output
meta: number; // 0-1: confidence in the confidence assessment itself
}
export interface AssertionResult {
mode: AssertionMode;
ccs: number; // composite confidence score
axes: ConfidenceAxes; // per-axis breakdown
weakAxes: (keyof ConfidenceAxes)[]; // axes below floor
cascadeDepth: number; // 0 if no cascade, N if fell back N times
reasoning: string; // human-readable explanation of routing decision
}
export interface RouterConfig {
assertFloor: number; // CCS threshold for ASSERT (default: 0.9)
probabilisticFloor: number; // CCS threshold for PROBABILISTIC (default: 0.5)
axisFloors: Partial>; // per-axis minimums
weights: Record; // axis weights (sum to 1)
cascadeEnabled: boolean; // enable Cascade fallback on REFUSE
maxCascadeDepth: number; // max fallback attempts (default: 3)
}
```
## Reference implementation
```typescript
export function route(axes: ConfidenceAxes, config: RouterConfig): AssertionResult {
const ccs = Object.entries(config.weights).reduce(
(sum, [axis, weight]) => sum + weight * axes[axis as keyof ConfidenceAxes], 0
);
const weakAxes = Object.entries(config.axisFloors)
.filter(([axis, floor]) => axes[axis as keyof ConfidenceAxes] < (floor ?? 0))
.map(([axis]) => axis as keyof ConfidenceAxes);
let mode: AssertionMode;
if (weakAxes.length >= 2 || ccs < config.probabilisticFloor) {
mode = 'INVESTIGATIVE';
} else if (ccs >= config.assertFloor && weakAxes.length === 0) {
mode = 'ASSERT';
} else if (ccs >= config.probabilisticFloor) {
mode = 'PROBABILISTIC';
} else {
mode = 'REFUSE';
}
return { mode, ccs, axes, weakAxes, cascadeDepth: 0, reasoning: explainRouting(mode, ccs, weakAxes) };
}
function explainRouting(mode: AssertionMode, ccs: number, weakAxes: string[]): string {
switch (mode) {
case 'ASSERT': return `CCS ${ccs.toFixed(2)} above assert floor. All axes above minimum.`;
case 'PROBABILISTIC': return `CCS ${ccs.toFixed(2)} in probabilistic range.${weakAxes.length ? ` Weak: ${weakAxes.join(', ')}.` : ''}`;
case 'INVESTIGATIVE': return `CCS ${ccs.toFixed(2)} below threshold.${weakAxes.length >= 2 ? ` ${weakAxes.length} axes below floor: ${weakAxes.join(', ')}.` : ''}`;
case 'REFUSE': return `Output vetoed. CCS ${ccs.toFixed(2)} insufficient for any assertion mode.`;
}
}
```
## Production status
In 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.
## Prior art
- **Epistemic logic** — modal logic frameworks for knowledge vs. belief (Hintikka 1962)
- **Calibration in ML** — Guo et al. (2017), "On Calibration of Modern Neural Networks"
- **Selective prediction** — Geifman & El-Yaniv (2017), reject option for classifiers
- **Conformal prediction** — Vovk et al. (2005), distribution-free confidence sets
## Part of the cognitive stack
This engine is one component of a [10-system cognitive architecture](https://github.com/duke-of-beans/cognitive-stack) for persistent AI development. Related engines:
- [Composite Confidence Score](https://github.com/duke-of-beans/composite-confidence-score) — the 7-axis confidence function this router depends on
- [Veto Authority](https://github.com/duke-of-beans/veto-authority) — the quality-floor veto that triggers REFUSE mode
- [Tribunal](https://github.com/duke-of-beans/tribunal) — multi-perspective deliberation for INVESTIGATIVE-mode outputs
- [ORACLE Router](https://github.com/duke-of-beans/oracle-router) — entropy-minimizing dispatch for follow-up actions
---
*Built by [David Kirsch](https://github.com/duke-of-beans). MIT License.*