nlm-memory 0.4.0

package/src/llm/deepseek-client.ts

@@ -0,0 +1,150 @@
+/**
+ * DeepSeekClient — LLMClient backed by DeepSeek's OpenAI-compatible chat API.
+ *
+ * Use case (per Python notes confirmed 2026-05-07 / 2026-05-13):
+ *   • v4-flash handles inputs up to ~60K chars reliably; we cap at 30K to
+ *     stay well inside the deterministic zone.
+ *   • ~$0.002/session at typical sizes — full backfill of ~1,200 sessions
+ *     ≈ $2.50.
+ *   • Strong extraction quality (12+ entities, accurate decisions,
+ *     0.9 confidence) where phi4-mini struggles or times out.
+ *
+ * Same prompt module as OllamaClient — only the transport differs. Same
+ * error semantics: LLMUnreachableError for network/HTTP, ClassifierSchemaError
+ * for unparseable / shape-wrong output. Reads DEEPSEEK_API_KEY at construct
+ * time unless an explicit key is passed.
+ *
+ * Embedding is not supported by DeepSeek's API — `embed()` throws. Wire a
+ * separate embedder (OllamaClient) for semantic recall.
+ */
+
+import type {
+  ClassifyResult,
+  EmbedResult,
+  EmbeddingKind,
+  LLMClient,
+} from "@ports/llm-client.js";
+import { LLMUnreachableError } from "@ports/llm-client.js";
+import {
+  CLASSIFIER_SYSTEM_PROMPT,
+  buildUserPrompt,
+  coerceClassifyResult,
+  stripJsonFences,
+  validateClassifierJson,
+} from "@core/classifier/prompt.js";
+import { ClassifierSchemaError } from "./ollama-client.js";
+
+export type FetchImpl = typeof fetch;
+
+export interface DeepSeekClientOptions {
+  readonly apiKey?: string;
+  readonly baseUrl?: string;
+  readonly classifyModel?: string;
+  readonly classifyTimeoutMs?: number;
+  readonly maxTranscriptChars?: number;
+  readonly fetchImpl?: FetchImpl;
+}
+
+interface ChatResponse {
+  readonly choices?: ReadonlyArray<{ readonly message?: { readonly content?: string } }>;
+}
+
+export class DeepSeekClient implements LLMClient {
+  private readonly apiKey: string;
+  private readonly baseUrl: string;
+  private readonly classifyModel: string;
+  private readonly classifyTimeoutMs: number;
+  private readonly maxTranscriptChars: number;
+  private readonly fetchImpl: FetchImpl;
+
+  constructor(opts: DeepSeekClientOptions = {}) {
+    const key = opts.apiKey ?? process.env["DEEPSEEK_API_KEY"];
+    if (!key) {
+      throw new Error(
+        "DEEPSEEK_API_KEY not set. Export it, place it in ~/.nlm/.env, or pass apiKey explicitly.",
+      );
+    }
+    this.apiKey = key;
+    this.baseUrl = (opts.baseUrl ?? "https://api.deepseek.com/v1").replace(/\/+$/, "");
+    this.classifyModel = opts.classifyModel ?? "deepseek-v4-flash";
+    this.classifyTimeoutMs = opts.classifyTimeoutMs ?? 180_000;
+    this.maxTranscriptChars = opts.maxTranscriptChars ?? 30_000;
+    this.fetchImpl = opts.fetchImpl ?? fetch;
+  }
+
+  async embed(_text: string, _kind: EmbeddingKind): Promise<EmbedResult> {
+    throw new Error(
+      "DeepSeekClient.embed not supported — DeepSeek's API has no embeddings endpoint. Wire OllamaClient for embeddings.",
+    );
+  }
+
+  async classify(transcript: string, priorContext: string = ""): Promise<ClassifyResult> {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.classifyTimeoutMs);
+    try {
+      // DeepSeek's reliable zone is ≤30K, narrower than the prompt module's
+      // 15K default. We pre-truncate to our wider cap to feed the model more
+      // context than Ollama can handle, then buildUserPrompt's own truncation
+      // is a no-op.
+      const sized =
+        transcript.length <= this.maxTranscriptChars
+          ? transcript
+          : transcript.slice(0, this.maxTranscriptChars / 2 - 40) +
+            "\n\n[... transcript truncated; below is the closing portion ...]\n\n" +
+            transcript.slice(transcript.length - this.maxTranscriptChars / 2 + 40);
+      const userPrompt = buildUserPrompt(sized, priorContext);
+
+      const res = await this.fetchImpl(`${this.baseUrl}/chat/completions`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.apiKey}`,
+        },
+        body: JSON.stringify({
+          model: this.classifyModel,
+          messages: [
+            { role: "system", content: CLASSIFIER_SYSTEM_PROMPT },
+            { role: "user", content: userPrompt },
+          ],
+          response_format: { type: "json_object" },
+          temperature: 0.1,
+          // 8192 covers reasoning + JSON output. deepseek-v4-flash is a
+          // reasoning model — its hidden chain-of-thought counts against
+          // max_tokens but never reaches `content`. At 1024 the reasoning
+          // consumed the entire budget and the JSON output came back empty
+          // (finish_reason: length, content: ""). Backfill verified ~72% of
+          // real claude-code sessions hit that mode at 1024. Real-world
+          // observed reasoning_tokens: ~900-1100; JSON body adds 200-1000
+          // depending on facts/entity counts. 8192 leaves headroom.
+          max_tokens: 8192,
+          stream: false,
+        }),
+        signal: controller.signal,
+      });
+      if (!res.ok) {
+        throw new LLMUnreachableError(
+          "deepseek",
+          `status ${res.status}: ${await res.text().catch(() => "")}`,
+        );
+      }
+      const data = (await res.json()) as ChatResponse;
+      const rawContent = data.choices?.[0]?.message?.content?.trim() ?? "";
+      const content = stripJsonFences(rawContent);
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(content);
+      } catch {
+        throw new ClassifierSchemaError("deepseek returned non-JSON content");
+      }
+      if (!validateClassifierJson(parsed)) {
+        throw new ClassifierSchemaError("deepseek response missing required keys");
+      }
+      return coerceClassifyResult(parsed);
+    } catch (e) {
+      if (e instanceof LLMUnreachableError || e instanceof ClassifierSchemaError) throw e;
+      throw new LLMUnreachableError("deepseek", e);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+}

package/src/llm/env-autoload.ts

@@ -0,0 +1,55 @@
+/**
+ * Mirror of `classifier.autoload_env` from the Python daemon. Reads KEY=VALUE
+ * pairs from a small list of likely .env locations into process.env. Existing
+ * env vars are NOT overridden.
+ *
+ * Returns the list of paths actually loaded. Safe to call multiple times.
+ */
+
+import { readFileSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+
+const DEFAULT_SEARCH_PATHS = [
+  "~/.nlm/.env",
+  "./.env",
+  "../.env",
+  "../../.env",
+];
+
+function expandHome(p: string): string {
+  if (p.startsWith("~/")) return resolve(homedir(), p.slice(2));
+  return p;
+}
+
+export function autoloadEnv(extraPaths: ReadonlyArray<string> = []): string[] {
+  const loaded: string[] = [];
+  const paths = [...DEFAULT_SEARCH_PATHS, ...extraPaths];
+  for (const raw of paths) {
+    const path = expandHome(raw);
+    if (!existsSync(path)) continue;
+    try {
+      const content = readFileSync(path, "utf8");
+      for (const line of content.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#") || !trimmed.includes("=")) continue;
+        const eq = trimmed.indexOf("=");
+        const key = trimmed.slice(0, eq).trim();
+        let value = trimmed.slice(eq + 1).trim();
+        if (
+          (value.startsWith('"') && value.endsWith('"')) ||
+          (value.startsWith("'") && value.endsWith("'"))
+        ) {
+          value = value.slice(1, -1);
+        }
+        if (key && process.env[key] === undefined) {
+          process.env[key] = value;
+        }
+      }
+      loaded.push(path);
+    } catch {
+      continue;
+    }
+  }
+  return loaded;
+}

package/src/llm/ollama-client.ts

@@ -0,0 +1,189 @@
+/**
+ * OllamaClient — LLMClient backed by a local Ollama HTTP endpoint.
+ *
+ * embed()    → POST /api/embeddings  (nomic-embed-text by default)
+ * classify() → POST /api/chat        (phi4-mini by default, format=json)
+ *
+ * Network/HTTP failure maps to LLMUnreachableError so RecallService can
+ * degrade to keyword mode without crashing. Classification parse failures
+ * resolve to null (caller's choice whether to retry or route to inbox).
+ *
+ * Layering: this file lives in the outer ring. core/ depends on LLMClient,
+ * not on this concrete class. Tests can substitute a fake client.
+ */
+
+import type {
+  ClassifyResult,
+  EmbedResult,
+  EmbeddingKind,
+  LLMClient,
+} from "@ports/llm-client.js";
+import { LLMUnreachableError } from "@ports/llm-client.js";
+import {
+  CLASSIFIER_SYSTEM_PROMPT,
+  buildUserPrompt,
+  coerceClassifyResult,
+  stripJsonFences,
+  validateClassifierJson,
+} from "@core/classifier/prompt.js";
+
+export type FetchImpl = typeof fetch;
+
+// Tried raising 8000 → 28000 on 2026-05-25 to recover the answer-tail of
+// long gold sessions (median LongMemEval-S gold body is 14,294 chars). The
+// Ollama /api/embeddings endpoint returned 500 on 54% of those large
+// inputs despite nomic-embed-text's nominal 8192-token context — semantic
+// R@5 collapsed from 87.2% → 15.8%. Reverted. Real fix is chunk + max-pool
+// (each body split into ≤8K-char chunks, store all vectors, score against
+// max cosine at query time) so coverage doesn't depend on a single embed
+// call. Filed as #174.
+const MAX_EMBED_CHARS = 8_000;
+
+const EMBED_PREFIXES: Record<EmbeddingKind, string> = {
+  query: "search_query: ",
+  document: "search_document: ",
+};
+
+export function l2Normalize(vec: Float32Array): Float32Array {
+  let sumSq = 0;
+  for (let i = 0; i < vec.length; i++) {
+    const v = vec[i] ?? 0;
+    sumSq += v * v;
+  }
+  if (sumSq === 0) return vec;
+  const norm = Math.sqrt(sumSq);
+  const out = new Float32Array(vec.length);
+  for (let i = 0; i < vec.length; i++) {
+    out[i] = (vec[i] ?? 0) / norm;
+  }
+  return out;
+}
+
+export interface OllamaClientOptions {
+  readonly baseUrl?: string;
+  readonly embedModel?: string;
+  readonly classifyModel?: string;
+  readonly timeoutMs?: number;
+  readonly classifyTimeoutMs?: number;
+  /** Inject a fake fetch for tests. Defaults to global fetch. */
+  readonly fetchImpl?: FetchImpl;
+}
+
+interface EmbeddingsResponse {
+  readonly embedding?: ReadonlyArray<number>;
+}
+
+interface ChatResponse {
+  readonly message?: { readonly content?: string };
+}
+
+export class OllamaClient implements LLMClient {
+  private readonly baseUrl: string;
+  private readonly embedModel: string;
+  private readonly classifyModel: string;
+  private readonly timeoutMs: number;
+  private readonly classifyTimeoutMs: number;
+  private readonly fetchImpl: FetchImpl;
+
+  constructor(opts: OllamaClientOptions = {}) {
+    this.baseUrl = (opts.baseUrl ?? "http://localhost:11434").replace(/\/+$/, "");
+    this.embedModel = opts.embedModel ?? "nomic-embed-text";
+    this.classifyModel = opts.classifyModel ?? "phi4-mini:latest";
+    this.timeoutMs = opts.timeoutMs ?? 10_000;
+    this.classifyTimeoutMs = opts.classifyTimeoutMs ?? 180_000;
+    this.fetchImpl = opts.fetchImpl ?? fetch;
+  }
+
+  async embed(text: string, kind: EmbeddingKind): Promise<EmbedResult> {
+    // nomic-embed-text v1.5 is an asymmetric retrieval model. The
+    // search_query:/search_document: prefix is part of the training
+    // contract; omitting it or using the wrong one degrades retrieval
+    // quality measurably. MAX_EMBED_CHARS matches the Python ceiling.
+    const truncated = text.slice(0, MAX_EMBED_CHARS);
+    const prompt = `${EMBED_PREFIXES[kind]}${truncated}`;
+
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      const res = await this.fetchImpl(`${this.baseUrl}/api/embeddings`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ model: this.embedModel, prompt }),
+        signal: controller.signal,
+      });
+      if (!res.ok) {
+        throw new LLMUnreachableError("ollama", `status ${res.status}`);
+      }
+      const data = (await res.json()) as EmbeddingsResponse;
+      if (!data.embedding || data.embedding.length === 0) {
+        throw new LLMUnreachableError("ollama", "empty embedding");
+      }
+      const raw = new Float32Array(data.embedding);
+      return { vector: l2Normalize(raw), model: this.embedModel };
+    } catch (e) {
+      if (e instanceof LLMUnreachableError) throw e;
+      throw new LLMUnreachableError("ollama", e);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  /**
+   * Send a transcript through the Ollama classifier with the shared system
+   * prompt. Returns a ClassifyResult on success, or throws on network failure
+   * (LLMUnreachableError) or schema-invalid output (Error). The Python
+   * counterpart returned None on parse failure; we throw a typed error so
+   * callers explicitly handle retry / inbox routing rather than swallowing
+   * silent nulls.
+   */
+  async classify(transcript: string, priorContext: string = ""): Promise<ClassifyResult> {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.classifyTimeoutMs);
+    try {
+      const userPrompt = buildUserPrompt(transcript, priorContext);
+      const res = await this.fetchImpl(`${this.baseUrl}/api/chat`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          model: this.classifyModel,
+          messages: [
+            { role: "system", content: CLASSIFIER_SYSTEM_PROMPT },
+            { role: "user", content: userPrompt },
+          ],
+          stream: false,
+          format: "json",
+          options: { temperature: 0.1 },
+        }),
+        signal: controller.signal,
+      });
+      if (!res.ok) {
+        throw new LLMUnreachableError("ollama", `status ${res.status}`);
+      }
+      const data = (await res.json()) as ChatResponse;
+      const rawContent = data.message?.content?.trim() ?? "";
+      const content = stripJsonFences(rawContent);
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(content);
+      } catch {
+        throw new ClassifierSchemaError("ollama returned non-JSON content");
+      }
+      if (!validateClassifierJson(parsed)) {
+        throw new ClassifierSchemaError("ollama response missing required keys");
+      }
+      return coerceClassifyResult(parsed);
+    } catch (e) {
+      if (e instanceof LLMUnreachableError || e instanceof ClassifierSchemaError) throw e;
+      throw new LLMUnreachableError("ollama", e);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+}
+
+export class ClassifierSchemaError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ClassifierSchemaError";
+  }
+}