SDK Reference

Methods & Return Types

The Axon class exposes three core public methods: infer() for end-to-end routing and model completion, classify() for dry-run tier inspection, and health() for proactive readiness checks.

infer(prompt, options?)

The primary public method of the SDK. Internally runs the complete pipeline: Gate evaluation, Judge classification (if escalated), tier resolution, and model execution.

const result = await axon.infer("Analyze this SQL query plan", {
  context: {
    codeContext: "EXPLAIN ANALYZE SELECT * FROM users...",
  },
});

Parameters

  • prompt string

    The user prompt to route and execute.

  • options Optional | { context?: AxonContext }

    Contextual metadata, conversation turns, or code snippets.

Return Types: Discriminated Union

infer() returns a strict discriminated union that reflects runtime execution reality:

1. InferSuccessok: true

The allocated tier model responded successfully.

{
  ok: true,
  response: string,
  tier: "frontier" | "balanced" | "fast",
  costSaved: number | null,
  latencySaved: number | null,
  usedFallback: false
}
2. InferDegradedok: true

Allocated tier failed; prompt safely completed by Fallback tier.

{
  ok: true,
  response: string,
  tier: FallbackTier,
  costSaved: number | null,
  latencySaved: number | null,
  usedFallback: true,
  failedStage: string,
  failedReason: string
}
3. InferStoppedok: false

Irreversible prompt failed on Frontier; stopped to prevent degraded side-effects.

{
  ok: false,
  needsConfirmation: true,
  reason: string,
  attemptedTier: "frontier",
  proposedFallback: string
}
Unrecoverable Failure

If the allocated tier fails AND the fallback tier also fails, infer() throws an exception with descriptive failure reasons from both providers. There is no ambiguous fake response returned.

classify(prompt, options?)

Evaluates a prompt through Stage 1 (Gate) and Stage 2 (Judge) to inspect routing decisions without making a completion call to the target model.

const decision = await axon.classify("Generate an auth migration script");

console.log(decision.allocatedTier); // "frontier"
console.log(decision.source);        // "judge" (or "gate")
console.log(decision.rubricRatings);
// { blastRadius: "High", irreversibility: true, reasoningDepth: "Medium", ambiguity: "Clear" }

Use Cases

  • Offline Benchmarking: Powers the Axon Eval Harness to score prompt routing against human-labeled CSV datasets.
  • Telemetry & Auditing: Inspect model tier distribution before enabling live model execution.

health(options?)

Inspects the readiness of all configured tiers. Axon uses the same status shape for both proactive readiness and reactive runtime error reporting.

// 1. Structural Check (free, instant, no network calls)
const status = await axon.health();

// 2. Live Probe Check (sends real ping requests to model providers)
const liveStatus = await axon.health({ live: true });

console.log(liveStatus);
// {
//   frontier: "ok",
//   balanced: "ok",
//   fast: "failed: invalid key",
//   fallback: "ok"
// }

Health results distinguish structural passes from verified live connections. Duplicate slots (e.g. when judge or fallbackTier points to an existing tier config) reuse probe calls to avoid double-billing.