@mcp-abap-adt/llm-agent 20.7.1 → 20.9.0

package/dist/resilience/retry-embedder.js

@@ -0,0 +1,124 @@
+/**
+ * RetryEmbedder — IEmbedder decorators that retry transient failures with
+ * exponential backoff. Ported from RetryLlm (llm-agent-libs) onto IEmbedder,
+ * which throws instead of returning a Result.
+ *
+ * Two classes behind a factory, following wrapEmbedder: a single class exposing
+ * embedBatch unconditionally would make every non-batch embedder look
+ * batch-capable to isBatchEmbedder.
+ */
+import { isBatchEmbedder } from '../interfaces/rag.js';
+import { RagError } from '../interfaces/types.js';
+import { DefaultWaitStrategy } from '../interfaces/wait-strategy.js';
+const DEFAULT_OPTIONS = {
+    maxAttempts: 3,
+    backoffMs: 2000,
+    retryOn: [429, 500, 502, 503],
+    // Stateless, so one shared instance is safe.
+    waitStrategy: new DefaultWaitStrategy(),
+};
+const MAX_CAUSE_DEPTH = 5;
+/**
+ * Resolve an HTTP status from an unknown thrown value: own status/statusCode,
+ * then the same walking `cause`, bounded by depth and a visited set so a cyclic
+ * chain cannot hang. Returns undefined when no numeric status is present.
+ */
+export function extractStatusCode(err) {
+    const visited = new Set();
+    let cur = err;
+    for (let depth = 0; depth < MAX_CAUSE_DEPTH; depth++) {
+        if (typeof cur !== 'object' || cur === null || visited.has(cur))
+            return;
+        visited.add(cur);
+        const rec = cur;
+        if (typeof rec.status === 'number')
+            return rec.status;
+        if (typeof rec.statusCode === 'number')
+            return rec.statusCode;
+        cur = rec.cause;
+    }
+    return undefined;
+}
+/**
+ * Whether a thrown value should be retried against a set of HTTP status codes.
+ *
+ * A structured status (own `status`/`statusCode`, or the same on `cause`) is
+ * authoritative. Only when none is present does it fall back to the message,
+ * and there it matches on **word boundaries** — a bare `includes('429')` also
+ * fires on `4290`, an id, or a byte count, turning a hard error into a
+ * multi-second backoff stall.
+ *
+ * Shared by both retry decorators (embedder and LLM) so the classification
+ * cannot drift between them.
+ */
+export function isRetryableStatus(err, retryOn) {
+    const status = extractStatusCode(err);
+    if (status !== undefined)
+        return retryOn.includes(status);
+    const msg = err instanceof Error ? err.message : String(err);
+    return retryOn.some((code) => new RegExp(`\\b${code}\\b`).test(msg));
+}
+export class RetryEmbedder {
+    inner;
+    opts;
+    constructor(inner, options) {
+        this.inner = inner;
+        // waitStrategy is re-applied after the spread: an explicit
+        // `{ waitStrategy: undefined }` would otherwise overwrite the default with
+        // undefined and crash on the first backoff.
+        this.opts = {
+            ...DEFAULT_OPTIONS,
+            ...options,
+            waitStrategy: options?.waitStrategy ?? DEFAULT_OPTIONS.waitStrategy,
+        };
+    }
+    async embed(text, options) {
+        return this.run(() => this.inner.embed(text, options), options);
+    }
+    async run(call, options) {
+        for (let attempt = 0;; attempt++) {
+            if (options?.signal?.aborted) {
+                throw new RagError('Aborted', 'ABORTED');
+            }
+            try {
+                return await call();
+            }
+            catch (err) {
+                if (attempt >= this.opts.maxAttempts || !this.isRetryable(err))
+                    throw err;
+                await this.backoff(attempt, options?.signal);
+            }
+        }
+    }
+    isRetryable(err) {
+        return isRetryableStatus(err, this.opts.retryOn);
+    }
+    /**
+     * Delegated to IWaitStrategy rather than hand-rolled: honouring the signal is
+     * part of that contract — an already-aborted signal returns immediately
+     * (addEventListener never fires for an event that already dispatched), and
+     * the listener is removed when the timer wins so a request- or session-scoped
+     * signal does not accumulate one per retry.
+     */
+    async backoff(attempt, signal) {
+        const delay = this.opts.backoffMs * 2 ** attempt;
+        await this.opts.waitStrategy.wait(delay, signal);
+    }
+}
+export class RetryBatchEmbedder extends RetryEmbedder {
+    inner;
+    constructor(inner, options) {
+        super(inner, options);
+        this.inner = inner;
+    }
+    async embedBatch(texts, options) {
+        return this.run(() => this.inner.embedBatch(texts, options), options);
+    }
+}
+/** Preserves batch capability: never turns a non-batch embedder into one. */
+export function withRetry(inner, options) {
+    return isBatchEmbedder(inner)
+        ? new RetryBatchEmbedder(inner, options)
+        : new RetryEmbedder(inner, options);
+}
+//# sourceMappingURL=retry-embedder.js.map

package/dist/resilience/retry-embedder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry-embedder.js","sourceRoot":"","sources":["../../src/resilience/retry-embedder.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcp-abap-adt/llm-agent",
-  "version": "20.7.1",
+  "version": "20.9.0",
   "description": "Core interfaces, types, and lightweight default implementations for LLM agent orchestration.",
   "type": "module",
   "main": "dist/index.js",