@reaatech/otel-cost-exporter-calculator

Status: Pre-1.0 — APIs may change in minor versions. Pin to a specific version in production.

LLM token cost calculator with model name normalization, provider detection, and LRU pricing caching. Converts raw token counts from GenAI semantic convention spans into per-model cost breakdowns in USD.

Installation

npm install @reaatech/otel-cost-exporter-calculator
# or
pnpm add @reaatech/otel-cost-exporter-calculator

Feature Overview

• Cost calculator engine — full CostCalculator with dependency injection: pricing provider, LRU cache, model normalizer, and optional default price
• Pure calculation function — calculateCost() is a side-effect-free function taking a PriceEntry and token counts, returning a CostBreakdown
• Model name normalization — strips provider prefixes (openai/gpt-4), version suffixes (-v2, :latest), regional variants (-us, -eu), FT prefixes, and resolves common aliases (gpt4 → gpt-4)
• Provider detection — infers provider from model name when gen_ai.system is missing (e.g., gpt-* → openai, claude-* → anthropic)
• LRU pricing cache — configurable LRU cache with hit/miss statistics; minimizes repeated pricing table lookups in high-throughput pipelines
• Prompt caching costs — separate tracking for cache read and cache creation token costs (Anthropic)
• Billable input token calculation — automatically subtracts cache read tokens from input tokens before pricing
• Default price fallback — optionally assign a USD-per-1M-token default for unknown models
• Dual ESM/CJS output — works with import and require

Quick Start

import {
  createCostCalculator,
  createModelNormalizer,
  createPricingCache,
} from "@reaatech/otel-cost-exporter-calculator";
import { loadPricingData, createPricingTable } from "@reaatech/otel-cost-exporter-pricing";
 
// Set up dependencies
const data = await loadPricingData();
const pricing = createPricingTable(data);
const cache = createPricingCache();
const normalizer = createModelNormalizer();
 
const calculator = createCostCalculator({
  pricing,
  cache,
  normalizer,
  defaultPrice: 2.0,    // USD per 1M tokens for unknown models
});
 
// Calculate cost
const result = calculator.calculate("gpt-4", 1_000_000, 500_000, {
  cacheReadTokens: 0,
  cacheCreationTokens: 0,
});
 
console.log(`Input cost: $${result.inputCostUsd}`);
console.log(`Output cost: $${result.outputCostUsd}`);
console.log(`Total cost: $${result.totalCostUsd}`);

API Reference

Cost Calculator Engine

createCostCalculator(deps)

Creates a full cost calculator with caching and normalization.

function createCostCalculator(deps: CostCalculatorDeps): CostCalculator

CostCalculatorDeps

CostCalculator

CostResult

PricingError

Low-Level Calculation

calculateCost(entry, inputTokens, outputTokens, cacheReadTokens?, cacheCreationTokens?)

Pure function that converts token counts to a CostBreakdown:

function calculateCost(
  entry: PriceEntry,
  inputTokens: number,
  outputTokens: number,
  cacheReadTokens?: number,
  cacheCreationTokens?: number,
): CostBreakdown

Automatically computes billable input tokens as max(0, inputTokens - cacheReadTokens) before pricing.

Model Normalizer

createModelNormalizer()

Creates a model name normalizer with built-in aliases:

function createModelNormalizer(): ModelNormalizer

ModelNormalizer

Built-in provider detection

Built-in aliases

Pricing Cache

createPricingCache(maxSize?)

LRU pricing entry cache with configurable size:

function createPricingCache(maxSize?: number): PricingCache

PricingCache

CacheStats

Usage Patterns

Cache Statistics Monitoring

const cache = createPricingCache(5000);
 
// After processing a batch of spans...
const stats = cache.stats();
console.log(`Hit rate: ${(stats.hitRate * 100).toFixed(1)}%`);
console.log(`Entries: ${stats.size}/${stats.maxSize}`);

Custom Model Aliases

const normalizer = createModelNormalizer();
 
// Register a custom alias for your fine-tuned model
normalizer.addAlias("my-finance-gpt", "gpt-4");
 
const result = normalizer.normalize("my-finance-gpt");
// → { provider: "openai", canonicalName: "gpt-4" }

Unknown Model Fallback

// With defaultPrice set, unknown models get a fallback price
const calculator = createCostCalculator({
  pricing,
  cache,
  normalizer,
  defaultPrice: 2.0,
});
 
// "nonexistent-model" will use $2.00/1M tokens for both input and output
const result = calculator.calculate("nonexistent-model", 100, 50);
console.log(result.totalCostUsd); // ~0.0003 (very small)

Related Packages

• @reaatech/otel-cost-exporter-core — Domain types, Zod schemas, and semconv constants
• @reaatech/otel-cost-exporter-pricing — Pricing table management with bundled provider data
• @reaatech/otel-cost-exporter — OTel-native cost metrics exporter

License

MIT