@graphrefly/graphrefly 0.45.0 → 0.47.0

package/dist/types-BB5Lw-pB.d.ts

@@ -0,0 +1,442 @@
+import { Node } from '@graphrefly/pure-ts/core';
+import { NodeInput } from '@graphrefly/pure-ts/extra';
+
+/**
+ * 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;
+/**
+ * Convenience: compute a {@link PriceBreakdown} directly from a
+ * {@link import("./capabilities.js").ModelCapabilities} object + usage.
+ *
+ * When callers look up capabilities themselves (via
+ * `capabilitiesRegistry.lookup(...)` or `adapter.capabilities?.(model)`),
+ * this helper skips the pricing-registry round-trip and computes the price
+ * from `capabilities.pricing` directly.
+ *
+ * Returns `zeroPrice()` when `capabilities.pricing` is undefined — never throws.
+ *
+ * @param capabilities - Model capabilities object (`capabilities.pricing` may be absent).
+ * @param usage - Per-call usage to price.
+ * @param opts - Pass-through to {@link computePrice}.
+ *
+ * @example
+ * ```ts
+ * const cap = registry.lookup("anthropic", "claude-sonnet-4-6");
+ * const price = pricingFor(cap, resp.usage, { tier: "batch", withBreakdown: true });
+ * ```
+ *
+ * @category ai
+ */
+declare function pricingFor(capabilities: ModelCapabilities | undefined, usage: TokenUsage, opts?: {
+    tier?: string;
+    withBreakdown?: boolean;
+}): PriceBreakdown;
+
+/**
+ * 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>;
+    /**
+     * Reactive view of `(provider, model)` → `ModelCapabilities`. Re-emits
+     * whenever any `register()` / `remove()` touches the underlying store, so
+     * UIs and gated middleware (capability-aware retry, feature flags) can
+     * subscribe instead of polling. Prefix fallback mirrors the imperative
+     * `lookup()`: exact match first, then longest-prefix within provider.
+     */
+    lookupNode(provider: string, model: string): Node<ModelCapabilities | undefined>;
+    /** Reactive view of every registered entry. */
+    readonly entriesNode: Node<readonly ModelCapabilities[]>;
+    /** Reactive slice of entries for a single provider. */
+    byProvider(provider: string): Node<readonly 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>;
+    /**
+     * Handler invoked when the LLM requests this tool.
+     *
+     * The optional `opts.signal` fires when the reactive surface that owns
+     * this invocation is torn down (e.g. the agent's `switchMap` over
+     * `toolCalls` superseded with a fresh batch, the agent was aborted, or
+     * the parent graph destroyed). Signal-aware handlers should thread it
+     * into `fetch(url, {signal})`, child-process kill, DB cancel, etc., so
+     * in-flight side effects actually stop. Handlers that ignore the
+     * signal still work — but their work continues to completion regardless
+     * of supersede.
+     */
+    readonly handler: (args: Record<string, unknown>, opts?: {
+        signal?: AbortSignal;
+    }) => 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 CapabilitiesRegistry as C, type LLMAdapter as L, type ModelCapabilities as M, type PriceBreakdown as P, type Rate as R, type StreamDelta as S, type TieredRate as T, type ChatMessage as a, type LLMInvokeOptions as b, type LLMResponse as c, type ModelFeatures as d, type ModelLimits as e, type ModelPricing as f, type PricingFn as g, type PricingRegistry as h, type TokenUsage as i, type ToolCall as j, type ToolDefinition as k, composePricing as l, computePrice as m, createCapabilitiesRegistry as n, createPricingRegistry as o, pricingFor as p, registryPricing as r, zeroPrice as z };