bikky 0.3.1 → 0.3.3

package/dist/llm/telemetry.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.test.d.ts","sourceRoot":"","sources":["../../src/llm/telemetry.test.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/llm/telemetry.test.js

@@ -0,0 +1,89 @@
+/**
+ * Tests for LLM telemetry — JSONL append, rotation, error swallowing.
+ */
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { estimateTokens, writeTelemetry } from "./telemetry.js";
+describe("llm/telemetry", () => {
+    let dir;
+    let file;
+    const noopLog = () => undefined;
+    beforeEach(() => {
+        dir = fs.mkdtempSync(path.join(os.tmpdir(), "bikky-telemetry-"));
+        file = path.join(dir, "llm.jsonl");
+        process.env.BIKKY_LLM_LOG = file;
+        delete process.env.BIKKY_LLM_LOG_MAX_BYTES;
+    });
+    afterEach(() => {
+        delete process.env.BIKKY_LLM_LOG;
+        delete process.env.BIKKY_LLM_LOG_MAX_BYTES;
+        fs.rmSync(dir, { recursive: true, force: true });
+    });
+    function makeRecord(overrides = {}) {
+        return {
+            ts: new Date().toISOString(),
+            prompt: "extraction",
+            model: "gpt-4o-mini",
+            provider: "openai",
+            ok: true,
+            latency_ms: 123,
+            tokens_in_est: 10,
+            tokens_out_est: 20,
+            ...overrides,
+        };
+    }
+    describe("estimateTokens", () => {
+        it("returns ceil(len/4) for non-empty input", () => {
+            assert.equal(estimateTokens(""), 0);
+            assert.equal(estimateTokens("abcd"), 1);
+            assert.equal(estimateTokens("abcde"), 2);
+            assert.equal(estimateTokens("a".repeat(100)), 25);
+        });
+    });
+    describe("writeTelemetry", () => {
+        it("appends a JSONL record to the configured log path", async () => {
+            await writeTelemetry(makeRecord({ prompt: "first" }), noopLog);
+            await writeTelemetry(makeRecord({ prompt: "second" }), noopLog);
+            const lines = fs.readFileSync(file, "utf-8").trim().split("\n");
+            assert.equal(lines.length, 2);
+            const first = JSON.parse(lines[0]);
+            const second = JSON.parse(lines[1]);
+            assert.equal(first.prompt, "first");
+            assert.equal(second.prompt, "second");
+            assert.equal(first.provider, "openai");
+        });
+        it("creates the parent directory if missing", async () => {
+            const nested = path.join(dir, "a", "b", "c", "llm.jsonl");
+            process.env.BIKKY_LLM_LOG = nested;
+            await writeTelemetry(makeRecord(), noopLog);
+            assert.ok(fs.existsSync(nested));
+        });
+        it("rotates to .1 when the file exceeds max bytes", async () => {
+            process.env.BIKKY_LLM_LOG_MAX_BYTES = "200";
+            // Seed an oversize file
+            fs.writeFileSync(file, "x".repeat(500));
+            await writeTelemetry(makeRecord(), noopLog);
+            assert.ok(fs.existsSync(`${file}.1`), "rotated file should exist");
+            const active = fs.readFileSync(file, "utf-8");
+            // Active file should only contain the new record after rotation
+            assert.equal(active.trim().split("\n").length, 1);
+        });
+        it("never throws when the path is unwritable; warns once via the logger", async () => {
+            // Point at a path that cannot be created (parent is a file, not a dir)
+            const blocker = path.join(dir, "blocker");
+            fs.writeFileSync(blocker, "not-a-dir");
+            process.env.BIKKY_LLM_LOG = path.join(blocker, "llm.jsonl");
+            const warnings = [];
+            const log = (_level, msg) => { warnings.push(String(msg)); };
+            await writeTelemetry(makeRecord(), log);
+            await writeTelemetry(makeRecord(), log);
+            // Module-level `warned` flag may already be set from a previous test;
+            // assert at most one warning was added in this call sequence.
+            assert.ok(warnings.length <= 1, "should warn at most once per process");
+        });
+    });
+});
+//# sourceMappingURL=telemetry.test.js.map

package/dist/llm/telemetry.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.test.js","sourceRoot":"","sources":["../../src/llm/telemetry.test.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAChE,OAAO,MAAM,MAAM,oBAAoB,CAAC;AACxC,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,MAAM,SAAS,CAAC;AAEzB,OAAO,EAAE,cAAc,EAAE,cAAc,EAA2B,MAAM,gBAAgB,CAAC;AAEzF,QAAQ,CAAC,eAAe,EAAE,GAAG,EAAE;IAC7B,IAAI,GAAW,CAAC;IAChB,IAAI,IAAY,CAAC;IACjB,MAAM,OAAO,GAAG,GAAS,EAAE,CAAC,SAAS,CAAC;IAEtC,UAAU,CAAC,GAAG,EAAE;QACd,GAAG,GAAG,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,kBAAkB,CAAC,CAAC,CAAC;QACjE,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC;QACnC,OAAO,CAAC,GAAG,CAAC,aAAa,GAAG,IAAI,CAAC;QACjC,OAAO,OAAO,CAAC,GAAG,CAAC,uBAAuB,CAAC;IAC7C,CAAC,CAAC,CAAC;IAEH,SAAS,CAAC,GAAG,EAAE;QACb,OAAO,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC;QACjC,OAAO,OAAO,CAAC,GAAG,CAAC,uBAAuB,CAAC;QAC3C,EAAE,CAAC,MAAM,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACnD,CAAC,CAAC,CAAC;IAEH,SAAS,UAAU,CAAC,YAAyC,EAAE;QAC7D,OAAO;YACL,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YAC5B,MAAM,EAAE,YAAY;YACpB,KAAK,EAAE,aAAa;YACpB,QAAQ,EAAE,QAAQ;YAClB,EAAE,EAAE,IAAI;YACR,UAAU,EAAE,GAAG;YACf,aAAa,EAAE,EAAE;YACjB,cAAc,EAAE,EAAE;YAClB,GAAG,SAAS;SACb,CAAC;IACJ,CAAC;IAED,QAAQ,CAAC,gBAAgB,EAAE,GAAG,EAAE;QAC9B,EAAE,CAAC,yCAAyC,EAAE,GAAG,EAAE;YACjD,MAAM,CAAC,KAAK,CAAC,cAAc,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;YACpC,MAAM,CAAC,KAAK,CAAC,cAAc,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC;YACxC,MAAM,CAAC,KAAK,CAAC,cAAc,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC;YACzC,MAAM,CAAC,KAAK,CAAC,cAAc,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACpD,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,gBAAgB,EAAE,GAAG,EAAE;QAC9B,EAAE,CAAC,mDAAmD,EAAE,KAAK,IAAI,EAAE;YACjE,MAAM,cAAc,CAAC,UAAU,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC;YAC/D,MAAM,cAAc,CAAC,UAAU,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC;YAEhE,MAAM,KAAK,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAChE,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;YAC9B,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAE,CAAuB,CAAC;YAC1D,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAE,CAAuB,CAAC;YAC3D,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;YACpC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;YACtC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;QACzC,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,yCAAyC,EAAE,KAAK,IAAI,EAAE;YACvD,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,WAAW,CAAC,CAAC;YAC1D,OAAO,CAAC,GAAG,CAAC,aAAa,GAAG,MAAM,CAAC;YAEnC,MAAM,cAAc,CAAC,UAAU,EAAE,EAAE,OAAO,CAAC,CAAC;YAC5C,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;QACnC,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,+CAA+C,EAAE,KAAK,IAAI,EAAE;YAC7D,OAAO,CAAC,GAAG,CAAC,uBAAuB,GAAG,KAAK,CAAC;YAC5C,wBAAwB;YACxB,EAAE,CAAC,aAAa,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;YAExC,MAAM,cAAc,CAAC,UAAU,EAAE,EAAE,OAAO,CAAC,CAAC;YAE5C,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,UAAU,CAAC,GAAG,IAAI,IAAI,CAAC,EAAE,2BAA2B,CAAC,CAAC;YACnE,MAAM,MAAM,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;YAC9C,gEAAgE;YAChE,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;QACpD,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,qEAAqE,EAAE,KAAK,IAAI,EAAE;YACnF,uEAAuE;YACvE,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;YAC1C,EAAE,CAAC,aAAa,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;YACvC,OAAO,CAAC,GAAG,CAAC,aAAa,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;YAE5D,MAAM,QAAQ,GAAa,EAAE,CAAC;YAC9B,MAAM,GAAG,GAAG,CAAC,MAAc,EAAE,GAAY,EAAQ,EAAE,GAAG,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YAEpF,MAAM,cAAc,CAAC,UAAU,EAAE,EAAE,GAAG,CAAC,CAAC;YACxC,MAAM,cAAc,CAAC,UAAU,EAAE,EAAE,GAAG,CAAC,CAAC;YAExC,sEAAsE;YACtE,8DAA8D;YAC9D,MAAM,CAAC,EAAE,CAAC,QAAQ,CAAC,MAAM,IAAI,CAAC,EAAE,sCAAsC,CAAC,CAAC;QAC1E,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/llm/types.d.ts

@@ -1,41 +1,8 @@
 /**
- * Shared types for embedding and inference providers.
+ * Cross-cutting types not specific to embedding or inference.
+ * Embedding types live in ./embedding/types.ts.
+ * Inference types (ChatCompletionOpts, ResponseFormat, JsonSchemaSpec, etc.)
+ * live in ./inference/types.ts.
  */
 export type LogFn = (level: string, ...args: unknown[]) => void;
-export interface EmbeddingProviderConfig {
-    provider: "ollama" | "openai" | "bedrock";
-    baseUrl: string;
-    model: string;
-    dimensions: number;
-    apiKey: string | null;
-}
-export interface InferenceProviderConfig {
-    provider: "ollama" | "openai" | "bedrock";
-    ollama_url: string;
-    ollama_model: string;
-    openai_api_key: string | null;
-    openai_model: string;
-    bedrock_region: string;
-    bedrock_model: string;
-}
-export interface ChatCompletionOpts {
-    messages: Array<{
-        role: string;
-        content: string;
-    }>;
-    temperature?: number;
-    max_tokens?: number;
-    response_format?: ResponseFormat;
-}
-export type ResponseFormat = {
-    type: "json_object";
-} | {
-    type: "json_schema";
-    json_schema: JsonSchemaSpec;
-};
-export interface JsonSchemaSpec {
-    name: string;
-    strict?: boolean;
-    schema: Record<string, unknown>;
-}
 //# sourceMappingURL=types.d.ts.map

package/dist/llm/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/llm/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,MAAM,KAAK,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;AAIhE,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAID,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;IAC1C,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACnD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,cAAc,CAAC;CAClC;AAED,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,GACvB;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,WAAW,EAAE,cAAc,CAAA;CAAE,CAAC;AAEzD,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/llm/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,MAAM,KAAK,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC"}

package/dist/llm/types.js

@@ -1,5 +1,8 @@
 /**
- * Shared types for embedding and inference providers.
+ * Cross-cutting types not specific to embedding or inference.
+ * Embedding types live in ./embedding/types.ts.
+ * Inference types (ChatCompletionOpts, ResponseFormat, JsonSchemaSpec, etc.)
+ * live in ./inference/types.ts.
  */
 export {};
 //# sourceMappingURL=types.js.map

package/dist/llm/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/llm/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/llm/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/logger.d.ts

@@ -1,11 +1,26 @@
 /**
- * Simple rotating file logger.
- * Writes to file only — stdout/stderr are reserved for MCP stdio transport.
+ * Structured logger backed by pino.
+ *
+ * Output is JSON-lines written to a rotating log file. We do NOT log to
+ * stdout/stderr because the MCP server reserves stdio for its transport.
+ *
+ * The exported `LogFn` signature is preserved for backward compatibility:
+ * callers continue to invoke `log("INFO", "msg", ...args)` and pino emits
+ * a structured record `{level, time, name, msg, ...extra}`. New code can
+ * pass a plain object as the first arg to attach structured fields:
+ *
+ *   log("INFO", { event: "embed_request", provider: "openai" }, "ok");
+ *
+ * We rotate the file in-process (no worker threads) by checking size after
+ * each write and recreating the pino destination when the threshold is
+ * exceeded.
  */
 export type LogLevel = "DEBUG" | "INFO" | "WARN" | "ERROR";
-export type LogFn = (level: LogLevel, ...args: unknown[]) => void;
+export type LogFn = (level: LogLevel | string, ...args: unknown[]) => void;
 interface LoggerOpts {
+    /** Bytes before rotation (default 2MB). */
     maxSize?: number;
+    /** Rotated files to keep (default 3). */
     maxFiles?: number;
 }
 export declare function createLogger(name: string, filePath: string, opts?: LoggerOpts): LogFn;

package/dist/logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAC3D,MAAM,MAAM,KAAK,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;AAElE,UAAU,UAAU;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE,UAAe,GACpB,KAAK,CAgCP"}
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAMH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAC3D,MAAM,MAAM,KAAK,GAAG,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;AAE3E,UAAU,UAAU;IAClB,2CAA2C;IAC3C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yCAAyC;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAyCD,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE,UAAe,GACpB,KAAK,CAsEP"}

package/dist/logger.js

@@ -1,41 +1,123 @@
 /**
- * Simple rotating file logger.
- * Writes to file only — stdout/stderr are reserved for MCP stdio transport.
+ * Structured logger backed by pino.
+ *
+ * Output is JSON-lines written to a rotating log file. We do NOT log to
+ * stdout/stderr because the MCP server reserves stdio for its transport.
+ *
+ * The exported `LogFn` signature is preserved for backward compatibility:
+ * callers continue to invoke `log("INFO", "msg", ...args)` and pino emits
+ * a structured record `{level, time, name, msg, ...extra}`. New code can
+ * pass a plain object as the first arg to attach structured fields:
+ *
+ *   log("INFO", { event: "embed_request", provider: "openai" }, "ok");
+ *
+ * We rotate the file in-process (no worker threads) by checking size after
+ * each write and recreating the pino destination when the threshold is
+ * exceeded.
  */
 import fs from "node:fs";
 import path from "node:path";
+import pino from "pino";
+const LEVEL_MAP = {
+    DEBUG: "debug",
+    INFO: "info",
+    WARN: "warn",
+    ERROR: "error",
+    debug: "debug",
+    info: "info",
+    warn: "warn",
+    error: "error",
+};
+function buildPino(name, filePath) {
+    const dest = pino.destination({ dest: filePath, sync: true, append: true, mkdir: true });
+    return pino({
+        name,
+        level: "debug",
+        // Omit pid / hostname — every line carries `name` instead.
+        base: { name },
+        timestamp: pino.stdTimeFunctions.isoTime,
+        formatters: {
+            // Emit human-readable level strings ("info") rather than numeric codes.
+            level(label) {
+                return { level: label };
+            },
+        },
+    }, dest);
+}
+function safeSize(filePath) {
+    try {
+        return fs.statSync(filePath).size;
+    }
+    catch {
+        return 0;
+    }
+}
 export function createLogger(name, filePath, opts = {}) {
     const maxSize = opts.maxSize ?? 2 * 1024 * 1024;
     const maxFiles = opts.maxFiles ?? 3;
     fs.mkdirSync(path.dirname(filePath), { recursive: true });
-    let fd = fs.openSync(filePath, "a");
-    let currentSize = 0;
-    try {
-        currentSize = fs.fstatSync(fd).size;
-    }
-    catch { /* new file */ }
+    let logger = buildPino(name, filePath);
+    let writtenSinceCheck = 0;
     function rotate() {
-        fs.closeSync(fd);
+        try {
+            logger.flush();
+        }
+        catch {
+            /* ignore — pino sync mode flushes on every write */
+        }
         for (let i = maxFiles - 1; i >= 1; i--) {
             const from = i === 1 ? filePath : `${filePath}.${i - 1}`;
             const to = `${filePath}.${i}`;
             try {
                 fs.renameSync(from, to);
             }
-            catch { /* missing file is fine */ }
+            catch {
+                /* missing file is fine */
+            }
         }
-        fd = fs.openSync(filePath, "w");
-        currentSize = 0;
+        logger = buildPino(name, filePath);
+        writtenSinceCheck = 0;
     }
-    return (level, ...args) => {
-        const ts = new Date().toISOString().replace("T", " ").slice(0, 19);
-        const msg = args.map((a) => typeof a === "string" ? a : JSON.stringify(a)).join(" ");
-        const line = `[${ts}] [${name}] ${level}: ${msg}\n`;
-        const buf = Buffer.from(line);
-        fs.writeSync(fd, buf);
-        currentSize += buf.length;
-        if (currentSize > maxSize)
+    function maybeRotate() {
+        // Cheap heuristic: only stat the file once we've written enough bytes
+        // to plausibly cross the threshold. Avoids a stat on every log line.
+        if (writtenSinceCheck < 4096)
+            return;
+        writtenSinceCheck = 0;
+        if (safeSize(filePath) > maxSize)
             rotate();
+    }
+    return (level, ...args) => {
+        const lvl = LEVEL_MAP[level] ?? "info";
+        const fn = logger[lvl].bind(logger);
+        let approxBytes = 0;
+        const first = args[0];
+        if (first !== null &&
+            typeof first === "object" &&
+            !Array.isArray(first) &&
+            !(first instanceof Error)) {
+            // Structured form: log("INFO", {fields}, "msg", ...)
+            const rest = args.slice(1);
+            const msg = rest
+                .map((a) => (typeof a === "string" ? a : a instanceof Error ? a.message : JSON.stringify(a)))
+                .join(" ");
+            fn(first, msg);
+            try {
+                approxBytes = JSON.stringify(first).length + msg.length;
+            }
+            catch {
+                approxBytes = msg.length;
+            }
+        }
+        else {
+            const msg = args
+                .map((a) => (typeof a === "string" ? a : a instanceof Error ? a.message : JSON.stringify(a)))
+                .join(" ");
+            fn(msg);
+            approxBytes = msg.length;
+        }
+        writtenSinceCheck += approxBytes + 80; // +80 for JSON envelope (level/time/name/...)
+        maybeRotate();
     };
 }
 //# sourceMappingURL=logger.js.map

package/dist/logger.js.map

@@ -1 +1 @@
-{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAU7B,MAAM,UAAU,YAAY,CAC1B,IAAY,EACZ,QAAgB,EAChB,OAAmB,EAAE;IAErB,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;IAChD,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,CAAC,CAAC;IAEpC,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAE1D,IAAI,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IACpC,IAAI,WAAW,GAAG,CAAC,CAAC;IACpB,IAAI,CAAC;QAAC,WAAW,GAAG,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC;IAAC,CAAC;IAAC,MAAM,CAAC,CAAC,cAAc,CAAC,CAAC;IAErE,SAAS,MAAM;QACb,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;QACjB,KAAK,IAAI,CAAC,GAAG,QAAQ,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YACvC,MAAM,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,QAAQ,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YACzD,MAAM,EAAE,GAAG,GAAG,QAAQ,IAAI,CAAC,EAAE,CAAC;YAC9B,IAAI,CAAC;gBAAC,EAAE,CAAC,UAAU,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YAAC,CAAC;YAAC,MAAM,CAAC,CAAC,0BAA0B,CAAC,CAAC;QACvE,CAAC;QACD,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;QAChC,WAAW,GAAG,CAAC,CAAC;IAClB,CAAC;IAED,OAAO,CAAC,KAAe,EAAE,GAAG,IAAe,EAAQ,EAAE;QACnD,MAAM,EAAE,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACnE,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CACzB,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAC9C,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACZ,MAAM,IAAI,GAAG,IAAI,EAAE,MAAM,IAAI,KAAK,KAAK,KAAK,GAAG,IAAI,CAAC;QACpD,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC9B,EAAE,CAAC,SAAS,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;QACtB,WAAW,IAAI,GAAG,CAAC,MAAM,CAAC;QAC1B,IAAI,WAAW,GAAG,OAAO;YAAE,MAAM,EAAE,CAAC;IACtC,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"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"}

package/dist/logger.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Tests for the pino-backed structured file logger.
+ */
+export {};
+//# sourceMappingURL=logger.test.d.ts.map

package/dist/logger.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.test.d.ts","sourceRoot":"","sources":["../src/logger.test.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/logger.test.js

@@ -0,0 +1,103 @@
+/**
+ * Tests for the pino-backed structured file logger.
+ */
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { createLogger } from "./logger.js";
+function readLines(file) {
+    return fs
+        .readFileSync(file, "utf-8")
+        .trim()
+        .split("\n")
+        .filter((l) => l.length > 0)
+        .map((l) => JSON.parse(l));
+}
+describe("logger (pino-backed)", () => {
+    let dir;
+    let file;
+    beforeEach(() => {
+        dir = fs.mkdtempSync(path.join(os.tmpdir(), "bikky-logger-"));
+        file = path.join(dir, "nested", "test.log");
+    });
+    afterEach(() => {
+        fs.rmSync(dir, { recursive: true, force: true });
+    });
+    it("creates the parent directory and writes a JSON line with name + msg", () => {
+        const log = createLogger("svc", file);
+        log("INFO", "hello", { a: 1 });
+        const lines = readLines(file);
+        assert.equal(lines.length, 1);
+        assert.equal(lines[0].level, "info");
+        assert.equal(lines[0].name, "svc");
+        assert.equal(lines[0].msg, 'hello {"a":1}');
+        assert.match(lines[0].time, /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/);
+    });
+    it("maps DEBUG/INFO/WARN/ERROR levels to pino lowercase labels", () => {
+        const log = createLogger("svc", file);
+        log("DEBUG", "d");
+        log("INFO", "i");
+        log("WARN", "w");
+        log("ERROR", "e");
+        const lines = readLines(file);
+        assert.equal(lines.length, 4);
+        assert.deepEqual(lines.map((l) => [l.level, l.msg]), [
+            ["debug", "d"],
+            ["info", "i"],
+            ["warn", "w"],
+            ["error", "e"],
+        ]);
+    });
+    it("merges a leading object arg as structured fields", () => {
+        const log = createLogger("svc", file);
+        log("INFO", { event: "embed_request", provider: "openai" }, "ok");
+        const lines = readLines(file);
+        assert.equal(lines.length, 1);
+        assert.equal(lines[0].event, "embed_request");
+        assert.equal(lines[0].provider, "openai");
+        assert.equal(lines[0].msg, "ok");
+    });
+    it("serialises non-string args into msg via JSON.stringify", () => {
+        const log = createLogger("svc", file);
+        log("INFO", "msg", [1, 2], 42);
+        const lines = readLines(file);
+        assert.equal(lines[0].msg, "msg [1,2] 42");
+    });
+    it("renders Error args via .message rather than {}", () => {
+        const log = createLogger("svc", file);
+        log("ERROR", "boom", new Error("kaboom"));
+        const lines = readLines(file);
+        assert.match(lines[0].msg, /boom kaboom/);
+    });
+    it("rotates when the file exceeds maxSize", () => {
+        const log = createLogger("svc", file, { maxSize: 200, maxFiles: 3 });
+        for (let i = 0; i < 50; i++)
+            log("INFO", "x".repeat(80));
+        assert.ok(fs.existsSync(file), "active log file exists");
+        assert.ok(fs.existsSync(`${file}.1`), "rotated file .1 exists");
+        const active = fs.statSync(file).size;
+        const rotated = fs.statSync(`${file}.1`).size;
+        assert.ok(active <= rotated);
+    });
+    it("caps the number of rotated files at maxFiles", () => {
+        const log = createLogger("svc", file, { maxSize: 100, maxFiles: 2 });
+        for (let i = 0; i < 100; i++)
+            log("INFO", "x".repeat(80));
+        assert.ok(fs.existsSync(`${file}.1`));
+        assert.ok(!fs.existsSync(`${file}.3`), "should not keep .3");
+    });
+    it("appends to an existing log file", () => {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, '{"pre":"existing"}\n');
+        const log = createLogger("svc", file);
+        log("INFO", "after");
+        const contents = fs.readFileSync(file, "utf-8");
+        assert.ok(contents.startsWith('{"pre":"existing"}\n'));
+        const lines = contents.trim().split("\n");
+        const last = JSON.parse(lines[lines.length - 1]);
+        assert.equal(last.msg, "after");
+    });
+});
+//# sourceMappingURL=logger.test.js.map

package/dist/logger.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.test.js","sourceRoot":"","sources":["../src/logger.test.ts"],"names":[],"mappings":"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"}

package/dist/mcp/api.d.ts

@@ -4,7 +4,8 @@
  */
 import type { QdrantFilter, QdrantGetResult, QdrantScrollResult, QdrantSearchResult } from "./types.js";
 import { embed, getEmbeddingDimensions, getEmbeddingConfig, initEmbedding } from "../llm/index.js";
-export type { EmbeddingProviderConfig } from "../llm/index.js";
+import type { ChatCompletionOpts } from "../llm/index.js";
+export type { ResolvedEmbeddingConfig } from "../llm/index.js";
 export { embed, getEmbeddingDimensions, getEmbeddingConfig, initEmbedding };
 export declare const MEMORY_DIR: string;
 export declare function getCollection(): string;
@@ -12,11 +13,24 @@ export declare function setCollection(name: string): void;
 export declare let qdrantUrl: string | null;
 export declare let qdrantApiKey: string | null;
 export declare let ready: boolean;
+/**
+ * Reason the system is not ready, when known. Set by `setSetupError` from the
+ * MCP boot path if `initEmbedding`/`ensureCollection` fails. Surfaced in
+ * `requireReady()` and `get_setup_status` so users see an actionable message
+ * instead of a generic "setup_required".
+ */
+export declare let setupError: string | null;
 export declare function setQdrantUrl(v: string | null): void;
 export declare function setQdrantApiKey(v: string | null): void;
 export declare function setReady(v: boolean): void;
+export declare function setSetupError(v: string | null): void;
 export declare const log: import("../logger.js").LogFn;
 export declare function chatComplete(systemPrompt: string, userPrompt: string): Promise<string>;
+/**
+ * Run a pre-rendered prompt (from src/prompts/*) through the LLM. The
+ * RenderedPrompt already carries messages, response_format, temperature, etc.
+ */
+export declare function chatCompleteRendered(opts: ChatCompletionOpts): Promise<string>;
 export declare function qdrantReq<T>(method: string, urlPath: string, body?: unknown): Promise<T>;
 export declare function ensureCollection(indexes: Array<{
     field_name: string;

package/dist/mcp/api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../src/mcp/api.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACxG,OAAO,EAAE,KAAK,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,aAAa,EAA2B,MAAM,iBAAiB,CAAC;AAC5H,YAAY,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAC/D,OAAO,EAAE,KAAK,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,aAAa,EAAE,CAAC;AAU5E,eAAO,MAAM,UAAU,QAAY,CAAC;AAGpC,wBAAgB,aAAa,IAAI,MAAM,CAA2B;AAClE,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAGhD;AAWD,eAAO,IAAI,SAAS,EAAE,MAAM,GAAG,IAAW,CAAC;AAC3C,eAAO,IAAI,YAAY,EAAE,MAAM,GAAG,IAAW,CAAC;AAC9C,eAAO,IAAI,KAAK,SAAQ,CAAC;AAIzB,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAGnD;AACD,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAGtD;AACD,wBAAgB,QAAQ,CAAC,CAAC,EAAE,OAAO,GAAG,IAAI,CAAe;AAMzD,eAAO,MAAM,GAAG,8BAGd,CAAC;AA0BH,wBAAsB,YAAY,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA6B5F;AAgBD,wBAAsB,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,CAE9F;AAED,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,KAAK,CAAC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAGlH;AAED,wBAAsB,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAInH;AAED,wBAAsB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,YAAY,GAAG,SAAS,EAAE,KAAK,SAAI,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAO7H;AAED,wBAAsB,YAAY,CAAC,MAAM,EAAE,YAAY,EAAE,KAAK,SAAK,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAMhG;AAED,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAKxG;AAED,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,eAAe,CAAC,CAK7E"}
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../src/mcp/api.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACxG,OAAO,EAAE,KAAK,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,aAAa,EAA2B,MAAM,iBAAiB,CAAC;AAC5H,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAC1D,YAAY,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAC/D,OAAO,EAAE,KAAK,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,aAAa,EAAE,CAAC;AAU5E,eAAO,MAAM,UAAU,QAAY,CAAC;AAGpC,wBAAgB,aAAa,IAAI,MAAM,CAA2B;AAClE,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAGhD;AAWD,eAAO,IAAI,SAAS,EAAE,MAAM,GAAG,IAAW,CAAC;AAC3C,eAAO,IAAI,YAAY,EAAE,MAAM,GAAG,IAAW,CAAC;AAC9C,eAAO,IAAI,KAAK,SAAQ,CAAC;AACzB;;;;;GAKG;AACH,eAAO,IAAI,UAAU,EAAE,MAAM,GAAG,IAAW,CAAC;AAI5C,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAGnD;AACD,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAGtD;AACD,wBAAgB,QAAQ,CAAC,CAAC,EAAE,OAAO,GAAG,IAAI,CAAe;AACzD,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAoB;AAMzE,eAAO,MAAM,GAAG,8BAGd,CAAC;AA0BH,wBAAsB,YAAY,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAa5F;AAED;;;GAGG;AACH,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,CAKpF;AAqCD,wBAAsB,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,CAE9F;AAED,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,KAAK,CAAC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAGlH;AAED,wBAAsB,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAInH;AAED,wBAAsB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,YAAY,GAAG,SAAS,EAAE,KAAK,SAAI,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAO7H;AAED,wBAAsB,YAAY,CAAC,MAAM,EAAE,YAAY,EAAE,KAAK,SAAK,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAMhG;AAED,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAKxG;AAED,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,eAAe,CAAC,CAK7E"}

package/dist/mcp/api.js

@@ -28,6 +28,13 @@ let llmInitialized = false;
 export let qdrantUrl = null;
 export let qdrantApiKey = null;
 export let ready = false;
+/**
+ * Reason the system is not ready, when known. Set by `setSetupError` from the
+ * MCP boot path if `initEmbedding`/`ensureCollection` fails. Surfaced in
+ * `requireReady()` and `get_setup_status` so users see an actionable message
+ * instead of a generic "setup_required".
+ */
+export let setupError = null;
 let client = null;
 export function setQdrantUrl(v) {
     qdrantUrl = v ? v.replace(/\/+$/, "") : v;
@@ -38,6 +45,7 @@ export function setQdrantApiKey(v) {
     rebuildClient();
 }
 export function setReady(v) { ready = v; }
+export function setSetupError(v) { setupError = v; }
 // ---------------------------------------------------------------------------
 // Logging (to file only — stdout/stderr are MCP stdio transport)
 // ---------------------------------------------------------------------------
@@ -48,7 +56,7 @@ export const log = createLogger("memory-mcp", path.join(LOG_DIR, "mcp.log"), {
 // Adapter to bridge QdrantClient's QdrantLogFn signature to our file logger.
 const qdrantLogAdapter = (level, msg) => log(level, msg);
 function rebuildClient() {
-    if (qdrantUrl && qdrantApiKey && collectionName) {
+    if (qdrantUrl && collectionName) {
         const cfg = loadConfig();
         client = new QdrantClient({
             url: qdrantUrl,
@@ -68,22 +76,7 @@ function rebuildClient() {
 // LLM Chat Completion (for distillation)
 // ---------------------------------------------------------------------------
 export async function chatComplete(systemPrompt, userPrompt) {
-    if (!llmInitialized) {
-        const cfg = loadConfig();
-        initLLM({
-            config: {
-                provider: cfg.llm.provider,
-                ollama_url: cfg.llm.base_url,
-                ollama_model: cfg.llm.model,
-                openai_api_key: cfg.llm.api_key ?? null,
-                openai_model: cfg.llm.model,
-                bedrock_region: cfg.llm.bedrock_region,
-                bedrock_model: cfg.llm.model,
-            },
-            logger: log,
-        });
-        llmInitialized = true;
-    }
+    ensureLLMInitialized();
     const result = await chatCompletion({
         messages: [
             { role: "system", content: systemPrompt },
@@ -96,13 +89,45 @@ export async function chatComplete(systemPrompt, userPrompt) {
         throw new Error("LLM chat completion failed");
     return result;
 }
+/**
+ * Run a pre-rendered prompt (from src/prompts/*) through the LLM. The
+ * RenderedPrompt already carries messages, response_format, temperature, etc.
+ */
+export async function chatCompleteRendered(opts) {
+    ensureLLMInitialized();
+    const result = await chatCompletion(opts);
+    if (!result)
+        throw new Error("LLM chat completion failed");
+    return result;
+}
+function ensureLLMInitialized() {
+    if (llmInitialized)
+        return;
+    const cfg = loadConfig();
+    initLLM({
+        config: {
+            provider: cfg.llm.provider,
+            model: cfg.llm.model,
+            baseUrl: cfg.llm.base_url,
+            apiKey: cfg.llm.api_key ?? null,
+            fallback: cfg.llm.fallback_provider ?? null,
+            extra: cfg.llm.extra ?? {},
+            timeoutMs: cfg.llm.timeout_ms,
+            retries: cfg.llm.retries,
+            retryBaseDelayMs: cfg.llm.retry_base_delay_ms,
+        },
+        logger: log,
+    });
+    llmInitialized = true;
+}
 // ---------------------------------------------------------------------------
 // Qdrant REST Client
 // ---------------------------------------------------------------------------
 function getClient() {
     if (!client) {
-        throw new Error("Qdrant client not initialized — credentials missing. " +
-            "Use configure_credentials or set QDRANT_URL + QDRANT_API_KEY.");
+        throw new Error("Qdrant client not initialized — URL missing. " +
+            "Use configure_credentials or set QDRANT_URL " +
+            "(QDRANT_API_KEY is optional for local / self-hosted instances).");
     }
     return client;
 }