@tyvm/knowhow 0.0.159 → 0.0.161

package/src/clients/types.ts

@@ -1,531 +0,0 @@
-export type ModelModality =
-  | "completion"
-  | "embedding"
-  | "image"
-  | "audio"
-  | "video"
-  | "transcription";
-
-export type MessageContent =
-  | { type: "text"; text: string }
-  | {
-      type: "image_url";
-      image_url: { url: string; detail?: "auto" | "low" | "high" };
-    }
-  | { type: "audio_url"; audio_url: { url: string } }
-  | { type: "video_url"; video_url: { url: string } };
-
-export interface Message {
-  role: "system" | "user" | "assistant" | "tool";
-  content?: string | MessageContent[] | null;
-
-  name?: string;
-  tool_call_id?: string;
-  tool_calls?: ToolCall[];
-}
-
-export interface OutputMessage extends Message {
-  content?: string | null;
-  /**
-   * The model's reasoning/thinking content, when the provider exposes it.
-   * - OpenAI Responses API: a human-readable summary of the model's reasoning
-   *   (populated when reasoning_summary is requested).
-   */
-  reasoning_summary?: string;
-  /**
-   * OpenAI Responses API only (internal): the raw reasoning output items
-   * (carrying encrypted_content) captured from a stateless response. These are
-   * re-injected into the next request's input to preserve the reasoning chain.
-   * Not intended for display.
-   *
-   * @deprecated Prefer the provider-agnostic `_reasoning_details` slot. This is
-   * retained for backward compatibility with the OpenAI client only.
-   */
-  _reasoning_items?: any[];
-  /**
-   * Provider-agnostic (internal): an opaque, provider-tagged carrier for the
-   * model's reasoning artifact that must be round-tripped verbatim on the next
-   * tool-use turn to preserve reasoning continuity. Each provider stashes its
-   * own native artifact here and re-injects it only when the `provider` tag
-   * matches, so provider-specific payload never leaks into the generic
-   * (OpenAI-format) message shape.
-   *
-   *  - openai / xai: Responses API `reasoning` output items (encrypted_content)
-   *  - anthropic:    `thinking` / `redacted_thinking` blocks (with signature/data)
-   *  - gemini:       `thoughtSignature` strings keyed by tool-call id (+ thought parts)
-   *
-   * Not intended for display.
-   */
-  _reasoning_details?: ReasoningDetails;
-}
-
-/**
- * Opaque, provider-tagged reasoning artifact. The `items` are provider-native
- * and only meaningful to the client whose id matches `provider`; any other
- * client must ignore them (they are never mapped into a foreign provider's
- * request payload).
- */
-export interface ReasoningDetails {
-  /** The provider that produced these items, e.g. "openai" | "xai" | "anthropic" | "gemini". */
-  provider: string;
-  /** Provider-native reasoning items to round-trip verbatim on the next turn. */
-  items: any[];
-}
-
-export interface ToolProp {
-  type?: string;
-  description?: string;
-  properties?: { [key: string]: ToolProp };
-  items?: ToolProp;
-  enum?: any[];
-}
-
-export interface Tool {
-  type: "function";
-  function: {
-    name: string;
-    description?: string;
-    parameters: {
-      type: string;
-      positional?: boolean;
-      /**
-       * When true, this tool is a local/in-memory (functional) tool that needs
-       * the per-call agent context. ToolsService will inject `_ctx` into the
-       * invocation (last positional arg for positional tools, or the `_ctx` key
-       * for non-positional tools). Tools that don't set this (e.g. MCP tools,
-       * which are serialized over the wire) never receive `_ctx`.
-       */
-      usesContext?: boolean;
-      properties: {
-        [key: string]: ToolProp;
-      };
-      required?: string[];
-    };
-  };
-}
-
-/**
- * Provider-neutral rate-limit information derived from response headers.
- * Reset values are ISO-8601 strings so callback payloads remain JSON-safe.
- */
-export interface ProviderRateLimitMetadata {
-  limit?: number;
-  remaining?: number;
-  resetAt?: string;
-  retryAfterSeconds?: number;
-  tokenLimit?: number;
-  tokenRemaining?: number;
-  tokenResetAt?: string;
-}
-
-/**
- * Safe telemetry details for one provider response. `rateLimit` is normalized
- * by the client for every observed response. `headers`, when present, contains
- * only the bounded allowlisted raw headers used to derive it.
- */
-export interface ProviderResponseMetadata {
-  statusCode?: number;
-  rateLimit: ProviderRateLimitMetadata;
-  headers?: Record<string, string>;
-  requestId?: string;
-}
-
-export type ProviderResponseMetadataObserver = (
-  metadata: ProviderResponseMetadata
-) => void;
-
-export interface ToolCall {
-  id: string;
-  type: "function";
-  function: {
-    name: string;
-    arguments: string;
-  };
-}
-
-export interface RetryOptions {
-  /**
-   * Request timeout in milliseconds per attempt. If the request does not complete
-   * within this time it is aborted and retried according to maxRetries.
-   */
-  timeout?: number;
-  /**
-   * Maximum number of retry attempts for retriable errors (5xx, timeout, ECONNRESET, 429).
-   * Default: 2. Set to 0 to disable retries.
-   */
-  maxRetries?: number;
-  /**
-   * Base backoff delay in milliseconds for exponential retry backoff.
-   * Default: 1000ms. Each retry waits backoffMs * 2^attempt ms.
-   */
-  backoffMs?: number;
-  /**
-   * Optional external AbortSignal. When the signal is aborted the current
-   * attempt is cancelled immediately and no further retries are made.
-   */
-  signal?: AbortSignal;
-  /**
-   * Synchronous observer invoked once for each provider HTTP response visible to
-   * this client, including errors and streaming handshakes.
-   */
-  onResponseMetadata?: ProviderResponseMetadataObserver;
-}
-
-/**
- * Every reasoning-effort spelling currently exposed by a supported provider.
- * Individual models may support only a subset; provider clients are responsible
- * for translating or clamping values where their APIs require it.
- */
-export const REASONING_EFFORTS = [
-  "none",
-  "minimal",
-  "low",
-  "medium",
-  "high",
-  "xhigh",
-  "max",
-] as const;
-export type ReasoningEffort = typeof REASONING_EFFORTS[number];
-
-export function isReasoningEffort(value: unknown): value is ReasoningEffort {
-  return (
-    typeof value === "string" &&
-    REASONING_EFFORTS.includes(value as ReasoningEffort)
-  );
-}
-
-export interface CompletionOptions extends RetryOptions {
-  model: string;
-  messages: Message[];
-  tools?: Tool[];
-  tool_choice?: "auto" | "none";
-  max_tokens?: number;
-  /**
-   * Reasoning effort level for models that support it.
-   * Maps to: OpenAI reasoning_effort/reasoning.effort, xAI reasoning.effort,
-   *          Gemini thinkingLevel/thinkingBudget, Anthropic thinking mode.
-   *
-   * "none"    = disable thinking where supported
-   * "minimal" = provider-defined minimum (for example Gemini/OpenAI)
-   * "low"     = low reasoning
-   * "medium"  = balanced reasoning
-   * "high"    = high reasoning
-   * "xhigh"   = extra-high reasoning (for example OpenAI/xAI/Anthropic)
-   * "max"     = maximum reasoning (Anthropic)
-   *
-   * A model may support only a subset of these provider-level values.
-   */
-  reasoning_effort?: ReasoningEffort;
-  /**
-   * When true, request a summarized view of the model's thinking process.
-   * - Anthropic: thinking.display = "summarized"
-   * - OpenAI:    reasoning.summary = "auto"
-   * Defaults to false (no summary displayed).
-   */
-  reasoning_summary?: boolean;
-  /**
-   * OpenAI Responses API only: when true, OpenAI stores the response server-side
-   * so subsequent turns can reference it via `previous_response_id` instead of
-   * resending the full reasoning/message history. Defaults to false (stateless).
-   * When false, the client automatically requests `reasoning.encrypted_content`
-   * and threads the reasoning items back in the next request's input.
-   */
-  store?: boolean;
-  /**
-   * OpenAI Responses API only: the id of a previously-stored response to continue
-   * from. Only meaningful when `store` was true on the prior request. When set,
-   * the model keeps its prior chain-of-thought instead of re-deriving it.
-   */
-  previous_response_id?: string;
-  /**
-   * When true, hints to the client that this task is long-running and it should
-   * use a long-TTL cache where available.
-   * - Anthropic: enables the `extended-cache-ttl-2025-02-19` beta and sets
-   *   `cache_control.ttl` to 3600 (1 hour) instead of the default 5-minute ephemeral cache.
-   */
-  long_ttl_cache?: boolean;
-}
-
-/**
- * Normalised token-usage shape that every client must return.
- * All clients must map their provider-specific field names into this structure
- * so that base.ts can accurately track input/output and cache utilization.
- */
-export interface TokenUsage {
-  /** Total input/prompt tokens consumed */
-  prompt_tokens: number;
-  /** Total output/completion tokens generated */
-  completion_tokens: number;
-  /** Alternative field name for input tokens (some providers use this) */
-  input_tokens?: number;
-  /** Alternative field name for output tokens (some providers use this) */
-  output_tokens?: number;
-  /** Convenience total (prompt + completion) */
-  total_tokens?: number;
-  /** Breakdown of output tokens — thinking/reasoning tokens are billed as output
-   *  but should NOT be counted toward the visible-content heuristics. */
-  output_tokens_details?: {
-    /** Anthropic: thinking_tokens, OpenAI: reasoning_tokens */
-    thinking_tokens?: number;
-    reasoning_tokens?: number;
-  };
-  /** Cache details */
-  prompt_tokens_details?: {
-    /** Tokens served from the prompt cache (reduces cost) */
-    cached_tokens: number;
-  };
-  /** Anthropic-style cache write tokens */
-  cache_creation_input_tokens?: number;
-  /** Anthropic-style cache read tokens (alternative field name) */
-  cache_read_input_tokens?: number;
-}
-
-export interface CompletionResponse {
-  choices: {
-    message: OutputMessage;
-  }[];
-
-  model: string;
-  usage: TokenUsage | undefined;
-  usd_cost?: number;
-  /**
-   * OpenAI Responses API only: the id of this response. When `store` was true,
-   * this can be passed as `previous_response_id` on the next request to continue
-   * the reasoning chain without resending history.
-   */
-  response_id?: string;
-}
-
-/** A single chunk yielded by a streaming completion. */
-export interface StreamChunk {
-  /** Incremental text token(s). Only present on intermediate chunks. */
-  delta?: string;
-  /** True on the final chunk (no delta, but usage/cost available). */
-  done: boolean;
-  usage?: TokenUsage;
-  usd_cost?: number;
-}
-
-export interface EmbeddingOptions extends RetryOptions {
-  input: string;
-  model?: string;
-}
-
-export interface EmbeddingResponse {
-  data: {
-    object: string;
-    embedding: number[];
-    index: number;
-  }[];
-  model: string;
-  usage: {
-    prompt_tokens: number;
-    total_tokens: number;
-  };
-  usd_cost?: number;
-}
-
-export interface AudioTranscriptionOptions extends RetryOptions {
-  file: Blob | File | any; // Support for Node.js ReadStream or web File/Blob
-  model?: string;
-  language?: string;
-  prompt?: string;
-  response_format?: "json" | "text" | "srt" | "verbose_json" | "vtt";
-  temperature?: number;
-  /** Optional file name hint used when constructing multipart form data */
-  fileName?: string;
-}
-
-export interface AudioTranscriptionResponse {
-  text: string;
-  language?: string;
-  duration?: number;
-  segments?: {
-    id: number;
-    seek: number;
-    start: number;
-    end: number;
-    text: string;
-    tokens: number[];
-    temperature: number;
-    avg_logprob: number;
-    compression_ratio: number;
-    no_speech_prob: number;
-  }[];
-  usd_cost?: number;
-}
-
-export interface AudioGenerationOptions extends RetryOptions {
-  model: string;
-  input: string;
-  voice: string; // e.g. "alloy", "echo", "fable", "onyx", "nova", "shimmer" for OpenAI; "Kore", "Puck" etc. for Gemini
-  response_format?: "mp3" | "opus" | "aac" | "flac" | "wav" | "pcm";
-  speed?: number;
-}
-
-export interface AudioGenerationResponse {
-  audio: Buffer;
-  format: string;
-  usd_cost?: number;
-}
-
-export interface ImageGenerationOptions extends RetryOptions {
-  model: string;
-  prompt: string;
-  n?: number;
-  size?: "256x256" | "512x512" | "1024x1024" | "1792x1024" | "1024x1792";
-  quality?: "standard" | "hd";
-  style?: "vivid" | "natural";
-  response_format?: "url" | "b64_json";
-  user?: string;
-}
-
-export interface ImageGenerationResponse {
-  created: number;
-  data: {
-    url?: string;
-    b64_json?: string;
-    revised_prompt?: string;
-  }[];
-  usd_cost?: number;
-}
-
-export interface VideoGenerationOptions extends RetryOptions {
-  model: string;
-  prompt: string;
-  duration?: number; // seconds
-  resolution?: string; // e.g. "1080p", "720p"
-  aspect_ratio?: string; // e.g. "16:9", "9:16", "1:1"
-  n?: number; // number of videos to generate
-  image_url?: string; // for image-to-video (XAI)
-  video_url?: string; // for video editing (XAI)
-}
-
-export interface VideoGenerationResponse {
-  created: number;
-  data: {
-    url?: string;
-    b64_json?: string;
-    video?: Buffer;
-  }[];
-  /** Opaque provider-specific job/operation ID used for status polling */
-  jobId?: string;
-  usd_cost?: number;
-}
-
-export interface VideoStatusOptions {
-  /** The job/operation ID returned from createVideoGeneration */
-  jobId: string;
-  model?: string;
-}
-
-export interface VideoStatusResponse {
-  jobId: string;
-  /** "queued" | "in_progress" | "completed" | "failed" | "expired" */
-  status: "queued" | "in_progress" | "completed" | "failed" | "expired";
-  /** Available when status === "completed" */
-  data?: {
-    url?: string;
-    b64_json?: string;
-    /** File resource name (Google) or asset identifier (other providers) */
-    fileUri?: string;
-  }[];
-  error?: string;
-  progress?: number;
-}
-
-// ─── File API ────────────────────────────────────────────────────────────────
-
-export interface FileUploadOptions {
-  /** Raw bytes to upload */
-  data: Buffer;
-  /** MIME type of the file, e.g. "video/mp4", "image/png" */
-  mimeType: string;
-  /** Optional display name */
-  displayName?: string;
-  /** Optional file name hint (used as key / object key on some providers) */
-  fileName?: string;
-}
-
-export interface FileUploadResponse {
-  /** Opaque file identifier that can be passed to downloadFile */
-  fileId: string;
-  /** Public or signed URL (if available) */
-  url?: string;
-  /** The file's URI on the provider's storage (Google files API uri) */
-  uri?: string;
-  mimeType?: string;
-  sizeBytes?: number;
-}
-
-export interface FileDownloadOptions {
-  /** Opaque file identifier returned by uploadFile / VideoStatusResponse */
-  fileId: string;
-  /** Optional: full URI / URL if you already have it */
-  uri?: string;
-  /** Optional: local file path to save the downloaded file to directly */
-  filePath?: string;
-}
-
-export interface FileDownloadResponse {
-  data: Buffer;
-  mimeType?: string;
-}
-
-export interface GenericClient {
-  setKey(key: string): void;
-  createChatCompletion(options: CompletionOptions): Promise<CompletionResponse>;
-  /** Optional streaming variant — yields incremental tokens then a final done chunk. */
-  createChatCompletionStream?(
-    options: CompletionOptions
-  ): AsyncGenerator<StreamChunk>;
-  createEmbedding(options: EmbeddingOptions): Promise<EmbeddingResponse>;
-  createAudioTranscription?(
-    options: AudioTranscriptionOptions
-  ): Promise<AudioTranscriptionResponse>;
-  createAudioGeneration?(
-    options: AudioGenerationOptions
-  ): Promise<AudioGenerationResponse>;
-  createImageGeneration?(
-    options: ImageGenerationOptions
-  ): Promise<ImageGenerationResponse>;
-  createVideoGeneration?(
-    options: VideoGenerationOptions
-  ): Promise<VideoGenerationResponse>;
-  /** Poll or fetch the current status of a video generation job */
-  getVideoStatus?(options: VideoStatusOptions): Promise<VideoStatusResponse>;
-  /** Download the generated video as a Buffer */
-  downloadVideo?(options: FileDownloadOptions): Promise<FileDownloadResponse>;
-  /** Upload a file to the provider's file storage */
-  uploadFile?(options: FileUploadOptions): Promise<FileUploadResponse>;
-  /** Download a file from the provider's file storage */
-  downloadFile?(options: FileDownloadOptions): Promise<FileDownloadResponse>;
-  /**
-   * When modality is provided, return only models for that modality (static list).
-   * When omitted, return ALL models (backward compat — may do a live API call).
-   */
-  getModels(
-    modality?: ModelModality
-  ): Promise<{ id: string; modality?: ModelModality[] }[]>;
-  /**
-   * Returns the context window limit and compression threshold for a given model,
-   * or undefined if the model is not known to this client.
-   * - contextLimit: the maximum number of tokens the model can handle
-   * - threshold: the point at which compression should kick in; equals contextLimit
-   *   unless the model has tiered pricing (input_gt_200k), in which case it is 200_000
-   */
-  getContextLimit?(
-    model: string
-  ): { contextLimit: number; threshold: number } | undefined;
-  /**
-   * Returns the pricing entry for a specific model, or the entire pricing map if no model is given.
-   * Returns undefined for a specific model if no pricing is known.
-   * Only implemented by HttpClient-based providers that have been given a pricing map via setPrices().
-   */
-  getPricing?(
-    model?: string
-  ):
-    | import("./pricing/types").ModelPricing
-    | Record<string, import("./pricing/types").ModelPricing>
-    | undefined;
-}

package/src/clients/withRetry.ts

@@ -1,89 +0,0 @@
-/**
- * Shared retry/timeout helper for all AI clients.
- *
- * Executes `fn` with exponential backoff for retriable errors:
- * - Rate limits (429)
- * - Timeouts (AbortError, ETIMEDOUT, ECONNRESET)
- * - Server errors (5xx)
- *
- * @param fn               Function to execute. Receives a combined AbortSignal
- *                         that fires on per-attempt timeout OR external signal abort.
- * @param opts             Any object with optional RetryOptions fields (timeout, maxRetries,
- *                         backoffMs, signal). Extra fields are ignored — so you can pass the
- *                         full options object from any AI method directly.
- *                         - timeout: Per-attempt timeout in ms. No timeout if omitted.
- *                         - maxRetries: Max retry attempts after first failure. Default: 2.
- *                         - backoffMs: Base backoff delay in ms. Default: 1000.
- *                         - signal: Optional external AbortSignal. When aborted, the current
- *                         attempt is cancelled and no further retries are made.
- */
-import type { RetryOptions } from "./types";
-
-export async function withRetry<T>(
-  fn: (signal?: AbortSignal) => Promise<T>,
-  opts: RetryOptions = {}
-): Promise<T> {
-  const maxRetries = opts.maxRetries ?? 2;
-  const backoffMs = opts.backoffMs ?? 1000;
-  const timeout = opts.timeout;
-  const externalSignal = opts.signal;
-
-  for (let attempt = 0; attempt <= maxRetries; attempt++) {
-    // If the external signal is already aborted, bail out immediately.
-    if (externalSignal?.aborted) {
-      throw externalSignal.reason ?? new DOMException("Aborted", "AbortError");
-    }
-
-    let timer: ReturnType<typeof setTimeout> | undefined;
-    // Combine per-attempt timeout with the external signal into one controller.
-    const controller = timeout || externalSignal ? new AbortController() : undefined;
-
-    if (controller) {
-      if (timeout) {
-        timer = setTimeout(() => controller.abort(new DOMException("Request timed out", "TimeoutError")), timeout);
-      }
-      // Forward external signal abort into our combined controller.
-      if (externalSignal) {
-        const onExternalAbort = () => controller.abort(externalSignal.reason ?? new DOMException("Aborted", "AbortError"));
-        if (externalSignal.aborted) {
-          controller.abort(externalSignal.reason ?? new DOMException("Aborted", "AbortError"));
-        } else {
-          externalSignal.addEventListener("abort", onExternalAbort, { once: true });
-          // Clean up the listener after the attempt resolves/rejects.
-          controller.signal.addEventListener("abort", () =>
-            externalSignal.removeEventListener("abort", onExternalAbort), { once: true }
-          );
-        }
-      }
-    }
-
-    try {
-      const result = await fn(controller?.signal);
-      return result;
-    } catch (err: unknown) {
-      clearTimeout(timer);
-      // If the external signal was aborted, don't retry — propagate immediately.
-      if (externalSignal?.aborted) {
-        throw err;
-      }
-      const errStr = String(err);
-      const isRetriable =
-        errStr.includes('429') ||
-        errStr.includes('timeout') ||
-        errStr.includes('TimeoutError') ||
-        errStr.includes('ECONNRESET') ||
-        errStr.includes('ETIMEDOUT') ||
-        errStr.includes('AbortError') ||
-        /5\d\d/.test(errStr);
-      if (isRetriable && attempt < maxRetries) {
-        const delay = backoffMs * Math.pow(2, attempt);
-        await new Promise((resolve) => setTimeout(resolve, delay));
-        continue;
-      }
-      throw err;
-    } finally {
-      clearTimeout(timer);
-    }
-  }
-  throw new Error('withRetry: exhausted retries');
-}