@reaatech/otel-genai-semconv-utils

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

Token counting, cost calculation, and PII redaction utilities for LLM observability. Provides accurate token estimation via tiktoken for OpenAI models, character-based estimation for other providers, per-request cost computation with baked-in pricing tables, and automatic detection and redaction of sensitive data (emails, SSNs, credit cards, IP addresses, phone numbers).

Installation

npm install @reaatech/otel-genai-semconv-utils
# or
pnpm add @reaatech/otel-genai-semconv-utils

Feature Overview

• Provider-aware token counting — tiktoken integration for OpenAI, estimation fallbacks for Anthropic, Vertex AI, and Bedrock
• Built-in pricing tables — pre-configured pricing for GPT-4, GPT-4o, Claude 3, Gemini, and Bedrock model families
• Custom pricing overrides — inject per-model pricing at construction time or via setter methods
• PII redaction — five default patterns (email, SSN, credit card, phone, IP) with add/remove/exclude API
• Object deep redaction — recursively redact PII from nested objects and arrays
• LRU caching — token counts and cost calculations are cached with configurable TTL and size limits
• Singleton accessors — getDefaultTokenCounter(), getDefaultCostCalculator(), getDefaultPIIRedactor() for zero-config use

Quick Start

import { CostCalculator, TokenCounter, PIIRedactor } from "@reaatech/otel-genai-semconv-utils";
 
const calculator = new CostCalculator();
const cost = calculator.calculate({
  provider: "openai",
  model: "gpt-4",
  inputTokens: 1000,
  outputTokens: 500,
});
// { total: 0.045, input: 0.03, output: 0.015, currency: "USD" }
 
const counter = new TokenCounter();
const tokens = counter.countTokens("Hello, world!");
// ~4 (estimated at 4 chars/token)
 
const redactor = new PIIRedactor();
const safe = redactor.redact("Contact user@example.com or 555-1234");
// "Contact [REDACTED_EMAIL] or [REDACTED_PHONE]"

API Reference

CostCalculator (class)

Constructor

new CostCalculator(options?: { customPricing?: Record<string, PricingInfo> })

Methods

CostCalculationParams

TokenCounter (class)

Constructor

new TokenCounter(options?: {
  provider?: ProviderType;
  customCounter?: ITokenCounter;
  enableCache?: boolean;
  cacheTTL?: number;
  maxCacheSize?: number;
})

Methods

ITokenCounter (interface)

Implement this to create a custom token counter:

interface ITokenCounter {
  countTokens(text: string): number;
  countMessageTokens(message: { role: string; content: string }): number;
  countConversationTokens(messages: Array<{ role: string; content: string }>): number;
}

EstimationTokenCounter (class)

A character-based token estimator using ~4 characters per token (English text). Used as the fallback when no provider-specific counter is configured.

PIIRedactor (class)

Constructor

new PIIRedactor(options?: PIIRedactionOptions)

PIIRedactionOptions

Methods

Default PII Patterns

Usage Patterns

Custom Pricing Overrides

const calculator = new CostCalculator({
  customPricing: {
    "gpt-4": { input: 0.03, output: 0.06 },
    "my-custom-model": { input: 0.001, output: 0.002, provider: "openai" },
  },
});

Provider-Specific Token Counters

import { OpenAITokenCounter } from "@reaatech/otel-genai-semconv-openai";
import { TokenCounter } from "@reaatech/otel-genai-semconv-utils";
 
const counter = new TokenCounter({
  customCounter: new OpenAITokenCounter(),
});
const tokens = counter.countTokens("Hello, world!");

Selective PII Redaction

const redactor = new PIIRedactor({ excludePatterns: ["Email addresses"] });
redactor.redact("user@example.com called 555-1234");
// "user@example.com called [REDACTED_PHONE]"

Related Packages

• @reaatech/otel-genai-semconv-core — Core types and constants
• @reaatech/otel-genai-semconv-openai — OpenAI provider instrumentation (with tiktoken counter)

License

MIT