@graphorin/provider 0.6.0 → 0.7.0

package/src/counters/index.ts

@@ -0,0 +1,35 @@
+/**
+ * Token-counter dispatcher and per-vendor strategies.
+ *
+ * @packageDocumentation
+ */
+
+export {
+  AnthropicAPICounter,
+  type AnthropicAPICounterOptions,
+} from './anthropic.js';
+export {
+  BedrockAPICounter,
+  type BedrockAPICounterOptions,
+} from './bedrock.js';
+export {
+  type CreateDefaultCounterOptions,
+  createDefaultCounter,
+} from './dispatcher.js';
+export {
+  __resetGlobalTokenCounter,
+  getGlobalTokenCounter,
+  setGlobalTokenCounter,
+} from './global.js';
+export { GoogleAPICounter, type GoogleAPICounterOptions } from './google.js';
+export { HeuristicCounter, type HeuristicCounterOptions } from './heuristic.js';
+export {
+  __resetTiktokenCache,
+  JsTiktokenCounter,
+  type JsTiktokenCounterOptions,
+} from './js-tiktoken.js';
+export {
+  type SerializedMessage,
+  serialiseMessageForCount,
+  serializedToString,
+} from './serialize.js';

package/src/counters/js-tiktoken.ts

@@ -0,0 +1,135 @@
+/**
+ * `JsTiktokenCounter` - default counter for OpenAI / OpenAI-compatible
+ * models. The package depends on the `js-tiktoken` peer; when the peer
+ * is missing, instantiation throws at first call rather than silently
+ * downgrading to a heuristic.
+ *
+ * @packageDocumentation
+ */
+
+import type { Message, TokenCounter } from '@graphorin/core';
+
+import { serialiseMessageForCount, serializedToString } from './serialize.js';
+
+/**
+ * Loose shape of a `js-tiktoken` encoding. Matches the public
+ * `Tiktoken` instance returned by `getEncoding(...)` in the upstream
+ * package (we only use `encode` / `name`).
+ *
+ * @internal
+ */
+interface TiktokenEncoding {
+  readonly name?: string;
+  encode(text: string): { length: number };
+}
+
+interface TiktokenModule {
+  getEncoding(name: string): TiktokenEncoding;
+  encodingForModel?: (model: string) => TiktokenEncoding;
+}
+
+/**
+ * Options for {@link JsTiktokenCounter}.
+ *
+ * @stable
+ */
+export interface JsTiktokenCounterOptions {
+  /** Encoding name (`'cl100k_base'`, `'o200k_base'`, …). Default `'cl100k_base'`. */
+  readonly encoding?: string;
+  /** Optional model id used by `encodingForModel`. Falls back to the explicit `encoding`. */
+  readonly modelId?: string;
+  /**
+   * Override the dynamically-loaded module. Used by tests to inject a
+   * stub without taking the real `js-tiktoken` peer dependency.
+   */
+  readonly moduleOverride?: TiktokenModule;
+  /** Identifier carried on the produced counter. */
+  readonly id?: string;
+}
+
+let cachedModule: TiktokenModule | null = null;
+
+/**
+ * Counter that delegates to the `js-tiktoken` package. Caches the
+ * dynamically-loaded module per process; tests use `moduleOverride`
+ * to supply a fixture-shaped substitute.
+ *
+ * @stable
+ */
+export class JsTiktokenCounter implements TokenCounter {
+  readonly id: string;
+  readonly version: string;
+  readonly #encoding: string;
+  readonly #modelId?: string;
+  readonly #moduleOverride?: TiktokenModule;
+  #encoder: TiktokenEncoding | null = null;
+
+  constructor(options: JsTiktokenCounterOptions = {}) {
+    this.#encoding = options.encoding ?? 'cl100k_base';
+    if (options.modelId !== undefined) this.#modelId = options.modelId;
+    if (options.moduleOverride !== undefined) this.#moduleOverride = options.moduleOverride;
+    this.id = options.id ?? `js-tiktoken@${this.#encoding}`;
+    this.version = `js-tiktoken-${this.#encoding}-v1`;
+  }
+
+  async count(messages: ReadonlyArray<Message>): Promise<number> {
+    const enc = await this.#getEncoder();
+    let total = 0;
+    for (const msg of messages) {
+      const serialised = serialiseMessageForCount(msg);
+      total += enc.encode(serializedToString(serialised)).length;
+    }
+    return total;
+  }
+
+  async countText(text: string): Promise<number> {
+    if (text.length === 0) return 0;
+    const enc = await this.#getEncoder();
+    return enc.encode(text).length;
+  }
+
+  async #getEncoder(): Promise<TiktokenEncoding> {
+    if (this.#encoder !== null) return this.#encoder;
+    const mod = this.#moduleOverride ?? (await loadTiktokenModule());
+    if (this.#modelId !== undefined && mod.encodingForModel !== undefined) {
+      try {
+        this.#encoder = mod.encodingForModel(this.#modelId);
+        return this.#encoder;
+      } catch {
+        // Fall through to the explicit encoding.
+      }
+    }
+    this.#encoder = mod.getEncoding(this.#encoding);
+    return this.#encoder;
+  }
+}
+
+async function loadTiktokenModule(): Promise<TiktokenModule> {
+  if (cachedModule !== null) return cachedModule;
+  let mod: TiktokenModule;
+  try {
+    mod = (await import('js-tiktoken')) as TiktokenModule;
+  } catch (cause) {
+    throw new Error(
+      "[graphorin/provider] JsTiktokenCounter requires the 'js-tiktoken' peer dependency. " +
+        'Install it with `pnpm add js-tiktoken` or pass moduleOverride for tests.',
+      { cause },
+    );
+  }
+  if (typeof mod.getEncoding !== 'function') {
+    throw new Error(
+      '[graphorin/provider] JsTiktokenCounter: installed js-tiktoken does not expose getEncoding().',
+    );
+  }
+  cachedModule = mod;
+  return cachedModule;
+}
+
+/**
+ * Test-only hook that resets the cached `js-tiktoken` module loader.
+ *
+ * @internal
+ */
+export function __resetTiktokenCache(): void {
+  cachedModule = null;
+}

package/src/counters/serialize.ts

@@ -0,0 +1,85 @@
+/**
+ * Canonical text-only serialization of a Graphorin `Message`. Used by
+ * counters that lack a vendor-native API (`JsTiktokenCounter`,
+ * `HeuristicCounter`).
+ *
+ * @internal
+ */
+
+import type { Message, MessageContent } from '@graphorin/core';
+
+/**
+ * Plain-text projection of a {@link Message}. The shape is what the
+ * counter actually feeds the tokenizer.
+ *
+ * @internal
+ */
+export interface SerializedMessage {
+  readonly role: string;
+  readonly text: string;
+  readonly toolCalls: ReadonlyArray<{ readonly name: string; readonly args: string }>;
+}
+
+/**
+ * Project a `Message` into a flat string suitable for tokenizers that
+ * do not understand multimodal content. Image / audio / file parts
+ * are replaced with the canonical placeholder `[image]` / `[audio]` /
+ * `[file]` so byte counts stay deterministic.
+ *
+ * @internal
+ */
+export function serialiseMessageForCount(msg: Message): SerializedMessage {
+  const role = msg.role;
+  const text = serialiseContent(msg.content);
+  const toolCalls =
+    (msg as { toolCalls?: ReadonlyArray<{ toolName: string; args: unknown }> }).toolCalls?.map(
+      (tc) => ({
+        name: tc.toolName,
+        args: typeof tc.args === 'string' ? tc.args : JSON.stringify(tc.args),
+      }),
+    ) ?? [];
+  return { role, text, toolCalls };
+}
+
+function serialiseContent(content: string | ReadonlyArray<MessageContent>): string {
+  if (typeof content === 'string') return content;
+  const buffer: string[] = [];
+  for (const part of content) {
+    switch (part.type) {
+      case 'text':
+        buffer.push(part.text);
+        break;
+      case 'image':
+        buffer.push('[image]');
+        break;
+      case 'audio':
+        buffer.push('[audio]');
+        break;
+      case 'file':
+        buffer.push(`[file:${part.mimeType}]`);
+        break;
+      case 'reasoning':
+        buffer.push(part.text);
+        break;
+      default:
+        // Unknown content variants are silently skipped to keep the
+        // counter forward-compatible.
+        break;
+    }
+  }
+  return buffer.join('\n');
+}
+
+/**
+ * Render a `SerializedMessage` as a single string with role prefix.
+ * Useful for naive estimators that count by character length.
+ *
+ * @internal
+ */
+export function serializedToString(msg: SerializedMessage): string {
+  const parts = [`[${msg.role}]`, msg.text];
+  for (const tc of msg.toolCalls) {
+    parts.push(`[tool-call:${tc.name}] ${tc.args}`);
+  }
+  return parts.join('\n');
+}

package/src/errors/errors.ts

@@ -0,0 +1,316 @@
+/**
+ * Typed error hierarchy for `@graphorin/provider`. Every error class
+ * carries a stable `kind` discriminant (lowercase, kebab-case) plus an
+ * optional `hint` string pointing the user at the recommended fix.
+ *
+ * @packageDocumentation
+ */
+
+import type { ProviderErrorKind } from '@graphorin/core';
+
+/**
+ * Base class for every error thrown by `@graphorin/provider`. Consumers
+ * narrow on the discriminant `kind` rather than `instanceof` - both
+ * work, but discriminants are subclass-friendly.
+ *
+ * @stable
+ */
+export class GraphorinProviderError extends Error {
+  override readonly name: string = 'GraphorinProviderError';
+  /** Stable discriminant - `'middleware-ordering'`, `'rate-limit-exceeded'`, … */
+  readonly kind: string;
+  /** Optional remediation hint shown alongside the message. */
+  readonly hint?: string;
+
+  constructor(kind: string, message: string, options?: { cause?: unknown; hint?: string }) {
+    super(message, options?.cause !== undefined ? { cause: options.cause } : undefined);
+    this.kind = kind;
+    if (options?.hint !== undefined) {
+      this.hint = options.hint;
+    }
+  }
+}
+
+/**
+ * The middleware composer detected an out-of-order middleware. The
+ * `offendingPair` field carries the `[outer, inner]` middleware names
+ * that violated the canonical order so consumers can surface a precise
+ * fix in IDE diagnostics.
+ *
+ * @stable
+ */
+export class MiddlewareOrderingError extends GraphorinProviderError {
+  override readonly name = 'MiddlewareOrderingError';
+  readonly offendingPair: readonly [string, string];
+  readonly canonicalOrder: readonly string[];
+
+  constructor(args: {
+    offendingPair: readonly [string, string];
+    canonicalOrder: readonly string[];
+    message?: string;
+  }) {
+    super(
+      'middleware-ordering',
+      args.message ??
+        `Middleware order violation: '${args.offendingPair[0]}' must not wrap '${args.offendingPair[1]}'. ` +
+          `Canonical order (outer → inner): ${args.canonicalOrder.join(' → ')}.`,
+      {
+        hint:
+          'Reorder the middleware array passed to composeProviderMiddleware([...]) to match the canonical order; ' +
+          'see @graphorin/provider/middleware for documentation.',
+      },
+    );
+    this.offendingPair = args.offendingPair;
+    this.canonicalOrder = args.canonicalOrder;
+  }
+}
+
+/**
+ * `withRedaction` was missing at production startup. Thrown by the
+ * production hook applied to every composed provider when
+ * `process.env.NODE_ENV === 'production'`.
+ *
+ * @stable
+ */
+export class MissingProductionMiddlewareError extends GraphorinProviderError {
+  override readonly name = 'MissingProductionMiddlewareError';
+  readonly missing: string;
+
+  constructor(missing: string) {
+    super(
+      'missing-production-middleware',
+      `Production startup hook: required middleware '${missing}' is missing from the provider chain.`,
+      {
+        hint:
+          `Compose '${missing}' as the innermost layer (closest to the underlying provider) before deploying. ` +
+          'See @graphorin/provider/middleware for the canonical composition order.',
+      },
+    );
+    this.missing = missing;
+  }
+}
+
+/**
+ * `withCostLimit` exceeded its configured ceiling. Carries the
+ * triggering scope (`session`, `agent`, `run`, …) so the caller can
+ * decide how to surface the breach.
+ *
+ * @stable
+ */
+export class CostBudgetExceededError extends GraphorinProviderError {
+  override readonly name = 'CostBudgetExceededError';
+  readonly scope: string;
+  readonly limit: number;
+  readonly observed: number;
+
+  constructor(args: { scope: string; limit: number; observed: number; currency?: string }) {
+    super(
+      'cost-budget-exceeded',
+      `Cost budget exceeded for '${args.scope}': observed ${args.observed.toFixed(4)} ${args.currency ?? 'USD'} ` +
+        `> limit ${args.limit.toFixed(4)} ${args.currency ?? 'USD'}.`,
+      {
+        hint: 'Raise the limit in withCostLimit({...}), tighten the prompt, or switch to a cheaper model tier.',
+      },
+    );
+    this.scope = args.scope;
+    this.limit = args.limit;
+    this.observed = args.observed;
+  }
+}
+
+/**
+ * `withRateLimit` exhausted its bucket and the caller did not opt
+ * into `'queue'` mode.
+ *
+ * @stable
+ */
+export class RateLimitExceededError extends GraphorinProviderError {
+  override readonly name = 'RateLimitExceededError';
+  readonly retryAfterMs: number;
+
+  constructor(retryAfterMs: number) {
+    super('rate-limit-exceeded', `Rate limit exceeded; retry after ${retryAfterMs}ms.`, {
+      hint: 'Slow down the request rate, raise the bucket size in withRateLimit({...}), or switch to mode: "queue".',
+    });
+    this.retryAfterMs = retryAfterMs;
+  }
+}
+
+/**
+ * `withRedaction` detected a hit AND the policy is configured for
+ * `failClosed: true`. The matched value is **never** part of the
+ * message - only the pattern name and field path.
+ *
+ * @stable
+ */
+export class PromptRedactionError extends GraphorinProviderError {
+  override readonly name = 'PromptRedactionError';
+  readonly patternName: string;
+  readonly fieldPath: string;
+  readonly role?: string;
+
+  constructor(args: { patternName: string; fieldPath: string; role?: string }) {
+    super(
+      'prompt-redaction-fail-closed',
+      `Outbound prompt-redaction policy is fail-closed and matched pattern '${args.patternName}' ` +
+        `at '${args.fieldPath}'${args.role ? ` (role: ${args.role})` : ''}.`,
+      {
+        hint: 'Sanitize the prompt before calling the provider, or disable failClosed in withRedaction({...}) for this environment.',
+      },
+    );
+    this.patternName = args.patternName;
+    this.fieldPath = args.fieldPath;
+    if (args.role !== undefined) this.role = args.role;
+  }
+}
+
+/**
+ * Raised when a `baseUrl`-driven local adapter is configured against
+ * a public host over plaintext HTTP. Adapters refuse to start unless
+ * `allowInsecureTransport: true` is supplied (and the override is
+ * audit-logged).
+ *
+ * @stable
+ */
+export class LocalProviderInsecureTransportError extends GraphorinProviderError {
+  override readonly name = 'LocalProviderInsecureTransportError';
+  readonly baseUrl: string;
+
+  constructor(baseUrl: string) {
+    super(
+      'local-provider-insecure-transport',
+      `Refusing to start: the provider baseUrl '${baseUrl}' is public AND plaintext (http://). ` +
+        `Switch to https:// or set allowInsecureTransport: true to acknowledge the risk.`,
+      {
+        hint:
+          'Public local-LLM endpoints must be served over TLS. Acceptable alternatives: terminate TLS in front of the model server, ' +
+          'tunnel through SSH / WireGuard / Tailscale, or pass allowInsecureTransport: true (audit-logged).',
+      },
+    );
+    this.baseUrl = baseUrl;
+  }
+}
+
+/**
+ * Legacy alias preserved for one minor; prefer
+ * {@link LocalProviderInsecureTransportError}. Removed in v0.2.
+ *
+ * @deprecated Use {@link LocalProviderInsecureTransportError} instead.
+ */
+export const OllamaInsecureTransportError = LocalProviderInsecureTransportError;
+export type OllamaInsecureTransportError = LocalProviderInsecureTransportError;
+
+/**
+ * Body phrasings used by the major providers when the request blew the
+ * model's context window. Sniffed by {@link classifyHttpStatus} so a
+ * 400 that is really a context overflow surfaces as `'context-length'`
+ * (the kind the compaction / emergency tiers key on), not a generic
+ * `'invalid-request'`.
+ */
+const CONTEXT_LENGTH_BODY_RE =
+  /context[_ -]?length|context window|prompt is too long|maximum context|too many tokens|exceeds? the (?:model'?s? )?max/i;
+
+/**
+ * Map an HTTP status (plus optional error-body text) onto the
+ * canonical `ProviderErrorKind`. One
+ * shared table so `withRetry` / `withFallback` and consumers switching
+ * on the documented kinds see consistent values from every HTTP
+ * adapter:
+ *
+ * - `429` → `'rate-limit'`
+ * - `401` / `403` → `'unauthorized'`
+ * - `400` / `404` / `422` → `'invalid-request'` (or
+ *   `'context-length'` when the body says so)
+ * - `503` / `529` → `'capacity'` (529 is Anthropic's overloaded code)
+ * - other `5xx` and `0` (network failure) → `'transient'`
+ *
+ * @stable
+ */
+export function classifyHttpStatus(status: number, bodyText?: string): ProviderErrorKind {
+  if (status === 429) return 'rate-limit';
+  if (status === 401 || status === 403) return 'unauthorized';
+  if (status === 400 || status === 404 || status === 422) {
+    if (bodyText !== undefined && CONTEXT_LENGTH_BODY_RE.test(bodyText)) return 'context-length';
+    return 'invalid-request';
+  }
+  if (status === 503 || status === 529) return 'capacity';
+  if (status >= 500 || status === 0) return 'transient';
+  return 'unknown';
+}
+
+/**
+ * Wrapped HTTP error returned by an adapter. Carries the original
+ * status code so middleware (`withRetry`, `withFallback`) can decide
+ * whether the error is retryable.
+ *
+ * @stable
+ */
+export class ProviderHttpError extends GraphorinProviderError {
+  override readonly name = 'ProviderHttpError';
+  readonly status: number;
+  readonly providerName: string;
+  /**
+   * The canonical `ProviderErrorKind` mapped from the HTTP status via
+   * {@link classifyHttpStatus} (the `kind` field keeps its stable
+   * `'provider-http'` discriminant). Middleware predicates consult
+   * this so a 429 fails over / retries as a rate limit.
+   */
+  readonly errorKind: ProviderErrorKind;
+  /**
+   * Backoff-relevant response headers captured from the failed
+   * response (`retry-after`, `x-ratelimit-*`), lowercased.
+   * `withRetry`'s Retry-After hint reader consumes them.
+   */
+  readonly headers?: Readonly<Record<string, string>>;
+
+  constructor(args: {
+    providerName: string;
+    status: number;
+    message: string;
+    cause?: unknown;
+    errorKind?: ProviderErrorKind;
+    headers?: Readonly<Record<string, string>>;
+  }) {
+    super('provider-http', `[${args.providerName}] HTTP ${args.status}: ${args.message}`, {
+      ...(args.cause !== undefined ? { cause: args.cause } : {}),
+    });
+    this.providerName = args.providerName;
+    this.status = args.status;
+    this.errorKind = args.errorKind ?? classifyHttpStatus(args.status, args.message);
+    if (args.headers !== undefined) this.headers = args.headers;
+  }
+}
+
+/**
+ * The streaming response did not match the documented wire format
+ * (e.g. malformed SSE chunk, truncated JSON).
+ *
+ * @stable
+ */
+export class ProviderStreamParseError extends GraphorinProviderError {
+  override readonly name = 'ProviderStreamParseError';
+  readonly providerName: string;
+
+  constructor(providerName: string, message: string, cause?: unknown) {
+    super('provider-stream-parse', `[${providerName}] ${message}`, {
+      ...(cause !== undefined ? { cause } : {}),
+    });
+    this.providerName = providerName;
+  }
+}
+
+/**
+ * The classifier dispatcher was given a non-Provider value. Programming
+ * error; fail-fast at the boundary.
+ *
+ * @stable
+ */
+export class InvalidProviderError extends GraphorinProviderError {
+  override readonly name = 'InvalidProviderError';
+
+  constructor(message: string) {
+    super('invalid-provider', message, {
+      hint: 'Pass the value returned by createProvider(...) (or any adapter factory) instead of a raw object.',
+    });
+  }
+}

package/src/errors/index.ts

@@ -0,0 +1,20 @@
+/**
+ * Public error surface for `@graphorin/provider`.
+ *
+ * @packageDocumentation
+ */
+
+export {
+  CostBudgetExceededError,
+  classifyHttpStatus,
+  GraphorinProviderError,
+  InvalidProviderError,
+  LocalProviderInsecureTransportError,
+  MiddlewareOrderingError,
+  MissingProductionMiddlewareError,
+  OllamaInsecureTransportError,
+  PromptRedactionError,
+  ProviderHttpError,
+  ProviderStreamParseError,
+  RateLimitExceededError,
+} from './errors.js';

package/src/index.ts

@@ -0,0 +1,42 @@
+/**
+ * @graphorin/provider - vendor-neutral LLM provider layer for the
+ * Graphorin framework.
+ *
+ * The package owns:
+ *
+ * - The `createProvider(...)` factory for wrapping adapter modules in
+ *   a stable `Provider` shape.
+ * - Four adapters out of the box: the Vercel AI SDK adapter for the
+ *   default cloud path, plus three local-LLM adapters (Ollama HTTP,
+ *   llama-server HTTP, and a generic OpenAI-compatible adapter for
+ *   LMStudio / LocalAI / vLLM / Together-style endpoints). All three
+ *   `baseUrl`-driven adapters share the same {@link LocalProviderTrust}
+ *   classifier.
+ * - The canonical-order middleware composer
+ *   ({@link composeProviderMiddleware}) and the seven built-in
+ *   middlewares (`withTracing`, `withRetry`, `withRateLimit`,
+ *   `withCostLimit`, `withCostTracking`, `withFallback`,
+ *   `withRedaction`).
+ * - The pluggable `TokenCounter` dispatcher (`createDefaultCounter`)
+ *   plus the per-vendor strategies and a heuristic fallback.
+ * - The per-provider model-tier auto-classifier
+ *   ({@link classifyModelTier}) that maps a `Provider`'s `modelId` to
+ *   one of `'fast' | 'balanced' | 'smart'`.
+ *
+ * @packageDocumentation
+ */
+
+/** Canonical version constant, derived from `package.json` at build time. */
+import pkg from '../package.json' with { type: 'json' };
+
+export const VERSION: string = pkg.version;
+
+export * from './adapters/index.js';
+export * from './counters/index.js';
+export * from './errors/index.js';
+export * from './middleware/index.js';
+export * from './model-tier/index.js';
+export * from './provider.js';
+export * from './reasoning/index.js';
+export { foldToolExamples } from './tool-examples.js';
+export * from './trust/index.js';

package/src/internal/abort.ts

@@ -0,0 +1,30 @@
+/**
+ * Abort detection shared by the retry / fallback predicates (PS-2).
+ *
+ * A network failure surfaces as `ProviderHttpError{ status: 0, cause }`,
+ * and a user/agent abort surfaces the same way - the distinguishing
+ * signal is an `AbortError` (DOMException) somewhere on the `cause`
+ * chain. Network errors should be retried and failed over; an abort must
+ * not be, even though the retry/fallback loops also short-circuit on
+ * `req.signal?.aborted` independently.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * True when `err` - or any error on its `cause` chain - is an abort
+ * (`name === 'AbortError'` or Node's `code === 'ABORT_ERR'`). Walks at
+ * most a few links so a cyclic / pathological cause chain cannot loop.
+ *
+ * @internal
+ */
+export function isAbortError(err: unknown): boolean {
+  let cursor: unknown = err;
+  for (let depth = 0; depth < 8 && cursor !== null && typeof cursor === 'object'; depth++) {
+    const e = cursor as { name?: unknown; code?: unknown; cause?: unknown };
+    if (e.name === 'AbortError' || e.code === 'ABORT_ERR') return true;
+    if (e.cause === cursor) break;
+    cursor = e.cause;
+  }
+  return false;
+}