// README.md

TokenTracker

A lightweight library for tracking and analyzing API token usage, particularly for AI APIs like Anthropic Claude and OpenAI.

Features

• Track token usage across different AI providers and models
• Calculate cost based on current pricing
• Generate detailed usage reports
• Support multiple storage options (memory, file, database)
• Easy integration with any JavaScript/TypeScript application

Installation

npm install ai-token-tracker

Quick Start

import { TokenTracker } from 'ai-token-tracker';

// Create a tracker
const tracker = new TokenTracker({
  storage: 'file',
  storagePath: './token-usage-data'
});

// Record API calls
tracker.recordApiCall({
  model: 'claude-3-opus-20240229',
  provider: 'anthropic',
  function: 'analyzeCode',
  purpose: 'code-review',
  usage: {
    promptTokens: 1500,
    completionTokens: 800,
    totalTokens: 2300
  }
});

// Generate a report
const report = tracker.generateReport('markdown');
console.log(report);

// Get statistics
const stats = tracker.getStatistics();
console.log(`Total cost: $${stats.totalCost.toFixed(4)}`);

Configuration Options

const tracker = new TokenTracker({
  // Storage options
  storage: 'file', // 'memory', 'file', or 'database'
  storagePath: './data', // Path for file storage
  
  // Grouping options
  groupBy: ['model', 'provider', 'function', 'purpose'],
  
  // Reporting options
  defaultReportFormat: 'markdown', // 'text', 'markdown', 'json', or 'html'
  detailedReporting: true,
  
  // Logging options
  enableLogging: true,
  
  // Custom pricing
  customPricing: {
    'my-custom-model': { input: 0.01, output: 0.03 }
  }
});

API Reference

TokenTracker Class

Constructor

constructor(options?: TrackingOptions)

Creates a new TokenTracker instance with the specified options.

Methods

recordApiCall(params: {
  model: string;
  provider: string;
  function: string;
  purpose: string;
  usage: TokenUsage;
  metadata?: Record<string, any>;
}): void

Records an API call with token usage information.

generateReport(
  format?: 'text' | 'markdown' | 'json' | 'html',
  filters?: Partial<{
    startDate: string;
    endDate: string;
    model: string;
    provider: string;
    function: string;
    purpose: string;
  }>
): string

Generates a usage report in the specified format, optionally filtered by criteria.

getStatistics(filters?: any): TokenStatistics

Returns statistics about token usage, optionally filtered by criteria.

getTotalCost(filters?: any): number

Returns the total cost of all tracked API calls, optionally filtered by criteria.

getTotalCalls(filters?: any): number

Returns the total number of API calls, optionally filtered by criteria.

getTotalTokens(filters?: any): number

Returns the total number of tokens used, optionally filtered by criteria.

clearAllRecords(): void

Clears all tracking records.

exportRecords(filters?: any): string

Exports records as a JSON string, optionally filtered by criteria.

importRecords(jsonRecords: string): number

Imports records from a JSON string, returns the number of imported records.

License

MIT