bikky 0.3.1 → 0.3.2

package/dist/llm/errors.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Shared error hierarchy for LLM (inference) and embedding providers.
+ *
+ * Models the same shape as `src/lib/qdrant-client.ts` so callers can branch on
+ * type instead of string-matching log messages. Inference providers catch these
+ * internally and degrade to `null` for the fallback chain (see
+ * `src/llm/inference/index.ts`); embedding providers re-throw them so callers
+ * can surface a meaningful reason.
+ */
+export type LlmErrorClass = "auth" | "rate_limit" | "bad_request" | "transient" | "timeout" | "unknown";
+export interface LlmErrorDetails {
+    /** Provider name, e.g. "openai", "portkey". */
+    provider: string;
+    /** Model id, when known. */
+    model?: string;
+    /** HTTP status code, when the failure was an HTTP response. */
+    status?: number;
+    /** Truncated response body, when available. */
+    body?: string;
+    /** Retry-After header value (seconds) for rate-limit responses. */
+    retryAfterMs?: number;
+    /** Underlying cause, when this wraps another error. */
+    cause?: unknown;
+}
+/**
+ * Base class for all LLM/embedding HTTP failures. Subclasses set `kind` so that
+ * `instanceof` and `kind === "..."` both work.
+ */
+export declare class LlmHttpError extends Error {
+    readonly kind: LlmErrorClass;
+    readonly provider: string;
+    readonly model?: string;
+    readonly status?: number;
+    readonly body?: string;
+    readonly retryAfterMs?: number;
+    constructor(kind: LlmErrorClass, message: string, details: LlmErrorDetails);
+}
+export declare class LlmAuthError extends LlmHttpError {
+    constructor(details: LlmErrorDetails);
+}
+export declare class LlmBadRequestError extends LlmHttpError {
+    constructor(details: LlmErrorDetails);
+}
+export declare class LlmRateLimitError extends LlmHttpError {
+    constructor(details: LlmErrorDetails);
+}
+export declare class LlmTransientError extends LlmHttpError {
+    constructor(details: LlmErrorDetails);
+}
+export declare class LlmTimeoutError extends LlmHttpError {
+    constructor(details: LlmErrorDetails);
+}
+export declare class LlmUnknownError extends LlmHttpError {
+    constructor(details: LlmErrorDetails);
+}
+/** Convenience: vector-dimension mismatch — config says X, model returned Y. */
+export declare class EmbeddingDimensionMismatchError extends Error {
+    readonly provider: string;
+    readonly model: string;
+    readonly expected: number;
+    readonly actual: number;
+    constructor(provider: string, model: string, expected: number, actual: number);
+}
+/**
+ * Map an HTTP status code to a typed error class.
+ * Mirrors the classification in `src/lib/qdrant-client.ts:classifyStatus`.
+ */
+export declare function classifyHttpStatus(status: number): LlmErrorClass;
+/** Build the right error subclass for an HTTP failure. */
+export declare function makeHttpError(status: number, details: Omit<LlmErrorDetails, "status">): LlmHttpError;
+/**
+ * Map a thrown fetch error (network/abort) to a typed error.
+ *
+ * - DOMException `name === "TimeoutError"` (from AbortSignal.timeout) → LlmTimeoutError
+ * - Anything else (DNS, ECONNRESET, etc.) → LlmTransientError
+ */
+export declare function classifyFetchError(err: unknown, details: Omit<LlmErrorDetails, "status">): LlmHttpError;
+/**
+ * Parse a Retry-After header (seconds or HTTP date) into milliseconds, capped
+ * at 60s to avoid runaway sleeps.
+ */
+export declare function parseRetryAfterMs(header: string | null): number | undefined;
+/**
+ * Sleep with exponential backoff + jitter, optionally honouring a server-sent
+ * Retry-After hint. Mirrors `src/lib/qdrant-client.ts` semantics.
+ */
+export declare function backoffDelayMs(opts: {
+    attempt: number;
+    baseMs: number;
+    capMs: number;
+    retryAfterMs?: number;
+}): number;
+/** True when an error class is worth retrying. */
+export declare function isRetryable(kind: LlmErrorClass): boolean;
+//# sourceMappingURL=errors.d.ts.map

package/dist/llm/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/llm/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,MAAM,aAAa,GACrB,MAAM,GACN,YAAY,GACZ,aAAa,GACb,WAAW,GACX,SAAS,GACT,SAAS,CAAC;AAEd,MAAM,WAAW,eAAe;IAC9B,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB,4BAA4B;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,uDAAuD;IACvD,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;GAGG;AACH,qBAAa,YAAa,SAAQ,KAAK;IACrC,SAAgB,IAAI,EAAE,aAAa,CAAC;IACpC,SAAgB,QAAQ,EAAE,MAAM,CAAC;IACjC,SAAgB,KAAK,CAAC,EAAE,MAAM,CAAC;IAC/B,SAAgB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChC,SAAgB,IAAI,CAAC,EAAE,MAAM,CAAC;IAC9B,SAAgB,YAAY,CAAC,EAAE,MAAM,CAAC;gBAE1B,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe;CAc3E;AAED,qBAAa,YAAa,SAAQ,YAAY;gBAChC,OAAO,EAAE,eAAe;CAGrC;AAED,qBAAa,kBAAmB,SAAQ,YAAY;gBACtC,OAAO,EAAE,eAAe;CAGrC;AAED,qBAAa,iBAAkB,SAAQ,YAAY;gBACrC,OAAO,EAAE,eAAe;CAGrC;AAED,qBAAa,iBAAkB,SAAQ,YAAY;gBACrC,OAAO,EAAE,eAAe;CAGrC;AAED,qBAAa,eAAgB,SAAQ,YAAY;gBACnC,OAAO,EAAE,eAAe;CAGrC;AAED,qBAAa,eAAgB,SAAQ,YAAY;gBACnC,OAAO,EAAE,eAAe;CAGrC;AAED,gFAAgF;AAChF,qBAAa,+BAAgC,SAAQ,KAAK;IACxD,SAAgB,QAAQ,EAAE,MAAM,CAAC;IACjC,SAAgB,KAAK,EAAE,MAAM,CAAC;IAC9B,SAAgB,QAAQ,EAAE,MAAM,CAAC;IACjC,SAAgB,MAAM,EAAE,MAAM,CAAC;gBACnB,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAW9E;AASD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,CAQhE;AAED,0DAA0D;AAC1D,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,eAAe,EAAE,QAAQ,CAAC,GAAG,YAAY,CASpG;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,eAAe,EAAE,QAAQ,CAAC,GAAG,YAAY,CAKvG;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,SAAS,CAY3E;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,GAAG,MAAM,CAKT;AAED,kDAAkD;AAClD,wBAAgB,WAAW,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAExD"}

package/dist/llm/errors.js

@@ -0,0 +1,164 @@
+/**
+ * Shared error hierarchy for LLM (inference) and embedding providers.
+ *
+ * Models the same shape as `src/lib/qdrant-client.ts` so callers can branch on
+ * type instead of string-matching log messages. Inference providers catch these
+ * internally and degrade to `null` for the fallback chain (see
+ * `src/llm/inference/index.ts`); embedding providers re-throw them so callers
+ * can surface a meaningful reason.
+ */
+/**
+ * Base class for all LLM/embedding HTTP failures. Subclasses set `kind` so that
+ * `instanceof` and `kind === "..."` both work.
+ */
+export class LlmHttpError extends Error {
+    kind;
+    provider;
+    model;
+    status;
+    body;
+    retryAfterMs;
+    constructor(kind, message, details) {
+        super(message);
+        this.name = new.target.name;
+        this.kind = kind;
+        this.provider = details.provider;
+        this.model = details.model;
+        this.status = details.status;
+        this.body = details.body;
+        this.retryAfterMs = details.retryAfterMs;
+        if (details.cause !== undefined) {
+            // Preserve the underlying cause for stack-trace inspection.
+            this.cause = details.cause;
+        }
+    }
+}
+export class LlmAuthError extends LlmHttpError {
+    constructor(details) {
+        super("auth", buildMessage(details), details);
+    }
+}
+export class LlmBadRequestError extends LlmHttpError {
+    constructor(details) {
+        super("bad_request", buildMessage(details), details);
+    }
+}
+export class LlmRateLimitError extends LlmHttpError {
+    constructor(details) {
+        super("rate_limit", buildMessage(details), details);
+    }
+}
+export class LlmTransientError extends LlmHttpError {
+    constructor(details) {
+        super("transient", buildMessage(details), details);
+    }
+}
+export class LlmTimeoutError extends LlmHttpError {
+    constructor(details) {
+        super("timeout", buildMessage({ ...details, body: details.body ?? "request timed out" }), details);
+    }
+}
+export class LlmUnknownError extends LlmHttpError {
+    constructor(details) {
+        super("unknown", buildMessage(details), details);
+    }
+}
+/** Convenience: vector-dimension mismatch — config says X, model returned Y. */
+export class EmbeddingDimensionMismatchError extends Error {
+    provider;
+    model;
+    expected;
+    actual;
+    constructor(provider, model, expected, actual) {
+        super(`Embedding dimension mismatch [${provider}/${model}]: config.embedding.dimensions=${expected} but the model returned ${actual}. ` +
+            `Update embedding.dimensions in ~/.bikky/config.json (or via configure_credentials) and re-create the Qdrant collection.`);
+        this.name = "EmbeddingDimensionMismatchError";
+        this.provider = provider;
+        this.model = model;
+        this.expected = expected;
+        this.actual = actual;
+    }
+}
+function buildMessage(d) {
+    const target = d.model ? `${d.provider}/${d.model}` : d.provider;
+    const statusPart = d.status !== undefined ? ` (${d.status})` : "";
+    const bodyPart = d.body ? `: ${d.body.slice(0, 200)}` : "";
+    return `[${target}]${statusPart}${bodyPart}`;
+}
+/**
+ * Map an HTTP status code to a typed error class.
+ * Mirrors the classification in `src/lib/qdrant-client.ts:classifyStatus`.
+ */
+export function classifyHttpStatus(status) {
+    if (status === 401 || status === 403)
+        return "auth";
+    if (status === 429)
+        return "rate_limit";
+    if (status === 400 || status === 422)
+        return "bad_request";
+    if (status === 408 || status === 425 || status >= 500)
+        return "transient";
+    if (status >= 200 && status < 300)
+        return "unknown"; // never used — caller must check ok
+    if (status >= 400)
+        return "bad_request";
+    return "unknown";
+}
+/** Build the right error subclass for an HTTP failure. */
+export function makeHttpError(status, details) {
+    const full = { ...details, status };
+    switch (classifyHttpStatus(status)) {
+        case "auth": return new LlmAuthError(full);
+        case "rate_limit": return new LlmRateLimitError(full);
+        case "bad_request": return new LlmBadRequestError(full);
+        case "transient": return new LlmTransientError(full);
+        default: return new LlmUnknownError(full);
+    }
+}
+/**
+ * Map a thrown fetch error (network/abort) to a typed error.
+ *
+ * - DOMException `name === "TimeoutError"` (from AbortSignal.timeout) → LlmTimeoutError
+ * - Anything else (DNS, ECONNRESET, etc.) → LlmTransientError
+ */
+export function classifyFetchError(err, details) {
+    const e = err;
+    const isAbort = e?.name === "TimeoutError" || e?.name === "AbortError";
+    const ctx = { ...details, cause: err, body: e?.message };
+    return isAbort ? new LlmTimeoutError(ctx) : new LlmTransientError(ctx);
+}
+/**
+ * Parse a Retry-After header (seconds or HTTP date) into milliseconds, capped
+ * at 60s to avoid runaway sleeps.
+ */
+export function parseRetryAfterMs(header) {
+    if (!header)
+        return undefined;
+    const seconds = Number(header);
+    if (Number.isFinite(seconds) && seconds >= 0) {
+        return Math.min(seconds, 60) * 1000;
+    }
+    const dateMs = Date.parse(header);
+    if (!Number.isNaN(dateMs)) {
+        const delta = dateMs - Date.now();
+        if (delta > 0)
+            return Math.min(delta, 60_000);
+    }
+    return undefined;
+}
+/**
+ * Sleep with exponential backoff + jitter, optionally honouring a server-sent
+ * Retry-After hint. Mirrors `src/lib/qdrant-client.ts` semantics.
+ */
+export function backoffDelayMs(opts) {
+    if (opts.retryAfterMs !== undefined)
+        return Math.min(opts.retryAfterMs, opts.capMs);
+    const exp = Math.min(opts.capMs, opts.baseMs * 2 ** opts.attempt);
+    // Full jitter: random in [0, exp).
+    return Math.floor(Math.random() * exp);
+}
+/** True when an error class is worth retrying. */
+export function isRetryable(kind) {
+    return kind === "transient" || kind === "rate_limit" || kind === "timeout";
+}
+//# sourceMappingURL=errors.js.map

package/dist/llm/errors.js.map

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

package/dist/llm/errors.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=errors.test.d.ts.map

package/dist/llm/errors.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.test.d.ts","sourceRoot":"","sources":["../../src/llm/errors.test.ts"],"names":[],"mappings":""}

package/dist/llm/errors.test.js

@@ -0,0 +1,103 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { classifyHttpStatus, makeHttpError, classifyFetchError, parseRetryAfterMs, backoffDelayMs, isRetryable, LlmAuthError, LlmRateLimitError, LlmBadRequestError, LlmTransientError, LlmTimeoutError, LlmUnknownError, EmbeddingDimensionMismatchError, } from "./errors.js";
+describe("classifyHttpStatus", () => {
+    it("maps 401/403 → auth, 429 → rate_limit, 400/422 → bad_request, 5xx → transient", () => {
+        assert.equal(classifyHttpStatus(401), "auth");
+        assert.equal(classifyHttpStatus(403), "auth");
+        assert.equal(classifyHttpStatus(429), "rate_limit");
+        assert.equal(classifyHttpStatus(400), "bad_request");
+        assert.equal(classifyHttpStatus(422), "bad_request");
+        assert.equal(classifyHttpStatus(404), "bad_request");
+        assert.equal(classifyHttpStatus(500), "transient");
+        assert.equal(classifyHttpStatus(503), "transient");
+        assert.equal(classifyHttpStatus(408), "transient");
+    });
+});
+describe("makeHttpError", () => {
+    it("returns the right subclass for each status", () => {
+        assert.ok(makeHttpError(401, { provider: "openai" }) instanceof LlmAuthError);
+        assert.ok(makeHttpError(429, { provider: "openai" }) instanceof LlmRateLimitError);
+        assert.ok(makeHttpError(404, { provider: "openai" }) instanceof LlmBadRequestError);
+        assert.ok(makeHttpError(503, { provider: "openai" }) instanceof LlmTransientError);
+        assert.ok(makeHttpError(301, { provider: "openai" }) instanceof LlmUnknownError);
+    });
+    it("formats message as [provider/model] (status): body", () => {
+        const err = makeHttpError(404, {
+            provider: "ollama",
+            model: "qwen3-embedding:0.6b",
+            body: "model not found",
+        });
+        assert.match(err.message, /\[ollama\/qwen3-embedding:0\.6b\] \(404\): model not found/);
+    });
+    it("preserves provider, status, body, kind", () => {
+        const err = makeHttpError(429, { provider: "p", body: "slow down", retryAfterMs: 1000 });
+        assert.equal(err.kind, "rate_limit");
+        assert.equal(err.status, 429);
+        assert.equal(err.provider, "p");
+        assert.equal(err.retryAfterMs, 1000);
+    });
+});
+describe("parseRetryAfterMs", () => {
+    it("parses integer seconds", () => {
+        assert.equal(parseRetryAfterMs("5"), 5_000);
+    });
+    it("caps at 60s", () => {
+        assert.equal(parseRetryAfterMs("9999"), 60_000);
+    });
+    it("returns undefined for null / invalid input", () => {
+        assert.equal(parseRetryAfterMs(null), undefined);
+        assert.equal(parseRetryAfterMs("abc"), undefined);
+    });
+});
+describe("backoffDelayMs", () => {
+    it("respects cap with full jitter", () => {
+        for (let attempt = 0; attempt < 5; attempt++) {
+            const d = backoffDelayMs({ attempt, baseMs: 100, capMs: 2_000 });
+            assert.ok(d >= 0 && d <= 2_000, `attempt ${attempt} produced ${d}`);
+        }
+    });
+    it("honours retryAfterMs (capped)", () => {
+        assert.equal(backoffDelayMs({ attempt: 0, baseMs: 100, capMs: 2_000, retryAfterMs: 5_000 }), 2_000);
+        assert.equal(backoffDelayMs({ attempt: 0, baseMs: 100, capMs: 10_000, retryAfterMs: 500 }), 500);
+    });
+});
+describe("isRetryable", () => {
+    it("retries timeout / rate_limit / transient", () => {
+        assert.ok(isRetryable("timeout"));
+        assert.ok(isRetryable("rate_limit"));
+        assert.ok(isRetryable("transient"));
+    });
+    it("does NOT retry auth / bad_request / unknown", () => {
+        assert.equal(isRetryable("auth"), false);
+        assert.equal(isRetryable("bad_request"), false);
+        assert.equal(isRetryable("unknown"), false);
+    });
+});
+describe("classifyFetchError", () => {
+    it("maps TimeoutError → LlmTimeoutError", () => {
+        const e = new Error("timeout");
+        e.name = "TimeoutError";
+        assert.ok(classifyFetchError(e, { provider: "p" }) instanceof LlmTimeoutError);
+    });
+    it("maps AbortError → LlmTimeoutError", () => {
+        const e = new Error("aborted");
+        e.name = "AbortError";
+        assert.ok(classifyFetchError(e, { provider: "p" }) instanceof LlmTimeoutError);
+    });
+    it("maps generic network error → LlmTransientError", () => {
+        const e = new TypeError("fetch failed");
+        assert.ok(classifyFetchError(e, { provider: "p" }) instanceof LlmTransientError);
+    });
+});
+describe("EmbeddingDimensionMismatchError", () => {
+    it("includes provider, model, expected, actual", () => {
+        const e = new EmbeddingDimensionMismatchError("openai", "text-embedding-3-small", 1536, 768);
+        assert.equal(e.provider, "openai");
+        assert.equal(e.expected, 1536);
+        assert.equal(e.actual, 768);
+        assert.match(e.message, /1536/);
+        assert.match(e.message, /768/);
+    });
+});
+//# sourceMappingURL=errors.test.js.map

package/dist/llm/errors.test.js.map

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

package/dist/llm/fetch.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Resilient JSON fetch helper for LLM and embedding providers.
+ *
+ * Adds three things to plain `fetch()`:
+ *   1. Per-request timeout (AbortSignal.timeout)
+ *   2. Retry on transient HTTP failures (5xx, 408, 425), rate-limits (429,
+ *      honouring Retry-After), and network errors
+ *   3. Typed error classification — see `./errors.ts`
+ *
+ * Mirrors the patterns used by `src/lib/qdrant-client.ts` so callers can rely
+ * on a single error hierarchy across LLM, embedding, and Qdrant.
+ */
+import { LlmHttpError } from "./errors.js";
+export interface ResilientFetchOptions {
+    /** Endpoint URL. */
+    url: string;
+    /** Standard `fetch` init (method, headers, body, …). `signal` is overridden. */
+    init: RequestInit;
+    /** Per-attempt timeout in milliseconds. */
+    timeoutMs: number;
+    /** Max retry attempts for transient failures (excluding the first try). */
+    retries: number;
+    /** Base backoff in milliseconds. */
+    baseDelayMs: number;
+    /** Maximum backoff cap in milliseconds. */
+    capDelayMs: number;
+    /** Provider name (for typed errors). */
+    provider: string;
+    /** Model id, when known. */
+    model?: string;
+}
+/**
+ * POST-with-retry wrapper. Returns a successful Response (caller still parses
+ * the body). Throws a typed `LlmHttpError` on terminal failure.
+ */
+export declare function resilientFetch(opts: ResilientFetchOptions): Promise<Response>;
+/** Re-export the LlmHttpError type guard for callers that want to branch. */
+export { LlmHttpError };
+//# sourceMappingURL=fetch.d.ts.map

package/dist/llm/fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch.d.ts","sourceRoot":"","sources":["../../src/llm/fetch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EACL,YAAY,EAMb,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,qBAAqB;IACpC,oBAAoB;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,gFAAgF;IAChF,IAAI,EAAE,WAAW,CAAC;IAClB,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,2EAA2E;IAC3E,OAAO,EAAE,MAAM,CAAC;IAChB,oCAAoC;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,2CAA2C;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,wCAAwC;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,4BAA4B;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAID;;;GAGG;AACH,wBAAsB,cAAc,CAAC,IAAI,EAAE,qBAAqB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAgCnF;AAED,6EAA6E;AAC7E,OAAO,EAAE,YAAY,EAAE,CAAC"}

package/dist/llm/fetch.js

@@ -0,0 +1,52 @@
+/**
+ * Resilient JSON fetch helper for LLM and embedding providers.
+ *
+ * Adds three things to plain `fetch()`:
+ *   1. Per-request timeout (AbortSignal.timeout)
+ *   2. Retry on transient HTTP failures (5xx, 408, 425), rate-limits (429,
+ *      honouring Retry-After), and network errors
+ *   3. Typed error classification — see `./errors.ts`
+ *
+ * Mirrors the patterns used by `src/lib/qdrant-client.ts` so callers can rely
+ * on a single error hierarchy across LLM, embedding, and Qdrant.
+ */
+import { LlmHttpError, classifyFetchError, isRetryable, makeHttpError, parseRetryAfterMs, backoffDelayMs, } from "./errors.js";
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * POST-with-retry wrapper. Returns a successful Response (caller still parses
+ * the body). Throws a typed `LlmHttpError` on terminal failure.
+ */
+export async function resilientFetch(opts) {
+    const { url, init, timeoutMs, retries, baseDelayMs, capDelayMs, provider, model } = opts;
+    let attempt = 0;
+    for (;;) {
+        let resp;
+        try {
+            resp = await fetch(url, { ...init, signal: AbortSignal.timeout(timeoutMs) });
+        }
+        catch (e) {
+            const err = classifyFetchError(e, { provider, model });
+            if (isRetryable(err.kind) && attempt < retries) {
+                await sleep(backoffDelayMs({ attempt, baseMs: baseDelayMs, capMs: capDelayMs }));
+                attempt++;
+                continue;
+            }
+            throw err;
+        }
+        if (resp.ok)
+            return resp;
+        // Non-2xx — read body once for diagnostics.
+        const body = await resp.text().catch(() => "");
+        const retryAfterMs = parseRetryAfterMs(resp.headers.get("retry-after"));
+        const err = makeHttpError(resp.status, { provider, model, body, retryAfterMs });
+        if (isRetryable(err.kind) && attempt < retries) {
+            await sleep(backoffDelayMs({ attempt, baseMs: baseDelayMs, capMs: capDelayMs, retryAfterMs }));
+            attempt++;
+            continue;
+        }
+        throw err;
+    }
+}
+/** Re-export the LlmHttpError type guard for callers that want to branch. */
+export { LlmHttpError };
+//# sourceMappingURL=fetch.js.map

package/dist/llm/fetch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch.js","sourceRoot":"","sources":["../../src/llm/fetch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,WAAW,EACX,aAAa,EACb,iBAAiB,EACjB,cAAc,GACf,MAAM,aAAa,CAAC;AAqBrB,MAAM,KAAK,GAAG,CAAC,EAAU,EAAiB,EAAE,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;AAEnF;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,IAA2B;IAC9D,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,IAAI,CAAC;IACzF,IAAI,OAAO,GAAG,CAAC,CAAC;IAEhB,SAAS,CAAC;QACR,IAAI,IAAc,CAAC;QACnB,IAAI,CAAC;YACH,IAAI,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;QAC/E,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,MAAM,GAAG,GAAG,kBAAkB,CAAC,CAAC,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC;YACvD,IAAI,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,OAAO,GAAG,OAAO,EAAE,CAAC;gBAC/C,MAAM,KAAK,CAAC,cAAc,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC;gBACjF,OAAO,EAAE,CAAC;gBACV,SAAS;YACX,CAAC;YACD,MAAM,GAAG,CAAC;QACZ,CAAC;QAED,IAAI,IAAI,CAAC,EAAE;YAAE,OAAO,IAAI,CAAC;QAEzB,4CAA4C;QAC5C,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;QAC/C,MAAM,YAAY,GAAG,iBAAiB,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC;QACxE,MAAM,GAAG,GAAG,aAAa,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC,CAAC;QAEhF,IAAI,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,OAAO,GAAG,OAAO,EAAE,CAAC;YAC/C,MAAM,KAAK,CAAC,cAAc,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC;YAC/F,OAAO,EAAE,CAAC;YACV,SAAS;QACX,CAAC;QACD,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC;AAED,6EAA6E;AAC7E,OAAO,EAAE,YAAY,EAAE,CAAC"}

package/dist/llm/index.d.ts

@@ -1,4 +1,7 @@
-export type { EmbeddingProviderConfig, InferenceProviderConfig, ChatCompletionOpts, ResponseFormat, LogFn } from "./types.js";
-export { initEmbedding, embed, getEmbeddingConfig, getEmbeddingDimensions } from "./embedding.js";
-export { initLLM, chatCompletion } from "./inference.js";
+export type { LogFn } from "./types.js";
+export type { ResolvedEmbeddingConfig, EmbeddingProvider, InitEmbeddingInput } from "./embedding/index.js";
+export { initEmbedding, embed, getEmbeddingConfig, getEmbeddingDimensions, registerEmbeddingProvider, getEmbeddingProvider, listEmbeddingProviders, } from "./embedding/index.js";
+export type { ResolvedInferenceConfig, InferenceProvider, ChatCompletionOpts, InitLLMInput, } from "./inference/index.js";
+export type { ResponseFormat, JsonSchemaSpec } from "./inference/types.js";
+export { initLLM, chatCompletion, getInferenceConfig, registerInferenceProvider, getInferenceProvider, listInferenceProviders, } from "./inference/index.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/llm/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/llm/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,uBAAuB,EAAE,uBAAuB,EAAE,kBAAkB,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAC9H,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAClG,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/llm/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,YAAY,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC3G,OAAO,EACL,aAAa,EACb,KAAK,EACL,kBAAkB,EAClB,sBAAsB,EACtB,yBAAyB,EACzB,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,uBAAuB,EACvB,iBAAiB,EACjB,kBAAkB,EAClB,YAAY,GACb,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3E,OAAO,EACL,OAAO,EACP,cAAc,EACd,kBAAkB,EAClB,yBAAyB,EACzB,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,sBAAsB,CAAC"}

package/dist/llm/index.js

@@ -1,3 +1,3 @@
-export { initEmbedding, embed, getEmbeddingConfig, getEmbeddingDimensions } from "./embedding.js";
-export { initLLM, chatCompletion } from "./inference.js";
+export { initEmbedding, embed, getEmbeddingConfig, getEmbeddingDimensions, registerEmbeddingProvider, getEmbeddingProvider, listEmbeddingProviders, } from "./embedding/index.js";
+export { initLLM, chatCompletion, getInferenceConfig, registerInferenceProvider, getInferenceProvider, listInferenceProviders, } from "./inference/index.js";
 //# sourceMappingURL=index.js.map

package/dist/llm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/llm/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAClG,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/llm/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,aAAa,EACb,KAAK,EACL,kBAAkB,EAClB,sBAAsB,EACtB,yBAAyB,EACzB,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,sBAAsB,CAAC;AAQ9B,OAAO,EACL,OAAO,EACP,cAAc,EACd,kBAAkB,EAClB,yBAAyB,EACzB,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,sBAAsB,CAAC"}

package/dist/llm/inference/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Public API for the inference (chat completion) layer.
+ *
+ * Importing this module registers all bundled providers via the side-effect
+ * barrel, so callers only need to call `initLLM(...)` and `chatCompletion(...)`.
+ *
+ * Failure contract: provider `chat()` returns `null` on any failure (auth,
+ * rate-limit, transient, timeout). The reason is recorded internally; callers
+ * that need to surface it to the user can call `getLastInferenceError()`. The
+ * fallback chain in `chatCompletion()` retries the secondary provider once,
+ * then logs a consolidated error covering both attempts.
+ */
+import "./providers/index.js";
+import { getInferenceProvider, listInferenceProviders, registerInferenceProvider } from "./registry.js";
+import type { ChatCompletionOpts, InferenceProvider, InitLLMInput, LogFn, ResolvedInferenceConfig } from "./types.js";
+import { LlmHttpError } from "../errors.js";
+export declare function initLLM(opts: {
+    config: InitLLMInput;
+    logger?: LogFn;
+}): ResolvedInferenceConfig;
+export declare function getInferenceConfig(): ResolvedInferenceConfig;
+/**
+ * The most-recent classified error from the inference layer, or null if the
+ * last call succeeded. Used by MCP tools to surface a meaningful reason when
+ * `chatCompletion()` returns null.
+ */
+export declare function getLastInferenceError(): LlmHttpError | null;
+/**
+ * Internal hook used by providers to record the typed reason for a `null`
+ * return. Exported so providers in `./providers/*` can reach it; not part of
+ * the public API.
+ */
+export declare function _recordInferenceError(err: LlmHttpError | null): void;
+export declare function chatCompletion(opts: ChatCompletionOpts): Promise<string | null>;
+/** Test-only reset. */
+export declare function _resetInference(): void;
+export { registerInferenceProvider, getInferenceProvider, listInferenceProviders, };
+export type { InferenceProvider, ChatCompletionOpts, ResolvedInferenceConfig, InitLLMInput, };
+//# sourceMappingURL=index.d.ts.map

package/dist/llm/inference/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/llm/inference/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,sBAAsB,CAAC;AAE9B,OAAO,EACL,oBAAoB,EACpB,sBAAsB,EACtB,yBAAyB,EAC1B,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EACV,kBAAkB,EAClB,iBAAiB,EACjB,YAAY,EACZ,KAAK,EACL,uBAAuB,EACxB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAU5C,wBAAgB,OAAO,CAAC,IAAI,EAAE;IAAE,MAAM,EAAE,YAAY,CAAC;IAAC,MAAM,CAAC,EAAE,KAAK,CAAA;CAAE,GAAG,uBAAuB,CAgB/F;AAED,wBAAgB,kBAAkB,IAAI,uBAAuB,CAG5D;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,IAAI,YAAY,GAAG,IAAI,CAE3D;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI,GAAG,IAAI,CAEpE;AAED,wBAAsB,cAAc,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAqCrF;AAED,uBAAuB;AACvB,wBAAgB,eAAe,IAAI,IAAI,CAItC;AAkBD,OAAO,EACL,yBAAyB,EACzB,oBAAoB,EACpB,sBAAsB,GACvB,CAAC;AACF,YAAY,EACV,iBAAiB,EACjB,kBAAkB,EAClB,uBAAuB,EACvB,YAAY,GACb,CAAC"}