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

package/src/readiness.ts

@@ -0,0 +1,203 @@
+/**
+ * Readiness sequence (spec.md §9.1), run exactly in the spec's order:
+ *
+ * 1. determine the effective endpoint;
+ * 2. check reachability;
+ * 3. check model availability;
+ * 4. pull the model in managed mode if needed;
+ * 5. produce a probe embedding;
+ * 6. validate the vector dimension;
+ * 7. cache profile and probe timestamp (done by the caller, `provider.ts`,
+ *    which owns the cached `EmbeddingReadinessV1`).
+ */
+import type { Clock, EmbeddingReadinessV1, Random } from "@untangle-code/domain";
+import { configInvalidError, embeddingUnavailableError } from "@untangle-code/observability";
+
+import type { BackoffConfig } from "./backoff.js";
+import { withRetry } from "./backoff.js";
+import { redactEndpointUrl } from "./endpoint.js";
+import { isRequestCancellation, OllamaHttpError, type OllamaHttpClient } from "./http.js";
+import {
+  embed,
+  listTags,
+  pullModel,
+  tagsContainModel,
+  type OllamaTagsResponseV1,
+} from "./ollama-api.js";
+import type { SleepFn, OllamaEmbeddingProviderConfig } from "./types.js";
+import { DEFAULT_MANAGED_URL, DEFAULT_NATIVE_PROBE_URL } from "./types.js";
+import { assertVectorDimension } from "./validation.js";
+
+export const READINESS_PROBE_TEXT = "untangle embedding readiness probe";
+
+export interface ReadinessDeps {
+  httpClient: OllamaHttpClient;
+  clock: Clock;
+  random: Random;
+  sleep: SleepFn;
+  backoffConfig: BackoffConfig;
+}
+
+export interface ReadinessOutcome {
+  readiness: EmbeddingReadinessV1;
+  /** The resolved, non-redacted endpoint — used internally for subsequent embed calls. */
+  endpointUrl: string;
+}
+
+function isRetryableOllamaError(error: unknown): boolean {
+  return error instanceof OllamaHttpError && error.retryable;
+}
+
+async function requestWithRetry<T>(
+  fn: () => Promise<T>,
+  deps: ReadinessDeps,
+  signal?: AbortSignal,
+): Promise<T> {
+  return withRetry(
+    fn,
+    deps.backoffConfig,
+    { random: deps.random, sleep: deps.sleep },
+    {
+      signal,
+      isRetryable: isRetryableOllamaError,
+    },
+  );
+}
+
+/** `GET /api/tags`, treating any failure as "not reachable" — EXCEPT cancellation, which propagates. */
+async function tryListTags(
+  url: string,
+  deps: ReadinessDeps,
+  signal?: AbortSignal,
+): Promise<OllamaTagsResponseV1 | null> {
+  try {
+    return await requestWithRetry(() => listTags(deps.httpClient, url, signal), deps, signal);
+  } catch (error) {
+    if (isRequestCancellation(error, signal)) {
+      throw error;
+    }
+    return null;
+  }
+}
+
+async function checkReachable(
+  url: string,
+  deps: ReadinessDeps,
+  signal?: AbortSignal,
+): Promise<OllamaTagsResponseV1> {
+  const tags = await tryListTags(url, deps, signal);
+  if (!tags) {
+    throw embeddingUnavailableError(`Ollama endpoint ${redactEndpointUrl(url)} is not reachable.`, {
+      retryable: true,
+      context: { endpoint: redactEndpointUrl(url) },
+    });
+  }
+  return tags;
+}
+
+interface ResolvedEndpoint {
+  url: string;
+  /** Whether this endpoint is one Untangle manages (spec.md §3.1) — safe to auto-pull models on it. */
+  managed: boolean;
+  tags: OllamaTagsResponseV1;
+}
+
+/** spec.md §9.1 steps 1-2: determine the effective endpoint and confirm it is reachable. */
+async function resolveEndpoint(
+  config: OllamaEmbeddingProviderConfig,
+  deps: ReadinessDeps,
+  signal?: AbortSignal,
+): Promise<ResolvedEndpoint> {
+  if (config.mode === "external") {
+    if (!config.url) {
+      throw configInvalidError(
+        'EmbeddingConfig.url is required when embeddings.mode is "external" (spec.md §4.5).',
+        { retryable: false },
+      );
+    }
+    return {
+      url: config.url,
+      managed: false,
+      tags: await checkReachable(config.url, deps, signal),
+    };
+  }
+  if (config.mode === "managed") {
+    const url = config.url ?? config.managedUrl ?? DEFAULT_MANAGED_URL;
+    return { url, managed: true, tags: await checkReachable(url, deps, signal) };
+  }
+  // "auto" (spec.md §3.1): native probe first, managed endpoint as fallback.
+  const nativeUrl = config.nativeProbeUrl ?? DEFAULT_NATIVE_PROBE_URL;
+  const nativeTags = await tryListTags(nativeUrl, deps, signal);
+  if (nativeTags) {
+    return { url: nativeUrl, managed: false, tags: nativeTags };
+  }
+  const managedUrl = config.url ?? config.managedUrl ?? DEFAULT_MANAGED_URL;
+  return { url: managedUrl, managed: true, tags: await checkReachable(managedUrl, deps, signal) };
+}
+
+export async function runReadinessSequence(
+  config: OllamaEmbeddingProviderConfig,
+  deps: ReadinessDeps,
+  signal?: AbortSignal,
+): Promise<ReadinessOutcome> {
+  const { url, managed, tags } = await resolveEndpoint(config, deps, signal);
+  const modelName = config.profile.model;
+
+  // Step 3: model availability.
+  let available = tagsContainModel(tags.models, modelName);
+
+  // Step 4: pull in managed mode if needed (spec.md §3.2 forbids touching an external endpoint).
+  if (!available) {
+    if (!managed) {
+      throw embeddingUnavailableError(
+        `Ollama model "${modelName}" is not available at ${redactEndpointUrl(url)}, and this endpoint is not managed by Untangle — pull it manually (spec.md §3.2).`,
+        { retryable: false, context: { endpoint: redactEndpointUrl(url), model: modelName } },
+      );
+    }
+    await requestWithRetry(() => pullModel(deps.httpClient, url, modelName, signal), deps, signal);
+    const refreshed = await requestWithRetry(
+      () => listTags(deps.httpClient, url, signal),
+      deps,
+      signal,
+    );
+    available = tagsContainModel(refreshed.models, modelName);
+    if (!available) {
+      throw embeddingUnavailableError(
+        `Ollama model "${modelName}" was still not available after pulling it from ${redactEndpointUrl(url)}.`,
+        { retryable: false, context: { endpoint: redactEndpointUrl(url), model: modelName } },
+      );
+    }
+  }
+
+  // Step 5: probe embedding.
+  const probeResponse = await requestWithRetry(
+    () => embed(deps.httpClient, url, modelName, [READINESS_PROBE_TEXT], signal),
+    deps,
+    signal,
+  );
+  const probeVector = probeResponse.embeddings[0];
+  if (!probeVector) {
+    throw embeddingUnavailableError(
+      `Ollama probe embedding returned no vector for model "${modelName}".`,
+      { retryable: false, context: { endpoint: redactEndpointUrl(url), model: modelName } },
+    );
+  }
+
+  // Step 6: dimension validation (must fail BEFORE the first upsert, spec.md §4.8).
+  assertVectorDimension(probeVector, config.profile.dimensions, {
+    endpoint: redactEndpointUrl(url),
+    model: modelName,
+    stage: "readiness_probe",
+  });
+
+  // Step 7: profile + probe timestamp are cached by the caller from this result.
+  return {
+    readiness: {
+      endpoint: redactEndpointUrl(url),
+      model: modelName,
+      dimensions: probeVector.length,
+      probedAt: deps.clock.nowIso(),
+    },
+    endpointUrl: url,
+  };
+}

package/src/sleep.ts

@@ -0,0 +1,27 @@
+/**
+ * Real, abortable {@link SleepFn} implementation. The only production
+ * implementation of the port declared in `types.ts`; tests inject a fake
+ * that resolves immediately instead of waiting for real time to pass.
+ */
+import type { SleepFn } from "./types.js";
+
+export const realSleep: SleepFn = (ms, signal) =>
+  new Promise<void>((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason);
+      return;
+    }
+    const timer = setTimeout(() => {
+      cleanup();
+      resolve();
+    }, ms);
+    const onAbort = (): void => {
+      cleanup();
+      reject(signal?.reason);
+    };
+    function cleanup(): void {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+    }
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });

package/src/truncation.ts

@@ -0,0 +1,41 @@
+/**
+ * Truncation guard (spec.md §9.3).
+ *
+ * Ollama's `/api/embed` truncates silently to the model's context window by
+ * default (`truncate: true`) and does not report, per input, whether
+ * truncation actually happened. The chunker (a separate package) is already
+ * responsible for keeping prepared text within budget in the normal case;
+ * this guard exists purely to catch the exceptional case where it did not
+ * and flag the resulting point honestly rather than silently accepting a
+ * vector computed from a truncated text (vision.md 8.4 "no silent data
+ * loss").
+ *
+ * Detection is a conservative, offline token estimate compared against the
+ * configured `contextLength` — the same trade-off `@untangle-code/chunker`
+ * makes for its own budget checks (over-estimating real BPE token counts is
+ * far safer than under-estimating, which would hide a real truncation).
+ * The estimator is intentionally duplicated rather than imported: chunker
+ * uses it to fit a budget ahead of time, this module uses it to flag a
+ * budget miss after the fact, and importing chunker here would add a
+ * runtime dependency between packages that otherwise have no reason to
+ * know about each other (rule 3 spirit).
+ */
+
+/** Conservative average characters per token — deliberately lower than the ~4 real average. */
+const CHARS_PER_TOKEN = 3;
+
+/** Estimates a conservative (over-)approximation of `text`'s token count. */
+export function estimateTokenCount(text: string): number {
+  if (text.length === 0) {
+    return 0;
+  }
+  return Math.max(1, Math.ceil(text.length / CHARS_PER_TOKEN));
+}
+
+/**
+ * True when `text`'s estimated token count exceeds `contextLength` — the
+ * point at which Ollama's provider-side truncation actually applies.
+ */
+export function wouldProviderTruncate(text: string, contextLength: number): boolean {
+  return estimateTokenCount(text) > contextLength;
+}

package/src/types.ts

@@ -0,0 +1,132 @@
+/**
+ * Local types for the Ollama `EmbeddingProvider` adapter (spec.md §9, §4.5;
+ * architecture.md §6.8).
+ */
+import type { EmbeddingProfile } from "@untangle-code/domain";
+
+/** Endpoint resolution mode (spec.md §4.5 `EmbeddingConfig.mode`). */
+export type OllamaEndpointMode = "auto" | "managed" | "external";
+
+/**
+ * Operational settings for one {@link OllamaEmbeddingProvider} instance.
+ *
+ * `profile` carries exactly the eight `EmbeddingProfile` fields that feed
+ * `embedding_profile_id` (spec.md §5.7) — everything else here is
+ * operational (endpoints, batching, timeouts) and deliberately NOT part of
+ * the profile, matching domain's `EmbeddingProfile` doc comment. Callers
+ * (typically `@untangle-code/config`'s `deriveEmbeddingProfile`) are
+ * responsible for assembling `profile` from the user's `EmbeddingConfig`;
+ * this package only consumes the result, keeping it decoupled from the
+ * config package (rule 3: no dependency on a package built in the same
+ * wave).
+ */
+export interface OllamaEmbeddingProviderConfig {
+  profile: EmbeddingProfile;
+  mode: OllamaEndpointMode;
+  /**
+   * Explicit endpoint override. Required when `mode` is `"external"`.
+   * When `mode` is `"managed"`, overrides {@link managedUrl}. Ignored in
+   * `"auto"` mode's native-probe step, but used as the managed fallback
+   * there too when set.
+   */
+  // Optional fields below spell out `| undefined` explicitly (rather than
+  // just `?:`) so callers under `exactOptionalPropertyTypes` — including
+  // this package's own test helper, which builds a config by spreading
+  // caller overrides over defaults — can assign `undefined` to force a
+  // field genuinely absent instead of merely "not overridden".
+  url?: string | undefined;
+  /** Name of the env var holding a bearer token; the token itself is never logged (spec.md §24). */
+  apiKeyEnv?: string | undefined;
+  /** Model context window in tokens, used only for the truncation guard (spec.md §9.3). */
+  contextLength: number;
+  /** Number of prepared texts sent per Ollama `/api/embed` request. */
+  batchSize: number;
+  /** Upper bound on concurrently in-flight HTTP requests to Ollama. */
+  maxConnections: number;
+  /** Per-request timeout in milliseconds. */
+  requestTimeoutMs: number;
+  /** Native Ollama probe URL for `"auto"` mode (spec.md §3.1 default). */
+  nativeProbeUrl?: string | undefined;
+  /** Managed-container endpoint default (spec.md §3.1 default port 11435). */
+  managedUrl?: string | undefined;
+  /** Maximum retry attempts per request before a transient error is treated as permanent. */
+  maxRetries?: number | undefined;
+  /** Base delay for exponential backoff (spec.md §9.2). */
+  baseBackoffMs?: number | undefined;
+  /** Backoff delay cap. */
+  maxBackoffMs?: number | undefined;
+}
+
+/** spec.md §3.1 defaults. */
+export const DEFAULT_NATIVE_PROBE_URL = "http://127.0.0.1:11434";
+export const DEFAULT_MANAGED_URL = "http://127.0.0.1:11435";
+
+export const DEFAULT_MAX_RETRIES = 5;
+export const DEFAULT_BASE_BACKOFF_MS = 250;
+export const DEFAULT_MAX_BACKOFF_MS = 8000;
+
+// ---------------------------------------------------------------------------
+// Embedding cache (spec.md §9.4)
+// ---------------------------------------------------------------------------
+
+/**
+ * Cache key per spec.md §9.4: `embedding_profile_id + SHA256(prepared_text)`.
+ * Kept as a structured object (rather than a pre-joined string) so a
+ * persistent implementation is free to choose its own storage shape.
+ */
+export interface EmbeddingCacheKey {
+  embeddingProfileId: string;
+  /** `SHA256(prepared_text)`, hex-encoded. */
+  preparedTextHash: string;
+}
+
+export interface EmbeddingCacheEntry {
+  vector: number[];
+  /** Whether provider-side truncation applied when this vector was produced (spec.md §9.3). */
+  truncated: boolean;
+}
+
+/**
+ * Narrow, storage-agnostic embedding cache port.
+ *
+ * NOT a `@untangle-code/domain` port — the task that produced this adapter
+ * defines it here deliberately so it can be exercised immediately, but this
+ * interface conceptually belongs in domain's `ports.ts` next to
+ * `EmbeddingProvider` so that `storage-local` (or any other persistent
+ * implementation) can implement a shared, versioned contract instead of a
+ * package-local one. Flagged in the WP-10 report's `openIssues` for a
+ * follow-up move.
+ */
+export interface EmbeddingCachePort {
+  get(
+    key: EmbeddingCacheKey,
+    options?: { signal?: AbortSignal | undefined },
+  ): Promise<EmbeddingCacheEntry | null>;
+  set(
+    key: EmbeddingCacheKey,
+    entry: EmbeddingCacheEntry,
+    options?: { signal?: AbortSignal | undefined },
+  ): Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// Sleep (backoff delay)
+// ---------------------------------------------------------------------------
+
+/**
+ * Injectable delay primitive for backoff waits (spec.md §9.2). Not a
+ * `@untangle-code/domain` port (domain has no scheduling port, only `Clock`
+ * for reading "now") — tests inject a fake that resolves instantly while
+ * still recording the requested delays, so the exponential-backoff schedule
+ * is asserted without the test suite actually waiting.
+ */
+export type SleepFn = (ms: number, signal?: AbortSignal) => Promise<void>;
+
+/** Progress reported once per network batch (spec.md §9.2 "Fortschritt MUSS pro Batch aktualisiert werden"). */
+export interface EmbeddingBatchProgressV1 {
+  batchIndex: number;
+  batchCount: number;
+  /** Texts embedded so far across all batches of this call, including cache hits. */
+  embeddedCount: number;
+  totalCount: number;
+}

package/src/validation.ts

@@ -0,0 +1,23 @@
+/**
+ * Vector-dimension validation (spec.md §9.1 step 6, §4.8 "Falsch
+ * konfigurierte Dimensionen MÜSSEN vor dem ersten Index-Upsert erkannt
+ * werden"). Applied both to the readiness probe vector and to every
+ * subsequent batch result — defense in depth, not just a one-time check.
+ */
+import { embeddingDimensionMismatchError } from "@untangle-code/observability";
+
+export function assertVectorDimension(
+  vector: number[],
+  expectedDimensions: number,
+  context: Record<string, unknown>,
+): void {
+  if (vector.length !== expectedDimensions) {
+    throw embeddingDimensionMismatchError(
+      `Ollama returned a ${vector.length}-dimensional vector but the embedding profile expects ${expectedDimensions} dimensions.`,
+      {
+        retryable: false,
+        context: { ...context, actualDimensions: vector.length, expectedDimensions },
+      },
+    );
+  }
+}