Skip to content
reaatechREAATECH

@reaatech/confidence-router-core

npm v0.1.0

Provides the core type definitions, configuration utilities, and the `DecisionEngine` class for evaluating classification confidence against routing thresholds. It serves as the foundational library for building custom routing logic within the confidence-router ecosystem.

npm →source →

@reaatech/confidence-router-core

npm version License: MIT CI

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

Core type definitions, error classes, configuration utilities, and the DecisionEngine for the confidence-router ecosystem. This package is the single source of truth for all type shapes used throughout @reaatech/confidence-router-*.

Installation

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

Feature Overview

  • All public type definitions — Prediction, ClassificationResult, RoutingDecision, RouterConfig, Classifier interface, and more
  • Typed error class — RouterError with enumerated RouterErrorType codes for every failure mode
  • DecisionEngine — pure-function threshold evaluator that scores confidence against route/clarify/fallback boundaries
  • Configuration utilities — DEFAULT_CONFIG, validateConfig, mergeConfig with built-in sanity checks
  • Dependency injection interfaces — RouterInterface, ClassifierRegistryInterface, LanguageManagerInterface, PromptGeneratorInterface, ConfidenceRouterDeps
  • Zero runtime dependencies — lightweight and tree-shakeable
  • Dual ESM/CJS output — works with import and require

Quick Start

typescript
import { DecisionEngine, mergeConfig, RouterError, RouterErrorType } from "@reaatech/confidence-router-core";
 
const engine = new DecisionEngine(
  mergeConfig({ routeThreshold: 0.8, fallbackThreshold: 0.3, clarificationEnabled: true })
);
 
const decision = engine.decide({
  predictions: [
    { label: "book_flight", confidence: 0.92 },
    { label: "check_status", confidence: 0.08 },
  ],
});
 
console.log(decision.type); // "ROUTE"

API Reference

Types

ExportDescription
Prediction{ label: string; confidence: number; metadata?: Record<string, unknown> }
ClassificationResult{ predictions: Prediction[]; metadata?: ... }
RoutingDecision{ type: DecisionType; confidence?, target?, prompt?, options?, metadata? }
RouterConfigAll configuration fields: routeThreshold, fallbackThreshold, clarificationEnabled, clarificationLanguages?, maxClarificationOptions?, etc.
DecisionTypeUnion: ROUTE" | "CLARIFY" | "FALLBACK
ClassifierInterface: name, type, enabled, priority, classify(input, context?), validate?()
LanguageConfig{ code, name, nativeName, direction, clarificationTemplates, formatting }
EvaluationDataset{ examples: LabeledExample[]; metadata? }
LabeledExample{ input, expectedLabel, expectedDecision?, predictions?, context? }
EvaluationMetrics{ accuracy, precision, recall, f1Score, confusionMatrix, decisionsByType }
OptimizedThresholds{ routeThreshold, fallbackThreshold, score, metrics }
FallbackHandler(classification: ClassificationResult) => RoutingDecision

Errors

All errors extend the standard Error class and carry a type discriminator.

ClassType EnumWhen
RouterError(varies)Base class for all routing errors
RouterErrorType.CONFIGURATION_ERROR—Invalid configuration
RouterErrorType.CLASSIFICATION_ERROR—Invalid classifier output
RouterErrorType.LANGUAGE_NOT_SUPPORTED—Unknown language code
RouterErrorType.THRESHOLD_INVALID—Threshold out of [0, 1] range
RouterErrorType.CLASSIFIER_NOT_FOUND—Named classifier not registered
RouterErrorType.DATASET_INVALID—Evaluation dataset invalid
typescript
import { RouterError, RouterErrorType } from "@reaatech/confidence-router-core";
 
throw new RouterError(
  RouterErrorType.THRESHOLD_INVALID,
  "routeThreshold must be between 0 and 1",
  { detail: "extra context" }
);

DecisionEngine

typescript
import { DecisionEngine } from "@reaatech/confidence-router-core";
MethodReturnsDescription
decide(classification)RoutingDecisionEvaluates top prediction confidence against configured thresholds
evaluateThresholds(score)DecisionTypeMaps a raw confidence score to ROUTE, CLARIFY, or FALLBACK

Configuration Utilities

ExportDescription
DEFAULT_CONFIGDefault RouterConfig (routeThreshold: 0.8, fallbackThreshold: 0.3, clarificationEnabled: true)
validateConfig(config)Throws RouterError if thresholds are invalid or maxClarificationOptions < 2
mergeConfig(partial?)Merges a partial config with defaults

Dependency Injection Interfaces

InterfaceMethods
RouterInterfacedecide(), getConfig(), updateConfig()
ClassifierRegistryInterfaceregister(), get(), classify(), getFallbackChain()
LanguageManagerInterfacegetLanguage(), addLanguage(), hasLanguage(), getSupportedLanguages()
PromptGeneratorInterfacegenerate(predictions, languageCode, customTemplate?, maxOptions?)
ConfidenceRouterDeps{ languageManager?, promptGenerator?, classifierRegistry? }

Usage with Dependency Injection

The ConfidenceRouterDeps interface allows callers to inject custom implementations:

typescript
import type { ConfidenceRouterDeps } from "@reaatech/confidence-router-core";
 
const deps: ConfidenceRouterDeps = {
  languageManager: new CustomLanguageManager(),
  promptGenerator: new CustomPromptGenerator(lm),
  classifierRegistry: new CustomRegistry(),
};

Decision Logic

code
score >= routeThreshold    →  ROUTE
score <  fallbackThreshold  →  FALLBACK
otherwise (clarify enabled)  →  CLARIFY
otherwise                    →  FALLBACK

Related Packages

License

MIT

All packagesconfidence-router overview