SDK Reference

Axon Class & Configuration

The primary interface for the SDK is the Axon class. It encapsulates the tier definitions, the Judge evaluator, fallback routing, and baseline cost computation.

Constructor

Instantiates an in-process router instance.

import { Axon } from "axon-llmrouter";

const axon = new Axon({
  tiers: {
    frontier: {
      model: "gpt-4o",
      apiKey: process.env.OPENAI_API_KEY!,
    },
    balanced: {
      model: "claude-3-5-sonnet-20241022",
      apiKey: process.env.ANTHROPIC_API_KEY!,
    },
    fast: {
      model: "claude-3-5-haiku-20241022",
      apiKey: process.env.ANTHROPIC_API_KEY!,
    },
  },
  // Optional: defaults to Fast tier model if omitted
  judge: {
    model: "gemini-1.5-flash",
    apiKey: process.env.GEMINI_API_KEY!,
  },
  fallbackTier: "balanced",
});

Configuration Options (AxonConfig)

  • tiersRequired | Record<'frontier' | 'balanced' | 'fast', TierConfig>

    Defines the models powering each of the three tiers. All three tiers (frontier, balanced, fast) must be configured.

  • judgeOptional | TierConfig

    The model responsible for rubric evaluation in Stage 2. If omitted, Axon defaults to using your configured Fast tier model.

  • fallbackTierRequired | 'frontier' | 'balanced' | 'fast'

    The safety tier to redirect inference to if an allocated model fails. Also serves as the baseline for costSaved calculations.

  • pricingOptional | Record<string, ModelPricing>

    Dev-supplied custom token pricing map. Merges with Axon's DEFAULT_PRICING table; dev entries take precedence on conflict.

Tier Configuration (TierConfig)

Each tier is specified with the following properties:

FieldTypeDescription
modelstringModel identifier (e.g. "gpt-4o", "claude-3-5-sonnet", "meta-llama/llama-3.1-70b").
apiKeystringAPI key for provider authentication. Safe for BYOK (Bring Your Own Key) per-request instantiation.
provider'openai' | 'anthropic' | 'google' (Optional)Explicit provider adapter override. If omitted, Axon infers the provider from model name or baseURL.
baseURLstring (Optional)Custom base URL for OpenAI-compatible gateways (Groq, Together, Fireworks, vLLM, Ollama).

Construction Checks

When new Axon(...) is called, it executes a synchronous structural check:

  • Validates that API keys are non-empty strings.
  • Verifies that any custom baseURL is well-formed.
  • Checks provider resolvability for all configured tiers.
  • Emits non-blocking console warnings if pricing is missing for configured models.

No network requests are dispatched at construct time. For live connectivity validation, use the axon.health({ live: true }) method.