Skip to content
reaatech

@reaatech/llm-router-core

npm v1.0.0

Core TypeScript types, Zod schemas, and input validation for the llm-router ecosystem, providing 30+ domain types and 11 runtime validation schemas for model definitions, routing requests, configurations, budgets, quality scores, and cost telemetry. Exports composable enums, circuit breaker types, and dual ESM/CJS modules with zero runtime dependencies beyond `zod`.

npm →source →

@reaatech/llm-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 TypeScript types, Zod schemas, and input validation for the llm-router ecosystem. This package is the single source of truth for all domain types used throughout the @reaatech/llm-router-* monorepo.

Installation

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

Feature Overview

  • 30+ exported types — every routing domain object has a matching TypeScript interface
  • 11 Zod schemas — runtime validation for model definitions, routing requests, configs, budgets, quality scores, and cost telemetry
  • Composable enums — ModelCapability covers 13 capability axes (code, reasoning, vision, etc.)
  • Circuit breaker types — CLOSED | OPEN | HALF_OPEN state machine with config shapes
  • Zero dependencies beyond zod — lightweight and tree-shakeable
  • Dual ESM/CJS output — works with import and require

Quick Start

typescript
import {
  ModelDefinitionSchema,
  RoutingRequestSchema,
  RouterConfigSchema,
  type ModelDefinition,
  type RoutingRequest,
} from "@reaatech/llm-router-core";
 
// Validate a model definition at the boundary
const model = ModelDefinitionSchema.parse({
  id: "gpt-4-turbo",
  provider: "openai",
  costPerMillionInput: 10,
  costPerMillionOutput: 30,
  maxTokens: 128000,
  capabilities: ["code", "reasoning"],
});
 
// Validate an incoming routing request
const req = RoutingRequestSchema.parse({
  prompt: "Review this code for bugs.",
  strategy: "cost-optimized",
  maxTokens: 4096,
});

Exports

Domain Types

The core domain objects the entire router operates on.

ExportDescription
ModelDefinitionModel config: id, provider, cost per million tokens, max tokens, capabilities, API key env
ModelCapabilityString enum: code, reasoning, vision, long-context, analysis, general, chinese, evaluation, complex-reasoning, creative, math, summarization, translation
RoutingRequestIncoming request: prompt, maxTokens, requiredCapabilities, budgetId, strategy, userTier, timeoutMs, confidenceThreshold, metadata
RoutingContextStrategy decision context: timestamp, requestId, latency history per model, circuit breaker states, remaining budget
RoutingDecisionSelected model: modelId, strategy, estimated cost/tokens, isFallback, fallbackPosition, alternatives considered, selection reason
RoutingResultExecution result: decision, actual cost/tokens, latencyMs, content, success flag, qualityScore, requestId, completedAt
RoutingStrategyStrategy interface: name, priority, applies(), select()

Fallback & Resilience

ExportDescription
FallbackChainDefinitionOrdered model list with circuit breaker config
CircuitBreakerConfigThresholds: failureThreshold, resetTimeoutMs, halfOpenMaxCalls
CircuitBreakerStateCLOSED" | "OPEN" | "HALF_OPEN

Cost & Budget

ExportDescription
CostTelemetryPer-request record: requestId, modelId, cost, inputTokens, outputTokens, strategy, budgetId, timestamp
BudgetConfigDaily limit, alert thresholds (fractions of limit), hard/soft limit, reset schedule
BudgetStateSpending tracking: spentToday, remaining, limitExceeded, alerts triggered

Evaluation

ExportDescription
QualityScoreMulti-criteria score: overall, relevance, correctness, completeness, clarity, custom criteria, explanation
EvalResultPer-request evaluation: requestId, modelId, qualityScore, criteria breakdown, evaluator model, metadata

Schemas (Zod)

Every domain type has a corresponding Zod schema for runtime validation.

ExportValidates
ModelDefinitionSchemaModel config objects
RoutingRequestSchemaIncoming routing requests
RoutingDecisionSchemaRouter’s model selections
RoutingResultSchemaExecution results
RouterConfigSchemaThe complete YAML/JSON router config file
StrategyConfigSchemaStrategy configuration blocks (cost-optimized, latency-optimized, etc.)
FallbackChainSchemaFallback chain definitions
CircuitBreakerConfigSchemaCircuit breaker thresholds
BudgetConfigSchemaBudget configurations
QualityScoreSchemaQuality evaluation results
CostTelemetrySchemaCost tracking records

Schema Input Types

ExportDescription
ModelDefinitionInputz.infer<typeof ModelDefinitionSchema>
RoutingRequestInputz.infer<typeof RoutingRequestSchema>
RouterConfigInputz.infer<typeof RouterConfigSchema>
StrategyConfigInputz.infer<typeof StrategyConfigSchema>
FallbackChainInputz.infer<typeof FallbackChainSchema>
BudgetConfigInputz.infer<typeof BudgetConfigSchema>

Usage Pattern

Every schema export has a matching type export. Use the schema for runtime validation and the type for compile-time checking:

typescript
import { ModelDefinitionSchema, type ModelDefinition } from "@reaatech/llm-router-core";
 
function loadModel(raw: unknown): ModelDefinition {
  // Parse at the boundary — throws ZodError on invalid data
  return ModelDefinitionSchema.parse(raw);
}

Related Packages

License

MIT

All packagesllm-router overview