@graphrefly/graphrefly 0.27.0 → 0.29.0

package/dist/types-O3GzJY2U.d.cts

@@ -0,0 +1,401 @@
+import { NodeInput } from './extra/sources.cjs';
+
+/**
+ * Pluggable pricing for LLM adapters.
+ *
+ * The library ships the **shape** (types + computation helpers + registry
+ * factory) and **zero model data**. Users populate a `PricingRegistry` with
+ * the prices for the models they use — either by hand, from a curated table,
+ * or by importing a third-party dataset (litellm JSON, etc.).
+ *
+ * Pricing is a pure function of raw `TokenUsage`. The library does not
+ * know current prices, regional rates, tier thresholds, or promotional
+ * discounts — those are all user domain.
+ */
+
+/**
+ * A rate per 1M tokens. Supports threshold-based tiering (Anthropic
+ * long-context >200K, Gemini >200K) via optional `thresholdTokens` +
+ * `pricePerMillionAbove`.
+ *
+ * `total input tokens` (sum of every input class) is the axis the threshold
+ * applies to — matches how Anthropic and Gemini measure it.
+ */
+interface TieredRate {
+    pricePerMillion: number;
+    thresholdTokens?: number;
+    pricePerMillionAbove?: number;
+}
+/** Shorthand: a plain `number` stands for `{pricePerMillion: n}`. */
+type Rate = TieredRate | number;
+/** USD-per-1M rates per token class. All fields optional. */
+interface ModelPricing {
+    input?: {
+        regular?: Rate;
+        cacheRead?: Rate;
+        cacheWrite5m?: Rate;
+        cacheWrite1h?: Rate;
+        cacheWriteOther?: Rate;
+        audio?: Rate;
+        image?: Rate;
+        video?: Rate;
+        toolUse?: Rate;
+        extensions?: Record<string, Rate>;
+    };
+    output?: {
+        regular?: Rate;
+        reasoning?: Rate;
+        audio?: Rate;
+        predictionAccepted?: Rate;
+        predictionRejected?: Rate;
+        extensions?: Record<string, Rate>;
+    };
+    /**
+     * Per-unit costs for non-token axes. Values are USD per unit; units
+     * match `TokenUsage.auxiliary` keys (e.g. `webSearchRequests`, `cacheStorageHours`).
+     */
+    auxiliary?: Record<string, number>;
+    /**
+     * Service-tier multipliers. Applied to the summed per-class price.
+     * E.g. `{ batch: 0.5, flex: 0.5, priority: 1.25 }`. Default (no tier or
+     * tier not present in the map): multiplier = 1.
+     */
+    tierMultipliers?: Record<string, number>;
+    /** Currency code (ISO 4217). Defaults to "USD" when constructed via helpers. */
+    currency: string;
+}
+/** Result of computing a price from usage + pricing. */
+interface PriceBreakdown {
+    /** Total charge in `currency`. */
+    total: number;
+    currency: string;
+    /**
+     * Optional per-class subtotals. Keys are dot-separated paths like
+     * `"input.regular"`, `"output.reasoning"`, `"auxiliary.webSearchRequests"`.
+     */
+    breakdown?: Record<string, number>;
+}
+/** Zero-charge breakdown — returned when no pricing is available for a model. */
+declare function zeroPrice(currency?: string): PriceBreakdown;
+/**
+ * Compute price from a usage object + model pricing.
+ *
+ * - Tier-threshold math uses `sumInputTokens(usage)` as the axis.
+ * - Service tier (`opts.tier`) multiplies the final total via `tierMultipliers`.
+ * - Each token class is priced independently using the matching `Rate` lookup.
+ * - `breakdown` is populated when `opts.withBreakdown = true` (default false
+ *   to keep hot-path allocations low).
+ */
+declare function computePrice(usage: TokenUsage, pricing: ModelPricing, opts?: {
+    tier?: string;
+    withBreakdown?: boolean;
+}): PriceBreakdown;
+/** Pure function: given usage + call context, produce a price. */
+type PricingFn = (usage: TokenUsage, ctx: {
+    model: string;
+    provider: string;
+    tier?: string;
+    withBreakdown?: boolean;
+}) => PriceBreakdown;
+/**
+ * A keyed store of `ModelPricing`. Users populate it at app startup.
+ * The library ships the factory and zero data.
+ *
+ * Keys are `(provider, model)` pairs. Lookup attempts exact match first,
+ * then longest-prefix match on model (e.g. `"claude-sonnet-4-6"` matches a
+ * stored `"claude-sonnet-4-6"` entry when looking up
+ * `"claude-sonnet-4-6-20260401"`).
+ *
+ * **Prefix-match footgun:** a registered `"gemini-1"` will also match a
+ * lookup for `"gemini-1.5-pro"` (since `"gemini-1.5-pro".startsWith("gemini-1")`
+ * is true). Longest-match tie-breaking mitigates most cases, but when
+ * registering a short family-prefix alongside versioned descendants, make sure
+ * the versioned entry is present — otherwise the family prefix wins. Best
+ * practice: register exact versioned model ids; use short family aliases
+ * sparingly and only when all version variants share one pricing schedule.
+ */
+interface PricingRegistry {
+    lookup(provider: string, model: string): ModelPricing | undefined;
+    register(provider: string, model: string, pricing: ModelPricing): void;
+    /** Remove a model's entry; returns `true` if it existed. */
+    remove(provider: string, model: string): boolean;
+    /** Enumerate all entries (for debugging / dump). */
+    entries(): IterableIterator<[string, string, ModelPricing]>;
+}
+/** Create a fresh `PricingRegistry`. Optionally seed with entries. */
+declare function createPricingRegistry(initial?: ReadonlyArray<readonly [provider: string, model: string, pricing: ModelPricing]>): PricingRegistry;
+/**
+ * Build a `PricingFn` from a `PricingRegistry`. If no entry matches, returns
+ * `{ total: 0, currency: "USD" }` (never throws). Callers who need "unknown
+ * model" failures can compose their own `PricingFn`.
+ */
+declare function registryPricing(registry: PricingRegistry, defaultCurrency?: string): PricingFn;
+/** Compose multiple `PricingFn`s — first non-zero wins. Useful for registry layering. */
+declare function composePricing(...fns: readonly PricingFn[]): PricingFn;
+
+/**
+ * Pluggable model capabilities (roadmap §9.3d).
+ *
+ * The library defines the **shape** of what's knowable about a model
+ * (context window, rate limits, features, pricing reference) and provides
+ * a registry factory. Capability **data** is user-supplied — no baked-in
+ * tables, no drift-prone catalog.
+ */
+
+/**
+ * Rate and size limits for a single model at the user's service tier.
+ *
+ * Where providers expose distinct standard / batch / flex limits, register
+ * each as a separate model id with its own `ModelLimits`.
+ */
+interface ModelLimits {
+    /** Total tokens the model can process per request (input + output). */
+    contextWindow?: number;
+    /** Max input tokens if distinct from contextWindow. */
+    maxInputTokens?: number;
+    /** Max generated output tokens (excludes reasoning unless provider folds them). */
+    maxOutputTokens?: number;
+    /** Max reasoning/thinking tokens budget. */
+    maxReasoningTokens?: number;
+    /** Minimum prompt size for prompt caching to activate. */
+    minCacheTokens?: number;
+    /** Requests-per-minute rate limit. */
+    rpm?: number;
+    /** Requests-per-day rate limit. */
+    rpd?: number;
+    /** Tokens-per-minute rate limit (input + output, per provider convention). */
+    tpm?: number;
+    /** Tokens-per-day rate limit. */
+    tpd?: number;
+    /** Max concurrent in-flight requests. */
+    concurrentRequests?: number;
+    /** Provider-specific limits not covered above. */
+    extensions?: Record<string, number>;
+}
+interface ModelFeatures {
+    toolUse?: boolean;
+    vision?: boolean;
+    audioInput?: boolean;
+    audioOutput?: boolean;
+    reasoning?: boolean;
+    streaming?: boolean;
+    promptCache?: boolean;
+    batchApi?: boolean;
+    /** Provider-specific feature flags. */
+    extensions?: Record<string, boolean>;
+}
+/** Static facts about a model. Pricing is optional; keep a separate registry if preferred. */
+interface ModelCapabilities {
+    id: string;
+    provider: string;
+    pricing?: ModelPricing;
+    limits?: ModelLimits;
+    features?: ModelFeatures;
+    /** Free-form metadata (release date, deprecation flag, provider notes). */
+    metadata?: Record<string, unknown>;
+}
+interface CapabilitiesRegistry {
+    lookup(provider: string, model: string): ModelCapabilities | undefined;
+    register(cap: ModelCapabilities): void;
+    remove(provider: string, model: string): boolean;
+    entries(): IterableIterator<ModelCapabilities>;
+}
+/** Create a fresh `CapabilitiesRegistry`. Optionally seed with entries. */
+declare function createCapabilitiesRegistry(initial?: readonly ModelCapabilities[]): CapabilitiesRegistry;
+
+/**
+ * Input token classes.
+ *
+ * Every provider's native usage object maps into this shape without loss.
+ * All fields except `regular` are optional — providers that don't expose
+ * the class simply leave it undefined.
+ */
+interface InputTokens {
+    /** Uncached regular input tokens (cache miss or never-cached). */
+    regular: number;
+    /** Read from prompt cache (all TTLs — providers don't split reads by TTL today). */
+    cacheRead?: number;
+    /** Written to cache with 5-min TTL (Anthropic `ephemeral_5m_input_tokens`). */
+    cacheWrite5m?: number;
+    /** Written to cache with 1-hour TTL (Anthropic `ephemeral_1h_input_tokens`). */
+    cacheWrite1h?: number;
+    /** Written to cache with other/unspecified TTL (Gemini explicit caches). */
+    cacheWriteOther?: number;
+    /** Audio input tokens (OpenAI realtime, Gemini audio). */
+    audio?: number;
+    /** Image input tokens (Gemini per-modality). */
+    image?: number;
+    /** Video input tokens (Gemini per-modality). */
+    video?: number;
+    /** Tool-use result tokens fed back to the model (Gemini `toolUsePromptTokenCount`). */
+    toolUse?: number;
+    /** Provider-specific classes not covered above. Open-ended by design. */
+    extensions?: Record<string, number>;
+}
+/** Output token classes. */
+interface OutputTokens {
+    /** Regular generated output (non-reasoning, non-audio). */
+    regular: number;
+    /** Reasoning / thinking tokens (OpenAI o-series, Gemini thoughts, Grok reasoning). */
+    reasoning?: number;
+    /** Audio output tokens. */
+    audio?: number;
+    /** Predicted-output tokens accepted (OpenAI predictions API). */
+    predictionAccepted?: number;
+    /** Predicted-output tokens rejected (still billed at output rate). */
+    predictionRejected?: number;
+    extensions?: Record<string, number>;
+}
+/** Per-call token usage in canonical shape. No pricing, no interpretation. */
+interface TokenUsage {
+    input: InputTokens;
+    output: OutputTokens;
+    /**
+     * Per-call non-token costs (web-search requests, tool invocations, cache
+     * storage-hours, etc.). Units are domain-specific — pricing functions
+     * interpret them via `ModelPricing.auxiliary`.
+     */
+    auxiliary?: Record<string, number>;
+    /**
+     * Raw provider usage object, unmodified. Escape hatch for anything the
+     * canonical shape doesn't model.
+     */
+    raw?: unknown;
+}
+/** A single chat message in a conversation. */
+type ChatMessage = {
+    readonly role: "system" | "user" | "assistant" | "tool";
+    readonly content: string;
+    readonly name?: string;
+    readonly toolCallId?: string;
+    readonly toolCalls?: readonly ToolCall[];
+    readonly metadata?: Record<string, unknown>;
+};
+/** A tool invocation request from an LLM. */
+type ToolCall = {
+    readonly id: string;
+    readonly name: string;
+    readonly arguments: Record<string, unknown>;
+};
+/** A tool definition for LLM consumption. */
+type ToolDefinition = {
+    readonly name: string;
+    readonly description: string;
+    readonly parameters: Record<string, unknown>;
+    readonly handler: (args: Record<string, unknown>) => NodeInput<unknown>;
+    /**
+     * V0 version of the backing node at tool-definition-creation time.
+     * Snapshot — re-create the tool definition to refresh.
+     */
+    readonly version?: {
+        id: string;
+        version: number;
+    };
+};
+/** The response from an LLM invocation. */
+interface LLMResponse {
+    readonly content: string;
+    readonly toolCalls?: readonly ToolCall[];
+    /**
+     * Token usage. Optional — provider adapters should always populate it, but
+     * test mocks and adapter middlewares that synthesize responses can omit it.
+     * Downstream consumers that compute cost should default to {@link emptyUsage}.
+     */
+    readonly usage?: TokenUsage;
+    readonly finishReason?: string;
+    readonly latencyMs?: number;
+    readonly model?: string;
+    readonly provider?: string;
+    /** Service tier the call was served with (standard / batch / flex / priority). */
+    readonly tier?: string;
+    readonly metadata?: Record<string, unknown>;
+}
+/**
+ * Adapter-facing incremental stream event.
+ *
+ * Provider adapters emit these; higher-level surfaces (`streamingPromptNode`,
+ * `agentLoop`) assemble them into consumer-facing `StreamChunk` with their own
+ * `source`/`accumulated`/`index` context.
+ *
+ * **Shape rationale — why object tagged-union vs. the framework `[TYPE, data]`
+ * tuple?** `StreamDelta` is an *application-layer event payload* that flows
+ * inside a single framework `DATA` message, one abstraction level above the
+ * reactive protocol. The framework's `[Type, Data?]` tuple (DIRTY / DATA /
+ * RESOLVED / COMPLETE / ERROR) is the protocol message form delivered through
+ * `subscribe`. Using the protocol form here would force us to invent new
+ * framework-level symbols (`TOKEN`, `USAGE`, etc.) that leak into user code,
+ * and TypeScript discriminated-union exhaustiveness works much better with
+ * objects than tuples. Object-tagged unions match the idiomatic JS/TS
+ * convention for discriminated events (Redux actions, DOM events).
+ */
+type StreamDelta = {
+    readonly type: "token";
+    readonly delta: string;
+} | {
+    readonly type: "tool-call-delta";
+    readonly delta: {
+        readonly id?: string;
+        readonly name?: string;
+        readonly argumentsDelta?: string;
+    };
+} | {
+    readonly type: "thinking";
+    readonly delta: string;
+} | {
+    readonly type: "usage";
+    readonly usage: TokenUsage;
+} | {
+    readonly type: "finish";
+    readonly reason: string;
+};
+/** Options passed to `invoke()` / `stream()`. */
+interface LLMInvokeOptions {
+    model?: string;
+    temperature?: number;
+    maxTokens?: number;
+    /** Budget for reasoning/thinking tokens, if the model supports it. */
+    maxReasoningTokens?: number;
+    tools?: readonly ToolDefinition[];
+    systemPrompt?: string;
+    /** Hint the adapter to cache the prompt. TTL values depend on provider. */
+    cacheHint?: {
+        ttl?: "5m" | "1h" | string;
+        minTokens?: number;
+    };
+    /** Service tier: "standard" | "batch" | "flex" | "priority" | provider-custom. */
+    tier?: string;
+    signal?: AbortSignal;
+    /**
+     * Provider-specific passthrough — merged into the native request body.
+     * Escape hatch for features not yet in the canonical options.
+     */
+    providerExtras?: Record<string, unknown>;
+    /**
+     * Open-ended per-call context threaded to cache / fallback key functions.
+     * Callers who want to shard caches by tenant, session, feature flag, or
+     * any other dimension populate this and supply a custom `keyFn` that
+     * incorporates it. Not sent to providers — stripped from canonical key
+     * hashing when no custom `keyFn` is supplied. Type is `unknown` to avoid
+     * prescribing a shape; callers pick their own.
+     */
+    keyContext?: unknown;
+}
+/**
+ * Provider-agnostic LLM adapter (spec §5.10 compliant).
+ *
+ * - `invoke()` returns a `NodeInput<LLMResponse>` — the caller bridges to
+ *   reactive via `fromAny(...)`. Adapter implementations may return a
+ *   Promise (simplest), a Node (reactive), or a plain value (testing).
+ * - `stream()` returns `AsyncIterable<StreamDelta>` — the terminal delta of
+ *   type `"usage"` carries the final `TokenUsage` for the streamed call.
+ */
+interface LLMAdapter {
+    readonly provider: string;
+    readonly model?: string;
+    invoke(messages: readonly ChatMessage[], opts?: LLMInvokeOptions): NodeInput<LLMResponse>;
+    stream(messages: readonly ChatMessage[], opts?: LLMInvokeOptions): AsyncIterable<StreamDelta>;
+    /** Optional capability lookup; typically delegates to a `CapabilitiesRegistry`. */
+    capabilities?(model?: string): ModelCapabilities | undefined;
+}
+
+export { type ChatMessage as C, type LLMAdapter as L, type ModelCapabilities as M, type PricingFn as P, type Rate as R, type StreamDelta as S, type TokenUsage as T, type LLMInvokeOptions as a, type LLMResponse as b, type ToolCall as c, type ToolDefinition as d, type CapabilitiesRegistry as e, type ModelFeatures as f, type ModelLimits as g, type ModelPricing as h, type PriceBreakdown as i, type PricingRegistry as j, type TieredRate as k, composePricing as l, computePrice as m, createCapabilitiesRegistry as n, createPricingRegistry as o, registryPricing as r, zeroPrice as z };