@agentproto/model-catalog 0.2.0

package/dist/catalog-aQHd559b.d.ts

@@ -0,0 +1,594 @@
+import { C as CatalogProvider } from './base-BNHcMifc.js';
+
+/**
+ * LLM Pricing Catalog — per-token costs for all LLM models.
+ *
+ * Migrated from `packages/core/src/config/llm-pricing.ts` (commit `eeb1acdc`
+ * era). The original location now re-exports from here so every existing
+ * consumer (orchestrator dynamic imports, agent-analytics) keeps working.
+ *
+ * Prices in USD per 1M tokens (input and output separated).
+ * Credit costs are what we charge users (includes margin).
+ */
+
+interface LLMPricing {
+    /** Provider cost: $ per 1M input tokens */
+    inputPer1M: number;
+    /** Provider cost: $ per 1M output tokens */
+    outputPer1M: number;
+    /**
+     * Strategic per-model centicredit override for input. Bypasses the
+     * default `inputPer1M × text-markup / CC_USD_RATE` formula. Use only
+     * for explicit loss-leader / promo models — formula path is
+     * cost-plus-margin by construction and self-heals when providers
+     * change rates.
+     *
+     * Unit: **centicredits per 1M input tokens** (1 displayed credit =
+     * 100 cc). Example: `overrideCreditInputPer1M: 1000` charges 10
+     * displayed credits per 1M input tokens.
+     */
+    overrideCreditInputPer1M?: number;
+    /** Same as `overrideCreditInputPer1M`, for output tokens. Unit: cc/1M. */
+    overrideCreditOutputPer1M?: number;
+    /**
+     * Provider-side discount for cache-read tokens (Anthropic prompt
+     * caching: ~10% of base input). Default 1.0 — no cache discount —
+     * for providers without prompt caching. Applies to BOTH the
+     * provider-cost calculation AND the derived credit cost so the
+     * margin holds for cached vs uncached tokens.
+     */
+    cacheReadMultiplier?: number;
+    /**
+     * Provider-side premium for cache-creation tokens (Anthropic prompt
+     * caching: ~125% of base input — slightly more than uncached, but
+     * the savings come from subsequent reads). Default 1.0. Applies to
+     * BOTH sides like `cacheReadMultiplier`.
+     */
+    cacheWriteMultiplier?: number;
+    /**
+     * Router / SDK used to call the model. Same model can be reachable via
+     * multiple providers — `claude-sonnet-4-5` is `provider: "anthropic"`
+     * when called through the Anthropic SDK and `provider: "openrouter"`
+     * when routed through OpenRouter. Distinct from `vendor`: this is HOW
+     * we reach the model, not WHO made it.
+     *   - bare ids (`claude-sonnet-4-5`, `gpt-4o`, `gemini-2.5-flash`)
+     *     → `"anthropic" | "openai" | "google"` (direct providers)
+     *   - slash ids (`anthropic/claude-sonnet-4-5`, `qwen/qwen3-coder`)
+     *     → `"openrouter"` (always — the slash is the OpenRouter route
+     *     convention and the OpenRouter SDK is what runs them)
+     *
+     * The runtime can still pass an explicit `connectorUsed` to
+     * `emitUsageEvent` — that wins over this default and covers the
+     * edge case where a guild has multiple connectors and the
+     * dispatcher routed to a non-default one.
+     */
+    provider?: CatalogProvider;
+    /**
+     * Who authored / built the model. Permanent attribute, independent of
+     * the router: `claude-sonnet-4-5` is always `vendor: "anthropic"`
+     * regardless of whether `provider` is `"anthropic"` (direct) or
+     * `"openrouter"` (proxied). Used for display labels, BYOK gating, and
+     * analytics grouping. Examples: `anthropic`, `openai`, `google`,
+     * `moonshot`, `mistralai`, `minimax`, `meta`, `qwen`, `deepseek`.
+     */
+    vendor?: string;
+}
+declare const LLM_PRICING_CATALOG: {
+    "claude-opus-4-5": {
+        inputPer1M: number;
+        outputPer1M: number;
+        cacheReadMultiplier: number;
+        cacheWriteMultiplier: number;
+        vendor: string;
+        provider: "anthropic";
+    };
+    "claude-sonnet-4-5": {
+        inputPer1M: number;
+        outputPer1M: number;
+        cacheReadMultiplier: number;
+        cacheWriteMultiplier: number;
+        vendor: string;
+        provider: "anthropic";
+    };
+    "claude-haiku-4-5": {
+        inputPer1M: number;
+        outputPer1M: number;
+        cacheReadMultiplier: number;
+        cacheWriteMultiplier: number;
+        vendor: string;
+        provider: "anthropic";
+    };
+    "gemini-2.5-flash": {
+        inputPer1M: number;
+        outputPer1M: number;
+        cacheReadMultiplier: number;
+        vendor: string;
+        provider: "google";
+    };
+    "gemini-2.5-pro": {
+        inputPer1M: number;
+        outputPer1M: number;
+        cacheReadMultiplier: number;
+        vendor: string;
+        provider: "google";
+    };
+    "gemini-3.5-flash": {
+        inputPer1M: number;
+        outputPer1M: number;
+        cacheReadMultiplier: number;
+        vendor: string;
+        provider: "google";
+    };
+    "gemini-2.5-flash-lite": {
+        inputPer1M: number;
+        outputPer1M: number;
+        cacheReadMultiplier: number;
+        vendor: string;
+        provider: "google";
+    };
+    "gemini-3.1-pro-preview": {
+        inputPer1M: number;
+        outputPer1M: number;
+        cacheReadMultiplier: number;
+        vendor: string;
+        provider: "google";
+    };
+    "gemini-3-flash-preview": {
+        inputPer1M: number;
+        outputPer1M: number;
+        cacheReadMultiplier: number;
+        vendor: string;
+        provider: "google";
+    };
+    "gemini-3.1-flash-lite": {
+        inputPer1M: number;
+        outputPer1M: number;
+        cacheReadMultiplier: number;
+        vendor: string;
+        provider: "google";
+    };
+    "gpt-5.5": {
+        inputPer1M: number;
+        outputPer1M: number;
+        cacheReadMultiplier: number;
+        vendor: string;
+        provider: "openai";
+    };
+    "gpt-5.5-pro": {
+        inputPer1M: number;
+        outputPer1M: number;
+        vendor: string;
+        provider: "openai";
+    };
+    "gpt-5.4": {
+        inputPer1M: number;
+        outputPer1M: number;
+        cacheReadMultiplier: number;
+        vendor: string;
+        provider: "openai";
+    };
+    "gpt-5.4-mini": {
+        inputPer1M: number;
+        outputPer1M: number;
+        cacheReadMultiplier: number;
+        vendor: string;
+        provider: "openai";
+    };
+    "gpt-5.4-nano": {
+        inputPer1M: number;
+        outputPer1M: number;
+        cacheReadMultiplier: number;
+        vendor: string;
+        provider: "openai";
+    };
+    "gpt-5.4-pro": {
+        inputPer1M: number;
+        outputPer1M: number;
+        vendor: string;
+        provider: "openai";
+    };
+    "gpt-5.2": {
+        inputPer1M: number;
+        outputPer1M: number;
+        cacheReadMultiplier: number;
+        vendor: string;
+        provider: "openai";
+    };
+    "gpt-5.1": {
+        inputPer1M: number;
+        outputPer1M: number;
+        cacheReadMultiplier: number;
+        vendor: string;
+        provider: "openai";
+    };
+    "gpt-5": {
+        inputPer1M: number;
+        outputPer1M: number;
+        cacheReadMultiplier: number;
+        vendor: string;
+        provider: "openai";
+    };
+    "gpt-4.1": {
+        inputPer1M: number;
+        outputPer1M: number;
+        vendor: string;
+        provider: "openai";
+    };
+    "gpt-4.1-mini": {
+        inputPer1M: number;
+        outputPer1M: number;
+        vendor: string;
+        provider: "openai";
+    };
+    "gpt-4.1-nano": {
+        inputPer1M: number;
+        outputPer1M: number;
+        cacheReadMultiplier: number;
+        vendor: string;
+        provider: "openai";
+    };
+    "gpt-4o": {
+        inputPer1M: number;
+        outputPer1M: number;
+        vendor: string;
+        provider: "openai";
+    };
+    "gpt-4o-mini": {
+        inputPer1M: number;
+        outputPer1M: number;
+        vendor: string;
+        provider: "openai";
+    };
+    o3: {
+        inputPer1M: number;
+        outputPer1M: number;
+        vendor: string;
+        provider: "openai";
+    };
+    "o4-mini": {
+        inputPer1M: number;
+        outputPer1M: number;
+        cacheReadMultiplier: number;
+        vendor: string;
+        provider: "openai";
+    };
+    "o3-mini": {
+        inputPer1M: number;
+        outputPer1M: number;
+        vendor: string;
+        provider: "openai";
+    };
+    o1: {
+        inputPer1M: number;
+        outputPer1M: number;
+        cacheReadMultiplier: number;
+        vendor: string;
+        provider: "openai";
+    };
+    "o1-mini": {
+        inputPer1M: number;
+        outputPer1M: number;
+        vendor: string;
+        provider: "openai";
+    };
+    "MiniMax-M2": {
+        inputPer1M: number;
+        outputPer1M: number;
+        cacheReadMultiplier: number;
+        cacheWriteMultiplier: number;
+        vendor: string;
+        provider: "minimax";
+    };
+    "M2-her": {
+        inputPer1M: number;
+        outputPer1M: number;
+        cacheReadMultiplier: number;
+        cacheWriteMultiplier: number;
+        vendor: string;
+        provider: "minimax";
+    };
+    "MiniMax-M2.1": {
+        inputPer1M: number;
+        outputPer1M: number;
+        cacheReadMultiplier: number;
+        cacheWriteMultiplier: number;
+        vendor: string;
+        provider: "minimax";
+    };
+    "MiniMax-M2.5": {
+        inputPer1M: number;
+        outputPer1M: number;
+        cacheReadMultiplier: number;
+        cacheWriteMultiplier: number;
+        vendor: string;
+        provider: "minimax";
+    };
+    "MiniMax-M2.7": {
+        inputPer1M: number;
+        outputPer1M: number;
+        vendor: string;
+        provider: "minimax";
+    };
+    "kimi-k2.6": {
+        inputPer1M: number;
+        outputPer1M: number;
+        cacheReadMultiplier: number;
+        vendor: string;
+        provider: "moonshot";
+    };
+    "kimi-k2.5": {
+        inputPer1M: number;
+        outputPer1M: number;
+        cacheReadMultiplier: number;
+        vendor: string;
+        provider: "moonshot";
+    };
+    "kimi-k2-0905-preview": {
+        inputPer1M: number;
+        outputPer1M: number;
+        cacheReadMultiplier: number;
+        vendor: string;
+        provider: "moonshot";
+    };
+    "kimi-k2-turbo-preview": {
+        inputPer1M: number;
+        outputPer1M: number;
+        cacheReadMultiplier: number;
+        vendor: string;
+        provider: "moonshot";
+    };
+    "kimi-k2-thinking": {
+        inputPer1M: number;
+        outputPer1M: number;
+        cacheReadMultiplier: number;
+        vendor: string;
+        provider: "moonshot";
+    };
+    "kimi-k2-thinking-turbo": {
+        inputPer1M: number;
+        outputPer1M: number;
+        cacheReadMultiplier: number;
+        vendor: string;
+        provider: "moonshot";
+    };
+    "mistral-large-latest": {
+        inputPer1M: number;
+        outputPer1M: number;
+        vendor: string;
+        provider: "mistral";
+    };
+    "mistral-small-creative-latest": {
+        inputPer1M: number;
+        outputPer1M: number;
+        vendor: string;
+        provider: "mistral";
+    };
+    "mistral-small-2501": {
+        inputPer1M: number;
+        outputPer1M: number;
+        vendor: string;
+        provider: "mistral";
+    };
+    "mistral-small-latest": {
+        inputPer1M: number;
+        outputPer1M: number;
+        cacheReadMultiplier: number;
+        vendor: string;
+        provider: "mistral";
+    };
+};
+/**
+ * Every canonical catalog model id — derived straight from the pricing
+ * map keys (`satisfies` above preserves the literal keys). Downstream
+ * curation/config should constrain their ids to this so a typo or a
+ * removed model is a build error, not a broken row at runtime.
+ */
+type LlmModelId = keyof typeof LLM_PRICING_CATALOG;
+declare const MODEL_ALIASES: {
+    "claude-opus-4-6": string;
+    "claude-sonnet-4-6": string;
+    "claude-4-opus": string;
+    "claude-4-sonnet": string;
+    "claude-3-5-haiku": string;
+    "claude-haiku-4-5-20251001": string;
+    "claude-opus-4": string;
+    "claude-sonnet-4": string;
+    "claude-haiku-3.5": string;
+    "gemini-3.1-flash-lite-preview": string;
+    "google/gemini-3.1-pro-preview": string;
+    "google/gemini-3.5-flash": string;
+    "google/gemini-3-flash-preview": string;
+    "google/gemini-3.1-flash-lite": string;
+    "google/gemini-2.5-flash": string;
+    "google/gemini-2.5-flash-lite": string;
+    "google/gemini-2.5-pro": string;
+    "openai/gpt-4.1": string;
+    "openai/gpt-4.1-mini": string;
+    "openai/gpt-4.1-nano": string;
+    "openai/gpt-5": string;
+    "openai/gpt-5.1": string;
+    "openai/gpt-5.2": string;
+    "openai/gpt-5.4": string;
+    "openai/gpt-5.4-mini": string;
+    "openai/gpt-5.4-nano": string;
+    "openai/gpt-5.5": string;
+    "openai/o3": string;
+    "openai/o4-mini": string;
+    "openai/o3-mini": string;
+    "openai/o1": string;
+    "openai/o1-mini": string;
+    "minimax-m2": string;
+    "minimax-m2.1": string;
+    "minimax-m2.5": string;
+    "minimax-m2.7": string;
+    "kimi-k2": string;
+    "moonshotai/kimi-k2.5": string;
+    "moonshotai/kimi-k2.6": string;
+    "mistralai/mistral-large-latest": string;
+    "mistralai/mistral-small-latest": string;
+};
+/** Every alias id that resolves to a canonical model — the alias keys. */
+type LlmModelAlias = keyof typeof MODEL_ALIASES;
+/** Any model id the catalog recognises — canonical key or alias. */
+type KnownLlmId = LlmModelId | LlmModelAlias;
+/**
+ * Resolves a model id to its pricing entry. Tries direct match → alias →
+ * partial-prefix match. Used both for cost computation and BYOK shadow
+ * accounting; semantics are load-bearing for migration.
+ */
+declare function resolvePricing(modelId: string): LLMPricing | undefined;
+/**
+ * Resolves a model id to its canonical catalog key (or the original id if no
+ * match). Public surface for consumers that need the canonical id without
+ * the pricing payload.
+ */
+declare function resolveAlias(modelId: string): string;
+/**
+ * Resolve a model id to its DEFAULT provider — the single source of truth for
+ * "which SDK reaches this model when no per-model override is set". Reads the
+ * resolved catalog entry's `provider` field (direct id → alias → partial
+ * prefix, same resolution as `resolvePricing`). Returns undefined for unknown
+ * ids so callers can fall back to their own heuristic.
+ *
+ * This is the abstraction that decouples the provider from the model-id STRING:
+ * instead of inferring "claude-* → anthropic" at each call site, the provider
+ * is an explicit catalog attribute. A model reachable through more than one
+ * provider (e.g. Claude via the direct Anthropic SDK vs. OpenRouter) is held as
+ * distinct catalog entries — the bare id (`claude-haiku-4-5`, provider
+ * `anthropic`) and the slash route (`anthropic/claude-haiku-4.5`, provider
+ * `openrouter`) — each carrying its own `provider`.
+ */
+declare function getModelProvider(modelId: string): CatalogProvider | undefined;
+/**
+ * The unified registry view of a model: canonical id, default provider, vendor,
+ * and pricing — everything the routing + billing layers need from ONE lookup.
+ * Returns undefined for unknown ids.
+ */
+interface ModelRoute {
+    /** Canonical catalog key (post-alias). */
+    canonicalId: string;
+    /** Default provider — the SDK used when no per-model override is set. */
+    provider?: CatalogProvider;
+    /** Model author/vendor (permanent; independent of the routing provider). */
+    vendor?: string;
+    /** Billing pricing entry. */
+    pricing: LLMPricing;
+}
+declare function resolveModelRoute(modelId: string): ModelRoute | undefined;
+/**
+ * Default fallback: roughly gemini-flash pricing (cheapest). Unknown
+ * model ids resolve to this — the formula path then computes credit
+ * cost from `inputPer1M`/`outputPer1M`, so unknown models always price
+ * at default markup × cheap-model rates, never at zero.
+ */
+declare const DEFAULT_PRICING: LLMPricing;
+interface LLMCreditCostResult {
+    /**
+     * Total **centicredits** to charge — what `useAccountCredits` debits
+     * directly (ledger column is cc). Reflects any per-model override or
+     * per-app markup; never below `MIN_CREDITS_PER_TURN_CC`.
+     *
+     * Unit: cc (1 displayed credit = 100 cc). Format for display with
+     * `displayCredits(cc) → cr`.
+     */
+    credits: number;
+    /**
+     * What the *pure formula* would have charged (provider cost ×
+     * text-markup), independent of per-model overrides. Surfaced so
+     * `usage_events.calculated_credits` can record the formula-derived
+     * value next to the override-applied debit — easy reconciliation
+     * against Langfuse traces. Unit: cc.
+     */
+    calculatedCredits: number;
+    /** Breakdown of `credits` (each in cc). */
+    inputCredits: number;
+    outputCredits: number;
+    cacheReadCredits: number;
+    cacheWriteCredits: number;
+    /** Production cost in USD (true provider cost, with cache multipliers applied). */
+    productionCost: number;
+    /** Model pricing used */
+    pricing: LLMPricing;
+    /** Whether fallback pricing was used */
+    isFallback: boolean;
+    /** Markup actually applied. Same as `pricingRegistry.getMarkup("text", appId)` when no override. */
+    markup: number;
+    /** True when a per-model `overrideCredit*Per1M` field bypassed the formula. */
+    hasOverride: boolean;
+}
+interface LLMUsageBreakdown {
+    /**
+     * Input tokens that were NOT served from cache. With Anthropic prompt
+     * caching, providers often report `inputTokens` already EXCLUDING
+     * cached portions — pass the same number you'd pass to the legacy
+     * 3-arg signature; cache fields are ADDED on top.
+     */
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadInputTokens?: number;
+    cacheCreationInputTokens?: number;
+}
+interface CalculateLLMCreditCostOptions {
+    /**
+     * App invoking the LLM. Routes per-app markup overrides registered
+     * via `pricingRegistry.registerApp(appId, ...)`. When omitted, core
+     * defaults apply.
+     */
+    appId?: string;
+    /**
+     * Direct markup override (escape hatch for tests / one-off
+     * reconciliation). When set, bypasses `pricingRegistry` for both
+     * formula and `calculatedCredits` math. Takes precedence over
+     * `appId`.
+     */
+    markupOverride?: number;
+}
+declare function calculateLLMCreditCost(modelId: string, inputTokens: number, outputTokens: number): LLMCreditCostResult;
+declare function calculateLLMCreditCost(modelId: string, usage: LLMUsageBreakdown, opts?: CalculateLLMCreditCostOptions): LLMCreditCostResult;
+interface CacheStats {
+    /**
+     * Cache hit rate as a 0..1 fraction of total input tokens (raw + cache
+     * read + cache create). 0 means no cache activity, 1 means everything
+     * read from cache, 0 for output-only calls. `null` when there were no
+     * input tokens at all.
+     */
+    cacheHitRate: number | null;
+    /**
+     * Provider USD we *saved* vs the same input billed at the uncached
+     * rate. Cache reads at 0.1× save 0.9× of the input cost; cache writes
+     * at 1.25× actually COST 0.25× more than uncached (negative savings).
+     * Sum across both. Negative means cache-write overhead exceeded
+     * cache-read savings (rare — usually means the prompt prefix was
+     * cached on the first turn but never re-used).
+     */
+    providerCostSavedUsd: number;
+    /**
+     * Centicredits the user *saved* vs the same input billed at the
+     * uncached rate. Same sign convention as `providerCostSavedUsd`.
+     * Unit: cc (format with `displayCredits(cc)` for UI).
+     */
+    creditsSaved: number;
+    /**
+     * True iff the model carries cache multipliers in its pricing.
+     * Useful for explaining "this model doesn't support caching" in UI.
+     */
+    cacheSupported: boolean;
+}
+/**
+ * Turn a credit-cost result into cache-utilisation stats. Pure compute.
+ *
+ * Use cases:
+ *   - "Cache saved 87% on this call" in a UI tooltip.
+ *   - Per-conversation dashboards: "across this conversation, prompt
+ *     caching saved you $0.42 / 12 credits."
+ *   - Regression alarms — if cacheHitRate drops below an expected
+ *     threshold on a known-cacheable workload, something broke in
+ *     prompt-prefix stability.
+ *
+ * Returns `cacheSupported: false` for models without cache multipliers
+ * (gpt-4o-mini, gemini, mistral) — all fields are zero in that case
+ * (no cache activity is possible).
+ */
+declare function getCacheStats(modelId: string, usage: LLMUsageBreakdown, opts?: CalculateLLMCreditCostOptions): CacheStats;
+
+export { type CacheStats as C, DEFAULT_PRICING as D, type KnownLlmId as K, type LLMCreditCostResult as L, MODEL_ALIASES as M, type CalculateLLMCreditCostOptions as a, type LLMPricing as b, type LLMUsageBreakdown as c, LLM_PRICING_CATALOG as d, type LlmModelAlias as e, type LlmModelId as f, type ModelRoute as g, calculateLLMCreditCost as h, getCacheStats as i, getModelProvider as j, resolveModelRoute as k, resolvePricing as l, resolveAlias as r };