VANTAGE
Documentation

Sonar AI Observability (@xtnd/vantage-sonar)

Package: @xtnd/vantage-sonar
Source Directory: xtnd-vantage/packages/sonar/

1. Overview

@xtnd/vantage-sonar provides end-to-end telemetry, token economics, prompt caching ROI calculation, and quota monitoring across the industry's leading frontier LLMs (OpenAI, Anthropic Claude, and Google Gemini).

2. Model Pricing Table (MODEL_PRICING_TABLE)

Sonar includes a granular pricing matrix calibrated per 1,000,000 (1M) tokens:

Provider Model Input Cost / 1M Cached Input / 1M Output Cost / 1M Reasoning Cost / 1M
OpenAI gpt-4o $2.50 $1.25 (50% off) $10.00 —
gpt-4o-mini $0.15 $0.075 (50% off) $0.60 —
o1 $15.00 $7.50 (50% off) $60.00 $60.00
o3-mini $1.10 $0.55 (50% off) $4.40 $4.40
Anthropic claude-3-7-sonnet $3.00 $0.30 (90% off) $15.00 $15.00
claude-3-5-sonnet $3.00 $0.30 (90% off) $15.00 —
claude-3-5-haiku $0.80 $0.08 (90% off) $4.00 —
claude-3-opus $15.00 $1.50 (90% off) $75.00 —
Google gemini-2.0-flash $0.10 $0.025 (75% off) $0.40 —
gemini-2.0-flash-thinking $0.10 $0.025 (75% off) $0.40 $0.40
gemini-1.5-pro $1.25 $0.3125 (75% off) $5.00 —
gemini-1.5-flash $0.075 $0.01875 (75% off) $0.30 —

3. Cost & Cache ROI Calculation (calculateTokenCost)

The calculation engine accounts for cached prompt discounts and reasoning tokens:

export function calculateTokenCost(
  model: string,
  tokens: {
    promptTokens: number;
    cachedPromptTokens?: number;
    completionTokens: number;
    reasoningTokens?: number;
  }
): TokenCostBreakdown

Breakdown Output Schema:

  • promptTokens: Net uncached prompt tokens billed at full price.
  • cachedPromptTokens: Cached tokens billed at the provider discount rate.
  • completionTokens: Output tokens generated.
  • reasoningTokens: Internal "thinking" tokens (o1, o3-mini, Gemini 2.0 Flash Thinking, Claude 3.7 hybrid).
  • promptCostUsd: Total prompt cost in USD.
  • cachedPromptCostUsd: Total cached prompt cost in USD.
  • completionCostUsd: Total completion cost in USD.
  • reasoningCostUsd: Total reasoning cost in USD.
  • totalCostUsd: Exact sum cost for the inference.
  • cacheSavingsUsd: Dollar amount saved by hitting prompt cache vs full prompt pricing.

4. Provider Response Parsers

Sonar standardizes metadata extraction across heterogeneous provider formats:

4.1 OpenAI (parsers/openai.ts)

  • Rate Limits: Parses x-ratelimit-remaining-tokens, x-ratelimit-remaining-requests, x-ratelimit-reset-tokens.
  • Reasoning Tokens: Extracts usage.completion_tokens_details.reasoning_tokens.
  • Cache Hits: Extracts usage.prompt_tokens_details.cached_tokens.

4.2 Anthropic (parsers/anthropic.ts)

  • Rate Limits: Parses anthropic-ratelimit-tokens-remaining, anthropic-ratelimit-tokens-reset.
  • Cache Hits: Extracts usage.cache_read_input_tokens and usage.cache_creation_input_tokens.

4.3 Google Gemini (parsers/gemini.ts)

  • Token Metadata: Extracts usageMetadata.promptTokenCount, candidatesTokenCount, cachedContentTokenCount, and thinkingTokenCount.

5. Multi-Account AI Quota Tracker (VantageAIQuotaTracker)

Manages budget headroom, burn velocity, and renewal cycles across OpenAI, Anthropic, and Gemini accounts.

Autonomous Event Thresholds

When an account's quota state is updated:

  • Remaining Balance <= 1%: Immediately emits a P0_CRITICAL event (ai:quota:exhausted). Serves as an instant kill-switch or emergency failover trigger.
  • Remaining Balance <= 20%: Emits a P1_HIGH event (ai:quota:warning) to notify administrators of impending depletion.

Renewal Countdown (calculateTimeUntilRenewal)

Calculates real-time countdown to billing cycle resets:

const countdown = tracker.calculateTimeUntilRenewal('openai');
console.log(`OpenAI quota resets in: ${countdown.days}d ${countdown.hours}h ${countdown.minutes}m`);