@reaatech/confidence-router

Status: Pre-1.0 — APIs may change in minor versions. Pin to a specific version in production.

A lightweight, pluggable routing engine that converts classification uncertainty into intelligent decisions. Given a classification result with confidence scores, it decides whether to route, clarify, or fallback.

This is the main entry point — it bundles all sub-packages (core, classifiers, languages, evaluation) and wires them together with sensible defaults. For tree-shaking or minimal installs, depend on the individual sub-packages directly.

Installation

npm install @reaatech/confidence-router
# or
pnpm add @reaatech/confidence-router

Requires Node.js >= 22.

Feature Overview

• Threshold-based decision engine — route high-confidence predictions, clarify ambiguous ones, fallback on uncertainty
• Pluggable classifiers — keyword, embedding similarity, and LLM (OpenAI/Anthropic) classifiers out of the box
• Multi-language clarification — 47 built-in locales with localized prompt templates and formatting
• Fallback chain execution — tries classifiers in priority order until one succeeds
• Threshold optimization — grid search across threshold combinations to maximize F1
• Dependency injection — swap out any component via constructor deps for custom behavior
• Zero external runtime dependencies — uses native fetch (Node 18+) for LLM calls
• Dual ESM/CJS output — works with import and require

Quick Start

import { ConfidenceRouter } from "@reaatech/confidence-router";

const router = new ConfidenceRouter({
  routeThreshold: 0.8,
  fallbackThreshold: 0.3,
  clarificationEnabled: true,
});

// Make a routing decision from a classification result
const decision = router.decide({
  predictions: [
    { label: "book_flight", confidence: 0.92 },
    { label: "check_status", confidence: 0.08 },
  ],
});

console.log(decision.type);  // "ROUTE"
console.log(decision.target); // "book_flight"

API Reference

ConfidenceRouter (class)

import { ConfidenceRouter } from "@reaatech/confidence-router";

const router = new ConfidenceRouter(config?, deps?);

Constructor

| Parameter | Type | Description | |-----------|------|-------------| | config | Partial<RouterConfig> | Optional configuration overrides | | deps | ConfidenceRouterDeps | Optional DI overrides for internal components |

RouterConfig

| Property | Type | Default | Description | |----------|------|---------|-------------| | routeThreshold | number | 0.8 | Confidence above this routes to the top label | | fallbackThreshold | number | 0.3 | Confidence below this triggers fallback | | clarificationEnabled | boolean | true | Enable the clarify decision band | | clarificationLanguages | string[] | ["en"] | Language codes for clarification prompts | | clarificationPromptTemplate | string | — | Custom prompt with {options} placeholder | | maxClarificationOptions | number | 3 | Max options to present in a clarify prompt | | defaultClassifier | string | — | Default classifier name to use | | fallbackHandler | FallbackHandler | — | Custom fallback decision handler |

Core Methods

| Method | Returns | Description | |--------|---------|-------------| | decide(classification) | RoutingDecision | Evaluates classification against thresholds | | decideBatch(classifications) | RoutingDecision[] | Batch evaluates multiple classifications | | classify(input, classifierName?, context?) | Promise<ClassificationResult> | Classifies input with a registered classifier | | process(input, classifierName?) | Promise<RoutingDecision> | End-to-end: classify then decide | | classifyWithFallback(input) | Promise<ClassificationResult> | Runs the fallback chain of classifiers |

Configuration Methods

| Method | Description | |--------|-------------| | updateConfig(config) | Merges new config; re-creates the internal decision engine | | getConfig() | Returns a copy of the current configuration |

Classifier Management

| Method | Description | |--------|-------------| | registerClassifier(classifier) | Registers a new classifier for use | | getClassifier(name) | Retrieves a registered classifier by name |

Evaluation Methods

| Method | Returns | Description | |--------|---------|-------------| | evaluate(dataset) | EvaluationMetrics | Evaluates current thresholds against a dataset | | optimizeThresholds(dataset, routeThresholds?, fallbackThresholds?) | OptimizedThresholds | Grid search for optimal thresholds |

RouterFactory

import { RouterFactory } from "@reaatech/confidence-router";

const router = RouterFactory.create({ routeThreshold: 0.9 });
const defaultRouter = RouterFactory.createWithDefaults();

| Method | Description | |--------|-------------| | RouterFactory.create(config?) | Creates a configured ConfidenceRouter | | RouterFactory.createWithDefaults() | Creates a ConfidenceRouter with all defaults |

Decision Tree

                    ┌─────────────────────┐
                    │  Classification      │
                    │  Result (score)      │
                    └──────────┬──────────┘
                               │
              ┌────────────────┼────────────────┐
              ▼                ▼                ▼
     score >= route     route > score    fallback >= score
       0.8 (default)    >= fallback      0.3 (default)
              │                │                │
              ▼                ▼                ▼
          ┌──────┐        ┌─────────┐     ┌──────────┐
          │ROUTE │        │ CLARIFY │     │ FALLBACK │
          └──────┘        └─────────┘     └──────────┘

Usage Patterns

With Built-in Classifiers

import { ConfidenceRouter, KeywordClassifier } from "@reaatech/confidence-router";

const router = new ConfidenceRouter();

router.registerClassifier(new KeywordClassifier([
  { label: "book", keywords: ["book", "reserve"] },
  { label: "cancel", keywords: ["cancel", "refund"] },
  { label: "status", keywords: ["status", "track"] },
]));

const decision = await router.process("I want to book a flight");

Multi-language Clarification

const router = new ConfidenceRouter({
  clarificationLanguages: ["en", "es", "ja"],
});

const decision = router.decide({
  predictions: [
    { label: "book_flight", confidence: 0.55 },
    { label: "check_status", confidence: 0.45 },
  ],
});

console.log(decision.type);  // "CLARIFY"
console.log(decision.prompt); // "Did you mean: book_flight or check_status?"

Threshold Optimization

const router = new ConfidenceRouter();

const dataset = {
  examples: [
    { input: "book a flight", expectedLabel: "book_flight" },
    { input: "cancel reservation", expectedLabel: "cancel" },
  ],
};

const optimal = router.optimizeThresholds(dataset);
// → { routeThreshold: 0.75, fallbackThreshold: 0.2, score: 0.92, metrics: {...} }

router.updateConfig({
  routeThreshold: optimal.routeThreshold,
  fallbackThreshold: optimal.fallbackThreshold,
});

Dependency Injection

import { ConfidenceRouter } from "@reaatech/confidence-router";
import { LanguageManager, PromptGenerator } from "@reaatech/confidence-router-languages";

const lm = new LanguageManager();
lm.addLanguage({ code: "tlh", name: "Klingon", nativeName: "tlhIngan Hol", direction: "ltr", ... });

const router = new ConfidenceRouter(undefined, {
  languageManager: lm,
  promptGenerator: new PromptGenerator(lm),
});

Related Packages

• @reaatech/confidence-router-core — Core types, config, errors, DecisionEngine
• @reaatech/confidence-router-classifiers — Built-in classifier implementations
• @reaatech/confidence-router-languages — Multi-language support (47 locales)
• @reaatech/confidence-router-evaluation — Threshold optimization

License

MIT