observability-toolkit 1.8.5 → 2.1.0

package/dist/lib/cost/cost-estimation.d.ts

@@ -0,0 +1,264 @@
+/**
+ * Cost Estimation Layer
+ *
+ * Provides token-to-cost calculation, budget alerting patterns,
+ * and cost attribution by session/user for LLM usage tracking.
+ *
+ * @security
+ * - All inputs are validated at runtime using Zod schemas
+ * - Token counts bounded to Number.MAX_SAFE_INTEGER
+ * - Attributions array capped to prevent OOM
+ * - Old date entries cleaned up automatically
+ *
+ * @threading
+ * NOT THREAD-SAFE: This module is designed for single-threaded use.
+ * Do not call recordSpend() concurrently from multiple async contexts
+ * without external synchronization.
+ *
+ * @see MODEL_PRICING in constants.ts for provider pricing data
+ */
+import { z } from 'zod';
+import { refreshPricingFromUrl, setPricingOverrides, clearPricingCache, getPricingCacheStatus } from './pricing-cache.js';
+export { refreshPricingFromUrl, setPricingOverrides, clearPricingCache, getPricingCacheStatus, };
+/**
+ * Error thrown when cost estimation inputs are invalid.
+ */
+export declare class CostEstimationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Error thrown for invalid model names.
+ */
+export declare class InvalidModelError extends CostEstimationError {
+    constructor(model: string);
+}
+export declare const tokenUsageSchema: z.ZodObject<{
+    inputTokens: z.ZodInt;
+    outputTokens: z.ZodInt;
+    cacheReadTokens: z.ZodOptional<z.ZodInt>;
+    cacheCreationTokens: z.ZodOptional<z.ZodInt>;
+}, z.core.$strip>;
+export declare const budgetConfigSchema: z.ZodObject<{
+    dailyLimit: z.ZodOptional<z.ZodNumber>;
+    sessionLimit: z.ZodOptional<z.ZodNumber>;
+    userDailyLimit: z.ZodOptional<z.ZodNumber>;
+    alertThreshold: z.ZodDefault<z.ZodNumber>;
+    criticalThreshold: z.ZodDefault<z.ZodNumber>;
+    maxAttributions: z.ZodDefault<z.ZodInt>;
+    retentionDays: z.ZodDefault<z.ZodInt>;
+}, z.core.$strip>;
+export declare const costBreakdownSchema: z.ZodObject<{
+    inputCost: z.ZodNumber;
+    outputCost: z.ZodNumber;
+    totalCost: z.ZodNumber;
+    model: z.ZodString;
+    cacheDiscount: z.ZodOptional<z.ZodNumber>;
+    usedFallbackPricing: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export declare const alertLevelSchema: z.ZodEnum<{
+    ok: "ok";
+    warning: "warning";
+    critical: "critical";
+    exceeded: "exceeded";
+}>;
+export declare const budgetCheckResultSchema: z.ZodObject<{
+    level: z.ZodEnum<{
+        ok: "ok";
+        warning: "warning";
+        critical: "critical";
+        exceeded: "exceeded";
+    }>;
+    message: z.ZodString;
+    currentSpend: z.ZodNumber;
+    limit: z.ZodNumber;
+    percentUsed: z.ZodNumber;
+    remainingBudget: z.ZodNumber;
+}, z.core.$strip>;
+export declare const costAttributionSchema: z.ZodObject<{
+    sessionId: z.ZodOptional<z.ZodString>;
+    userId: z.ZodOptional<z.ZodString>;
+    model: z.ZodString;
+    timestamp: z.ZodISODateTime;
+    inputTokens: z.ZodInt;
+    outputTokens: z.ZodInt;
+    totalCost: z.ZodNumber;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export declare const costSummarySchema: z.ZodObject<{
+    totalCost: z.ZodNumber;
+    totalInputTokens: z.ZodInt;
+    totalOutputTokens: z.ZodInt;
+    totalRequests: z.ZodInt;
+    byModel: z.ZodRecord<z.ZodString, z.ZodObject<{
+        cost: z.ZodNumber;
+        tokens: z.ZodInt;
+        requests: z.ZodInt;
+    }, z.core.$strip>>;
+    bySession: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        cost: z.ZodNumber;
+        requests: z.ZodInt;
+    }, z.core.$strip>>>;
+    byUser: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        cost: z.ZodNumber;
+        requests: z.ZodInt;
+    }, z.core.$strip>>>;
+    period: z.ZodObject<{
+        start: z.ZodISODateTime;
+        end: z.ZodISODateTime;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/** Token usage from an LLM call */
+export type TokenUsage = z.infer<typeof tokenUsageSchema>;
+/** Input type for token usage (allows undefined optional fields before defaults applied) */
+export type TokenUsageInput = z.input<typeof tokenUsageSchema>;
+/** Cost breakdown for a single LLM call */
+export type CostBreakdown = z.infer<typeof costBreakdownSchema>;
+/** Input type for cost breakdown */
+export type CostBreakdownInput = z.input<typeof costBreakdownSchema>;
+/** Budget alert status */
+export type AlertLevel = z.infer<typeof alertLevelSchema>;
+/** Input type for alert level */
+export type AlertLevelInput = z.input<typeof alertLevelSchema>;
+/** Budget configuration for alerting (allows partial input, defaults applied internally) */
+export type BudgetConfig = z.input<typeof budgetConfigSchema>;
+/** Alias for backward compatibility */
+export type BudgetConfigInput = BudgetConfig;
+/** Budget check result */
+export type BudgetCheckResult = z.infer<typeof budgetCheckResultSchema>;
+/** Input type for budget check result */
+export type BudgetCheckResultInput = z.input<typeof budgetCheckResultSchema>;
+/** Cost attribution record */
+export type CostAttribution = z.infer<typeof costAttributionSchema>;
+/** Input type for cost attribution */
+export type CostAttributionInput = z.input<typeof costAttributionSchema>;
+/** Aggregated cost summary */
+export type CostSummary = z.infer<typeof costSummarySchema>;
+/** Input type for cost summary */
+export type CostSummaryInput = z.input<typeof costSummarySchema>;
+/** Default cache read discount (90% cheaper than regular input) */
+export declare const DEFAULT_CACHE_DISCOUNT = 0.9;
+/** Minimum cost to report (avoid floating point noise) */
+export declare const MIN_REPORTABLE_COST = 0.0001;
+/**
+ * Calculate cost from token usage for a specific model.
+ *
+ * @param usage - Token usage data (validated at runtime)
+ * @param model - Model identifier (must match key in MODEL_PRICING)
+ * @param cacheDiscount - Discount for cached tokens (default 0.9 = 90% off)
+ * @returns Cost breakdown with input/output/total costs
+ * @throws {CostEstimationError} If usage or cacheDiscount is invalid
+ *
+ * @example
+ * const cost = calculateCost(
+ *   { inputTokens: 1000, outputTokens: 500 },
+ *   'claude-sonnet-4-20250514'
+ * );
+ * // Returns: { inputCost: 0.003, outputCost: 0.0075, totalCost: 0.0105 }
+ */
+export declare function calculateCost(usage: TokenUsage, model: string, cacheDiscount?: number): CostBreakdown;
+/**
+ * Get pricing for a model.
+ *
+ * @param model - Model identifier
+ * @returns Pricing per 1M tokens or null if unknown
+ */
+export declare function getModelPricing(model: string): {
+    input: number;
+    output: number;
+} | null;
+/**
+ * List all known models with pricing.
+ */
+export declare function listModelsWithPricing(): Array<{
+    model: string;
+    input: number;
+    output: number;
+}>;
+/**
+ * Check if pricing data is stale.
+ *
+ * @returns Staleness check result with days since update
+ */
+export declare function isPricingStale(): {
+    isStale: boolean;
+    daysSinceUpdate: number;
+    lastUpdated: string;
+};
+/**
+ * Check current spend against budget limits.
+ *
+ * @param currentSpend - Current spend in USD (must be non-negative)
+ * @param limit - Budget limit in USD (must be non-negative)
+ * @param config - Budget configuration with thresholds
+ * @returns Budget check result with alert level
+ * @throws {CostEstimationError} If inputs are invalid
+ *
+ * @example
+ * const result = checkBudget(8.50, 10.00, { alertThreshold: 0.8 });
+ * // Returns: { level: 'warning', percentUsed: 85, ... }
+ */
+export declare function checkBudget(currentSpend: number, limit: number, config?: Pick<BudgetConfig, 'alertThreshold' | 'criticalThreshold'>): BudgetCheckResult;
+/**
+ * Create a budget tracker for monitoring spend over time.
+ *
+ * @warning NOT THREAD-SAFE: Do not call recordSpend() concurrently.
+ *
+ * @param config - Budget configuration
+ * @returns Budget tracker with methods to record spend and check limits
+ *
+ * @example
+ * const tracker = createBudgetTracker({ dailyLimit: 10.00 });
+ * tracker.recordSpend(0.05, 'session-1', 'user-1');
+ * const status = tracker.checkDaily();
+ */
+export declare function createBudgetTracker(config?: BudgetConfig): {
+    /** Record a cost attribution. @throws {CostEstimationError} If metadata is too large */
+    recordSpend(cost: number, sessionId?: string, userId?: string, model?: string, inputTokens?: number, outputTokens?: number, metadata?: Record<string, unknown>): void;
+    checkDaily(date?: string): BudgetCheckResult | null;
+    checkSession(sessionId: string): BudgetCheckResult | null;
+    checkUserDaily(userId: string, date?: string): BudgetCheckResult | null;
+    getSummary(startDate?: string, endDate?: string): CostSummary;
+    getAttributions(): readonly CostAttribution[];
+    reset(): void;
+    cleanup(): void;
+    getStats(): {
+        attributions: number;
+        dailyEntries: number;
+        sessionEntries: number;
+        userDailyEntries: number;
+    };
+};
+/**
+ * Estimate cost for a batch of requests.
+ *
+ * @param requests - Array of token usage with model
+ * @returns Total cost and per-request breakdown
+ * @throws {CostEstimationError} If any request has invalid token usage
+ */
+export declare function estimateBatchCost(requests: Array<{
+    usage: TokenUsage;
+    model: string;
+}>): {
+    totalCost: number;
+    perRequest: CostBreakdown[];
+};
+/**
+ * Estimate cost before making a request (based on estimated tokens).
+ *
+ * @param estimatedInputTokens - Estimated input token count
+ * @param estimatedOutputTokens - Estimated output token count
+ * @param model - Target model
+ * @returns Estimated cost breakdown
+ * @throws {CostEstimationError} If token counts are invalid
+ */
+export declare function estimateCostBeforeRequest(estimatedInputTokens: number, estimatedOutputTokens: number, model: string): CostBreakdown;
+/**
+ * Estimate tokens from text (rough approximation).
+ *
+ * @param text - Input text
+ * @param charsPerToken - Average characters per token (default 4, must be positive)
+ * @returns Estimated token count
+ * @throws {CostEstimationError} If charsPerToken is not positive
+ */
+export declare function estimateTokens(text: string, charsPerToken?: number): number;
+//# sourceMappingURL=cost-estimation.d.ts.map

package/dist/lib/cost/cost-estimation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost-estimation.d.ts","sourceRoot":"","sources":["../../../src/lib/cost/cost-estimation.ts"],"names":[],"mappings":"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"}