nlm-memory 0.5.0 → 0.5.2

package/src/llm/deepseek-client.ts

@@ -1,150 +0,0 @@
-/**
- * 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

@@ -1,55 +0,0 @@
-/**
- * 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

@@ -1,189 +0,0 @@
-/**
- * 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";
-  }
-}