@tyvm/knowhow 0.0.159 → 0.0.161

package/src/clients/pricing/types.ts

@@ -1,125 +0,0 @@
-/**
- * A historical record of a model's pricing at a point in time.
- * Use this to track price changes over time.
- */
-export interface PricingChangelogEntry {
-  /** ISO date string when this pricing became effective (e.g. "2025-04-01") */
-  date: string;
-  /** Optional human-readable note about the change (e.g. "Promotional pricing announcement") */
-  note?: string;
-  /** The pricing values that were in effect from this date */
-  pricing: Omit<ModelPricing, "deprecated" | "deprecationDate" | "limitedAvailability" | "replacedBy" | "reasoningLevels" | "useResponsesApi" | "changelog">;
-}
-
-export type ModelType =
-  | "completion"
-  | "embedding"
-  | "image"
-  | "audio"
-  | "video"
-  | "transaction"
-  | "live";
-
-export interface ModelPricing {
-  input?: number;
-  output?: number;
-  cached_input?: number;
-  cache_write?: number;
-  cache_hit?: number;
-  input_audio?: number;
-  output_audio?: number;
-  input_gt_200k?: number;
-  output_gt_200k?: number;
-  image_generation?: number;
-  image_generation_per_1m_tokens?: number;
-  video_generation?: number;
-  output_image_per_1m_tokens?: number;
-  // Optional metadata — when set on a pricing entry, the catalog picks them up automatically
-  deprecated?: boolean;
-  deprecationDate?: string;
-  limitedAvailability?: boolean;
-  replacedBy?: string;
-  /** Supported reasoning effort levels for this model (ordered low→high). If set, effort will be clamped to these values. */
-  reasoningLevels?: string[];
-  /** If true, this model must be called via the Responses API (/v1/responses) instead of /v1/chat/completions */
-  useResponsesApi?: boolean;
-  /** Optional changelog of historical pricing entries, ordered from oldest to newest */
-  changelog?: PricingChangelogEntry[];
-}
-
-export interface ModelCatalogEntry {
-  id: string;
-  provider: string;
-  type: ModelType;
-  pricing: ModelPricing;
-  deprecated?: boolean;
-  deprecationDate?: string;
-  /** Model exists but is not generally available (e.g. Live API only, limited access, or returns empty responses) */
-  limitedAvailability?: boolean;
-  /** Recommended replacement model ID when this model is deprecated */
-  replacedBy?: string;
-}
-
-// ─── Bulk catalog helpers ─────────────────────────────────────────────────────
-
-export interface DeprecationOptions {
-  deprecated?: boolean;
-  deprecationDate?: string;
-  limitedAvailability?: boolean;
-  replacedBy?: string;
-}
-
-function makeEntries(
-  type: ModelType,
-  ids: string[],
-  provider: string,
-  pricing: Record<string, ModelPricing>,
-  deprecation?: DeprecationOptions
-): ModelCatalogEntry[] {
-  return ids.map((id) => {
-    const p = pricing[id] ?? {};
-    // Explicit dep options take precedence; fall back to metadata embedded in the pricing entry
-    const deprecated       = deprecation?.deprecated       ?? p.deprecated;
-    const deprecationDate  = deprecation?.deprecationDate  ?? p.deprecationDate;
-    const limitedAvailability = deprecation?.limitedAvailability ?? p.limitedAvailability;
-    const replacedBy       = deprecation?.replacedBy       ?? p.replacedBy;
-    // Strip metadata fields before storing as pricing
-    const { deprecated: _d, deprecationDate: _dd, limitedAvailability: _la, replacedBy: _rb, reasoningLevels: _rl, useResponsesApi: _ura, ...pricingOnly } = p;
-    return {
-      id,
-      provider,
-      type,
-      pricing: { input: 0, output: 0, ...pricingOnly },
-      deprecated,
-      deprecationDate,
-      limitedAvailability,
-      replacedBy,
-    };
-  });
-}
-
-export const completions  = (ids: string[], provider: string, pricing: Record<string, ModelPricing>, dep?: DeprecationOptions) => makeEntries("completion",   ids, provider, pricing, dep);
-export const embeddings   = (ids: string[], provider: string, pricing: Record<string, ModelPricing>, dep?: DeprecationOptions) => makeEntries("embedding",    ids, provider, pricing, dep);
-export const images       = (ids: string[], provider: string, pricing: Record<string, ModelPricing>, dep?: DeprecationOptions) => makeEntries("image",        ids, provider, pricing, dep);
-export const videos       = (ids: string[], provider: string, pricing: Record<string, ModelPricing>, dep?: DeprecationOptions) => makeEntries("video",        ids, provider, pricing, dep);
-export const audios       = (ids: string[], provider: string, pricing: Record<string, ModelPricing>, dep?: DeprecationOptions) => makeEntries("audio",        ids, provider, pricing, dep);
-export const transactions = (ids: string[], provider: string, pricing: Record<string, ModelPricing>, dep?: DeprecationOptions) => makeEntries("transaction",  ids, provider, pricing, dep);
-export const liveApi      = (ids: string[], provider: string, pricing: Record<string, ModelPricing>, dep?: DeprecationOptions) => makeEntries("live",         ids, provider, pricing, dep);
-
-// ─── Single-entry helpers (for deprecated/special cases) ─────────────────────
-
-export function completion(
-  id: string,
-  provider: string,
-  pricing: Partial<ModelPricing> = {},
-  deprecation?: DeprecationOptions
-): ModelCatalogEntry {
-  return {
-    id, provider, type: "completion",
-    pricing: { input: 0, output: 0, ...pricing },
-    deprecated: deprecation?.deprecated,
-    deprecationDate: deprecation?.deprecationDate,
-    limitedAvailability: deprecation?.limitedAvailability,
-    replacedBy: deprecation?.replacedBy,
-  };
-}

package/src/clients/pricing/xai.ts

@@ -1,137 +0,0 @@
-/**
- * xAI model IDs, pricing, and catalog.
- * Single source of truth for all xAI/Grok models.
- */
-import { completions, images, videos, ModelCatalogEntry, ModelPricing } from "./types";
-
-// ─── Model IDs ────────────────────────────────────────────────────────────────
-
-export const XaiModels = {
-  Grok4_6: "grok-4.6",
-  Grok_4_20_Reasoning: "grok-4.20-0309-reasoning",
-  Grok_4_20_NonReasoning: "grok-4.20-0309-non-reasoning",
-  Grok_4_20_MultiAgent: "grok-4.20-multi-agent-0309",
-  Grok4_5: "grok-4.5",
-  Grok4_1_Fast_Reasoning: "grok-4-1-fast-reasoning",
-  Grok4_1_Fast_NonReasoning: "grok-4-1-fast-non-reasoning",
-  GrokCodeFast: "grok-code-fast-1",
-  Grok4: "grok-4-0709",
-  Grok3Beta: "grok-3-beta",
-  Grok3MiniBeta: "grok-3-mini-beta",
-  Grok3FastBeta: "grok-3-fast-beta",
-  Grok3MiniFastBeta: "grok-3-mini-fast-beta",
-  // Deprecated alias IDs used by models.dev (latest aliases and older beta names)
-  Grok2Latest: "grok-2-latest",
-  Grok2VisionLatest: "grok-2-vision-latest",
-  Grok3Latest: "grok-3-latest",
-  Grok3FastLatest: "grok-3-fast-latest",
-  Grok3MiniLatest: "grok-3-mini-latest",
-  Grok3MiniFastLatest: "grok-3-mini-fast-latest",
-  GrokBeta: "grok-beta",
-  GrokVisionBeta: "grok-vision-beta",
-  // grok-4-1-fast variants (aliases for grok-4-1-fast-reasoning/non-reasoning)
-  Grok4_1_Fast: "grok-4-1-fast",
-  Grok4Fast: "grok-4-fast",
-  Grok4FastNonReasoning: "grok-4-fast-non-reasoning",
-  Grok21212: "grok-2-1212",
-  Grok2Vision1212: "grok-2-vision-1212",
-  GrokImagineImage: "grok-imagine-image",
-  GrokImagineVideo: "grok-imagine-video",
-  Grok2Image1212: "grok-2-image-1212",
-} as const;
-
-// ─── Modality arrays ──────────────────────────────────────────────────────────
-
-export const XaiTextModels: string[] = [
-  XaiModels.Grok4_6,
-  XaiModels.Grok_4_20_Reasoning, XaiModels.Grok_4_20_NonReasoning,
-  XaiModels.Grok_4_20_MultiAgent,
-  XaiModels.Grok4_1_Fast_Reasoning, XaiModels.Grok4_1_Fast_NonReasoning,
-  XaiModels.Grok4_5,
-  XaiModels.GrokCodeFast, XaiModels.Grok4,
-  XaiModels.Grok3Beta, XaiModels.Grok3MiniBeta, XaiModels.Grok3FastBeta, XaiModels.Grok3MiniFastBeta,
-];
-
-// Models that require the Responses API (/v1/responses) instead of /v1/chat/completions
-// The xAI reasoning variants and multi-agent model use the Responses API
-export const XaiResponsesOnlyModels: string[] = [
-  XaiModels.Grok_4_20_Reasoning,
-  XaiModels.Grok_4_20_NonReasoning,
-  XaiModels.Grok_4_20_MultiAgent,
-  XaiModels.Grok4_1_Fast_Reasoning,
-  XaiModels.Grok4_1_Fast_NonReasoning,
-];
-
-// Models that support the reasoning_effort parameter
-// Grok 4.6, Grok 4.20 multi-agent, and grok-3-mini variants support reasoning_effort
-export const XaiReasoningModels: string[] = [
-  XaiModels.Grok4_6,
-  XaiModels.Grok_4_20_MultiAgent,
-  XaiModels.Grok3MiniBeta,
-  XaiModels.Grok3MiniFastBeta,
-];
-
-// Deprecated xAI models — "Model not found" (400) when called
-export const XaiDeprecatedTextModels: string[] = [
-  XaiModels.Grok21212, XaiModels.Grok2Vision1212,
-  // Alias IDs from models.dev that map to deprecated/versioned models
-  XaiModels.Grok2Latest, XaiModels.Grok2VisionLatest,
-  XaiModels.Grok3Latest, XaiModels.Grok3FastLatest,
-  XaiModels.Grok3MiniLatest, XaiModels.Grok3MiniFastLatest,
-  XaiModels.GrokBeta, XaiModels.GrokVisionBeta,
-  XaiModels.Grok4_1_Fast, XaiModels.Grok4Fast, XaiModels.Grok4FastNonReasoning,
-];
-export const XaiImageModels: string[] = [XaiModels.GrokImagineImage, XaiModels.Grok2Image1212];
-export const XaiVideoModels: string[] = [XaiModels.GrokImagineVideo];
-
-// ─── Pricing (USD per 1M tokens / per-image / per-second) ────────────────────
-
-export const XaiTextPricing: Record<string, ModelPricing> = {
-  [XaiModels.Grok4_6]:                    { input: 2.0, input_gt_200k: 4.0, cache_hit: 0.50, output: 6.0, output_gt_200k: 12.0, reasoningLevels: ["low", "medium", "high", "xhigh"] },
-  [XaiModels.Grok_4_20_Reasoning]:       { input: 2.0, cache_hit: 0.20, output: 6.0, useResponsesApi: true },
-  [XaiModels.Grok_4_20_NonReasoning]:    { input: 2.0, cache_hit: 0.20, output: 6.0, useResponsesApi: true },
-  [XaiModels.Grok_4_20_MultiAgent]:      { input: 2.0, cache_hit: 0.20, output: 6.0, reasoningLevels: ["low", "medium", "high", "xhigh"], useResponsesApi: true },
-  [XaiModels.Grok4_1_Fast_Reasoning]:    { input: 0.2, cache_hit: 0.05, output: 0.5, useResponsesApi: true },
-  [XaiModels.Grok4_1_Fast_NonReasoning]: { input: 0.2, cache_hit: 0.05, output: 0.5, useResponsesApi: true },
-  [XaiModels.Grok4_5]:                   { input: 2.0, cache_hit: 0.50, output: 6.0 },
-  [XaiModels.GrokCodeFast]:              { input: 0.2, cache_hit: 0.02, output: 1.5 },
-  [XaiModels.Grok4]:                     { input: 3.0, output: 15.0 },
-  [XaiModels.Grok3Beta]:                 { input: 3.0, output: 15.0 },
-  [XaiModels.Grok3MiniBeta]:             { input: 0.3, output: 0.5 },
-  [XaiModels.Grok3FastBeta]:             { input: 5.0, output: 25.0 },
-  [XaiModels.Grok3MiniFastBeta]:         { input: 0.6, output: 4.0 },
-  [XaiModels.Grok21212]:       { input: 2.0, output: 10.0, deprecated: true },
-  [XaiModels.Grok2Vision1212]: { input: 2.0, output: 10.0, deprecated: true },
-  // Deprecated alias IDs (models.dev uses these; they map to versioned/beta models above)
-  [XaiModels.Grok2Latest]:          { input: 2.0, output: 10.0, deprecated: true },
-  [XaiModels.Grok2VisionLatest]:    { input: 2.0, output: 10.0, deprecated: true },
-  [XaiModels.Grok3Latest]:          { input: 3.0, output: 15.0, deprecated: true },
-  [XaiModels.Grok3FastLatest]:      { input: 5.0, output: 25.0, deprecated: true },
-  [XaiModels.Grok3MiniLatest]:      { input: 0.3, output: 0.5,  deprecated: true },
-  [XaiModels.Grok3MiniFastLatest]:  { input: 0.6, output: 4.0,  deprecated: true },
-  [XaiModels.GrokBeta]:             { input: 5.0, output: 15.0, deprecated: true },
-  [XaiModels.GrokVisionBeta]:       { input: 5.0, output: 15.0, deprecated: true },
-  // grok-4-1-fast / grok-4-fast aliases — deprecated in favor of versioned reasoning/non-reasoning variants
-  [XaiModels.Grok4_1_Fast]:         { input: 0.2, output: 0.5, deprecated: true },
-  [XaiModels.Grok4Fast]:            { input: 0.2, output: 0.5, deprecated: true },
-  [XaiModels.Grok4FastNonReasoning]:{ input: 0.2, output: 0.5, deprecated: true },
-};
-
-export const XaiImagePricing: Record<string, ModelPricing> = {
-  "grok-imagine-image-pro":        { image_generation: 0.07 },
-  [XaiModels.GrokImagineImage]:    { image_generation: 0.02 },
-  [XaiModels.Grok2Image1212]:      { image_generation: 0.07 },
-};
-
-export const XaiVideoPricing: Record<string, ModelPricing> = {
-  [XaiModels.GrokImagineVideo]: { video_generation: 0.05 },
-};
-
-// ─── Catalog ──────────────────────────────────────────────────────────────────
-// Metadata (deprecated, useResponsesApi) is read directly from XaiTextPricing entries.
-
-export const XAI_MODEL_CATALOG: ModelCatalogEntry[] = [
-  ...completions([...XaiTextModels, ...XaiDeprecatedTextModels], "xai", XaiTextPricing),
-  ...images(XaiImageModels, "xai", XaiImagePricing),
-  ...videos(XaiVideoModels, "xai", XaiVideoPricing),
-];

package/src/clients/qwen.ts

@@ -1,16 +0,0 @@
-import { HttpClient } from "./http";
-import { QwenTextPricing } from "./pricing/qwen";
-
-/**
- * QWEN Cloud client — OpenAI-compatible API
- * https://dashscope-intl.aliyuncs.com/compatible-mode/v1
- * Alibaba Cloud's Qwen model family via the international DashScope endpoint.
- * Set env var QWEN_CLOUD_API_KEY to enable.
- */
-export class GenericQwenClient extends HttpClient {
-  constructor(apiKey = process.env.QWEN_CLOUD_API_KEY) {
-    super("https://dashscope-intl.aliyuncs.com/compatible-mode/v1");
-    if (apiKey) this.setJwt(apiKey);
-    this.setPrices(QwenTextPricing);
-  }
-}

package/src/clients/responseMetadata.ts

@@ -1,221 +0,0 @@
-import {
-  ProviderRateLimitMetadata,
-  ProviderResponseMetadata,
-  RetryOptions,
-} from "./types";
-
-const MAX_HEADER_VALUE_LENGTH = 256;
-const MAX_HEADERS = 24;
-const MAX_TOTAL_HEADER_CHARS = 4096;
-const SAFE_HEADER_NAMES = new Set([
-  "retry-after",
-  "ratelimit-limit",
-  "ratelimit-remaining",
-  "ratelimit-reset",
-  "request-id",
-  "x-request-id",
-  "cf-ray",
-  "x-amzn-requestid",
-  "x-amz-request-id",
-]);
-const SAFE_HEADER_PREFIXES = ["x-ratelimit-", "anthropic-ratelimit-"];
-
-type HeaderSource =
-  | Headers
-  | Record<string, unknown>
-  | Iterable<[string, unknown]>
-  | undefined;
-
-function isSafeHeader(name: string) {
-  return (
-    SAFE_HEADER_NAMES.has(name) ||
-    SAFE_HEADER_PREFIXES.some((prefix) => name.startsWith(prefix))
-  );
-}
-
-function entriesFor(headers: HeaderSource): Iterable<[string, unknown]> {
-  if (!headers) return [];
-  if (Symbol.iterator in Object(headers)) {
-    return headers as Iterable<[string, unknown]>;
-  }
-  if (typeof (headers as Headers).forEach === "function") {
-    const entries: Array<[string, unknown]> = [];
-    (headers as Headers).forEach((value, name) => entries.push([name, value]));
-    return entries;
-  }
-  return Object.entries(headers as Record<string, unknown>);
-}
-
-function nonNegativeNumber(value: string | undefined) {
-  if (value === undefined || value.trim() === "") return undefined;
-  const number = Number(value);
-  return Number.isFinite(number) && number >= 0 ? number : undefined;
-}
-
-function resetAt(value: string | undefined, now: Date) {
-  if (!value) return undefined;
-  const seconds = nonNegativeNumber(value);
-  if (seconds !== undefined)
-    return new Date(now.getTime() + seconds * 1000).toISOString();
-
-  // OpenAI-compatible APIs commonly return compact durations such as `6m0s`.
-  const duration = [...value.trim().matchAll(/(\d+(?:\.\d+)?)(ms|s|m|h|d)/gi)];
-  if (
-    duration.length &&
-    duration.map((part) => part[0]).join("") === value.trim()
-  ) {
-    const milliseconds = duration.reduce((total, [, amount, unit]) => {
-      const multiplier = {
-        ms: 1,
-        s: 1_000,
-        m: 60_000,
-        h: 3_600_000,
-        d: 86_400_000,
-      }[unit.toLowerCase()];
-      return total + Number(amount) * multiplier;
-    }, 0);
-    return new Date(now.getTime() + milliseconds).toISOString();
-  }
-
-  const timestamp = Date.parse(value);
-  return Number.isNaN(timestamp)
-    ? undefined
-    : new Date(timestamp).toISOString();
-}
-
-function retryAfterSeconds(value: string | undefined, now: Date) {
-  const seconds = nonNegativeNumber(value);
-  if (seconds !== undefined) return seconds;
-  if (!value) return undefined;
-  const timestamp = Date.parse(value);
-  return Number.isNaN(timestamp)
-    ? undefined
-    : Math.max(0, (timestamp - now.getTime()) / 1000);
-}
-
-/**
- * Derives one JSON-safe shape from standard, OpenAI-compatible, and Anthropic
- * rate-limit headers. Callers receive this even when a provider supplied none.
- */
-export function normalizeRateLimitMetadata(
-  headers: Record<string, string>,
-  now = new Date()
-): ProviderRateLimitMetadata {
-  const header = (...names: string[]) =>
-    names.map((name) => headers[name]).find((value) => value !== undefined);
-  const limit = nonNegativeNumber(
-    header(
-      "anthropic-ratelimit-requests-limit",
-      "ratelimit-limit",
-      "x-ratelimit-limit-requests",
-      "x-ratelimit-limit"
-    )
-  );
-  const remaining = nonNegativeNumber(
-    header(
-      "anthropic-ratelimit-requests-remaining",
-      "ratelimit-remaining",
-      "x-ratelimit-remaining-requests",
-      "x-ratelimit-remaining"
-    )
-  );
-  const requestResetAt = resetAt(
-    header(
-      "anthropic-ratelimit-requests-reset",
-      "ratelimit-reset",
-      "x-ratelimit-reset-requests",
-      "x-ratelimit-reset"
-    ),
-    now
-  );
-  const tokenLimit = nonNegativeNumber(
-    header("anthropic-ratelimit-tokens-limit", "x-ratelimit-limit-tokens")
-  );
-  const tokenRemaining = nonNegativeNumber(
-    header(
-      "anthropic-ratelimit-tokens-remaining",
-      "x-ratelimit-remaining-tokens"
-    )
-  );
-  const tokenResetAt = resetAt(
-    header("anthropic-ratelimit-tokens-reset", "x-ratelimit-reset-tokens"),
-    now
-  );
-  const retryAfter = retryAfterSeconds(header("retry-after"), now);
-  return {
-    ...(limit !== undefined && { limit }),
-    ...(remaining !== undefined && { remaining }),
-    ...(requestResetAt && { resetAt: requestResetAt }),
-    ...(retryAfter !== undefined && { retryAfterSeconds: retryAfter }),
-    ...(tokenLimit !== undefined && { tokenLimit }),
-    ...(tokenRemaining !== undefined && { tokenRemaining }),
-    ...(tokenResetAt && { tokenResetAt }),
-  };
-}
-
-/**
- * Converts provider headers to the deliberately small telemetry-safe surface.
- * This function never returns request bodies, credentials, cookies, or arbitrary
- * provider headers.
- */
-export function normalizeResponseMetadata(input: {
-  statusCode?: number;
-  headers?: HeaderSource;
-  requestId?: string | null;
-  observedAt?: Date;
-}): ProviderResponseMetadata {
-  const headers: Record<string, string> = {};
-  let totalChars = 0;
-
-  for (const [rawName, rawValue] of entriesFor(input.headers)) {
-    const name = String(rawName).toLowerCase();
-    if (
-      !isSafeHeader(name) ||
-      Object.prototype.hasOwnProperty.call(headers, name)
-    )
-      continue;
-    const value = String(rawValue).slice(0, MAX_HEADER_VALUE_LENGTH);
-    if (
-      Object.keys(headers).length >= MAX_HEADERS ||
-      totalChars + name.length + value.length > MAX_TOTAL_HEADER_CHARS
-    )
-      break;
-    headers[name] = value;
-    totalChars += name.length + value.length;
-  }
-
-  const requestId =
-    input.requestId ??
-    headers["request-id"] ??
-    headers["x-request-id"] ??
-    headers["x-amzn-requestid"] ??
-    headers["x-amz-request-id"];
-  return {
-    ...(typeof input.statusCode === "number" && {
-      statusCode: input.statusCode,
-    }),
-    rateLimit: normalizeRateLimitMetadata(headers, input.observedAt),
-    ...(Object.keys(headers).length > 0 && { headers }),
-    ...(requestId && {
-      requestId: String(requestId).slice(0, MAX_HEADER_VALUE_LENGTH),
-    }),
-  };
-}
-
-/** Emits one visible HTTP response synchronously and isolates observer failures. */
-export function emitResponseMetadata(
-  options: Pick<RetryOptions, "onResponseMetadata"> | undefined,
-  input: {
-    statusCode?: number;
-    headers?: HeaderSource;
-    requestId?: string | null;
-  }
-) {
-  const observer = options?.onResponseMetadata;
-  if (!observer) return;
-  try {
-    observer(normalizeResponseMetadata(input));
-  } catch {
-    // Observability must never affect a provider request or its original error.
-  }
-}