genai-lite 0.8.2 → 0.9.0

package/dist/shared/adapters/errorUtils.js

@@ -3,8 +3,53 @@
 // Maps common HTTP status codes and network errors to standardized AdapterErrorCode and errorType.
 // Reduces duplication across OpenAI, Anthropic and other provider adapters.
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseRetryAfterMs = parseRetryAfterMs;
+exports.extractRetryAfterMs = extractRetryAfterMs;
 exports.getCommonMappedErrorDetails = getCommonMappedErrorDetails;
 const types_1 = require("../../llm/clients/types");
+/**
+ * Parses a Retry-After header value (delta-seconds or HTTP-date) into milliseconds.
+ *
+ * @param value - The raw header value
+ * @returns Milliseconds to wait, or undefined when unparseable/negative
+ */
+function parseRetryAfterMs(value) {
+    if (!value)
+        return undefined;
+    const seconds = Number(value);
+    if (!Number.isNaN(seconds)) {
+        return seconds >= 0 ? Math.round(seconds * 1000) : undefined;
+    }
+    const dateMs = Date.parse(value);
+    if (!Number.isNaN(dateMs)) {
+        const delta = dateMs - Date.now();
+        return delta > 0 ? delta : undefined;
+    }
+    return undefined;
+}
+/**
+ * Extracts a Retry-After value in ms from an SDK error object, tolerating the
+ * different places SDKs keep response headers (openai/anthropic `error.headers`
+ * as a Headers instance or plain object; Speakeasy-style `error.rawResponse`).
+ */
+function extractRetryAfterMs(error) {
+    const headerSources = [error?.headers, error?.rawResponse?.headers];
+    for (const headers of headerSources) {
+        if (!headers)
+            continue;
+        let raw;
+        if (typeof headers.get === 'function') {
+            raw = headers.get('retry-after');
+        }
+        else if (typeof headers === 'object') {
+            raw = headers['retry-after'] ?? headers['Retry-After'];
+        }
+        const parsed = parseRetryAfterMs(raw);
+        if (parsed !== undefined)
+            return parsed;
+    }
+    return undefined;
+}
 /**
  * Maps common error patterns to standardized error codes and types
  *
@@ -25,6 +70,28 @@ function getCommonMappedErrorDetails(error, providerMessageOverride) {
     let errorMessage = providerMessageOverride || error?.message || 'Unknown error occurred';
     let errorType = 'server_error';
     let status;
+    const retryAfterMs = extractRetryAfterMs(error);
+    // Handle user-initiated aborts and client-side timeouts first — the SDKs raise
+    // these as named errors (openai: APIUserAbortError/APIConnectionTimeoutError;
+    // fetch/undici: AbortError/TimeoutError DOMExceptions)
+    if (error &&
+        (error.name === 'APIUserAbortError' ||
+            error.name === 'AbortError' ||
+            (error instanceof DOMException && error.name === 'AbortError'))) {
+        return {
+            errorCode: types_1.ADAPTER_ERROR_CODES.REQUEST_ABORTED,
+            errorMessage: providerMessageOverride || error.message || 'Request was aborted',
+            errorType: 'abort_error',
+        };
+    }
+    if (error &&
+        (error.name === 'APIConnectionTimeoutError' || error.name === 'TimeoutError')) {
+        return {
+            errorCode: types_1.ADAPTER_ERROR_CODES.REQUEST_TIMEOUT,
+            errorMessage: providerMessageOverride || error.message || 'Request timed out',
+            errorType: 'timeout_error',
+        };
+    }
     // Handle API errors with HTTP status codes
     if (error && typeof error.status === 'number') {
         const httpStatus = error.status;
@@ -102,6 +169,7 @@ function getCommonMappedErrorDetails(error, providerMessageOverride) {
         errorCode,
         errorMessage,
         errorType,
-        status
+        status,
+        ...(retryAfterMs !== undefined && { retryAfterMs })
     };
 }

package/dist/shared/adapters/logprobsUtils.d.ts

@@ -0,0 +1,13 @@
+import type { TokenLogprob } from "../../llm/types";
+/**
+ * Maps an OpenAI-shaped chat-completions logprobs payload
+ * (`choice.logprobs.content[].{token, logprob, top_logprobs[]}`) to the
+ * library's normalized {@link TokenLogprob} array.
+ *
+ * llama-server's chat endpoint produces the same shape, so this mapper is
+ * shared across the OpenAI-SDK-based adapters.
+ *
+ * @param logprobs - The raw `choice.logprobs` object from the provider response
+ * @returns Normalized token logprobs, or undefined when absent/empty
+ */
+export declare function mapOpenAIChatLogprobs(logprobs: any): TokenLogprob[] | undefined;

package/dist/shared/adapters/logprobsUtils.js

@@ -0,0 +1,33 @@
+"use strict";
+// AI Summary: Shared mapper for OpenAI-shaped chat-completions logprobs payloads.
+// Used by the OpenAI, OpenRouter and llama.cpp adapters (identical wire shape).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mapOpenAIChatLogprobs = mapOpenAIChatLogprobs;
+/**
+ * Maps an OpenAI-shaped chat-completions logprobs payload
+ * (`choice.logprobs.content[].{token, logprob, top_logprobs[]}`) to the
+ * library's normalized {@link TokenLogprob} array.
+ *
+ * llama-server's chat endpoint produces the same shape, so this mapper is
+ * shared across the OpenAI-SDK-based adapters.
+ *
+ * @param logprobs - The raw `choice.logprobs` object from the provider response
+ * @returns Normalized token logprobs, or undefined when absent/empty
+ */
+function mapOpenAIChatLogprobs(logprobs) {
+    const content = logprobs?.content;
+    if (!Array.isArray(content) || content.length === 0) {
+        return undefined;
+    }
+    return content.map((entry) => ({
+        token: entry.token,
+        logprob: entry.logprob,
+        ...(Array.isArray(entry.top_logprobs) &&
+            entry.top_logprobs.length > 0 && {
+            topLogprobs: entry.top_logprobs.map((alt) => ({
+                token: alt.token,
+                logprob: alt.logprob,
+            })),
+        }),
+    }));
+}

package/dist/shared/services/AdapterRegistry.js

@@ -50,7 +50,9 @@ class AdapterRegistry {
             if (AdapterClass) {
                 try {
                     const adapterConfig = adapterConfigs[provider.id];
-                    const adapterInstance = new AdapterClass(adapterConfig);
+                    // Inject logger into adapter config
+                    const configWithLogger = { ...adapterConfig, logger: this.logger };
+                    const adapterInstance = new AdapterClass(configWithLogger);
                     this.registerAdapter(providerId, adapterInstance);
                     registeredCount++;
                     successfullyRegisteredProviders.push(provider.id);

package/dist/shared/services/withRetry.d.ts

@@ -0,0 +1,50 @@
+import type { Logger } from "../../logging/types";
+/**
+ * Retry policy configuration.
+ */
+export interface RetryPolicy {
+    /** Maximum number of retries after the initial attempt (default 2 → up to 3 attempts) */
+    maxRetries: number;
+    /** Base delay before the first retry, in ms (default 500) */
+    initialDelayMs: number;
+    /** Upper bound for any single delay, in ms (default 10000) */
+    maxDelayMs: number;
+    /** Exponential growth factor per attempt (default 2) */
+    backoffFactor: number;
+}
+export declare const DEFAULT_RETRY_POLICY: RetryPolicy;
+/**
+ * Verdict returned by the caller's shouldRetry callback.
+ */
+export interface RetryVerdict {
+    /** Whether the operation should be retried */
+    retry: boolean;
+    /** Provider-suggested wait (e.g. from a Retry-After header); used when larger than the computed backoff */
+    retryAfterMs?: number;
+}
+export interface WithRetryOptions extends Partial<RetryPolicy> {
+    /** Abort signal — no further retries (or waits) once aborted */
+    signal?: AbortSignal;
+    /** Logger for retry warnings */
+    logger?: Logger;
+    /** Label used in log messages (e.g. "openai/gpt-4.1") */
+    label?: string;
+}
+/**
+ * Runs an async operation with retries and exponential backoff.
+ *
+ * Unlike typical retry helpers, this operates on RETURNED values rather than
+ * exceptions: the caller's `shouldRetry` inspects each result (genai-lite
+ * adapters return failure responses instead of throwing) and decides whether
+ * to retry. The last result is always returned — never thrown.
+ *
+ * Delay per retry: `min(maxDelayMs, initialDelayMs * backoffFactor^attempt)`
+ * with ±20% jitter; a provider-supplied `retryAfterMs` is honored when larger
+ * (still capped at `maxDelayMs`).
+ *
+ * @param operation - The operation to run; receives the 0-based attempt index
+ * @param shouldRetry - Inspects a result and decides whether to retry
+ * @param options - Policy overrides, abort signal, logger
+ * @returns The final result (successful, non-retryable, or last exhausted attempt)
+ */
+export declare function withRetry<T>(operation: (attempt: number) => Promise<T>, shouldRetry: (result: T) => RetryVerdict, options?: WithRetryOptions): Promise<T>;

package/dist/shared/services/withRetry.js

@@ -0,0 +1,78 @@
+"use strict";
+// AI Summary: Generic retry helper with exponential backoff and jitter.
+// Works on RETURNED values (genai-lite adapters never throw), honors Retry-After
+// hints and AbortSignals. Used by LLMService's unified retry layer.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_RETRY_POLICY = void 0;
+exports.withRetry = withRetry;
+exports.DEFAULT_RETRY_POLICY = {
+    maxRetries: 2,
+    initialDelayMs: 500,
+    maxDelayMs: 10000,
+    backoffFactor: 2,
+};
+/**
+ * Runs an async operation with retries and exponential backoff.
+ *
+ * Unlike typical retry helpers, this operates on RETURNED values rather than
+ * exceptions: the caller's `shouldRetry` inspects each result (genai-lite
+ * adapters return failure responses instead of throwing) and decides whether
+ * to retry. The last result is always returned — never thrown.
+ *
+ * Delay per retry: `min(maxDelayMs, initialDelayMs * backoffFactor^attempt)`
+ * with ±20% jitter; a provider-supplied `retryAfterMs` is honored when larger
+ * (still capped at `maxDelayMs`).
+ *
+ * @param operation - The operation to run; receives the 0-based attempt index
+ * @param shouldRetry - Inspects a result and decides whether to retry
+ * @param options - Policy overrides, abort signal, logger
+ * @returns The final result (successful, non-retryable, or last exhausted attempt)
+ */
+async function withRetry(operation, shouldRetry, options) {
+    const policy = {
+        maxRetries: options?.maxRetries ?? exports.DEFAULT_RETRY_POLICY.maxRetries,
+        initialDelayMs: options?.initialDelayMs ?? exports.DEFAULT_RETRY_POLICY.initialDelayMs,
+        maxDelayMs: options?.maxDelayMs ?? exports.DEFAULT_RETRY_POLICY.maxDelayMs,
+        backoffFactor: options?.backoffFactor ?? exports.DEFAULT_RETRY_POLICY.backoffFactor,
+    };
+    let result = await operation(0);
+    for (let attempt = 0; attempt < policy.maxRetries; attempt++) {
+        const verdict = shouldRetry(result);
+        if (!verdict.retry || options?.signal?.aborted) {
+            return result;
+        }
+        // Exponential backoff with ±20% jitter; honor Retry-After when larger
+        const baseDelay = Math.min(policy.maxDelayMs, policy.initialDelayMs * Math.pow(policy.backoffFactor, attempt));
+        const jittered = baseDelay * (0.8 + Math.random() * 0.4);
+        const delayMs = Math.min(policy.maxDelayMs, Math.max(jittered, verdict.retryAfterMs ?? 0));
+        options?.logger?.warn(`Retrying${options.label ? ` ${options.label}` : ''} after failure ` +
+            `(attempt ${attempt + 2}/${policy.maxRetries + 1}, waiting ${Math.round(delayMs)}ms)`);
+        const aborted = await sleepUnlessAborted(delayMs, options?.signal);
+        if (aborted) {
+            return result;
+        }
+        result = await operation(attempt + 1);
+    }
+    return result;
+}
+/**
+ * Sleeps for the given duration unless the signal aborts first.
+ *
+ * @returns true when the wait was cut short by an abort
+ */
+function sleepUnlessAborted(ms, signal) {
+    if (signal?.aborted) {
+        return Promise.resolve(true);
+    }
+    return new Promise((resolve) => {
+        const onAbort = () => {
+            clearTimeout(timer);
+            resolve(true);
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve(false);
+        }, ms);
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}

package/dist/types/image.d.ts

@@ -337,6 +337,8 @@ export interface ImageProviderAdapterConfig {
     timeout?: number;
     /** Whether to check health before requests */
     checkHealth?: boolean;
+    /** Logger instance for adapter logging */
+    logger?: Logger;
 }
 /**
  * Interface that all image provider adapters must implement

package/package.json

@@ -1,59 +1,59 @@
-{
-  "name": "genai-lite",
-  "version": "0.8.2",
-  "description": "A lightweight, portable toolkit for interacting with various Generative AI APIs.",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "exports": {
-    ".": {
-      "import": "./dist/index.js",
-      "require": "./dist/index.js",
-      "types": "./dist/index.d.ts"
-    },
-    "./prompting": {
-      "import": "./dist/prompting/index.js",
-      "require": "./dist/prompting/index.js",
-      "types": "./dist/prompting/index.d.ts"
-    }
-  },
-  "author": "Luigi Acerbi <luigi.acerbi@gmail.com>",
-  "license": "MIT",
-  "funding": {
-    "type": "github",
-    "url": "https://github.com/sponsors/lacerbi"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/lacerbi/genai-lite.git"
-  },
-  "bugs": {
-    "url": "https://github.com/lacerbi/genai-lite/issues"
-  },
-  "homepage": "https://github.com/lacerbi/genai-lite#readme",
-  "files": [
-    "dist",
-    "src/config/llm-presets.json",
-    "src/config/image-presets.json"
-  ],
-  "scripts": {
-    "build": "tsc",
-    "test": "jest --coverage",
-    "test:watch": "jest --watch",
-    "test:e2e": "npm run build && jest --config jest.e2e.config.js",
-    "test:e2e:reasoning": "npm run build && jest --config jest.e2e.config.js reasoning.e2e.test.ts"
-  },
-  "dependencies": {
-    "@anthropic-ai/sdk": "^0.71.2",
-    "@google/genai": "^1.0.1",
-    "@mistralai/mistralai": "^1.11.0",
-    "js-tiktoken": "^1.0.20",
-    "openai": "^6.7.0"
-  },
-  "devDependencies": {
-    "@types/jest": ">=30.0.0",
-    "@types/node": ">=20.11.24",
-    "jest": ">=30.0.4",
-    "ts-jest": ">=29.4.0",
-    "typescript": ">=5.3.3"
-  }
-}
+{
+  "name": "genai-lite",
+  "version": "0.9.0",
+  "description": "A lightweight, portable toolkit for interacting with various Generative AI APIs.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./prompting": {
+      "import": "./dist/prompting/index.js",
+      "require": "./dist/prompting/index.js",
+      "types": "./dist/prompting/index.d.ts"
+    }
+  },
+  "author": "Luigi Acerbi <luigi.acerbi@gmail.com>",
+  "license": "MIT",
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/lacerbi"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lacerbi/genai-lite.git"
+  },
+  "bugs": {
+    "url": "https://github.com/lacerbi/genai-lite/issues"
+  },
+  "homepage": "https://github.com/lacerbi/genai-lite#readme",
+  "files": [
+    "dist",
+    "src/config/llm-presets.json",
+    "src/config/image-presets.json"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "jest --coverage",
+    "test:watch": "jest --watch",
+    "test:e2e": "npm run build && jest --config jest.e2e.config.js",
+    "test:e2e:reasoning": "npm run build && jest --config jest.e2e.config.js reasoning.e2e.test.ts"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.71.2",
+    "@google/genai": "^1.0.1",
+    "@mistralai/mistralai": "^1.11.0",
+    "js-tiktoken": "^1.0.20",
+    "openai": "^6.7.0"
+  },
+  "devDependencies": {
+    "@types/jest": ">=30.0.0",
+    "@types/node": ">=20.11.24",
+    "jest": ">=30.0.4",
+    "ts-jest": ">=29.4.0",
+    "typescript": ">=5.3.3"
+  }
+}