VANTAGE
Documentation

AI Observability Quickstart

Developer Guide • Metering LLMs, Prompt Caching ROI & Budget Alerting

1. Quickstart: 3-Minute Integration

You can integrate XTND Sonar into any Node.js, Cloudflare Worker, or browser project in three simple steps:

Step 1: Install the Standalone SDK

npm install @xtnd-dynamics/xtnd-sonar-sdk

Step 2: Route Your AI SDK Through the Gateway

Direct your AI client's base URL to https://api.sonar.vantage.xgi.io/v1/proxy/<provider>:

Anthropic:

import Anthropic from '@anthropic-ai/sdk';

const anthropic = new Anthropic({
  baseURL: 'https://api.sonar.vantage.xgi.io/v1/proxy/anthropic',
  apiKey: process.env.ANTHROPIC_API_KEY,
});

OpenAI:

import OpenAI from 'openai';

const openai = new OpenAI({
  baseURL: 'https://api.sonar.vantage.xgi.io/v1/proxy/openai/v1',
  apiKey: process.env.OPENAI_API_KEY,
});

Google Gemini:

import { GoogleGenerativeAI } from '@google/generative-ai';

// Construct fetch requests targeting:
// https://api.sonar.vantage.xgi.io/v1/proxy/gemini/v1beta/models/gemini-2.0-flash:generateContent?key=YOUR_API_KEY

2. Calculating Prompt Caching ROI

Prompt caching drastically cuts LLM operating costs (Anthropic offers up to 90% savings on cache hits). Sonar computes your exact savings on every request:

import { calculateTokenCost } from '@xtnd-dynamics/xtnd-sonar-sdk';

// Simulated response usage from Claude 3.7
const responseUsage = {
  input_tokens: 15000,
  cache_read_input_tokens: 12000, // 12,000 cached tokens
  output_tokens: 1800,
};

const cost = calculateTokenCost('claude-3-7-sonnet', {
  promptTokens: responseUsage.input_tokens,
  cachedPromptTokens: responseUsage.cache_read_input_tokens,
  completionTokens: responseUsage.output_tokens,
});

console.log('--- Inference Economics ---');
console.log(`Uncached Prompt Cost: $${cost.promptCostUsd.toFixed(4)}`);
console.log(`Cached Prompt Cost:   $${cost.cachedPromptCostUsd.toFixed(4)}`);
console.log(`Completion Cost:      $${cost.completionCostUsd.toFixed(4)}`);
console.log(`Total Billed:         $${cost.totalCostUsd.toFixed(4)}`);
console.log(`Dollar ROI (Saved):   $${cost.cacheSavingsUsd.toFixed(4)}`);

3. Quota Management & Automated Kill-Switches

import { sonar } from '@xtnd-dynamics/xtnd-sonar-sdk';

// Set up monthly tracking
sonar.quotas.updateQuota({
  provider: 'anthropic',
  monthlyLimitUsd: 1000.00,
  currentSpendUsd: 992.00, // < 1% remaining -> Dispatches P0_CRITICAL event
  billingRenewsAt: '2026-10-01T00:00:00Z',
});

// Guard an inference invocation
const quota = sonar.quotas.getQuota('anthropic');
if (quota && quota.remainingPercent <= 1.0) {
  // Gracefully fallback to an ultra-cheap model or display an alert
  console.warn('Anthropic budget exhausted. Falling back to Gemini Flash.');
}