@aria-cli/models

@aria/models

Model abstraction layer for ARIA with centralized model registry.

Overview

The @aria/models package provides:

• Model Registry - Single source of truth for all model definitions
• Model Router - Intelligent routing based on query characteristics
• Provider Abstraction - Unified interface for Anthropic, OpenAI, Google, xAI, and local models
• Routing Rules - Declarative rules for automatic model selection
• Type Safety - Full TypeScript support with strict types

Model Registry

The model registry is the single source of truth for all model definitions in ARIA. It centralizes model metadata, enabling zero-migration updates when models change.

Quick Start

import {
  MODELS,
  MODEL_REGISTRY,
  getModelByTier,
  getCliModels,
  toShortName,
} from "@aria/models";

// Access models by constant
const opus = MODELS.opus_4_6;
console.log(opus.id); // "claude-opus-4-6"
console.log(opus.displayName); // "Claude Opus 4.6"

// Get model by tier
const powerfulModel = getModelByTier("powerful");
// Returns: { id: "claude-opus-4-6", tier: "powerful", ... }

// Get all models for CLI
const cliModels = getCliModels(false);
// Returns: [haiku_4_5, sonnet_4_5, opus_4_6]

// Convert model ID to short name
const shortName = toShortName("claude-opus-4-6");
// Returns: "opus-4.6"

Model Registry Types

// Model tier classification
type ModelTier = "fast" | "balanced" | "powerful" | "ensemble";

// Model provider
type ModelProvider = "anthropic" | "openai" | "google" | "xai" | "local";

// Model capabilities
type ModelCapability = "thinking" | "tools" | "vision" | "streaming";

// Complete model definition
interface ModelDefinition {
  // Identity
  id: string; // Full model ID (e.g., "claude-opus-4-6")
  shortName: string; // Display name (e.g., "opus-4.6")
  displayName: string; // UI name (e.g., "Opus 4.6")

  // Classification
  tier: ModelTier;
  provider: ModelProvider;

  // UI
  description: string; // Short description for tooltips
  tierDisplayName: string; // Tier name for UI (e.g., "Deep Thinking")

  // Technical
  capabilities: ModelCapability[];
  maxContextTokens: number;
  maxOutputTokens: number;

  // Pricing (USD per 1M tokens)
  pricing: {
    inputPerMToken: number;
    outputPerMToken: number;
  };
}

Available Models

export const MODELS = {
  haiku_4_5: {
    id: "claude-haiku-4-5-20251001",
    shortName: "haiku-4.5",
    displayName: "Claude Haiku 4.5",
    tier: "fast",
    tierDisplayName: "Quick",
    provider: "anthropic",
    description: "Fast, cost-effective model for high-volume tasks",
    capabilities: ["tools", "streaming", "vision"],
    maxContextTokens: 200_000,
    maxOutputTokens: 8_192,
    pricing: { inputPerMToken: 0.8, outputPerMToken: 4.0 },
  },

  sonnet_4_5: {
    id: "claude-sonnet-4-5-20250929",
    shortName: "sonnet-4.5",
    displayName: "Claude Sonnet 4.5",
    tier: "balanced",
    tierDisplayName: "Standard",
    provider: "anthropic",
    description: "Balanced performance and cost for most tasks",
    capabilities: ["tools", "streaming", "vision"],
    maxContextTokens: 200_000,
    maxOutputTokens: 8_192,
    pricing: { inputPerMToken: 3.0, outputPerMToken: 15.0 },
  },

  opus_4_6: {
    id: "claude-opus-4-6",
    shortName: "opus-4.6",
    displayName: "Claude Opus 4.6",
    tier: "powerful",
    tierDisplayName: "Deep Thinking",
    provider: "anthropic",
    description: "Most capable model with extended thinking for complex tasks",
    capabilities: ["thinking", "tools", "streaming", "vision"],
    maxContextTokens: 200_000,
    maxOutputTokens: 8_192,
    pricing: { inputPerMToken: 15.0, outputPerMToken: 75.0 },
  },
};

export const MODEL_REGISTRY: readonly ReadonlyModelDefinition[] =
  Object.values(MODELS);

Registry API

Lookup Functions

// Get model by tier (returns first match)
function getModelByTier(tier: ModelTier): ModelDefinition | undefined;

// Get model by full ID
function getModelById(id: string): ModelDefinition | undefined;

// Get model by short name
function getModelByShortName(shortName: string): ModelDefinition | undefined;

// Get all models for a specific tier
function getModelsByTier(tier: ModelTier): ModelDefinition[];

UI Helpers

// Get models suitable for CLI quick-select
function getCliModels(showEnsemble = true): ModelDefinition[];

// Convert model ID to short display name
function toShortName(modelId: string): string;

// Get tier display name for UI
function getTierDisplayName(tier: ModelTier): string;

// Check if a tier is valid
function isValidTier(tier: unknown): tier is ModelTier;

Usage Examples

Router Integration

import { MODELS, ModelRouter } from "@aria/models";

export function createDefaultRouter(): ModelRouter {
  return new ModelRouter({
    fast: {
      provider: MODELS.haiku_4_5.provider,
      model: MODELS.haiku_4_5.id,
    },
    balanced: {
      provider: MODELS.sonnet_4_5.provider,
      model: MODELS.sonnet_4_5.id,
    },
    powerful: {
      provider: MODELS.opus_4_6.provider,
      model: MODELS.opus_4_6.id,
    },
    ensemble: [
      { provider: MODELS.opus_4_6.provider, model: MODELS.opus_4_6.id },
      { provider: "openai", model: "gpt-5.2" },
    ],
  });
}

CLI Integration

import { getCliModels } from "@aria/models";

const models: ModelOption[] = getCliModels(false).map((m) => ({
  name: m.shortName,
  description: m.tierDisplayName,
  isCurrent: currentTier === m.tier,
}));

Config Integration (Tier-Based Storage)

import { getModelByTier, ModelTier } from "@aria/models";

interface AriaConfig {
  preferredTier?: ModelTier; // Store tier, not model name
}

// Load config and resolve tier to model
const config = loadConfig();
const tier = config.preferredTier || "balanced";
const model = getModelByTier(tier);

console.log(model?.shortName); // "sonnet-4.5"

Benefits

• Single Source of Truth - Update model version in ONE place
• Zero-Migration Updates - When Opus 4.7 releases, users automatically get it (no config migration)
• Type Safety - Full TypeScript types prevent invalid references
• UI Consistency - All UIs use same model metadata
• Rich Metadata - Capabilities, pricing, display names in one place

Migration Guide

If you're using hardcoded model IDs:

// ❌ Before (hardcoded)
const provider = "anthropic";
const model = "claude-opus-4-6";

// ✅ After (registry)
import { MODELS } from "@aria/models";
const provider = MODELS.opus_4_6.provider;
const model = MODELS.opus_4_6.id;

If you're storing model names in config:

// ❌ Before (stores model name)
interface Config {
  preferredModel?: string; // "opus-4.6"
}

// ✅ After (stores tier)
import { ModelTier, getModelByTier } from "@aria/models";
interface Config {
  preferredTier?: ModelTier; // "powerful"
}

// Resolution at runtime
const model = getModelByTier(config.preferredTier || "balanced");

Model Router

Intelligently route queries to the best model based on characteristics.

import { ModelRouter } from "@aria/models";

const router = new ModelRouter({
  fast: { provider: "anthropic", model: "claude-haiku-4-5-20251001" },
  balanced: { provider: "anthropic", model: "claude-sonnet-4-5-20250929" },
  powerful: { provider: "anthropic", model: "claude-opus-4-6" },
  ensemble: [
    { provider: "anthropic", model: "claude-opus-4-6" },
    { provider: "openai", model: "gpt-5.2" },
  ],
});

// Chat by explicit tier
const response = await router.chat({
  messages: [{ role: "user", content: "Write code" }],
  tier: "powerful",
});

// Chat defaults to balanced tier
const response2 = await router.chat({
  messages: [{ role: "user", content: "Simple translation task" }],
});

Routing Rules

Declarative rules for automatic model selection based on content patterns.

import { codeGenerationRule, simpleQARule } from "@aria/models";

// Rules use registry for model selection
console.log(codeGenerationRule.model); // "claude-opus-4-6"
console.log(codeGenerationRule.tier); // "powerful"

// Available rules:
// - codeGenerationRule: Complex code tasks → Opus
// - analysisRule: Deep analysis → Opus
// - mathReasoningRule: Math/logic → Opus
// - creativeWritingRule: Creative content → Sonnet
// - simpleQARule: Simple questions → Haiku
// - summarizationRule: Summarization → Sonnet

Provider Abstraction

Unified interface for all model providers:

import { AnthropicProvider } from "@aria/models";

const provider = new AnthropicProvider({
  provider: "anthropic",
  model: "claude-opus-4-6",
  apiKey: process.env.ANTHROPIC_API_KEY!,
});

const response = await provider.chat({
  messages: [{ role: "user", content: "Explain quantum computing" }],
  temperature: 0.7,
  maxTokens: 1000,
});

console.log(response.content);

Supported Providers

• Anthropic - Claude models (Opus, Sonnet, Haiku)
• OpenAI - GPT models
• Google - Gemini models
• xAI - Grok models
• Local - Ollama and other local models

Extended Thinking Support

Anthropic provider supports adaptive thinking and effort parameters:

const response = await provider.chat({
  messages: [{ role: "user", content: "Solve this complex problem" }],
  thinking: { mode: "adaptive" }, // Enable adaptive thinking
  effort: "high", // Set reasoning depth
});

console.log(response.thinking); // Array of thinking blocks
console.log(response.usage); // Token usage including thinking tokens

API Reference

Types

• ModelTier - Tier classification (fast, balanced, powerful, ensemble)
• ModelProvider - Provider type (anthropic, openai, google, xai, local)
• ModelCapability - Model capability (thinking, tools, vision, streaming)
• ModelDefinition - Complete model metadata (mutable)
• ReadonlyModelDefinition - Immutable model definition for safe external use
• ModelRequest - Request parameters for model invocation
• ModelResponse - Response from model invocation
• RouterConfig - Configuration for ModelRouter (fast, balanced, powerful, ensemble)
• RoutedRequest - Request with optional tier selection
• ProviderSelection - Result of provider/model selection
• ProviderConfig - Configuration for instantiating a provider
• CostConfig / CostStats - Cost-aware routing configuration and statistics
• RateLimitConfig / RateLimitStats - Rate limiting configuration and statistics
• EscalationConfig - Automatic tier escalation configuration
• FallbackConfig / FallbackResult - Provider fallback configuration and results
• RoutingRuleConfig / RoutingRule / RoutingMatch - Declarative routing rule types

Constants

• MODELS - Typed model definitions object
• MODEL_REGISTRY - Readonly array of all model definitions

Functions

• Registry: getModelByTier, getModelById, getModelByShortName, getModelsByTier
• UI Helpers: getCliModels, toShortName, getTierDisplayName, isValidTier
• Router: createDefaultRouter, ModelRouter
• Cost Router: CostAwareRouter, defaultCostConfig
• Rate Limiting: RateLimiter, SlidingWindowRateLimiter, defaultRateLimitConfig
• Escalation: Escalator, defaultEscalationConfig
• Fallback: FallbackHandler
• Routing Rules: createRoutingRule, RoutingRuleMatcher
• Providers: AnthropicProvider, OpenAIProvider, GoogleProvider, LocalProvider, BaseProvider

Development

# Install dependencies
pnpm install

# Run tests
pnpm test

# Build
pnpm build

# Type check
pnpm typecheck

License

MIT