Skip to content
reaatechREAATECH

@reaatech/llm-router-core

npm v1.0.0

Provides the shared TypeScript interfaces and Zod schemas for defining LLM routing configurations, budget tracking, and circuit breaker states. It serves as the foundational type library for the `@reaatech/llm-router` ecosystem, requiring `zod` as a runtime dependency for schema validation.

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