kongbrain 0.1.0

package/src/embeddings.ts

@@ -0,0 +1,77 @@
+import { existsSync } from "node:fs";
+import type { EmbeddingConfig } from "./config.js";
+import { swallow } from "./errors.js";
+
+// Lazy-import node-llama-cpp to avoid top-level await issues with jiti.
+// The actual import happens inside initialize() at runtime.
+type LlamaEmbeddingContext = import("node-llama-cpp").LlamaEmbeddingContext;
+type LlamaModel = import("node-llama-cpp").LlamaModel;
+
+export class EmbeddingService {
+  private model: LlamaModel | null = null;
+  private ctx: LlamaEmbeddingContext | null = null;
+  private ready = false;
+  private embedCallCount = 0;
+
+  constructor(private readonly config: EmbeddingConfig) {}
+
+  async initialize(): Promise<void> {
+    if (!existsSync(this.config.modelPath)) {
+      throw new Error(
+        `Embedding model not found at: ${this.config.modelPath}\n  Download BGE-M3 GGUF or set EMBED_MODEL_PATH`,
+      );
+    }
+    const { getLlama, LlamaLogLevel } = await import("node-llama-cpp");
+    const llama = await getLlama({
+      logLevel: LlamaLogLevel.error,
+      logger: (level, message) => {
+        if (message.includes("missing newline token")) return;
+        if (level === LlamaLogLevel.error) console.error(`[llama] ${message}`);
+        else if (level === LlamaLogLevel.warn) console.warn(`[llama] ${message}`);
+      },
+    });
+    this.model = await llama.loadModel({ modelPath: this.config.modelPath });
+    this.ctx = await this.model.createEmbeddingContext();
+    this.ready = true;
+  }
+
+  async embed(text: string): Promise<number[]> {
+    if (!this.ready || !this.ctx) throw new Error("Embeddings not initialized");
+    this.embedCallCount++;
+    const result = await this.ctx.getEmbeddingFor(text);
+    return Array.from(result.vector);
+  }
+
+  async embedBatch(texts: string[]): Promise<number[][]> {
+    if (texts.length === 0) return [];
+    const results: number[][] = [];
+    for (const text of texts) {
+      results.push(await this.embed(text));
+    }
+    return results;
+  }
+
+  isAvailable(): boolean {
+    return this.ready;
+  }
+
+  drainEmbedCallCount(): number {
+    const count = this.embedCallCount;
+    this.embedCallCount = 0;
+    return count;
+  }
+
+  getEmbedCallCount(): number {
+    return this.embedCallCount;
+  }
+
+  async dispose(): Promise<void> {
+    try {
+      await this.ctx?.dispose();
+      await this.model?.dispose();
+      this.ready = false;
+    } catch (e) {
+      swallow("embeddings:dispose", e);
+    }
+  }
+}

package/src/errors.ts

@@ -0,0 +1,43 @@
+/**
+ * Lightweight error swallowing with severity levels.
+ *
+ * - swallow(ctx, e)       — SILENT: expected degradation (embeddings offline, non-critical telemetry).
+ *                           Only visible with KONGBRAIN_DEBUG=1.
+ * - swallow.warn(ctx, e)  — WARN: unexpected but recoverable (DB query failure, compaction failure).
+ *                           Always logged to stderr.
+ * - swallow.error(ctx, e) — ERROR: something is genuinely broken (cleanup failure, schema failure).
+ *                           Always logged to stderr with stack trace.
+ */
+
+const DEBUG = process.env.KONGBRAIN_DEBUG === "1";
+
+/**
+ * Swallow an error silently. Only visible with KONGBRAIN_DEBUG=1.
+ * Use for expected degradation (embeddings down, non-critical graph edges).
+ */
+function swallow(context: string, err?: unknown): void {
+  if (!DEBUG) return;
+  const msg = err instanceof Error ? err.message : String(err ?? "unknown");
+  console.debug(`[swallow] ${context}: ${msg}`);
+}
+
+/**
+ * Swallow an error but log a warning. Always visible.
+ * Use for unexpected-but-recoverable issues (DB failures, compaction failures).
+ */
+swallow.warn = function swallowWarn(context: string, err?: unknown): void {
+  const msg = err instanceof Error ? err.message : String(err ?? "unknown");
+  console.warn(`[warn] ${context}: ${msg}`);
+};
+
+/**
+ * Swallow an error but log an error. Always visible, includes stack.
+ * Use for genuinely broken things (cleanup failure, schema failure).
+ */
+swallow.error = function swallowError(context: string, err?: unknown): void {
+  const msg = err instanceof Error ? err.message : String(err ?? "unknown");
+  const stack = err instanceof Error ? `\n${err.stack}` : "";
+  console.error(`[ERROR] ${context}: ${msg}${stack}`);
+};
+
+export { swallow };