kiri-mcp-server 0.9.9 → 0.10.0

package/dist/src/shared/embedding/registry.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Embedding engine registry
+ * Manages LSH and semantic engines, selects based on feature flags
+ */
+import type { EmbeddingEngine, EmbeddingFeatureFlags } from "./engine.js";
+export declare class EmbeddingRegistry {
+    private static lshEngine;
+    private static semanticEngine;
+    /**
+     * Get embedding engine based on feature flags
+     * @param flags - Feature flags (semanticIndex)
+     * @param allowFallback - Fall back to LSH if semantic unavailable (default: true)
+     * @returns Embedding engine
+     */
+    static getEngine(flags: EmbeddingFeatureFlags, allowFallback?: boolean): Promise<EmbeddingEngine>;
+    /**
+     * Get LSH engine directly (for testing)
+     */
+    static getLshEngine(): EmbeddingEngine;
+    /**
+     * Reset semantic engine (for testing)
+     */
+    static resetSemanticEngine(): void;
+}
+//# sourceMappingURL=registry.d.ts.map

package/dist/src/shared/embedding/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../../src/shared/embedding/registry.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAI1E,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,MAAM,CAAC,SAAS,CAAmB;IAC3C,OAAO,CAAC,MAAM,CAAC,cAAc,CAA+B;IAE5D;;;;;OAKG;WACU,SAAS,CACpB,KAAK,EAAE,qBAAqB,EAC5B,aAAa,UAAO,GACnB,OAAO,CAAC,eAAe,CAAC;IAwB3B;;OAEG;IACH,MAAM,CAAC,YAAY,IAAI,eAAe;IAItC;;OAEG;IACH,MAAM,CAAC,mBAAmB,IAAI,IAAI;CAGnC"}

package/dist/src/shared/embedding/registry.js

@@ -0,0 +1,50 @@
+/**
+ * Embedding engine registry
+ * Manages LSH and semantic engines, selects based on feature flags
+ */
+import { LshEngine } from "./lsh-engine.js";
+import { SemanticEngine } from "./semantic-engine.js";
+export class EmbeddingRegistry {
+    static lshEngine = new LshEngine();
+    static semanticEngine = null;
+    /**
+     * Get embedding engine based on feature flags
+     * @param flags - Feature flags (semanticIndex)
+     * @param allowFallback - Fall back to LSH if semantic unavailable (default: true)
+     * @returns Embedding engine
+     */
+    static async getEngine(flags, allowFallback = true) {
+        // Default: LSH-64
+        if (!flags.semanticIndex) {
+            return this.lshEngine;
+        }
+        // Semantic requested: lazy-load engine
+        if (!this.semanticEngine) {
+            try {
+                this.semanticEngine = new SemanticEngine();
+                await this.semanticEngine.warmup();
+            }
+            catch (error) {
+                console.warn("Semantic engine unavailable, falling back to LSH:", error);
+                if (allowFallback) {
+                    return this.lshEngine;
+                }
+                throw error;
+            }
+        }
+        return this.semanticEngine;
+    }
+    /**
+     * Get LSH engine directly (for testing)
+     */
+    static getLshEngine() {
+        return this.lshEngine;
+    }
+    /**
+     * Reset semantic engine (for testing)
+     */
+    static resetSemanticEngine() {
+        this.semanticEngine = null;
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/src/shared/embedding/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../../../src/shared/embedding/registry.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD,MAAM,OAAO,iBAAiB;IACpB,MAAM,CAAC,SAAS,GAAG,IAAI,SAAS,EAAE,CAAC;IACnC,MAAM,CAAC,cAAc,GAA0B,IAAI,CAAC;IAE5D;;;;;OAKG;IACH,MAAM,CAAC,KAAK,CAAC,SAAS,CACpB,KAA4B,EAC5B,aAAa,GAAG,IAAI;QAEpB,kBAAkB;QAClB,IAAI,CAAC,KAAK,CAAC,aAAa,EAAE,CAAC;YACzB,OAAO,IAAI,CAAC,SAAS,CAAC;QACxB,CAAC;QAED,uCAAuC;QACvC,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,CAAC;YACzB,IAAI,CAAC;gBACH,IAAI,CAAC,cAAc,GAAG,IAAI,cAAc,EAAE,CAAC;gBAC3C,MAAM,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,CAAC;YACrC,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,OAAO,CAAC,IAAI,CAAC,mDAAmD,EAAE,KAAK,CAAC,CAAC;gBAEzE,IAAI,aAAa,EAAE,CAAC;oBAClB,OAAO,IAAI,CAAC,SAAS,CAAC;gBACxB,CAAC;gBACD,MAAM,KAAK,CAAC;YACd,CAAC;QACH,CAAC;QAED,OAAO,IAAI,CAAC,cAAc,CAAC;IAC7B,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,YAAY;QACjB,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,mBAAmB;QACxB,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;IAC7B,CAAC"}

package/dist/src/shared/embedding/semantic-engine.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Semantic embedding engine using Xenova/gte-small
+ * 384-dimensional embeddings via @xenova/transformers
+ */
+import type { EmbeddingEngine, EmbeddingModel, EmbeddingVector } from "./engine.js";
+export declare class SemanticEngine implements EmbeddingEngine {
+    readonly name: EmbeddingModel;
+    readonly dims = 384;
+    private pipeline;
+    private modelPath;
+    warmup(): Promise<void>;
+    embed(text: string): Promise<EmbeddingVector | null>;
+}
+//# sourceMappingURL=semantic-engine.d.ts.map

package/dist/src/shared/embedding/semantic-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-engine.d.ts","sourceRoot":"","sources":["../../../../src/shared/embedding/semantic-engine.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAKpF,qBAAa,cAAe,YAAW,eAAe;IACpD,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAsB;IACnD,QAAQ,CAAC,IAAI,OAAO;IAEpB,OAAO,CAAC,QAAQ,CAAyB;IACzC,OAAO,CAAC,SAAS,CAAuB;IAElC,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAoBvB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;CAyB3D"}

package/dist/src/shared/embedding/semantic-engine.js

@@ -0,0 +1,50 @@
+/**
+ * Semantic embedding engine using Xenova/gte-small
+ * 384-dimensional embeddings via @xenova/transformers
+ */
+import { MODELS } from "../models/model-manifest.js";
+import { ModelManager } from "../models/model-manager.js";
+export class SemanticEngine {
+    name = "semantic-gte-384";
+    dims = 384;
+    pipeline = null;
+    modelPath = null;
+    async warmup() {
+        if (this.pipeline)
+            return;
+        const model = MODELS["semantic-gte-384"];
+        // Ensure model is downloaded
+        this.modelPath = await ModelManager.ensureModel(model);
+        // Lazy-load @xenova/transformers (don't bundle if not used)
+        const { pipeline, env } = await import("@xenova/transformers");
+        // Configure to use cached model
+        env.cacheDir = this.modelPath;
+        env.allowRemoteModels = false; // Already downloaded
+        env.allowLocalModels = true;
+        // Load pipeline
+        this.pipeline = await pipeline("feature-extraction", model.source);
+    }
+    async embed(text) {
+        // Ensure model is loaded
+        if (!this.pipeline) {
+            await this.warmup();
+        }
+        try {
+            // Truncate to prevent OOM (~2k tokens max)
+            const truncated = text.slice(0, 8192);
+            // Generate embedding
+            const output = await this.pipeline(truncated, {
+                pooling: "mean",
+                normalize: true,
+            });
+            // Extract embedding vector
+            const values = Array.from(output.data);
+            return { dims: this.dims, values };
+        }
+        catch (error) {
+            console.warn(`Semantic embedding failed: ${error}`);
+            return null;
+        }
+    }
+}
+//# sourceMappingURL=semantic-engine.js.map

package/dist/src/shared/embedding/semantic-engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-engine.js","sourceRoot":"","sources":["../../../../src/shared/embedding/semantic-engine.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,6BAA6B,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAO1D,MAAM,OAAO,cAAc;IAChB,IAAI,GAAmB,kBAAkB,CAAC;IAC1C,IAAI,GAAG,GAAG,CAAC;IAEZ,QAAQ,GAAoB,IAAI,CAAC;IACjC,SAAS,GAAkB,IAAI,CAAC;IAExC,KAAK,CAAC,MAAM;QACV,IAAI,IAAI,CAAC,QAAQ;YAAE,OAAO;QAE1B,MAAM,KAAK,GAAG,MAAM,CAAC,kBAAkB,CAAC,CAAC;QAEzC,6BAA6B;QAC7B,IAAI,CAAC,SAAS,GAAG,MAAM,YAAY,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;QAEvD,4DAA4D;QAC5D,MAAM,EAAE,QAAQ,EAAE,GAAG,EAAE,GAAG,MAAM,MAAM,CAAC,sBAAsB,CAAC,CAAC;QAE/D,gCAAgC;QAChC,GAAG,CAAC,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC;QAC9B,GAAG,CAAC,iBAAiB,GAAG,KAAK,CAAC,CAAC,qBAAqB;QACpD,GAAG,CAAC,gBAAgB,GAAG,IAAI,CAAC;QAE5B,gBAAgB;QAChB,IAAI,CAAC,QAAQ,GAAG,MAAM,QAAQ,CAAC,oBAAoB,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACrE,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,IAAY;QACtB,yBAAyB;QACzB,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACnB,MAAM,IAAI,CAAC,MAAM,EAAE,CAAC;QACtB,CAAC;QAED,IAAI,CAAC;YACH,2CAA2C;YAC3C,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;YAEtC,qBAAqB;YACrB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,QAAS,CAAC,SAAS,EAAE;gBAC7C,OAAO,EAAE,MAAM;gBACf,SAAS,EAAE,IAAI;aAChB,CAAC,CAAC;YAEH,2BAA2B;YAC3B,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,IAAoB,CAAC,CAAC;YAEvD,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC;QACrC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,IAAI,CAAC,8BAA8B,KAAK,EAAE,CAAC,CAAC;YACpD,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;CACF"}

package/dist/src/shared/models/model-manager.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Model download and cache management
+ * Handles model downloads to ~/.kiri/models/
+ */
+import type { ModelDescriptor } from "./model-manifest.js";
+export interface ModelCacheMetadata {
+    name: string;
+    version: string;
+    downloadedAt: string;
+    checksum?: string;
+}
+export declare class ModelManager {
+    private static cacheDir;
+    /**
+     * Ensure model is downloaded and cached
+     * @param model - Model descriptor
+     * @param interactive - Show interactive prompt (default: true if TTY)
+     * @returns Path to cached model
+     */
+    static ensureModel(model: ModelDescriptor, interactive?: boolean): Promise<string>;
+    /**
+     * Check if model is cached
+     */
+    private static hasModel;
+    /**
+     * Download model using @xenova/transformers
+     */
+    private static downloadModel;
+    /**
+     * Prompt user for input (interactive mode)
+     */
+    private static promptUser;
+    /**
+     * Get model metadata
+     */
+    static getMetadata(modelPath: string): Promise<ModelCacheMetadata | null>;
+}
+//# sourceMappingURL=model-manager.d.ts.map

package/dist/src/shared/models/model-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-manager.d.ts","sourceRoot":"","sources":["../../../../src/shared/models/model-manager.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAQH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3D,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAsC;IAE7D;;;;;OAKG;WACU,WAAW,CACtB,KAAK,EAAE,eAAe,EACtB,WAAW,UAAuB,GACjC,OAAO,CAAC,MAAM,CAAC;IAuClB;;OAEG;mBACkB,QAAQ;IAK7B;;OAEG;mBACkB,aAAa;IA8BlC;;OAEG;mBACkB,UAAU;IAc/B;;OAEG;WACU,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC;CAahF"}

package/dist/src/shared/models/model-manager.js

@@ -0,0 +1,116 @@
+/**
+ * Model download and cache management
+ * Handles model downloads to ~/.kiri/models/
+ */
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import * as readline from "node:readline";
+export class ModelManager {
+    static cacheDir = join(homedir(), ".kiri", "models");
+    /**
+     * Ensure model is downloaded and cached
+     * @param model - Model descriptor
+     * @param interactive - Show interactive prompt (default: true if TTY)
+     * @returns Path to cached model
+     */
+    static async ensureModel(model, interactive = process.stdout.isTTY) {
+        const modelPath = join(this.cacheDir, `${model.name}@${model.version}`);
+        // Check if already cached
+        if (await this.hasModel(modelPath)) {
+            return modelPath;
+        }
+        // Built-in models don't need download
+        if (model.source === "builtin") {
+            return modelPath;
+        }
+        // Interactive prompt (if TTY)
+        if (interactive) {
+            const answer = await this.promptUser(`\nSemantic embeddings require ~${model.sizeMB}MB download to ${this.cacheDir}.\nDownload now? [Y/n]: `);
+            if (answer !== "Y" && answer !== "y" && answer !== "") {
+                throw new Error("Model download declined by user");
+            }
+        }
+        else {
+            // Non-interactive: Check if env var allows auto-download
+            if (process.env.KIRI_AUTO_DOWNLOAD !== "1") {
+                throw new Error("Semantic embeddings require model download. " +
+                    "Run interactively or set KIRI_AUTO_DOWNLOAD=1");
+            }
+        }
+        // Download with progress
+        console.info(`📥 Downloading ${model.name} (~${model.sizeMB}MB)...`);
+        await this.downloadModel(model, modelPath);
+        console.info(`✅ Model cached to ${modelPath}`);
+        return modelPath;
+    }
+    /**
+     * Check if model is cached
+     */
+    static async hasModel(modelPath) {
+        const metadataPath = join(modelPath, "metadata.json");
+        return existsSync(metadataPath);
+    }
+    /**
+     * Download model using @xenova/transformers
+     */
+    static async downloadModel(model, targetPath) {
+        try {
+            // Ensure cache directory exists
+            await mkdir(targetPath, { recursive: true });
+            // Import @xenova/transformers dynamically (lazy-load)
+            const { pipeline, env } = await import("@xenova/transformers");
+            // Configure cache directory
+            env.cacheDir = targetPath;
+            env.allowRemoteModels = true;
+            env.allowLocalModels = false;
+            // Trigger download by loading pipeline
+            // This downloads model files to targetPath
+            await pipeline("feature-extraction", model.source);
+            // Write metadata
+            const metadata = {
+                name: model.name,
+                version: model.version,
+                downloadedAt: new Date().toISOString(),
+            };
+            await writeFile(join(targetPath, "metadata.json"), JSON.stringify(metadata, null, 2));
+        }
+        catch (error) {
+            // Clean up partial download on error
+            throw new Error(`Model download failed: ${error}`);
+        }
+    }
+    /**
+     * Prompt user for input (interactive mode)
+     */
+    static async promptUser(question) {
+        const rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout,
+        });
+        return new Promise((resolve) => {
+            rl.question(question, (answer) => {
+                rl.close();
+                resolve(answer.trim());
+            });
+        });
+    }
+    /**
+     * Get model metadata
+     */
+    static async getMetadata(modelPath) {
+        const metadataPath = join(modelPath, "metadata.json");
+        if (!existsSync(metadataPath)) {
+            return null;
+        }
+        try {
+            const content = await readFile(metadataPath, "utf-8");
+            return JSON.parse(content);
+        }
+        catch {
+            return null;
+        }
+    }
+}
+//# sourceMappingURL=model-manager.js.map

package/dist/src/shared/models/model-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-manager.js","sourceRoot":"","sources":["../../../../src/shared/models/model-manager.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAC;AAW1C,MAAM,OAAO,YAAY;IACf,MAAM,CAAC,QAAQ,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;IAE7D;;;;;OAKG;IACH,MAAM,CAAC,KAAK,CAAC,WAAW,CACtB,KAAsB,EACtB,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,KAAK;QAElC,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QAExE,0BAA0B;QAC1B,IAAI,MAAM,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;YACnC,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,sCAAsC;QACtC,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAC/B,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,8BAA8B;QAC9B,IAAI,WAAW,EAAE,CAAC;YAChB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,UAAU,CAClC,kCAAkC,KAAK,CAAC,MAAM,kBAAkB,IAAI,CAAC,QAAQ,0BAA0B,CACxG,CAAC;YACF,IAAI,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,EAAE,EAAE,CAAC;gBACtD,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;YACrD,CAAC;QACH,CAAC;aAAM,CAAC;YACN,yDAAyD;YACzD,IAAI,OAAO,CAAC,GAAG,CAAC,kBAAkB,KAAK,GAAG,EAAE,CAAC;gBAC3C,MAAM,IAAI,KAAK,CACb,8CAA8C;oBAC5C,+CAA+C,CAClD,CAAC;YACJ,CAAC;QACH,CAAC;QAED,yBAAyB;QACzB,OAAO,CAAC,IAAI,CAAC,kBAAkB,KAAK,CAAC,IAAI,MAAM,KAAK,CAAC,MAAM,QAAQ,CAAC,CAAC;QACrE,MAAM,IAAI,CAAC,aAAa,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;QAC3C,OAAO,CAAC,IAAI,CAAC,qBAAqB,SAAS,EAAE,CAAC,CAAC;QAE/C,OAAO,SAAS,CAAC;IACnB,CAAC;IAED;;OAEG;IACK,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,SAAiB;QAC7C,MAAM,YAAY,GAAG,IAAI,CAAC,SAAS,EAAE,eAAe,CAAC,CAAC;QACtD,OAAO,UAAU,CAAC,YAAY,CAAC,CAAC;IAClC,CAAC;IAED;;OAEG;IACK,MAAM,CAAC,KAAK,CAAC,aAAa,CAAC,KAAsB,EAAE,UAAkB;QAC3E,IAAI,CAAC;YACH,gCAAgC;YAChC,MAAM,KAAK,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAE7C,sDAAsD;YACtD,MAAM,EAAE,QAAQ,EAAE,GAAG,EAAE,GAAG,MAAM,MAAM,CAAC,sBAAsB,CAAC,CAAC;YAE/D,4BAA4B;YAC5B,GAAG,CAAC,QAAQ,GAAG,UAAU,CAAC;YAC1B,GAAG,CAAC,iBAAiB,GAAG,IAAI,CAAC;YAC7B,GAAG,CAAC,gBAAgB,GAAG,KAAK,CAAC;YAE7B,uCAAuC;YACvC,2CAA2C;YAC3C,MAAM,QAAQ,CAAC,oBAAoB,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;YAEnD,iBAAiB;YACjB,MAAM,QAAQ,GAAuB;gBACnC,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,OAAO,EAAE,KAAK,CAAC,OAAO;gBACtB,YAAY,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;aACvC,CAAC;YACF,MAAM,SAAS,CAAC,IAAI,CAAC,UAAU,EAAE,eAAe,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;QACxF,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,qCAAqC;YACrC,MAAM,IAAI,KAAK,CAAC,0BAA0B,KAAK,EAAE,CAAC,CAAC;QACrD,CAAC;IACH,CAAC;IAED;;OAEG;IACK,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,QAAgB;QAC9C,MAAM,EAAE,GAAG,QAAQ,CAAC,eAAe,CAAC;YAClC,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,MAAM,EAAE,OAAO,CAAC,MAAM;SACvB,CAAC,CAAC;QAEH,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;YAC7B,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,EAAE;gBAC/B,EAAE,CAAC,KAAK,EAAE,CAAC;gBACX,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;YACzB,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,SAAiB;QACxC,MAAM,YAAY,GAAG,IAAI,CAAC,SAAS,EAAE,eAAe,CAAC,CAAC;QACtD,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;YAC9B,OAAO,IAAI,CAAC;QACd,CAAC;QAED,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;YACtD,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAC7B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC"}

package/dist/src/shared/models/model-manifest.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Model manifest and descriptors
+ * Defines available embedding models and their properties
+ */
+import type { EmbeddingModel } from "../embedding/engine.js";
+export interface ModelDescriptor {
+    /** Model identifier */
+    name: EmbeddingModel;
+    /** Model version */
+    version: string;
+    /** Download size in MB */
+    sizeMB: number;
+    /** Source (Hugging Face model ID or 'builtin') */
+    source: string;
+    /** Embedding dimensionality */
+    dims: number;
+}
+/**
+ * Available embedding models
+ */
+export declare const MODELS: Record<EmbeddingModel, ModelDescriptor>;
+//# sourceMappingURL=model-manifest.d.ts.map

package/dist/src/shared/models/model-manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-manifest.d.ts","sourceRoot":"","sources":["../../../../src/shared/models/model-manifest.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAE7D,MAAM,WAAW,eAAe;IAC9B,uBAAuB;IACvB,IAAI,EAAE,cAAc,CAAC;IAErB,oBAAoB;IACpB,OAAO,EAAE,MAAM,CAAC;IAEhB,0BAA0B;IAC1B,MAAM,EAAE,MAAM,CAAC;IAEf,kDAAkD;IAClD,MAAM,EAAE,MAAM,CAAC;IAEf,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,eAAO,MAAM,MAAM,EAAE,MAAM,CAAC,cAAc,EAAE,eAAe,CAe1D,CAAC"}

package/dist/src/shared/models/model-manifest.js

@@ -0,0 +1,24 @@
+/**
+ * Model manifest and descriptors
+ * Defines available embedding models and their properties
+ */
+/**
+ * Available embedding models
+ */
+export const MODELS = {
+    "lsh-64": {
+        name: "lsh-64",
+        version: "1",
+        sizeMB: 0,
+        source: "builtin",
+        dims: 64,
+    },
+    "semantic-gte-384": {
+        name: "semantic-gte-384",
+        version: "1",
+        sizeMB: 34,
+        source: "Xenova/gte-small",
+        dims: 384,
+    },
+};
+//# sourceMappingURL=model-manifest.js.map

package/dist/src/shared/models/model-manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-manifest.js","sourceRoot":"","sources":["../../../../src/shared/models/model-manifest.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAqBH;;GAEG;AACH,MAAM,CAAC,MAAM,MAAM,GAA4C;IAC7D,QAAQ,EAAE;QACR,IAAI,EAAE,QAAQ;QACd,OAAO,EAAE,GAAG;QACZ,MAAM,EAAE,CAAC;QACT,MAAM,EAAE,SAAS;QACjB,IAAI,EAAE,EAAE;KACT;IACD,kBAAkB,EAAE;QAClB,IAAI,EAAE,kBAAkB;QACxB,OAAO,EAAE,GAAG;QACZ,MAAM,EAAE,EAAE;QACV,MAAM,EAAE,kBAAkB;QAC1B,IAAI,EAAE,GAAG;KACV;CACF,CAAC"}

package/dist/src/shared/utils/validation.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Validation utilities for CLI arguments and user input
+ */
+/**
+ * Parse a string to a positive integer with validation
+ *
+ * @param value - String value to parse
+ * @param defaultValue - Default value if input is undefined
+ * @param name - Parameter name for error messages
+ * @returns Parsed integer
+ * @throws Error if value is not a valid positive integer
+ */
+export declare function parsePositiveInt(value: string | undefined, defaultValue: number, name: string): number;
+//# sourceMappingURL=validation.d.ts.map

package/dist/src/shared/utils/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../../../src/shared/utils/validation.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,MAAM,GACX,MAAM,CAUR"}

package/dist/src/shared/utils/validation.js

@@ -0,0 +1,22 @@
+/**
+ * Validation utilities for CLI arguments and user input
+ */
+/**
+ * Parse a string to a positive integer with validation
+ *
+ * @param value - String value to parse
+ * @param defaultValue - Default value if input is undefined
+ * @param name - Parameter name for error messages
+ * @returns Parsed integer
+ * @throws Error if value is not a valid positive integer
+ */
+export function parsePositiveInt(value, defaultValue, name) {
+    if (!value)
+        return defaultValue;
+    const parsed = parseInt(value, 10);
+    if (Number.isNaN(parsed) || parsed < 0) {
+        throw new Error(`Invalid ${name}: "${value}". Expected a positive integer. Use default ${defaultValue} or specify a valid number.`);
+    }
+    return parsed;
+}
+//# sourceMappingURL=validation.js.map

package/dist/src/shared/utils/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../../../src/shared/utils/validation.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;GAQG;AACH,MAAM,UAAU,gBAAgB,CAC9B,KAAyB,EACzB,YAAoB,EACpB,IAAY;IAEZ,IAAI,CAAC,KAAK;QAAE,OAAO,YAAY,CAAC;IAEhC,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACnC,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;QACvC,MAAM,IAAI,KAAK,CACb,WAAW,IAAI,MAAM,KAAK,+CAA+C,YAAY,6BAA6B,CACnH,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kiri-mcp-server",
-  "version": "0.9.9",
+  "version": "0.10.0",
   "description": "KIRI context extraction platform",
   "type": "module",
   "packageManager": "pnpm@9.0.0",
@@ -63,6 +63,8 @@
     "verify:tools": "tsx scripts/test/verify-all.ts --category tools",
     "verify:watch": "tsx scripts/test/verify-all.ts --category watch",
     "verify:eval": "tsx scripts/test/verify-all.ts --category eval",
+    "eval:golden": "tsx scripts/eval/run-golden.ts",
+    "eval:golden:verbose": "tsx scripts/eval/run-golden.ts --verbose",
     "check": "pnpm run lint && pnpm run test",
     "prepublishOnly": "pnpm run build"
   },
@@ -88,6 +90,7 @@
     "eslint-config-prettier": "^9.1.0",
     "eslint-plugin-import": "^2.29.1",
     "execa": "^9.6.0",
+    "fast-check": "^4.3.0",
     "lint-staged": "^15.2.10",
     "prettier": "^3.3.3",
     "simple-git-hooks": "^2.10.0",