@orquentra/codebuddy 2.6.0 → 2.7.0

package/CLAUDE_CODEX.md

@@ -266,8 +266,8 @@ Create `.mcp.json`:
       "args": ["serve"],
       "env": {
         "DATABASE_URL": "postgres://codebuddy:codebuddy@localhost:5432/codebuddy",
-        "HF_TOKEN": "hf_your_token",
-        "CODEBUDDY_NAMESPACE": "your-project"
+        "CODEBUDDY_NAMESPACE": "your-project",
+        "CODEBUDDY_PROJECT_ROOT": "/absolute/path/to/your-project"
       }
     }
   }
@@ -338,7 +338,7 @@ args = ["serve"]
 [mcp_servers."codebuddy-your-project".env]
 CODEBUDDY_NAMESPACE = "your-project"
 DATABASE_URL = "postgres://codebuddy:codebuddy@localhost:5432/codebuddy"
-HF_TOKEN = "hf_your_token"
+CODEBUDDY_PROJECT_ROOT = "/absolute/path/to/your-project"
 ```
 
 Restart Codex after installing or changing an MCP entry.
@@ -413,7 +413,9 @@ codebuddy migrate
 If Claude Code does not show CodeBuddy tools:
 
 - confirm `.mcp.json` is in the project root
-- confirm `HF_TOKEN`, `DATABASE_URL`, and `CODEBUDDY_NAMESPACE`
+- confirm `DATABASE_URL`, `CODEBUDDY_NAMESPACE`, and that the server starts in (or
+  `CODEBUDDY_PROJECT_ROOT` points to) a folder with `.codebuddy/config.json`.
+  `HF_TOKEN` is needed only for `provider.type: "huggingface"`.
 - restart Claude Code
 
 If Codex does not show CodeBuddy tools:

package/WORKFLOW.md

@@ -12,7 +12,7 @@ CodeBuddy is a shared notebook for AI agents.
 - Embeddings are prepared in the background so related memories can be found later.
 - When an agent asks a question, CodeBuddy picks the most useful memories that fit inside the token budget.
 - Agents can share facts with other agents through namespaces.
-- The CLI helps you see whether the database, Hugging Face models, and memory index are healthy.
+- The CLI helps you see whether the database, the embedding model (local by default), and memory index are healthy (`codebuddy doctor`, `codebuddy models`).
 
 ## Graphical Flow
 
@@ -38,7 +38,7 @@ CodeBuddy Core
      |
      +--> In-process embedding worker
      |      |
-     |      +--> Hugging Face resilience layer
+     |      +--> embedding provider (local model by default; Hugging Face or OpenRouter optional)
      |      |      |
      |      |      +--> retry/backoff
      |      |      +--> cold-start wait
@@ -71,7 +71,7 @@ Planner packs best items under token budget
 5. In one transaction, it writes the memory row and creates an embedding row with `status=pending`.
 6. For facts and summaries, it also writes a Markdown file.
 7. If the same content or idempotency key already exists, it returns the original ID with `deduplicated: true`.
-8. After the transaction, the in-process worker asks Hugging Face for embeddings.
+8. After the transaction, the in-process worker asks the embedding provider (the local model by default) for embeddings.
 9. The embedding row becomes `ready` or `failed`.
 
 ## Migration And Recovery Flow
@@ -130,7 +130,7 @@ source delete          ---> B remains
 - database connection
 - `pgvector` extension
 - vector index health
-- Hugging Face model reachability
+- embedding model readiness (`codebuddy models`)
 - gated model errors
 - cold vs warm model state
 - rate-limit pressure
@@ -140,7 +140,7 @@ source delete          ---> B remains
 
 ## Why Async Embeddings Matter
 
-Hugging Face free-tier models can be cold or rate-limited. CodeBuddy should not block a memory write just because a model needs time to wake up. It stores the memory first, marks the embedding as pending, and lets recall use recency until vectors are ready.
+A hosted embedding API can be cold or rate-limited, and the local model downloads once on first use. CodeBuddy should not block a memory write just because a model needs time to wake up. It stores the memory first, marks the embedding as pending, and lets recall use recency until vectors are ready.
 
 ## What The User Sees
 

package/dist/{chunk-U4HAJLIB.js → chunk-3QGW53GD.js}

@@ -1,6 +1,6 @@
 import {
   LOCAL_EMBEDDING_MODEL
-} from "./chunk-JPHJBCZB.js";
+} from "./chunk-HPOR6YXA.js";
 
 // src/providers/local.ts
 import { homedir } from "os";
@@ -11,8 +11,19 @@ var extractor = null;
 function modelCacheDir() {
   return process.env.CODEBUDDY_MODEL_CACHE ?? join(homedir(), ".cache", "codebuddy", "models");
 }
+var MISSING_RUNTIME = "Local models need the optional package @huggingface/transformers, which is not installed; dense recall is off and keyword recall still works. Install it with: npm i -g @huggingface/transformers (or reinstall CodeBuddy without --omit=optional).";
+function localRuntimeInstalled() {
+  try {
+    import.meta.resolve("@huggingface/transformers");
+    return true;
+  } catch {
+    return false;
+  }
+}
 function loadTransformers() {
-  transformers ??= import("@huggingface/transformers").then((module) => {
+  transformers ??= import("@huggingface/transformers").catch((error) => {
+    throw error.code === "ERR_MODULE_NOT_FOUND" ? new Error(MISSING_RUNTIME) : error;
+  }).then((module) => {
     module.env.cacheDir = modelCacheDir();
     module.env.logLevel = module.LogLevel.ERROR;
     return module;
@@ -85,7 +96,9 @@ async function rerankLocally(model, query, documents) {
 
 export {
   modelCacheDir,
+  MISSING_RUNTIME,
+  localRuntimeInstalled,
   LocalModelProvider,
   rerankLocally
 };
-//# sourceMappingURL=chunk-U4HAJLIB.js.map
+//# sourceMappingURL=chunk-3QGW53GD.js.map

package/dist/chunk-3QGW53GD.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/providers/local.ts"],"sourcesContent":["import { homedir } from \"node:os\";\nimport { join } from \"node:path\";\nimport type {\n  EmbeddingRequest,\n  EmbeddingResponse,\n  ModelProvider,\n  TextGenerationResponse,\n} from \"./adapter.js\";\nimport type { EmbeddingSpace } from \"./embedding-space.js\";\nimport { LOCAL_EMBEDDING_MODEL } from \"./models.js\";\n\n/**\n * Local Hugging Face models through transformers.js (ONNX Runtime, CPU). The\n * weights download once into `~/.cache/codebuddy/models` (override with\n * `CODEBUDDY_MODEL_CACHE`); afterwards nothing leaves the machine and no token\n * is needed. `@huggingface/transformers` is an optional dependency, loaded on\n * first use, so a missing install only disables semantic ranking.\n */\n\ntype Transformers = typeof import(\"@huggingface/transformers\");\n/** The slice of transformers.js' FeatureExtractionPipeline used here. */\ntype Extractor = (\n  texts: string[],\n  options: { pooling: \"cls\"; normalize: boolean },\n) => Promise<{ tolist(): number[][] }>;\n\n/** Hard cap on a single input; ModernBERT reads 8k tokens, memories are far shorter. */\nconst MAX_INPUT_CHARS = 8_000;\n\nlet transformers: Promise<Transformers> | null = null;\nlet extractor: Promise<Extractor> | null = null;\n\nexport function modelCacheDir(): string {\n  return process.env.CODEBUDDY_MODEL_CACHE ?? join(homedir(), \".cache\", \"codebuddy\", \"models\");\n}\n\n/** Shown when the optional runtime was not installed (`npm i --omit=optional`, a failed native build). */\nexport const MISSING_RUNTIME =\n  \"Local models need the optional package @huggingface/transformers, which is not installed; \" +\n  \"dense recall is off and keyword recall still works. Install it with: npm i -g @huggingface/transformers \" +\n  \"(or reinstall CodeBuddy without --omit=optional).\";\n\n/** Whether the optional local-model runtime can be loaded, without loading it. */\nexport function localRuntimeInstalled(): boolean {\n  try {\n    import.meta.resolve(\"@huggingface/transformers\");\n    return true;\n  } catch {\n    return false;\n  }\n}\n\nfunction loadTransformers(): Promise<Transformers> {\n  transformers ??= import(\"@huggingface/transformers\")\n    .catch((error: NodeJS.ErrnoException) => {\n      throw error.code === \"ERR_MODULE_NOT_FOUND\" ? new Error(MISSING_RUNTIME) : error;\n    })\n    .then((module) => {\n      module.env.cacheDir = modelCacheDir();\n      // Info/debug logs go to console.log, i.e. stdout: the MCP JSON-RPC channel\n      // under `codebuddy serve`. Errors only (they use stderr), here and in ONNX Runtime.\n      module.env.logLevel = module.LogLevel.ERROR;\n      return module;\n    });\n  // A failed import (optional dependency missing) is retried on the next call.\n  transformers.catch(() => {\n    transformers = null;\n  });\n  return transformers;\n}\n\nexport class LocalModelProvider implements ModelProvider {\n  readonly space: EmbeddingSpace = {\n    model: LOCAL_EMBEDDING_MODEL.id,\n    revision: LOCAL_EMBEDDING_MODEL.revision,\n    schema: LOCAL_EMBEDDING_MODEL.schema,\n    dimensions: LOCAL_EMBEDDING_MODEL.dimensions,\n  };\n\n  /** `request.model` is ignored: one provider is one embedding space. */\n  async embed(request: EmbeddingRequest): Promise<EmbeddingResponse> {\n    const inputs = (typeof request.input === \"string\" ? [request.input] : request.input).map(\n      (text) => text.slice(0, MAX_INPUT_CHARS),\n    );\n    extractor ??= loadTransformers().then(\n      async (module) =>\n        (await module.pipeline(\"feature-extraction\", this.space.model, {\n          revision: this.space.revision,\n          dtype: \"q8\",\n        })) as unknown as Extractor,\n    );\n    // A failed load (no network on first use) is retried on the next call.\n    extractor.catch(() => {\n      extractor = null;\n    });\n    const extract = await extractor;\n    // Granite r2 is trained with CLS pooling; L2-normalized so cosine = dot.\n    const output = await extract(inputs, { pooling: \"cls\", normalize: true });\n    return { ...this.space, vectors: output.tolist() };\n  }\n\n  async generateText(): Promise<TextGenerationResponse> {\n    throw new Error(\"The local provider only embeds; text generation uses the BYOK LLM layer.\");\n  }\n}\n\ntype Reranker = {\n  tokenizer: (\n    texts: string[],\n    options: { text_pair: string[]; padding: boolean; truncation: boolean },\n  ) => unknown;\n  model: (inputs: unknown) => Promise<{ logits: { tolist(): number[][] } }>;\n};\nconst rerankers = new Map<string, Promise<Reranker>>();\n\n/**\n * Local cross-encoder logits for (query, document) pairs, in input order.\n * Higher is more relevant; values order documents for one query and are not\n * calibrated across queries, so callers order by them and never threshold.\n */\nexport async function rerankLocally(\n  model: { id: string; revision?: string },\n  query: string,\n  documents: string[],\n): Promise<number[]> {\n  if (documents.length === 0) return [];\n  let pending = rerankers.get(model.id);\n  if (!pending) {\n    pending = loadTransformers().then(async (module) => {\n      const options = model.revision ? { revision: model.revision } : {};\n      const [tokenizer, classifier] = await Promise.all([\n        module.AutoTokenizer.from_pretrained(model.id, options),\n        module.AutoModelForSequenceClassification.from_pretrained(model.id, {\n          ...options,\n          dtype: \"q8\",\n        }),\n      ]);\n      return { tokenizer, model: classifier } as unknown as Reranker;\n    });\n    rerankers.set(model.id, pending);\n    pending.catch(() => rerankers.delete(model.id));\n  }\n  const { tokenizer, model: classifier } = await pending;\n  const inputs = tokenizer(\n    documents.map(() => query.slice(0, MAX_INPUT_CHARS)),\n    {\n      text_pair: documents.map((document) => document.slice(0, MAX_INPUT_CHARS)),\n      padding: true,\n      truncation: true,\n    },\n  );\n  const { logits } = await classifier(inputs);\n  return logits.tolist().map((row) => row[0] ?? Number.NEGATIVE_INFINITY);\n}\n"],"mappings":"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","names":["tokenizer","classifier"]}