@untangle-code/embeddings-ollama 0.0.0-stage → 0.1.0

package/dist/http.js

@@ -0,0 +1,136 @@
+/**
+ * Minimal Ollama HTTP client on Node 22's built-in `fetch` (no HTTP client
+ * dependency, per the WP-10 task). Every request carries a timeout and
+ * respects an external `AbortSignal`; a bounded semaphore caps concurrently
+ * in-flight requests (spec.md §9.2 "Verbindungslimit").
+ */
+import { joinUrl } from "./endpoint.js";
+/** Thrown by {@link OllamaHttpClient.requestJson} for any failed request. */
+export class OllamaHttpError extends Error {
+    status;
+    retryable;
+    constructor(message, options) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = "OllamaHttpError";
+        this.status = options.status;
+        this.retryable = options.retryable;
+    }
+}
+/** Thrown when a request is aborted by the CALLER's own signal (never retried). */
+export class OllamaRequestCancelledError extends Error {
+    constructor(cause) {
+        super("Ollama request cancelled", cause === undefined ? undefined : { cause });
+        this.name = "OllamaRequestCancelledError";
+    }
+}
+/**
+ * True for anything that represents the CALLER's own cancellation rather
+ * than a transport failure: an {@link OllamaRequestCancelledError}, a raw
+ * `AbortError` (e.g. from `backoff.ts`'s own `signal.throwIfAborted()`
+ * pre-check, which runs before this client gets a chance to wrap it), or
+ * simply `signal.aborted` already being true by the time the error is
+ * observed. Used everywhere this adapter must tell "the caller cancelled"
+ * apart from "the endpoint is unreachable" (rule 9: cancellation surfaces as
+ * `JOB_CANCELLED`, never as a swallowed/misclassified failure).
+ */
+export function isRequestCancellation(error, signal) {
+    return (error instanceof OllamaRequestCancelledError ||
+        (error instanceof DOMException && error.name === "AbortError") ||
+        signal?.aborted === true);
+}
+function isRetryableStatus(status) {
+    return status === 429 || status >= 500;
+}
+/** Counting semaphore bounding concurrent HTTP requests to one Ollama endpoint. */
+class Semaphore {
+    available;
+    waiters = [];
+    constructor(limit) {
+        this.available = Math.max(1, limit);
+    }
+    async acquire() {
+        if (this.available > 0) {
+            this.available -= 1;
+            return () => this.release();
+        }
+        await new Promise((resolve) => this.waiters.push(resolve));
+        this.available -= 1;
+        return () => this.release();
+    }
+    release() {
+        this.available += 1;
+        const next = this.waiters.shift();
+        if (next) {
+            next();
+        }
+    }
+}
+export class OllamaHttpClient {
+    semaphore;
+    fetchImpl;
+    requestTimeoutMs;
+    apiKeyEnv;
+    constructor(options) {
+        this.semaphore = new Semaphore(options.maxConnections);
+        this.fetchImpl = options.fetchImpl ?? fetch;
+        this.requestTimeoutMs = options.requestTimeoutMs;
+        this.apiKeyEnv = options.apiKeyEnv;
+    }
+    /**
+     * Sends one JSON request and parses a JSON response. Never retries by
+     * itself — callers wrap this in `backoff.ts`'s `withRetry`.
+     *
+     * Throws {@link OllamaRequestCancelledError} when `signal` (the caller's
+     * own signal, not the internal timeout) is the reason for the abort, and
+     * {@link OllamaHttpError} for every other failure (network error, timeout,
+     * non-2xx status), with `retryable` set per spec.md §9.2's transient/
+     * permanent split.
+     */
+    async requestJson(baseUrl, path, init, signal) {
+        if (signal?.aborted) {
+            throw new OllamaRequestCancelledError(signal.reason);
+        }
+        const release = await this.semaphore.acquire();
+        try {
+            const timeoutSignal = AbortSignal.timeout(this.requestTimeoutMs);
+            const combinedSignal = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
+            const headers = { "content-type": "application/json" };
+            const token = this.apiKeyEnv ? process.env[this.apiKeyEnv] : undefined;
+            if (token) {
+                headers["authorization"] = `Bearer ${token}`;
+            }
+            let response;
+            try {
+                response = await this.fetchImpl(joinUrl(baseUrl, path), {
+                    method: init.method,
+                    headers,
+                    signal: combinedSignal,
+                    // Conditionally spread rather than `body: undefined` — RequestInit's
+                    // `body` has no `| undefined` arm, so exactOptionalPropertyTypes
+                    // forbids assigning it explicitly (a GET request has no body).
+                    ...(init.body === undefined ? {} : { body: JSON.stringify(init.body) }),
+                });
+            }
+            catch (error) {
+                if (signal?.aborted) {
+                    throw new OllamaRequestCancelledError(error);
+                }
+                // Network failure (connection refused, DNS, our own timeout) — transient.
+                throw new OllamaHttpError(`Ollama request to ${path} failed: ${String(error)}`, {
+                    retryable: true,
+                    cause: error,
+                });
+            }
+            if (!response.ok) {
+                const bodyText = await response.text().catch(() => "");
+                throw new OllamaHttpError(`Ollama request to ${path} returned HTTP ${response.status}: ${bodyText.slice(0, 500)}`, { status: response.status, retryable: isRetryableStatus(response.status) });
+            }
+            const text = await response.text();
+            return text.length === 0 ? undefined : JSON.parse(text);
+        }
+        finally {
+            release();
+        }
+    }
+}
+//# sourceMappingURL=http.js.map

package/dist/http.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @untangle-code/embeddings-ollama — `EmbeddingProvider` adapter for Ollama
+ * (spec.md §9, architecture.md §6.8). This module is the only public export
+ * of the package (rule 11); everything else (`http.ts`, `ollama-api.ts`,
+ * `readiness.ts`, `backoff.ts`, `concurrency.ts`, `truncation.ts`,
+ * `endpoint.ts`, `validation.ts`) is an internal implementation detail,
+ * imported directly only by this package's own co-located tests.
+ */
+export * from "./provider.js";
+export * from "./types.js";
+export * from "./cache.js";
+export * from "./sleep.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,cAAc,eAAe,CAAC;AAG9B,cAAc,YAAY,CAAC;AAG3B,cAAc,YAAY,CAAC;AAI3B,cAAc,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,18 @@
+/**
+ * @untangle-code/embeddings-ollama — `EmbeddingProvider` adapter for Ollama
+ * (spec.md §9, architecture.md §6.8). This module is the only public export
+ * of the package (rule 11); everything else (`http.ts`, `ollama-api.ts`,
+ * `readiness.ts`, `backoff.ts`, `concurrency.ts`, `truncation.ts`,
+ * `endpoint.ts`, `validation.ts`) is an internal implementation detail,
+ * imported directly only by this package's own co-located tests.
+ */
+// The adapter itself.
+export * from "./provider.js";
+// Public configuration and port types.
+export * from "./types.js";
+// Default in-memory embedding cache (spec.md §9.4) — the port itself lives in types.ts.
+export * from "./cache.js";
+// Real (non-fake) sleep implementation, exported so callers assembling
+// `OllamaEmbeddingProviderDeps` outside tests don't need to reimplement it.
+export * from "./sleep.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,sBAAsB;AACtB,cAAc,eAAe,CAAC;AAE9B,uCAAuC;AACvC,cAAc,YAAY,CAAC;AAE3B,wFAAwF;AACxF,cAAc,YAAY,CAAC;AAE3B,uEAAuE;AACvE,4EAA4E;AAC5E,cAAc,YAAY,CAAC"}

package/dist/inflight.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Single-flight / in-flight de-duplication primitives (spec.md §9.4, WP-78).
+ *
+ * Used to make sure a running async operation for a given key is REUSED by
+ * concurrent callers instead of started twice — both for embedding a
+ * not-yet-cached text (`provider.ts`'s `embedSlice`) and for the readiness
+ * sequence (`ensureReadyOnce`). Deliberately generic and cache-agnostic:
+ * these helpers only manage the "who is doing this right now" bookkeeping,
+ * never the cache or the network call itself.
+ */
+/** An externally-settleable promise: `resolve`/`reject` are exposed to the caller. */
+export interface Deferred<T> {
+    promise: Promise<T>;
+    resolve: (value: T) => void;
+    reject: (reason: unknown) => void;
+}
+/** Creates a {@link Deferred}. The executor runs synchronously, so both fields are always assigned. */
+export declare function createDeferred<T>(): Deferred<T>;
+/**
+ * Awaits `shared` — a promise potentially also being awaited by OTHER
+ * callers — but lets THIS caller's own `signal` reject early without
+ * affecting `shared` itself: the underlying operation keeps running (and
+ * other joined callers keep waiting on it) even after one waiter's own
+ * signal aborts (WP-78 requirement: one waiter's cancellation must not
+ * cancel the operation for everyone else).
+ */
+export declare function raceWithSignal<T>(shared: Promise<T>, signal: AbortSignal | undefined): Promise<T>;
+/**
+ * Registry of in-flight operations keyed by an arbitrary string. `claim`
+ * MUST be called synchronously (no `await`) between checking for an
+ * existing entry and registering a new one — see call sites in
+ * `provider.ts` — so that two concurrent callers observing the same "no
+ * entry yet" state cannot both start the operation (the actual JS-level
+ * atomicity comes from there being no `await` in the claiming code, not
+ * from this class).
+ */
+export declare class InFlightRegistry<T> {
+    private readonly entries;
+    /** Returns the in-flight promise for `key`, if any is currently registered. */
+    get(key: string): Promise<T> | undefined;
+    /**
+     * Registers `promise` as the in-flight operation for `key`. The entry is
+     * removed automatically once `promise` settles — successfully or not — so
+     * a failed attempt frees the key immediately for a fresh retry (WP-78:
+     * "ein Fehlschlag den Eintrag wieder freigibt").
+     */
+    register(key: string, promise: Promise<T>): void;
+}
+//# sourceMappingURL=inflight.d.ts.map

package/dist/inflight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inflight.d.ts","sourceRoot":"","sources":["../src/inflight.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,sFAAsF;AACtF,MAAM,WAAW,QAAQ,CAAC,CAAC;IACzB,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IACpB,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;IAC5B,MAAM,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;CACnC;AAED,uGAAuG;AACvG,wBAAgB,cAAc,CAAC,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAQ/C;AAMD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,OAAO,CAAC,CAAC,CAAC,CAuBjG;AAED;;;;;;;;GAQG;AACH,qBAAa,gBAAgB,CAAC,CAAC;IAC7B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiC;IAEzD,+EAA+E;IACxE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,SAAS;IAI/C;;;;;OAKG;IACI,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI;CAYxD"}

package/dist/inflight.js

@@ -0,0 +1,87 @@
+/**
+ * Single-flight / in-flight de-duplication primitives (spec.md §9.4, WP-78).
+ *
+ * Used to make sure a running async operation for a given key is REUSED by
+ * concurrent callers instead of started twice — both for embedding a
+ * not-yet-cached text (`provider.ts`'s `embedSlice`) and for the readiness
+ * sequence (`ensureReadyOnce`). Deliberately generic and cache-agnostic:
+ * these helpers only manage the "who is doing this right now" bookkeeping,
+ * never the cache or the network call itself.
+ */
+/** Creates a {@link Deferred}. The executor runs synchronously, so both fields are always assigned. */
+export function createDeferred() {
+    let resolve;
+    let reject;
+    const promise = new Promise((res, rej) => {
+        resolve = res;
+        reject = rej;
+    });
+    return { promise, resolve, reject };
+}
+function toAbortError(signal) {
+    return signal.reason instanceof Error ? signal.reason : new DOMException("Aborted", "AbortError");
+}
+/**
+ * Awaits `shared` — a promise potentially also being awaited by OTHER
+ * callers — but lets THIS caller's own `signal` reject early without
+ * affecting `shared` itself: the underlying operation keeps running (and
+ * other joined callers keep waiting on it) even after one waiter's own
+ * signal aborts (WP-78 requirement: one waiter's cancellation must not
+ * cancel the operation for everyone else).
+ */
+export function raceWithSignal(shared, signal) {
+    if (!signal) {
+        return shared;
+    }
+    if (signal.aborted) {
+        return Promise.reject(toAbortError(signal));
+    }
+    return new Promise((resolve, reject) => {
+        const onAbort = () => {
+            reject(toAbortError(signal));
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+        shared.then((value) => {
+            signal.removeEventListener("abort", onAbort);
+            resolve(value);
+        }, (error) => {
+            signal.removeEventListener("abort", onAbort);
+            reject(error);
+        });
+    });
+}
+/**
+ * Registry of in-flight operations keyed by an arbitrary string. `claim`
+ * MUST be called synchronously (no `await`) between checking for an
+ * existing entry and registering a new one — see call sites in
+ * `provider.ts` — so that two concurrent callers observing the same "no
+ * entry yet" state cannot both start the operation (the actual JS-level
+ * atomicity comes from there being no `await` in the claiming code, not
+ * from this class).
+ */
+export class InFlightRegistry {
+    entries = new Map();
+    /** Returns the in-flight promise for `key`, if any is currently registered. */
+    get(key) {
+        return this.entries.get(key);
+    }
+    /**
+     * Registers `promise` as the in-flight operation for `key`. The entry is
+     * removed automatically once `promise` settles — successfully or not — so
+     * a failed attempt frees the key immediately for a fresh retry (WP-78:
+     * "ein Fehlschlag den Eintrag wieder freigibt").
+     */
+    register(key, promise) {
+        this.entries.set(key, promise);
+        // Void: this cleanup must never itself become an unhandled rejection —
+        // the caller is responsible for handling/propagating `promise`'s outcome.
+        void promise
+            .catch(() => undefined)
+            .finally(() => {
+            if (this.entries.get(key) === promise) {
+                this.entries.delete(key);
+            }
+        });
+    }
+}
+//# sourceMappingURL=inflight.js.map

package/dist/inflight.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inflight.js","sourceRoot":"","sources":["../src/inflight.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AASH,uGAAuG;AACvG,MAAM,UAAU,cAAc;IAC5B,IAAI,OAA4B,CAAC;IACjC,IAAI,MAAkC,CAAC;IACvC,MAAM,OAAO,GAAG,IAAI,OAAO,CAAI,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE;QAC1C,OAAO,GAAG,GAAG,CAAC;QACd,MAAM,GAAG,GAAG,CAAC;IACf,CAAC,CAAC,CAAC;IACH,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;AACtC,CAAC;AAED,SAAS,YAAY,CAAC,MAAmB;IACvC,OAAO,MAAM,CAAC,MAAM,YAAY,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,YAAY,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC;AACpG,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAI,MAAkB,EAAE,MAA+B;IACnF,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;QACnB,OAAO,OAAO,CAAC,MAAM,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC;IAC9C,CAAC;IACD,OAAO,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACxC,MAAM,OAAO,GAAG,GAAS,EAAE;YACzB,MAAM,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC;QAC/B,CAAC,CAAC;QACF,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1D,MAAM,CAAC,IAAI,CACT,CAAC,KAAK,EAAE,EAAE;YACR,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YAC7C,OAAO,CAAC,KAAK,CAAC,CAAC;QACjB,CAAC,EACD,CAAC,KAAc,EAAE,EAAE;YACjB,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YAC7C,MAAM,CAAC,KAAK,CAAC,CAAC;QAChB,CAAC,CACF,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,OAAO,gBAAgB;IACV,OAAO,GAAG,IAAI,GAAG,EAAsB,CAAC;IAEzD,+EAA+E;IACxE,GAAG,CAAC,GAAW;QACpB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC/B,CAAC;IAED;;;;;OAKG;IACI,QAAQ,CAAC,GAAW,EAAE,OAAmB;QAC9C,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QAC/B,uEAAuE;QACvE,0EAA0E;QAC1E,KAAK,OAAO;aACT,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC;aACtB,OAAO,CAAC,GAAG,EAAE;YACZ,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,OAAO,EAAE,CAAC;gBACtC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAC3B,CAAC;QACH,CAAC,CAAC,CAAC;IACP,CAAC;CACF"}

package/dist/ollama-api.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Typed slice of the Ollama HTTP API this adapter uses: `/api/tags` (model
+ * listing / reachability probe), `/api/pull` (managed-mode model fetch) and
+ * `/api/embed` (batch embedding). Shapes are the subset of each response
+ * this adapter reads — Ollama's actual responses carry more fields.
+ */
+import type { OllamaHttpClient } from "./http.js";
+export interface OllamaTagV1 {
+    name: string;
+    model?: string;
+}
+export interface OllamaTagsResponseV1 {
+    models: OllamaTagV1[];
+}
+export interface OllamaPullResponseV1 {
+    status: string;
+}
+export interface OllamaEmbedResponseV1 {
+    model: string;
+    embeddings: number[][];
+}
+/** `GET /api/tags` — used both as the reachability probe and the model-availability check. */
+export declare function listTags(client: OllamaHttpClient, baseUrl: string, signal?: AbortSignal): Promise<OllamaTagsResponseV1>;
+/**
+ * True when `modelTags` (as returned by {@link listTags}) contains
+ * `modelName`. Ollama tag names carry an implicit `:latest` suffix when the
+ * configured model name has none, so `"nomic-embed-text"` must match a tag
+ * named `"nomic-embed-text:latest"`.
+ */
+export declare function tagsContainModel(modelTags: OllamaTagV1[], modelName: string): boolean;
+/**
+ * `POST /api/pull` with `stream: false` — Ollama blocks until the pull
+ * completes (or fails) and returns a single JSON response, which keeps this
+ * call symmetric with every other request this client makes (one request,
+ * one JSON response, no NDJSON stream parsing).
+ */
+export declare function pullModel(client: OllamaHttpClient, baseUrl: string, modelName: string, signal?: AbortSignal): Promise<OllamaPullResponseV1>;
+/**
+ * `POST /api/embed`. `truncate: true` keeps Ollama's own truncation active
+ * as the last-resort safety net spec.md §9.3 describes; this adapter's own
+ * truncation guard (`truncation.ts`) decides the `embedding_truncated`
+ * payload flag independently of whether the server actually had to use it.
+ */
+export declare function embed(client: OllamaHttpClient, baseUrl: string, modelName: string, input: string[], signal?: AbortSignal): Promise<OllamaEmbedResponseV1>;
+//# sourceMappingURL=ollama-api.d.ts.map

package/dist/ollama-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ollama-api.d.ts","sourceRoot":"","sources":["../src/ollama-api.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAElD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,WAAW,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,EAAE,EAAE,CAAC;CACxB;AAED,8FAA8F;AAC9F,wBAAsB,QAAQ,CAC5B,MAAM,EAAE,gBAAgB,EACxB,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,oBAAoB,CAAC,CAE/B;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,WAAW,EAAE,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAUrF;AAED;;;;;GAKG;AACH,wBAAsB,SAAS,CAC7B,MAAM,EAAE,gBAAgB,EACxB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,oBAAoB,CAAC,CAO/B;AAED;;;;;GAKG;AACH,wBAAsB,KAAK,CACzB,MAAM,EAAE,gBAAgB,EACxB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EAAE,EACf,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,qBAAqB,CAAC,CAOhC"}

package/dist/ollama-api.js

@@ -0,0 +1,40 @@
+/** `GET /api/tags` — used both as the reachability probe and the model-availability check. */
+export async function listTags(client, baseUrl, signal) {
+    return client.requestJson(baseUrl, "api/tags", { method: "GET" }, signal);
+}
+/**
+ * True when `modelTags` (as returned by {@link listTags}) contains
+ * `modelName`. Ollama tag names carry an implicit `:latest` suffix when the
+ * configured model name has none, so `"nomic-embed-text"` must match a tag
+ * named `"nomic-embed-text:latest"`.
+ */
+export function tagsContainModel(modelTags, modelName) {
+    const wantsTag = modelName.includes(":");
+    return modelTags.some((tag) => {
+        const tagName = tag.name;
+        if (wantsTag) {
+            return tagName === modelName;
+        }
+        const [tagBase] = tagName.split(":");
+        return tagBase === modelName;
+    });
+}
+/**
+ * `POST /api/pull` with `stream: false` — Ollama blocks until the pull
+ * completes (or fails) and returns a single JSON response, which keeps this
+ * call symmetric with every other request this client makes (one request,
+ * one JSON response, no NDJSON stream parsing).
+ */
+export async function pullModel(client, baseUrl, modelName, signal) {
+    return client.requestJson(baseUrl, "api/pull", { method: "POST", body: { model: modelName, stream: false } }, signal);
+}
+/**
+ * `POST /api/embed`. `truncate: true` keeps Ollama's own truncation active
+ * as the last-resort safety net spec.md §9.3 describes; this adapter's own
+ * truncation guard (`truncation.ts`) decides the `embedding_truncated`
+ * payload flag independently of whether the server actually had to use it.
+ */
+export async function embed(client, baseUrl, modelName, input, signal) {
+    return client.requestJson(baseUrl, "api/embed", { method: "POST", body: { model: modelName, input, truncate: true } }, signal);
+}
+//# sourceMappingURL=ollama-api.js.map

package/dist/ollama-api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ollama-api.js","sourceRoot":"","sources":["../src/ollama-api.ts"],"names":[],"mappings":"AA0BA,8FAA8F;AAC9F,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,MAAwB,EACxB,OAAe,EACf,MAAoB;IAEpB,OAAO,MAAM,CAAC,WAAW,CAAuB,OAAO,EAAE,UAAU,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,MAAM,CAAC,CAAC;AAClG,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,SAAwB,EAAE,SAAiB;IAC1E,MAAM,QAAQ,GAAG,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;IACzC,OAAO,SAAS,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE;QAC5B,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,CAAC;QACzB,IAAI,QAAQ,EAAE,CAAC;YACb,OAAO,OAAO,KAAK,SAAS,CAAC;QAC/B,CAAC;QACD,MAAM,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACrC,OAAO,OAAO,KAAK,SAAS,CAAC;IAC/B,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,MAAwB,EACxB,OAAe,EACf,SAAiB,EACjB,MAAoB;IAEpB,OAAO,MAAM,CAAC,WAAW,CACvB,OAAO,EACP,UAAU,EACV,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,EAC7D,MAAM,CACP,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,KAAK,CACzB,MAAwB,EACxB,OAAe,EACf,SAAiB,EACjB,KAAe,EACf,MAAoB;IAEpB,OAAO,MAAM,CAAC,WAAW,CACvB,OAAO,EACP,WAAW,EACX,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,EAAE,EACrE,MAAM,CACP,CAAC;AACJ,CAAC"}

package/dist/provider.d.ts

@@ -0,0 +1,111 @@
+/**
+ * `EmbeddingProvider` port implementation for Ollama (domain `ports.ts`,
+ * spec.md §9, architecture.md §6.8).
+ */
+import type { Clock, EmbeddingBatchResultV1, EmbeddingProfile, EmbeddingProvider, EmbeddingReadinessV1, PortCallOptions, Random } from "@untangle-code/domain";
+import type { EmbeddingBatchProgressV1, EmbeddingCachePort, OllamaEmbeddingProviderConfig, SleepFn } from "./types.js";
+export interface OllamaEmbeddingProviderDeps {
+    clock: Clock;
+    random: Random;
+    /** Defaults to {@link InMemoryEmbeddingCache} (spec.md §9.4). */
+    cache?: EmbeddingCachePort;
+    /** Defaults to {@link realSleep}; tests inject a fake that resolves instantly. */
+    sleep?: SleepFn;
+    /** Defaults to the global `fetch`; tests inject a fake transport. */
+    fetchImpl?: typeof fetch;
+}
+export declare class OllamaEmbeddingProvider implements EmbeddingProvider {
+    readonly profile: EmbeddingProfile;
+    readonly profileId: string;
+    private readonly config;
+    private readonly clock;
+    private readonly random;
+    private readonly cache;
+    private readonly sleep;
+    private readonly httpClient;
+    private readonly backoffConfig;
+    private cachedReadiness;
+    private resolvedEndpointUrl;
+    private readyPromise;
+    /**
+     * One shared fetch-and-cache operation per still-uncached cache key
+     * (spec.md §9.4, WP-78): concurrent `embedDocuments`/`embedQuery` calls
+     * that race for the same not-yet-cached text join the SAME `/api/embed`
+     * request instead of each starting their own.
+     */
+    private readonly inFlightEmbeds;
+    constructor(config: OllamaEmbeddingProviderConfig, deps: OllamaEmbeddingProviderDeps);
+    ensureReady(options?: PortCallOptions): Promise<EmbeddingReadinessV1>;
+    embedDocuments(preparedTexts: string[], options?: PortCallOptions & {
+        onBatchProgress?: (progress: EmbeddingBatchProgressV1) => void;
+    }): Promise<EmbeddingBatchResultV1>;
+    embedQuery(preparedText: string, options?: PortCallOptions): Promise<number[]>;
+    /**
+     * Runs the readiness sequence exactly once per instance; concurrent
+     * callers (including through model-pull, spec.md §9.1 step 4) await the
+     * SAME run rather than each starting their own (WP-78 fehlerklasse: the
+     * same in-flight-dedup requirement applies here, not just to `/api/embed`).
+     *
+     * The shared run itself is started with NO caller's `signal` (it is
+     * intentionally not tied to whichever caller happened to trigger it) —
+     * `raceWithSignal` below still lets THIS caller's own signal reject its
+     * own wait promptly, without cancelling the readiness sequence still
+     * running for other, still-waiting callers.
+     */
+    private ensureReadyOnce;
+    private runReadiness;
+    private embedTexts;
+    private embedSlice;
+    /**
+     * Fetches every text in `items` in a SINGLE `/api/embed` request and
+     * settles each item's `deferred` with its own resulting cache entry, or
+     * rejects all of them on failure — which also frees their in-flight slots
+     * (`InFlightRegistry.register`'s cleanup), so the next call retries from
+     * scratch rather than being stuck on a broken promise (WP-78).
+     *
+     * Vor dem Absetzen des Requests wird der Cache ein ZWEITES Mal gelesen
+     * (WP-117, siehe {@link revalidateBeforeFetch}): die Miss-Entscheidung in
+     * `embedSlice` kann veraltet sein, sobald `cache.get()` verzögert auflöst.
+     *
+     * Intentionally takes no `AbortSignal`: this operation is shared by
+     * however many callers joined it, so it is not tied to any single one of
+     * their lifecycles (see `embedSlice`/`raceWithSignal`).
+     */
+    private fetchAndSettle;
+    /**
+     * Zweite Cache-Prüfung unmittelbar vor dem Request (WP-117).
+     *
+     * `embedSlice` trifft die Miss-/Join-Entscheidung EINMAL, aus einem
+     * einzigen `Promise.all` über `cache.get()`. Ein Cache, dessen `get()` den
+     * Zustand zum Aufrufzeitpunkt liest, aber erst später auflöst — also jeder
+     * netzgebundene Cache und damit genau der vorgesehene Erweiterungspunkt
+     * für einen persistenten Adapter —, öffnet ein Fenster: Aufrufer A kann
+     * zwischen der Anfrage und dem Auflösen von B's `get()` vollständig fertig
+     * werden, seinen Eintrag schreiben und seinen In-flight-Platz wieder
+     * freigeben. B fände dann weder Cache-Treffer noch In-flight-Eintrag und
+     * würde denselben Text ein zweites Mal einbetten.
+     *
+     * Diese Prüfung schließt das Fenster, weil sie STRIKT NACH der Beanspruchung
+     * des In-flight-Platzes liegt: der Platz wird erst freigegeben, nachdem
+     * `cache.set()` aufgelöst hat (siehe unten), also sieht ein `get()`, das
+     * danach abgesetzt wird, den geschriebenen Eintrag.
+     *
+     * Kein Deadlock und keine Wiederholungsschleife: genau EIN zusätzliches
+     * `cache.get()` je beanspruchtem Schlüssel, kein Warten auf fremde
+     * Deferreds (die eigenen Plätze hält dieser Aufruf selbst, ein anderer
+     * Aufrufer kann sie also nicht beanspruchen), und jedes Deferred wird auf
+     * jedem Pfad festgelegt — aus dem Cache, aus der Antwort oder per
+     * `reject` im `catch`.
+     *
+     * Kein `AbortSignal`: dieser Lauf gehört keinem einzelnen Aufrufer
+     * (dieselbe Begründung wie bei {@link fetchAndSettle}).
+     *
+     * Ein Fehler des Caches wird NICHT verschluckt (E4), sondern nach oben
+     * gereicht und weist damit die beteiligten Deferreds ab — dasselbe
+     * sichtbare Verhalten wie bei einem Fehlschlag der ERSTEN Cache-Lesung in
+     * `embedSlice`. Preis dieser Prüfung: eine zusätzliche Cache-Lesung je
+     * echtem Miss (dokumentiert in der README).
+     */
+    private revalidateBeforeFetch;
+}
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EACV,KAAK,EACL,sBAAsB,EACtB,gBAAgB,EAChB,iBAAiB,EACjB,oBAAoB,EACpB,eAAe,EACf,MAAM,EACP,MAAM,uBAAuB,CAAC;AAe/B,OAAO,KAAK,EACV,wBAAwB,EAGxB,kBAAkB,EAClB,6BAA6B,EAC7B,OAAO,EACR,MAAM,YAAY,CAAC;AAIpB,MAAM,WAAW,2BAA2B;IAC1C,KAAK,EAAE,KAAK,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,KAAK,CAAC,EAAE,kBAAkB,CAAC;IAC3B,kFAAkF;IAClF,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,qEAAqE;IACrE,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAoED,qBAAa,uBAAwB,YAAW,iBAAiB;IAC/D,SAAgB,OAAO,EAAE,gBAAgB,CAAC;IAC1C,SAAgB,SAAS,EAAE,MAAM,CAAC;IAElC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgC;IACvD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;IAC9B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqB;IAC3C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAU;IAChC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAmB;IAC9C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgB;IAE9C,OAAO,CAAC,eAAe,CAAmC;IAC1D,OAAO,CAAC,mBAAmB,CAAqB;IAChD,OAAO,CAAC,YAAY,CAA4B;IAEhD;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA+C;gBAE3D,MAAM,EAAE,6BAA6B,EAAE,IAAI,EAAE,2BAA2B;IAqB9E,WAAW,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAQrE,cAAc,CACzB,aAAa,EAAE,MAAM,EAAE,EACvB,OAAO,CAAC,EAAE,eAAe,GAAG;QAAE,eAAe,CAAC,EAAE,CAAC,QAAQ,EAAE,wBAAwB,KAAK,IAAI,CAAA;KAAE,GAC7F,OAAO,CAAC,sBAAsB,CAAC;IAUrB,UAAU,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAQ3F;;;;;;;;;;;OAWG;YACW,eAAe;YAcf,YAAY;YAgBZ,UAAU;YAwCV,UAAU;IA6FxB;;;;;;;;;;;;;;OAcG;YACW,cAAc;IA8C5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;YACW,qBAAqB;CAiBpC"}