/**
 * Canonical cost tracking with cache economics for LLM usage.
 *
 * Ported from Hermes `agent/usage_pricing.py` (spec section 7.5).
 * MVP slice: static pricing snapshot for major providers + cost helpers.
 *
 * Resolution priority:
 *   1. Exact model ID match in {@link PRICING_SNAPSHOT}
 *   2. Alias-strip (trailing date / version suffix removed)
 *   3. `null` → caller logs / tracks unknown model
 *
 * @module llm/usage-pricing
 * @task T9274
 * @epic T9261 (T-LLM-CRED-CENTRALIZATION Phase 3)
 */
import type { NormalizedUsage } from '@cleocode/contracts';
/**
 * Source attribution for a pricing entry.
 */
export type PricingSource = 'official_docs_snapshot' | 'provider_cost_api' | 'user_override';
/**
 * Per-million-token cost in USD for a model.
 *
 * Cache pricing is OPTIONAL — providers without prompt caching omit those
 * fields and `computeCost` treats them as the same as input/output rates.
 *
 * @task T9274 (T-LLM-CRED Phase 3)
 */
export interface PricingEntry {
    /** USD per million prompt tokens. */
    inputCostPerMillion: number;
    /** USD per million completion tokens. */
    outputCostPerMillion: number;
    /** USD per million cache-read tokens (Anthropic ephemeral cache hit). */
    cacheReadCostPerMillion?: number;
    /** USD per million cache-write tokens (Anthropic ephemeral cache miss / first write). */
    cacheWriteCostPerMillion?: number;
    /** Attribution for this pricing entry. */
    source: PricingSource;
    /** Snapshot date YYYY-MM-DD (present for `official_docs_snapshot` entries). */
    snapshotDate?: string;
}
/**
 * Canonical usage record — superset of {@link NormalizedUsage} with reasoning
 * tokens, explicit cache-write accounting, and an optional request count for
 * cost aggregation.
 */
export interface CanonicalUsage {
    /** Tokens consumed by the prompt (non-cached). */
    inputTokens: number;
    /** Tokens generated by the model. */
    outputTokens: number;
    /** Tokens served from prompt cache (read hit). */
    cacheReadTokens?: number;
    /** Tokens written to prompt cache (cache miss / first write). */
    cacheWriteTokens?: number;
    /** Model-internal reasoning tokens (o1 / extended-thinking). Billed at output rate. */
    reasoningTokens?: number;
    /** Number of API requests included in this usage record (default 1). */
    requestCount?: number;
}
/**
 * Static pricing snapshot (USD per million tokens).
 *
 * Sources:
 * - Anthropic: https://www.anthropic.com/pricing (2026-05-13)
 * - OpenAI: https://openai.com/pricing (2026-05-13)
 * - Google Gemini: https://ai.google.dev/pricing (2026-05-13)
 * - DeepSeek: https://api-docs.deepseek.com/quick_start/pricing (2026-05-13)
 *
 * Add new entries as providers expand. User overrides are applied via a
 * separate overrides map passed to {@link computeCost}.
 *
 * @remarks All values are frozen — mutate via `computeCost(usage, model, overrides)`.
 */
export declare const PRICING_SNAPSHOT: Readonly<Record<string, PricingEntry>>;
/**
 * Look up the pricing entry for a model.
 *
 * Resolution order:
 *   1. Exact match in {@link PRICING_SNAPSHOT}.
 *   2. Alias-strip: each {@link ALIAS_STRIP_PATTERNS} is tried in order.
 *   3. `null` when no entry is found.
 *
 * @param model - Provider model ID (e.g. `'claude-sonnet-4-6-20251001'`).
 * @returns The matching {@link PricingEntry} or `null`.
 */
export declare function lookupPricing(model: string): PricingEntry | null;
/**
 * Compute USD cost for a usage record at a given model's pricing tier.
 *
 * Cost breakdown:
 * - **Input tokens** → `inputCostPerMillion`
 * - **Output tokens** → `outputCostPerMillion`
 * - **Cache-read tokens** → `cacheReadCostPerMillion` (falls back to `inputCostPerMillion`)
 * - **Cache-write tokens** → `cacheWriteCostPerMillion` (falls back to `inputCostPerMillion`)
 * - **Reasoning tokens** → `outputCostPerMillion` (billed at output rate, per Anthropic/OpenAI)
 *
 * Returns `0` for unknown models — callers should log or track these separately.
 *
 * @param usage - Usage record ({@link CanonicalUsage} or {@link NormalizedUsage}).
 * @param model - Provider model ID.
 * @returns Total cost in USD.
 */
export declare function computeCost(usage: CanonicalUsage | NormalizedUsage, model: string): number;
/**
 * Convert a {@link NormalizedUsage} or {@link CanonicalUsage} to a full
 * {@link CanonicalUsage} record.
 *
 * Field mapping:
 * - `NormalizedUsage.cachedTokens` → `cacheReadTokens`
 * - All other optional fields default to `undefined`.
 *
 * @param u - Source usage record.
 * @returns A {@link CanonicalUsage} with all optional fields filled or `undefined`.
 */
export declare function toCanonicalUsage(u: NormalizedUsage | CanonicalUsage): CanonicalUsage;
//# sourceMappingURL=usage-pricing.d.ts.map