@24klynx/llm 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,352 @@
+import { ContentBlock } from "@lynx/core";
+
+//#region src/types.d.ts
+/**
+ * A chat message with a role and content, matching the OpenAI-compatible wire format.
+ * Unlike {@link import('@lynx/core').Message}, this is a wire-format type for the LLM API.
+ */
+interface ChatMessage {
+  /** Who sent this message. */
+  role: "user" | "assistant" | "system";
+  /** Message content — ContentBlock array or plain string. */
+  content: ContentBlock[] | string;
+}
+/**
+ * A single model that a provider can serve.
+ */
+interface ModelInfo {
+  /** Provider‑unique model identifier, e.g. "deepseek-chat". */
+  id: string;
+  /** Human‑readable label shown in model pickers. */
+  label: string;
+  /** Maximum combined context window in tokens. */
+  contextWindow: number;
+  /** Maximum tokens the model can emit in one response. */
+  maxOutput: number;
+}
+/**
+ * Static capabilities declared by a provider for a given model.
+ * Used by the router to decide which model can handle a request.
+ */
+interface ProviderCapability {
+  contextWindow: number;
+  maxOutput: number;
+  supportsReasoning: boolean;
+  supportsStreaming: boolean;
+  supportsToolUse: boolean;
+  supportsVision: boolean;
+  /** Provider supports Anthropic‑style cache_control or DeepSeek implicit prefix cache. */
+  promptCacheEnabled: boolean;
+}
+/**
+ * Every LLM provider (DeepSeek, OpenAI, etc.) implements this interface.
+ *
+ * The factory pattern is used instead of a class so the provider can be
+ * constructed without DI and tested with a mock.
+ */
+interface LlmProvider {
+  /** Unique provider id, e.g. "deepseek". */
+  readonly id: string;
+  /** List models this provider currently serves. */
+  listModels(): ModelInfo[];
+  /**
+   * Return the static capability blob for a model.
+   * Throws {@link import('@lynx/core').LlmError} if the model is unknown.
+   */
+  getCapability(modelId: string): ProviderCapability;
+  /**
+   * Stream completions from the provider.
+   *
+   * `messages` is an array of chat messages with roles and content blocks.
+   * `systemPrompt` is an optional system-level instruction prepended as
+   * a system message before `messages`. If empty, no system message is added.
+   *
+   * The returned AsyncGenerator yields {@link StreamEvent} values.
+   * The consumer drives iteration; when the consumer stops iterating
+   * the underlying HTTP request is aborted via the signal.
+   */
+  stream(modelId: string, messages: ChatMessage[], systemPrompt: string, tools: unknown[], signal: AbortSignal): AsyncGenerator<StreamEvent, void, void>;
+}
+/**
+ * Discriminated union of every event the LLM stream can emit.
+ *
+ * The consumer pattern‑matches on `type`:
+ * ```ts
+ * for await (const ev of provider.stream(...)) {
+ *   switch (ev.type) {
+ *     case 'text_delta': ...; break;
+ *     case 'tool_use': ...; break;
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+type StreamEvent = TextDeltaEvent | ReasoningDeltaEvent | ToolUseStartEvent | ToolUseDeltaEvent | ToolUseEndEvent | ToolResultEvent | ToolRecapEvent | ErrorEvent | DoneEvent;
+/** Incremental text chunk from the assistant. */
+interface TextDeltaEvent {
+  type: "text_delta";
+  /** Monotonically increasing index for this chunk. */
+  index: number;
+  /** The text fragment (may be an empty string for flush frames). */
+  text: string;
+}
+/** Reasoning / thinking token chunk (DeepSeek R1, o1, etc.). */
+interface ReasoningDeltaEvent {
+  type: "reasoning_delta";
+  index: number;
+  text: string;
+}
+/** A new tool_use block has started in the response. */
+interface ToolUseStartEvent {
+  type: "tool_use_start";
+  /** Unique call id generated by the provider. */
+  callId: string;
+  /** Tool name as registered in the tool catalog. */
+  name: string;
+}
+/** Incremental JSON fragment for the current tool_use block. */
+interface ToolUseDeltaEvent {
+  type: "tool_use_delta";
+  callId: string;
+  /** Partial JSON text. Concatenate to form the complete input. */
+  text: string;
+}
+/** The current tool_use block is complete. */
+interface ToolUseEndEvent {
+  type: "tool_use_end";
+  callId: string;
+  /** Parsed input object (provider‑side consolidation). */
+  input: Record<string, unknown>;
+}
+/** A tool_result block being fed back into the conversation. */
+interface ToolResultEvent {
+  type: "tool_result";
+  toolUseId: string;
+  content: string;
+  isError: boolean;
+}
+/** A non‑fatal stream error (e.g. a single turn failed but the session continues). */
+interface ErrorEvent {
+  type: "error";
+  code: string;
+  message: string;
+}
+/** Tool execution batch summary — generated locally after tools finish. */
+interface ToolRecapEvent {
+  type: "tool_recap";
+  /** Human-readable summary of completed tools (Chinese). */
+  summary: string;
+  /** Number of tools executed in this batch. */
+  toolCount: number;
+  /** Wall‑clock duration of the tool batch in ms. */
+  durationMs: number;
+}
+/** The stream completed successfully. */
+interface DoneEvent {
+  type: "done";
+  /** Total tokens consumed by this request (input + output). */
+  totalTokens?: number;
+}
+//#endregion
+//#region src/stream.d.ts
+/**
+ * Stream\<T\> — pull‑based AsyncIterator backed by an internal queue.
+ *
+ * Producers call `enqueue()` / `done()` / `error()`.
+ * Consumers use `for await … of`.
+ *
+ * This is deliberately a class (not EventEmitter) so the consumer
+ * controls back‑pressure — when nobody is iterating, values stay in
+ * the queue until `maxQueueSize` is reached.
+ */
+/**
+ * A cold, single‑consumer async iterator.
+ *
+ * ```ts
+ * const stream = new Stream<string>();
+ * producer(stream);
+ * for await (const chunk of stream) {
+ *   console.log(chunk);
+ * }
+ * ```
+ */
+declare class Stream<T> implements AsyncIterator<T>, AsyncIterable<T> {
+  private _queue;
+  private _resolvers;
+  private _done;
+  private _error;
+  private readonly _maxQueue;
+  constructor(maxQueueSize?: number);
+  /** Push a value into the stream. */
+  enqueue(value: T): void;
+  /** Signal that the stream has finished normally. */
+  done(): void;
+  /** Propagate an error to the consumer. */
+  error(err: Error): void;
+  [Symbol.asyncIterator](): AsyncIterator<T>;
+  next(): Promise<IteratorResult<T>>;
+}
+//#endregion
+//#region src/retry.d.ts
+/**
+ * withRetry — exponential backoff with jitter and Retry‑After respect.
+ *
+ * Used by every LLM provider for transient errors (429, 529, ECONNRESET, etc.).
+ *
+ * Algorithm:
+ *   delay = min(baseMs * 2^(attempt-1), maxMs)
+ *   jitter = delay * uniform(0.75, 1.25)
+ *   final  = min(jitter, maxMs)
+ */
+interface RetryOptions {
+  /** Base delay for the first retry (default 500ms). */
+  baseMs?: number;
+  /** Hard ceiling on delay (default 32s). */
+  maxMs?: number;
+  /** Maximum number of retries before giving up (default 10). */
+  maxRetries?: number;
+  /** Function that returns true if this error is retryable. */
+  isRetryable?: (err: Error) => boolean;
+  /**
+   * Whether this request is in the foreground (user-facing).
+   * Foreground requests retry on 529; background requests discard
+   * immediately to prevent cascade amplification. Defaults to true.
+   */
+  isForeground?: boolean;
+}
+/**
+ * Execute `fn` with exponential backoff.
+ *
+ * Only retries on transient errors. Non‑retryable errors are re‑thrown
+ * immediately.
+ *
+ * ```ts
+ * const result = await withRetry(() => fetchFromApi(), {
+ *   baseMs: 500,
+ *   maxMs: 32_000,
+ * });
+ * ```
+ */
+declare function withRetry<T>(fn: () => Promise<T>, opts?: RetryOptions): Promise<T>;
+//#endregion
+//#region src/capabilities.d.ts
+/**
+ * Return the capability blob for `provider/modelId`.
+ * Returns `undefined` for unknown models — callers should fall back
+ * or throw a {@link import('@lynx/core').ConfigError}.
+ */
+declare function getCapability(providerId: string, modelId: string): ProviderCapability | undefined;
+/**
+ * Return every known capability entry.
+ * Used by the model picker UI in the TUI layer.
+ */
+declare function listCapabilities(): Array<{
+  key: string;
+} & ProviderCapability>;
+//#endregion
+//#region src/fallback.d.ts
+/**
+ * Model/Provider fallback logic.
+ *
+ * When a provider returns a transient error (rate‑limit, overload) the
+ * fallback engine tries the next candidate in the configured chain.
+ * Permanent errors (auth) skip the provider entirely and move to the next.
+ *
+ * The primary use‑case is keeping the agent loop running when the
+ * preferred model is temporarily unavailable.
+ */
+/** A candidate provider+model pair in the fallback chain. */
+interface ModelCandidate {
+  provider: string;
+  model: string;
+}
+/** Record of a single fallback attempt for diagnostics. */
+interface FallbackAttempt {
+  provider: string;
+  model: string;
+  error: string;
+  code?: string;
+  /** HTTP status code if available. */
+  status?: number;
+}
+/** Result of a fallback run — which candidate succeeded and what was tried. */
+interface FallbackResult<T> {
+  result: T;
+  provider: string;
+  model: string;
+  attempts: FallbackAttempt[];
+}
+/** Error thrown when every candidate in the chain has been exhausted. */
+declare class FallbackExhaustedError extends Error {
+  readonly attempts: FallbackAttempt[];
+  constructor(attempts: FallbackAttempt[]);
+}
+/**
+ * Run `fn` with automatic fallback across a chain of model candidates.
+ *
+ * `fn` is called with (provider, model) and should return a result.
+ * If `fn` throws, the error is classified — transient errors move to the
+ * next candidate, permanent errors skip the provider, and fatal errors
+ * (like user abort) are re‑thrown immediately.
+ */
+declare function runWithFallback<T>(candidates: ModelCandidate[], fn: (candidate: ModelCandidate) => Promise<T>, opts?: {
+  signal?: AbortSignal;
+}): Promise<FallbackResult<T>>;
+/**
+ * Build a fallback chain from a primary model and a list of fallback refs.
+ *
+ * Fallback refs use the format `"provider/model"` (e.g. `"openai/gpt-4o-mini"`).
+ * If the provider prefix is omitted the primary's provider is used.
+ */
+declare function buildCandidateChain(primaryProvider: string, primaryModel: string, fallbackRefs: string[]): ModelCandidate[];
+//#endregion
+//#region src/providers/deepseek.d.ts
+interface DeepSeekConfig {
+  /** API key read from auth store. */
+  apiKey: string;
+  /** Base URL (defaults to https://api.deepseek.com). */
+  baseUrl?: string;
+  /** Request timeout in ms (default 120s). */
+  timeoutMs?: number;
+}
+/**
+ * Create a DeepSeek provider instance.
+ *
+ * Each call to `stream()` opens a fresh HTTP connection.
+ * The provider itself is stateless — the API key is the only configuration.
+ */
+declare function createDeepSeekProvider(config: DeepSeekConfig): LlmProvider;
+//#endregion
+//#region src/providers/openai.d.ts
+interface OpenAiConfig {
+  apiKey: string;
+  baseUrl?: string;
+  timeoutMs?: number;
+}
+/**
+ * Create an OpenAI provider instance.
+ *
+ * Same SSE parsing logic as DeepSeek — both follow the same wire protocol.
+ * The only differences are the base URL, models, and capability metadata.
+ */
+declare function createOpenAiProvider(config: OpenAiConfig): LlmProvider;
+//#endregion
+//#region src/providers/anthropic.d.ts
+interface AnthropicConfig {
+  /** API key from ANTHROPIC_API_KEY env var. */
+  apiKey: string;
+  /** Base URL (defaults to https://api.anthropic.com). */
+  baseUrl?: string;
+  /** Request timeout in ms (default 120s). */
+  timeoutMs?: number;
+}
+/**
+ * Create an Anthropic provider instance.
+ *
+ * Each call to `stream()` opens a fresh HTTP connection.
+ * The provider itself is stateless — the API key is the only configuration.
+ */
+declare function createAnthropicProvider(config: AnthropicConfig): LlmProvider;
+//#endregion
+export { type AnthropicConfig, type ChatMessage, type DeepSeekConfig, type DoneEvent, type ErrorEvent, type FallbackAttempt, FallbackExhaustedError, type FallbackResult, type LlmProvider, type ModelCandidate, type ModelInfo, type OpenAiConfig, type ProviderCapability, type ReasoningDeltaEvent, type RetryOptions, Stream, type StreamEvent, type TextDeltaEvent, type ToolResultEvent, type ToolUseDeltaEvent, type ToolUseEndEvent, type ToolUseStartEvent, buildCandidateChain, createAnthropicProvider, createDeepSeekProvider, createOpenAiProvider, getCapability, listCapabilities, runWithFallback, withRetry };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/types.ts","../src/stream.ts","../src/retry.ts","../src/capabilities.ts","../src/fallback.ts","../src/providers/deepseek.ts","../src/providers/openai.ts","../src/providers/anthropic.ts"],"mappings":"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"}