genai-lite 0.8.3 → 0.9.0

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/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/package.json

@@ -1,59 +1,59 @@
-{
-  "name": "genai-lite",
-  "version": "0.8.3",
-  "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"
+  }
+}