@juspay/neurolink/dist/utils/tokenUtils.d.ts

The pipe layer of an AI nervous system: one interface connecting provider neurons to your application, across three inference types — generate, stream and decide. `decide` returns typed, calibrated judgements from a non-generative model (~400ms, ~$0.00002

/**
 * Centralized token usage extraction utilities
 * Handles multiple provider formats and optional fields
 *
 * Consolidates token extraction logic from:
 * - analytics.ts
 * - streamAnalytics.ts
 */
import type { TokenUsage, RawUsageObject, TokenExtractionOptions } from "../types/index.js";
/**
 * Extract input token count from various provider formats
 * Priority: input > inputTokens > promptTokens
 */
export declare function extractInputTokens(usage: RawUsageObject): number;
/**
 * Extract output token count from various provider formats
 * Priority: output > outputTokens > completionTokens
 */
export declare function extractOutputTokens(usage: RawUsageObject): number;
/**
 * Extract total token count from various provider formats
 * Falls back to input + output if total is not provided
 */
export declare function extractTotalTokens(usage: RawUsageObject, input: number, output: number): number;
/**
 * Extract reasoning/thinking token count from various provider formats
 * Supports: reasoningTokens, thinkingTokens, reasoning_tokens, reasoning
 */
export declare function extractReasoningTokens(usage: RawUsageObject): number | undefined;
/**
 * Extract cache creation token count from various provider formats
 * Supports: cacheCreationInputTokens, cacheCreationTokens, and the ai@6
 * normalized `inputTokenDetails.cacheWriteTokens` (the only shape the native
 * direct-Anthropic path reports through generateText).
 */
export declare function extractCacheCreationTokens(usage: RawUsageObject): number | undefined;
/**
 * Extract cache read token count from various provider formats
 * Supports: cacheReadInputTokens, cacheReadTokens, and the ai@6 normalized
 * shapes — flat `cachedInputTokens` and nested
 * `inputTokenDetails.cacheReadTokens` (the only shapes the native
 * direct-Anthropic path reports through generateText).
 */
export declare function extractCacheReadTokens(usage: RawUsageObject): number | undefined;
/**
 * Extract cache read token count from the OVERLAPPING-convention nested path
 * used by OpenAI / DeepSeek / NIM / OpenAI-compatible providers:
 * `usage.prompt_tokens_details.cached_tokens`.
 *
 * Unlike {@link extractCacheReadTokens} (non-overlapping Anthropic/Vertex
 * convention where cache tokens are reported SEPARATELY from input), the value
 * returned here is a SUBSET already included in `prompt_tokens`. Callers that
 * use this value MUST subtract it from `input` to avoid double-counting.
 */
export declare function extractCachedInputTokensOverlapping(usage: RawUsageObject): number | undefined;
/**
 * Calculate cache savings percentage
 *
 * This represents the percentage of input tokens served from cache.
 * For Anthropic, cache read tokens cost 0.1x, so actual cost savings = cacheSavingsPercent * 0.9
 * For other providers, cost savings may vary based on their cache pricing.
 *
 * @param cacheReadTokens Number of tokens read from cache
 * @param inputTokens Number of non-cached input tokens
 * @returns Percentage of tokens served from cache (0-100), or undefined if no cache usage
 */
export declare function calculateCacheSavingsPercent(cacheReadTokens: number | undefined, inputTokens: number): number | undefined;
/**
 * Extract token usage from various provider response formats
 *
 * Handles multiple input formats:
 * - BaseProvider normalized format (input/output/total)
 * - AI SDK format (inputTokens/outputTokens/totalTokens)
 * - OpenAI/Mistral format (promptTokens/completionTokens)
 * - Nested usage objects
 *
 * Also extracts optional fields:
 * - Cache creation and read tokens (Anthropic-style)
 * - Reasoning/thinking tokens (OpenAI o1, Anthropic, Google)
 * - Cache savings percentage
 *
 * @param result Raw usage object from provider response
 * @param options Extraction options
 * @returns Normalized TokenUsage object
 */
export declare function extractTokenUsage(result: RawUsageObject | undefined | null, options?: TokenExtractionOptions): TokenUsage;
/**
 * Create a default/empty TokenUsage object
 * Useful for error handling and fallback scenarios
 */
export declare function createEmptyTokenUsage(): TokenUsage;
/**
 * Check if a TokenUsage object has any non-zero values
 */
export declare function hasTokenUsage(usage: TokenUsage): boolean;
/**
 * Merge two TokenUsage objects by summing their values
 * Useful for aggregating usage across multiple calls
 */
export declare function mergeTokenUsage(a: TokenUsage, b: TokenUsage): TokenUsage;