@lov3kaizen/agentsea-costs

AI cost management platform with real-time tracking, budget enforcement, and optimization recommendations.

Features

• Real-time Cost Tracking - Track API calls and costs as they happen
• Token Counting - Accurate token counting using tiktoken for OpenAI models
• Model Pricing Registry - Up-to-date pricing for major AI providers
• Budget Management - Set and enforce budgets at multiple scopes
• Cost Attribution - Attribute costs to users, agents, projects, features
• Analytics - Cost trends, forecasting, and anomaly detection
• Alerts - Threshold-based notifications via multiple channels
• Optimization - AI-powered cost optimization recommendations

Installation

npm install @lov3kaizen/agentsea-costs
# or
pnpm add @lov3kaizen/agentsea-costs

Quick Start

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-3-5-sonnet-20241022',
    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}`);

Cost Tracking

Track API Calls

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-3-5-sonnet-20241022',
  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-4o',
  usage: {
    prompt_tokens: 1000,
    completion_tokens: 500,
    total_tokens: 1500,
  },
});

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

Scoped Tracking

// 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-3-5-sonnet-20241022',
  tokens: {
    inputTokens: 500,
    outputTokens: 200,
    totalTokens: 700,
  },
});

Token Counting

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-3-5-sonnet-20241022',
});

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-3-5-sonnet-20241022',
  estimatedOutputTokens: 1000,
});

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

Model Pricing

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

const registry = new ModelPricingRegistry();

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

// Calculate cost
const cost = registry.calculateCost(
  'anthropic',
  'claude-3-5-sonnet-20241022',
  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-3-5-sonnet-20241022',
  'gpt-4o',
  { input: 1000000, output: 500000 }, // sample workload
);

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

Budget Management

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: ['[email protected]'] },
    { 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}`);
});

Budget Scopes

// 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',
});

Storage Adapters

Buffer Storage (In-Memory)

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`);
  },
});

Analytics

// 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 });

Event Handling

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);
});

Supported Providers

| Provider | Models | | --------- | -------------------------------------------------------- | | Anthropic | Claude 3.5 Sonnet, Claude 3.5 Haiku, Claude 3 Opus, etc. | | OpenAI | GPT-4o, GPT-4o-mini, GPT-4 Turbo, o1, etc. | | Google | Gemini 1.5 Pro, Gemini 1.5 Flash, Gemini 2.0 | | Mistral | Mistral Large, Mistral Small, Codestral | | Cohere | Command R+, Command R |

API Reference

CostManager

The main entry point for cost management.

interface CostManagerOptions {
  currency?: string; // Default: 'USD'
  autoFlushInterval?: number; // Default: 30000ms
  bufferSize?: number; // Default: 100
  realTimeTracking?: boolean; // Default: true
  defaultAttribution?: Partial<CostAttribution>;
  storage?: CostStorageAdapter;
  pricingRegistry?: ModelPricingRegistry;
}

BudgetManager

Manages budgets and enforces limits.

interface BudgetConfig {
  id: string;
  name: string;
  limit: number;
  currency: string;
  period: 'hourly' | 'daily' | 'weekly' | 'monthly' | 'quarterly' | 'yearly';
  scope: 'global' | 'user' | 'agent' | 'project' | 'team' | 'feature';
  scopeId?: string;
  warningThresholds?: number[];
  actions?: BudgetThresholdAction[];
  enabled: boolean;
}

ModelPricingRegistry

Manages model pricing information.

interface ModelPricing {
  model: string;
  provider: AIProvider;
  inputPricePerMillion: number;
  outputPricePerMillion: number;
  cacheReadPricePerMillion?: number;
  cacheWritePricePerMillion?: number;
  contextWindow?: number;
  maxOutputTokens?: number;
  currency: string;
}

Types

All types are exported from the package:

import type {
  // Cost
  CostRecord,
  CostAttribution,
  CostSummary,
  TokenUsage,
  CostBreakdown,

  // Pricing
  ModelPricing,
  TokenCountResult,
  CostEstimateResult,

  // Budget
  BudgetConfig,
  BudgetUsage,
  BudgetCheckResult,

  // Attribution
  AttributionDimension,
  AttributionSummary,

  // Analytics
  AnalyticsQuery,
  AnalyticsResult,
  ForecastResult,

  // Alerts
  AlertRule,
  Alert,
  NotificationConfig,

  // Storage
  CostStorageAdapter,
  StorageStats,
} from '@lov3kaizen/agentsea-costs';

License

MIT