Cost Tracking

pnpm add @lov3kaizen/agentsea-costs

import {
  CostManager,
  createCostManager,
  BufferStorage,
} from '@lov3kaizen/agentsea-costs';

// Create a cost manager
const costManager = createCostManager({
  currency: 'USD',
  defaultAttribution: {
    environment: 'production',
  },
});

// Track an Anthropic API call
await costManager.trackAnthropicResponse(
  {
    model: 'claude-sonnet-4-6',
    usage: {
      input_tokens: 1500,
      output_tokens: 500,
    },
  },
  {
    attribution: {
      userId: 'user-123',
      feature: 'chat',
    },
  },
);

// Get cost summary
const summary = await costManager.getSummary({
  startDate: new Date('2024-01-01'),
  endDate: new Date(),
});

console.log(`Total cost: $${summary.totalCost.toFixed(4)}`);
console.log(`Total tokens: ${summary.totalTokens}`);
console.log(`Requests: ${summary.requestCount}`);

import { CostManager, BufferStorage } from '@lov3kaizen/agentsea-costs';

// With persistent storage
const storage = new BufferStorage();
const costManager = new CostManager({ storage });

// Track any LLM call
await costManager.track({
  provider: 'anthropic',
  model: 'claude-sonnet-4-6',
  tokens: {
    inputTokens: 1000,
    outputTokens: 500,
    totalTokens: 1500,
  },
  latencyMs: 1200,
  attribution: {
    userId: 'user-123',
    agentId: 'agent-456',
    feature: 'document-analysis',
  },
});

// Track OpenAI responses directly
await costManager.trackOpenAIResponse({
  model: 'gpt-5.2',
  usage: {
    prompt_tokens: 1000,
    completion_tokens: 500,
    total_tokens: 1500,
  },
});

// Track errors
await costManager.trackError({
  provider: 'openai',
  model: 'gpt-5.2',
  error: 'Rate limit exceeded',
  estimatedInputTokens: 1000,
});

// Create scoped trackers for specific contexts
const userTracker = costManager.scoped({
  userId: 'user-123',
  environment: 'production',
});

// All calls through this tracker include the scope
await userTracker.track({
  provider: 'anthropic',
  model: 'claude-sonnet-4-6',
  tokens: {
    inputTokens: 500,
    outputTokens: 200,
    totalTokens: 700,
  },
});

import { TokenCounter, ModelPricingRegistry } from '@lov3kaizen/agentsea-costs';

const registry = new ModelPricingRegistry();
const counter = new TokenCounter(registry);

// Count tokens
const result = await counter.countTokens({
  text: 'Hello, how can I help you today?',
  model: 'claude-sonnet-4-6',
});

console.log(`Tokens: ${result.tokens}`);
console.log(`Estimated cost: $${result.estimatedInputCost}`);

// Estimate cost before making a call
const estimate = await counter.estimateCost({
  input: 'Your prompt here...',
  model: 'claude-sonnet-4-6',
  estimatedOutputTokens: 1000,
});

console.log(`Estimated total: $${estimate.estimatedCost.toFixed(4)}`);

import { ModelPricingRegistry } from '@lov3kaizen/agentsea-costs';

const registry = new ModelPricingRegistry();

// Get pricing for a model
const pricing = registry.getPricing('anthropic', 'claude-sonnet-4-6');
console.log(`Input: $${pricing.inputPricePerMillion}/1M tokens`);
console.log(`Output: $${pricing.outputPricePerMillion}/1M tokens`);

// Calculate cost
const cost = registry.calculateCost(
  'anthropic',
  'claude-sonnet-4-6',
  1000, // input tokens
  500, // output tokens
);
console.log(`Total: $${cost.totalCost.toFixed(4)}`);

// Find cheapest model with requirements
const cheapest = registry.findCheapestModel({
  requireVision: true,
  requireFunctionCalling: true,
  minContextWindow: 100000,
});

// Compare models
const comparison = registry.comparePricing(
  'claude-sonnet-4-6',
  'gpt-5.2',
  { input: 1000000, output: 500000 }, // sample workload
);

console.log(
  `${comparison.cheaperModel} is ${comparison.percentageDiff}% cheaper`,
);

import { BudgetManager, BufferStorage } from '@lov3kaizen/agentsea-costs';

const storage = new BufferStorage();
const budgetManager = new BudgetManager({}, storage);

// Create a budget
const budget = await budgetManager.createBudget({
  name: 'Monthly AI Budget',
  limit: 1000, // $1000
  period: 'monthly',
  scope: 'global',
  warningThresholds: [50, 80, 90],
  actions: [
    { threshold: 80, action: 'notify', notifyEmails: ['team@example.com'] },
    { threshold: 100, action: 'block' },
  ],
});

// Check budget before making a call
const check = await budgetManager.checkBudget({
  estimatedCost: 0.05,
  attribution: { userId: 'user-123' },
});

if (check.allowed) {
  // Proceed with API call
} else {
  console.log(`Blocked: ${check.reason}`);
}

// Get budget usage
const usage = await budgetManager.getUsage(budget.id);
console.log(`Used: $${usage.currentUsage} of $${usage.limit}`);
console.log(`${usage.usagePercentage.toFixed(1)}% used`);

// Listen for budget events
budgetManager.on('budget:warning', (alert) => {
  console.log(`Warning: ${alert.message}`);
});

budgetManager.on('budget:exceeded', (alert) => {
  console.log(`Exceeded: ${alert.message}`);
});

// User-level budget
await budgetManager.createBudget({
  name: 'User Daily Limit',
  limit: 10,
  period: 'daily',
  scope: 'user',
  scopeId: 'user-123',
});

// Project budget
await budgetManager.createBudget({
  name: 'Project Budget',
  limit: 500,
  period: 'monthly',
  scope: 'project',
  scopeId: 'project-abc',
});

// Feature-specific budget
await budgetManager.createBudget({
  name: 'Document Processing',
  limit: 100,
  period: 'weekly',
  scope: 'feature',
  scopeId: 'document-analysis',
});

import { BufferStorage } from '@lov3kaizen/agentsea-costs';

const storage = new BufferStorage({
  maxRecords: 10000,
  autoFlushInterval: 30000, // 30 seconds
  onFlush: async (records) => {
    // Persist records to external storage
    console.log(`Flushing ${records.length} records`);
  },
});

// Get cost summary
const summary = await costManager.getSummary({
  startDate: new Date('2024-01-01'),
  endDate: new Date(),
  providers: ['anthropic', 'openai'],
});

// Get costs by dimension
const byModel = await costManager.getCostsByDimension('model', {
  startDate: new Date('2024-01-01'),
});

byModel.forEach((m) => {
  console.log(
    `${m.value}: $${m.totalCost.toFixed(2)} (${m.percentage.toFixed(1)}%)`,
  );
});

// Get cost trends
const trends = await costManager.getCostTrends({
  granularity: 'day',
  startDate: new Date('2024-01-01'),
});

// Get top consumers
const topUsers = await costManager.getTopUsers({ limit: 10 });
const topModels = await costManager.getTopModels({ limit: 5 });
const topFeatures = await costManager.getTopFeatures({ limit: 5 });

costManager.on('cost:recorded', (record) => {
  console.log(
    `Tracked: ${record.model} - $${record.cost.totalCost.toFixed(4)}`,
  );
});

costManager.on('cost:batch', ({ records }) => {
  console.log(`Batch saved: ${records.length} records`);
});

costManager.on('budget:warning', (alert) => {
  sendSlackNotification(alert.message);
});

costManager.on('budget:exceeded', (alert) => {
  sendPagerDutyAlert(alert);
});

costManager.on('error', (error) => {
  console.error('Cost tracking error:', error.message);
});