mcard-js 2.1.12 → 2.1.13

package/dist/ptr/node/runtimes/loader.js.map

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

package/dist/ptr/node/runtimes/python.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Python runtime executor.
+ *
+ * Executes Python code via subprocess with automatic entry point detection.
+ */
+import { Runtime } from './base.js';
+export declare class PythonRuntime implements Runtime {
+    execute(code: string, context: unknown, config: any): Promise<unknown>;
+    /**
+     * Create Python wrapper script with entry point invocation.
+     */
+    private createWrapper;
+}
+//# sourceMappingURL=python.d.ts.map

package/dist/ptr/node/runtimes/python.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"python.d.ts","sourceRoot":"","sources":["../../../../src/ptr/node/runtimes/python.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,EAAE,OAAO,EAAyB,MAAM,WAAW,CAAC;AAM3D,qBAAa,aAAc,YAAW,OAAO;IACnC,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC;IA6B5E;;OAEG;IACH,OAAO,CAAC,aAAa;CAsDxB"}

package/dist/ptr/node/runtimes/python.js

@@ -0,0 +1,100 @@
+/**
+ * Python runtime executor.
+ *
+ * Executes Python code via subprocess with automatic entry point detection.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as util from 'util';
+import { execFile, parseOutput } from './base.js';
+import { findProjectRoot } from '../FileSystemUtils.js';
+const writeFile = util.promisify(fs.writeFile);
+const unlink = util.promisify(fs.unlink);
+export class PythonRuntime {
+    async execute(code, context, config) {
+        const entryPoint = config.entry_point || 'add';
+        const contextStr = JSON.stringify(context);
+        const projectRoot = findProjectRoot();
+        const wrapper = this.createWrapper(code, entryPoint);
+        const tmpFile = path.resolve(process.cwd(), `tmp_${Date.now()}.py`);
+        await writeFile(tmpFile, wrapper);
+        try {
+            const { stdout, stderr } = await execFile('python3', [tmpFile, contextStr], {
+                cwd: projectRoot,
+                env: {
+                    ...process.env,
+                    PYTHONPATH: `${projectRoot}${path.delimiter}${process.env.PYTHONPATH || ''}`
+                }
+            });
+            if (stderr)
+                console.error('[Python Stderr]', stderr);
+            return parseOutput(stdout);
+        }
+        catch (error) {
+            const stderr = error.stderr ? `\nStderr: ${error.stderr.toString()}` : '';
+            const stdout = error.stdout ? `\nStdout: ${error.stdout.toString()}` : '';
+            throw new Error(`Python execution failed: ${error.message}${stderr}${stdout}`);
+        }
+        finally {
+            await unlink(tmpFile);
+        }
+    }
+    /**
+     * Create Python wrapper script with entry point invocation.
+     */
+    createWrapper(code, entryPoint) {
+        return `
+import sys
+import json
+
+try:
+    context = json.loads(sys.argv[1])
+    target = context
+    
+    if isinstance(target, str):
+        target = target.encode('utf-8')
+except:
+    context = {}
+    target = {}
+    pass
+
+# User logic
+${code}
+
+# Entry point invocation
+def _is_arg_error(e):
+    msg = str(e).lower()
+    return 'positional argument' in msg or 'required argument' in msg or 'takes' in msg and 'argument' in msg
+
+try:
+    fn = None
+    if '${entryPoint}' in dir():
+        fn = ${entryPoint}
+    elif '${entryPoint}' in globals():
+        fn = globals()['${entryPoint}']
+        
+    if fn is not None:
+        try:
+            res = fn(context)
+        except TypeError as e:
+            if not _is_arg_error(e):
+                raise
+            try:
+                res = fn(target)
+            except TypeError as e2:
+                if not _is_arg_error(e2):
+                    raise
+                res = fn()
+        print(json.dumps(res))
+    else:
+        if 'result' in dir() or 'result' in globals():
+            print(json.dumps(result if 'result' in dir() else globals().get('result')))
+        else:
+            print(json.dumps(None))
+except Exception as e:
+    print(json.dumps({"error": str(e)}))
+    sys.exit(1)
+`;
+    }
+}
+//# sourceMappingURL=python.js.map

package/dist/ptr/node/runtimes/python.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"python.js","sourceRoot":"","sources":["../../../../src/ptr/node/runtimes/python.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,EAAW,QAAQ,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAExD,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,SAAS,CAAC,CAAC;AAC/C,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC;AAEzC,MAAM,OAAO,aAAa;IACtB,KAAK,CAAC,OAAO,CAAC,IAAY,EAAE,OAAgB,EAAE,MAAW;QACrD,MAAM,UAAU,GAAG,MAAM,CAAC,WAAW,IAAI,KAAK,CAAC;QAC/C,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QAC3C,MAAM,WAAW,GAAG,eAAe,EAAE,CAAC;QAEtC,MAAM,OAAO,GAAG,IAAI,CAAC,aAAa,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;QACrD,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,OAAO,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QACpE,MAAM,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAElC,IAAI,CAAC;YACD,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,QAAQ,CAAC,SAAS,EAAE,CAAC,OAAO,EAAE,UAAU,CAAC,EAAE;gBACxE,GAAG,EAAE,WAAW;gBAChB,GAAG,EAAE;oBACD,GAAG,OAAO,CAAC,GAAG;oBACd,UAAU,EAAE,GAAG,WAAW,GAAG,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,UAAU,IAAI,EAAE,EAAE;iBAC/E;aACJ,CAAC,CAAC;YACH,IAAI,MAAM;gBAAE,OAAO,CAAC,KAAK,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAAC;YAErD,OAAO,WAAW,CAAC,MAAM,CAAC,CAAC;QAC/B,CAAC;QAAC,OAAO,KAAU,EAAE,CAAC;YAClB,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,aAAa,KAAK,CAAC,MAAM,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC1E,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,aAAa,KAAK,CAAC,MAAM,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC1E,MAAM,IAAI,KAAK,CAAC,4BAA4B,KAAK,CAAC,OAAO,GAAG,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;QACnF,CAAC;gBAAS,CAAC;YACP,MAAM,MAAM,CAAC,OAAO,CAAC,CAAC;QAC1B,CAAC;IACL,CAAC;IAED;;OAEG;IACK,aAAa,CAAC,IAAY,EAAE,UAAkB;QAClD,OAAO;;;;;;;;;;;;;;;;EAgBb,IAAI;;;;;;;;;UASI,UAAU;eACL,UAAU;YACb,UAAU;0BACI,UAAU;;;;;;;;;;;;;;;;;;;;;;;CAuBnC,CAAC;IACE,CAAC;CACJ"}

package/dist/ptr/node/runtimes/wasm.d.ts

@@ -0,0 +1,10 @@
+/**
+ * WASM runtime executor.
+ *
+ * Executes WebAssembly modules via wasmtime CLI.
+ */
+import { Runtime } from './base.js';
+export declare class WasmRuntime implements Runtime {
+    execute(wasmPath: string, context: unknown, config: any, chapterDir: string): Promise<unknown>;
+}
+//# sourceMappingURL=wasm.d.ts.map

package/dist/ptr/node/runtimes/wasm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wasm.d.ts","sourceRoot":"","sources":["../../../../src/ptr/node/runtimes/wasm.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,qBAAa,WAAY,YAAW,OAAO;IACjC,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAsDvG"}

package/dist/ptr/node/runtimes/wasm.js

@@ -0,0 +1,55 @@
+/**
+ * WASM runtime executor.
+ *
+ * Executes WebAssembly modules via wasmtime CLI.
+ */
+import * as path from 'path';
+import * as child_process from 'child_process';
+export class WasmRuntime {
+    async execute(wasmPath, context, config, chapterDir) {
+        const fullPath = path.resolve(chapterDir, wasmPath);
+        const contextStr = typeof context === 'string' ? context : JSON.stringify(context ?? {});
+        return new Promise((resolve, reject) => {
+            const proc = child_process.spawn('wasmtime', [fullPath, contextStr]);
+            // Close stdin immediately - WASM programs don't read from stdin
+            proc.stdin.end();
+            let stdout = '';
+            let stderr = '';
+            proc.stdout.on('data', (data) => {
+                stdout += data.toString('utf-8');
+            });
+            proc.stderr.on('data', (data) => {
+                stderr += data.toString('utf-8');
+            });
+            proc.on('error', (err) => {
+                reject(err);
+            });
+            proc.on('close', (code) => {
+                if (code !== 0) {
+                    if (stderr.includes('command not found') || stderr.includes('wasmtime: not found')) {
+                        return reject(new Error('WASM runtime requires wasmtime CLI. Install it, e.g. with: brew install wasmtime'));
+                    }
+                    return reject(new Error(`wasmtime exited with code ${code}: ${stderr || stdout}`));
+                }
+                const out = stdout.trim();
+                if (!out) {
+                    return resolve(undefined);
+                }
+                // Try numeric first (for arithmetic chapters)
+                const numeric = out.trim();
+                if (numeric && !Number.isNaN(Number(numeric))) {
+                    return resolve(Number(numeric));
+                }
+                // Try JSON
+                try {
+                    return resolve(JSON.parse(out));
+                }
+                catch {
+                    // Fallback: raw string
+                    return resolve(out);
+                }
+            });
+        });
+    }
+}
+//# sourceMappingURL=wasm.js.map

package/dist/ptr/node/runtimes/wasm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wasm.js","sourceRoot":"","sources":["../../../../src/ptr/node/runtimes/wasm.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,KAAK,aAAa,MAAM,eAAe,CAAC;AAG/C,MAAM,OAAO,WAAW;IACpB,KAAK,CAAC,OAAO,CAAC,QAAgB,EAAE,OAAgB,EAAE,MAAW,EAAE,UAAkB;QAC7E,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;QACpD,MAAM,UAAU,GAAG,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC;QAEzF,OAAO,IAAI,OAAO,CAAU,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YAC5C,MAAM,IAAI,GAAG,aAAa,CAAC,KAAK,CAAC,UAAU,EAAE,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC,CAAC;YAErE,gEAAgE;YAChE,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC;YAEjB,IAAI,MAAM,GAAG,EAAE,CAAC;YAChB,IAAI,MAAM,GAAG,EAAE,CAAC;YAEhB,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,IAAY,EAAE,EAAE;gBACpC,MAAM,IAAI,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;YACrC,CAAC,CAAC,CAAC;YAEH,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,IAAY,EAAE,EAAE;gBACpC,MAAM,IAAI,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;YACrC,CAAC,CAAC,CAAC;YAEH,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE;gBACrB,MAAM,CAAC,GAAG,CAAC,CAAC;YAChB,CAAC,CAAC,CAAC;YAEH,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE;gBACtB,IAAI,IAAI,KAAK,CAAC,EAAE,CAAC;oBACb,IAAI,MAAM,CAAC,QAAQ,CAAC,mBAAmB,CAAC,IAAI,MAAM,CAAC,QAAQ,CAAC,qBAAqB,CAAC,EAAE,CAAC;wBACjF,OAAO,MAAM,CAAC,IAAI,KAAK,CAAC,kFAAkF,CAAC,CAAC,CAAC;oBACjH,CAAC;oBACD,OAAO,MAAM,CAAC,IAAI,KAAK,CAAC,6BAA6B,IAAI,KAAK,MAAM,IAAI,MAAM,EAAE,CAAC,CAAC,CAAC;gBACvF,CAAC;gBAED,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;gBAC1B,IAAI,CAAC,GAAG,EAAE,CAAC;oBACP,OAAO,OAAO,CAAC,SAAS,CAAC,CAAC;gBAC9B,CAAC;gBAED,8CAA8C;gBAC9C,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;gBAC3B,IAAI,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC;oBAC5C,OAAO,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;gBACpC,CAAC;gBAED,WAAW;gBACX,IAAI,CAAC;oBACD,OAAO,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;gBACpC,CAAC;gBAAC,MAAM,CAAC;oBACL,uBAAuB;oBACvB,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC;gBACxB,CAAC;YACL,CAAC,CAAC,CAAC;QACP,CAAC,CAAC,CAAC;IACP,CAAC;CACJ"}

package/dist/rag/GraphRAGEngine.d.ts

@@ -0,0 +1,26 @@
+import { GraphStore } from './graph/store';
+import { GraphExtractor } from './graph/extractor';
+import { MCardVectorStore } from '../storage/VectorStore';
+import { MCard } from '../model/MCard';
+export interface GraphRAGResponse {
+    answer: string;
+    sources: string[];
+    entities: any[];
+    relationships: any[];
+    graphContext: string;
+    vectorContext: string;
+    confidence: number;
+    metadata?: any;
+}
+export declare class GraphRAGEngine {
+    vectorStore: MCardVectorStore;
+    graphStore: GraphStore;
+    extractor: GraphExtractor;
+    llmModel: string;
+    config: any;
+    constructor(vectorDbPath: string, graphDbPath?: string | null, llmModel?: string, config?: any);
+    index(mcard: MCard, extractGraph?: boolean, force?: boolean): Promise<any>;
+    query(question: string, k?: number, useGraph?: boolean): Promise<GraphRAGResponse>;
+    private _getGraphContext;
+}
+//# sourceMappingURL=GraphRAGEngine.d.ts.map

package/dist/rag/GraphRAGEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GraphRAGEngine.d.ts","sourceRoot":"","sources":["../../src/rag/GraphRAGEngine.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAA2D,MAAM,eAAe,CAAC;AACpG,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAsB,MAAM,wBAAwB,CAAC;AAC9E,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AA6BvC,MAAM,WAAW,gBAAgB;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,EAAE,GAAG,EAAE,CAAC;IAChB,aAAa,EAAE,GAAG,EAAE,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,GAAG,CAAC;CAClB;AAED,qBAAa,cAAc;IACvB,WAAW,EAAE,gBAAgB,CAAC;IAC9B,UAAU,EAAE,UAAU,CAAC;IACvB,SAAS,EAAE,cAAc,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,GAAG,CAAC;gBAGR,YAAY,EAAE,MAAM,EACpB,WAAW,GAAE,MAAM,GAAG,IAAW,EACjC,QAAQ,GAAE,MAAwB,EAClC,MAAM,GAAE,GAAQ;IAoBd,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,YAAY,GAAE,OAAc,EAAE,KAAK,GAAE,OAAe,GAAG,OAAO,CAAC,GAAG,CAAC;IAqBvF,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAC,GAAE,MAAU,EAAE,QAAQ,GAAE,OAAc,GAAG,OAAO,CAAC,gBAAgB,CAAC;YA0EnF,gBAAgB;CAiDjC"}

package/dist/rag/GraphRAGEngine.js

@@ -0,0 +1,166 @@
+import { GraphStore, storeExtractionResult } from './graph/store';
+import { GraphExtractor } from './graph/extractor';
+import { MCardVectorStore } from '../storage/VectorStore';
+import { chatMonad } from '../ptr/llm/LLMRuntime';
+const GRAPHRAG_SYSTEM_PROMPT = `You are a helpful assistant that answers questions using both document context and a knowledge graph.
+
+You have access to:
+1. DOCUMENT CONTEXT: Relevant text passages from the knowledge base
+2. GRAPH CONTEXT: Entities and their relationships from the knowledge graph
+
+Use both sources to provide comprehensive, accurate answers.
+- Cite sources [1], [2], etc. for document context
+- Reference entities by name when using graph information
+- If the graph shows relationships that help answer the question, describe them
+
+Be thorough but concise. Acknowledge if information is incomplete.`;
+const GRAPH_QUERY_PROMPT = `Question: {question}
+
+=== DOCUMENT CONTEXT ===
+{vector_context}
+
+=== KNOWLEDGE GRAPH ===
+Entities: {entities}
+Relationships: {relationships}
+
+Please provide a comprehensive answer using both the document context and knowledge graph information.`;
+export class GraphRAGEngine {
+    vectorStore;
+    graphStore;
+    extractor;
+    llmModel;
+    config;
+    constructor(vectorDbPath, graphDbPath = null, llmModel = 'gemma3:latest', config = {}) {
+        this.config = config;
+        this.llmModel = llmModel;
+        // Init vector store
+        this.vectorStore = new MCardVectorStore(vectorDbPath, config);
+        // Init graph store
+        const gPath = graphDbPath || vectorDbPath;
+        this.graphStore = new GraphStore(gPath);
+        // Init extractor
+        // GraphExtractor constructor expects config object
+        this.extractor = new GraphExtractor({ model: llmModel, ...config });
+    }
+    async index(mcard, extractGraph = true, force = false) {
+        const stats = { vectors: 0, entities: 0, relationships: 0 };
+        let content = mcard.getContentAsText();
+        // Vector index
+        // We always index (INSERT OR REPLACE)
+        stats.vectors = await this.vectorStore.index(mcard.hash, content);
+        // Graph extract
+        if (extractGraph && (force || !(await this.graphStore.isExtracted(mcard.hash)))) {
+            const result = await this.extractor.extract(content);
+            if (result.success) {
+                const [entCount, relCount] = storeExtractionResult(this.graphStore, result, mcard.hash);
+                stats.entities = entCount;
+                stats.relationships = relCount;
+            }
+        }
+        return stats;
+    }
+    async query(question, k = 5, useGraph = true) {
+        // Vector Search
+        const results = await this.vectorStore.search(question, k);
+        const contextParts = [];
+        const sources = [];
+        results.forEach((r, i) => {
+            const chunk = r.content || `[Content from ${r.hash.substring(0, 8)}]`;
+            contextParts.push(`[${i + 1}] ${chunk}`);
+            sources.push(r.hash);
+        });
+        const vectorContext = contextParts.join('\n\n');
+        // Graph Search
+        let entities = [];
+        let relationships = [];
+        let graphContext = "";
+        if (useGraph) {
+            const graphData = await this._getGraphContext(question, sources);
+            entities = graphData.entities;
+            relationships = graphData.relationships;
+            if (entities.length > 0) {
+                const entStr = entities.slice(0, 10).map(e => `${e.name} (${e.type})`).join(', ');
+                const relStr = relationships.slice(0, 15).map(r => `${r.source} --${r.relationship}-> ${r.target}`).join('\n');
+                graphContext = `Entities: ${entStr}\nRelationships:\n${relStr}`;
+            }
+        }
+        // LLM Generation
+        let answer = "";
+        if (!vectorContext && entities.length === 0) {
+            answer = "I couldn't find relevant information.";
+        }
+        else {
+            const entStr = entities.length ? entities.map(e => `${e.name} (${e.type})`).join(', ') : "None found";
+            const relStr = relationships.length ? relationships.map(r => `  - ${r.source} --${r.relationship}-> ${r.target}`).join('\n') : "None found";
+            const prompt = GRAPH_QUERY_PROMPT
+                .replace('{question}', question)
+                .replace('{vector_context}', vectorContext || "No document context available.")
+                .replace('{entities}', entStr)
+                .replace('{relationships}', relStr);
+            const monad = chatMonad(null, // messages null
+            prompt, GRAPHRAG_SYSTEM_PROMPT, { model: this.llmModel, temperature: 0.3 });
+            const result = await monad.run();
+            if (result.isRight) {
+                const val = result.right;
+                answer = typeof val === 'object' ? val.content : val;
+            }
+            else {
+                answer = `Error: ${result.left}`;
+            }
+        }
+        return {
+            answer,
+            sources,
+            entities,
+            relationships,
+            graphContext,
+            vectorContext,
+            confidence: 0.8 // placeholder
+        };
+    }
+    async _getGraphContext(query, sourceHashes) {
+        const entities = [];
+        const seenIds = new Set();
+        // Word search
+        const words = query.split(/\s+/).filter(w => w.length > 3);
+        const uniqueWords = [...new Set(words)]; // dedupe words
+        for (const word of uniqueWords) {
+            // Check if searchEntities exists on GraphStore
+            const found = await this.graphStore.searchEntities(word, undefined, 5);
+            for (const ent of found) {
+                if (!seenIds.has(ent.id)) {
+                    seenIds.add(ent.id);
+                    entities.push(ent);
+                }
+            }
+        }
+        // Source search
+        const uniquesources = [...new Set(sourceHashes)].slice(0, 3);
+        for (const hash of uniquesources) {
+            const found = await this.graphStore.getEntitiesBySource(hash);
+            for (const ent of found) {
+                if (!seenIds.has(ent.id)) {
+                    seenIds.add(ent.id);
+                    entities.push(ent);
+                }
+            }
+        }
+        // Get Relationships
+        const relationships = [];
+        for (const ent of entities) {
+            const outRels = await this.graphStore.getRelationshipsFrom(ent.id);
+            for (const r of outRels) {
+                relationships.push({
+                    source: ent.name,
+                    relationship: r.relationship,
+                    target: r.targetName
+                });
+            }
+            // Limit per entity to avoid explosion
+            if (relationships.length > 50)
+                break;
+        }
+        return { entities, relationships };
+    }
+}
+//# sourceMappingURL=GraphRAGEngine.js.map

package/dist/rag/GraphRAGEngine.js.map

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

package/dist/rag/HandleVectorStore.d.ts

@@ -0,0 +1,201 @@
+/**
+ * Handle-Aware Vector Store for Semantic Versioning
+ *
+ * Extends VectorStore to enable semantic similarity detection
+ * across MCard versions linked to handles.
+ *
+ * Key Features:
+ * - Link MCards to handles during indexing
+ * - Compare versions within a handle by semantic similarity
+ * - Filter searches by handle
+ * - Sort version history by distance to current or query
+ * - Automatic upgrade type classification based on semantic delta
+ *
+ * @module mcard-js/rag/HandleVectorStore
+ */
+import { MCard } from '../model/MCard';
+import { MCardVectorStore, VectorStoreConfig } from '../storage/VectorStore';
+export { VectorStoreConfig } from '../storage/VectorStore';
+/**
+ * A version in a handle's history with embedding info.
+ */
+export interface HandleVersion {
+    hash: string;
+    versionOrder: number;
+    isCurrent: boolean;
+    createdAt: string;
+    parentHash?: string;
+    embeddingId?: number;
+    semanticDelta?: number;
+    upgradeType?: string;
+}
+/**
+ * Result from version similarity comparison.
+ */
+export interface VersionSimilarityResult {
+    hash: string;
+    versionOrder: number;
+    similarityToCurrent: number;
+    distanceToCurrent: number;
+    similarityToQuery?: number;
+    parentHash?: string;
+    upgradeType?: string;
+}
+/**
+ * Classify upgrade type based on semantic similarity to parent.
+ *
+ * Thresholds:
+ * - >= 0.95: trivial (formatting, typo fixes)
+ * - 0.85 - 0.94: minor (small edits, clarifications)
+ * - 0.70 - 0.84: major (significant content changes)
+ * - < 0.70: breaking (major semantic drift)
+ *
+ * @param semanticDelta Cosine similarity to parent version
+ * @returns Upgrade type string
+ */
+export declare function classifyUpgradeType(semanticDelta: number): string;
+/**
+ * Calculate Euclidean distance between two vectors.
+ */
+export declare function euclideanDistance(a: number[], b: number[]): number;
+/**
+ * Extended vector store with handle-aware version similarity.
+ *
+ * This class implements the Handle-Hash Duality pattern with semantic
+ * awareness, enabling:
+ *
+ * - Version tracking via handles
+ * - Semantic similarity detection across versions
+ * - Intelligent upgrade classification
+ * - Cross-version semantic search
+ *
+ * Architecture:
+ * - Handles remain stable identifiers (Proxy Pattern)
+ * - Hashes reference immutable content (Content-Addressing)
+ * - Embeddings enable semantic understanding (Vector Search)
+ *
+ * @example
+ * ```typescript
+ * const store = new HandleVectorStore(':memory:');
+ *
+ * // Index with handle association
+ * await store.indexWithHandle(mcard, 'my_document');
+ *
+ * // Get versions sorted by similarity to current
+ * const versions = await store.getVersionsBySimilarity('my_document');
+ *
+ * // Find versions similar to a query
+ * const results = await store.searchHandleVersions('my_document', 'machine learning');
+ * ```
+ */
+export declare class HandleVectorStore extends MCardVectorStore {
+    constructor(dbPath?: string, config?: Partial<VectorStoreConfig>);
+    /**
+     * Create handle-vector bridge tables for semantic versioning.
+     */
+    private initHandleTables;
+    /**
+     * Index an MCard and associate it with a handle.
+     *
+     * This method:
+     * 1. Indexes the MCard content with embeddings (via base class)
+     * 2. Links the MCard hash to the handle with version tracking
+     * 3. Computes semantic delta from parent version (if exists)
+     * 4. Classifies the upgrade type based on similarity
+     *
+     * @param mcard MCard to index
+     * @param handle Handle name to associate with
+     * @param isCurrent Whether this is the current version
+     * @param chunk Whether to chunk long content
+     * @returns Number of vectors indexed (0 if content couldn't be indexed)
+     */
+    indexWithHandle(mcard: MCard, handle: string, isCurrent?: boolean, chunk?: boolean): Promise<number>;
+    /**
+     * Get all versions for a handle.
+     *
+     * @param handle Handle name to query
+     * @returns List of HandleVersion objects, ordered by version_order (0 = current)
+     */
+    getHandleVersions(handle: string): HandleVersion[];
+    /**
+     * Get all version hashes for a handle.
+     *
+     * @param handle Handle name to query
+     * @returns List of hashes, ordered by version_order
+     */
+    getHandleVersionHashes(handle: string): string[];
+    /**
+     * Get the current version for a handle.
+     *
+     * @param handle Handle name to query
+     * @returns HandleVersion for current version, or undefined if handle not found
+     */
+    getCurrentVersion(handle: string): HandleVersion | undefined;
+    /**
+     * Get versions for a handle, sorted by similarity to a reference.
+     *
+     * @param handle Handle name
+     * @param referenceHash Hash to compare against (default: current version)
+     * @param metric 'cosine' (higher = more similar) or 'euclidean' (lower = more similar)
+     * @returns List of VersionSimilarityResult, sorted by similarity
+     */
+    getVersionsBySimilarity(handle: string, referenceHash?: string, metric?: 'cosine' | 'euclidean'): VersionSimilarityResult[];
+    /**
+     * Search within a handle's versions by semantic query.
+     *
+     * Useful for finding which version of a document best matches
+     * a specific concept or topic.
+     *
+     * @param handle Handle name to filter by
+     * @param query Search query text
+     * @param k Number of results
+     * @returns List of VersionSimilarityResult with query similarity scores
+     */
+    searchHandleVersions(handle: string, query: string, k?: number): Promise<VersionSimilarityResult[]>;
+    /**
+     * Compute pairwise cosine similarities between all versions of a handle.
+     *
+     * Optionally caches results in the version_similarity_cache table.
+     *
+     * @param handle Handle name
+     * @param cache Whether to cache computed similarities
+     * @returns Map of (hash_a, hash_b) string key to cosine similarity
+     */
+    computeVersionDistances(handle: string, cache?: boolean): Map<string, number>;
+    /**
+     * Get embedding vector for a hash.
+     *
+     * @param hash MCard hash
+     * @param chunkIndex Chunk index (default 0 for first/whole chunk)
+     * @returns Embedding vector as array of floats, or undefined if not found
+     */
+    private getEmbedding;
+    /**
+     * List all handles with indexed versions.
+     *
+     * @returns List of unique handle names
+     */
+    listHandles(): string[];
+    /**
+     * Count versions for a handle.
+     *
+     * @param handle Handle name
+     * @returns Number of versions
+     */
+    countVersions(handle: string): number;
+    /**
+     * Delete all version records for a handle.
+     *
+     * Note: This only removes the handle-version associations,
+     * not the underlying MCard embeddings.
+     *
+     * @param handle Handle name
+     * @returns Number of version records deleted
+     */
+    deleteHandle(handle: string): number;
+    /**
+     * Get extended vector store information including handle stats.
+     */
+    getInfo(): Record<string, unknown>;
+}
+//# sourceMappingURL=HandleVectorStore.d.ts.map

package/dist/rag/HandleVectorStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HandleVectorStore.d.ts","sourceRoot":"","sources":["../../src/rag/HandleVectorStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AACvC,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAmG,MAAM,wBAAwB,CAAC;AAI9K,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAM3D;;GAEG;AACH,MAAM,WAAW,aAAa;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAUjE;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAUlE;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,iBAAkB,SAAQ,gBAAgB;gBAEvC,MAAM,GAAE,MAAmB,EAAE,MAAM,GAAE,OAAO,CAAC,iBAAiB,CAAM;IAKhF;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAuBxB;;;;;;;;;;;;;;OAcG;IACG,eAAe,CACjB,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,MAAM,EACd,SAAS,GAAE,OAAc,EACzB,KAAK,GAAE,OAAc,GACtB,OAAO,CAAC,MAAM,CAAC;IAgHlB;;;;;OAKG;IACH,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,EAAE;IA8BlD;;;;;OAKG;IACH,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE;IAKhD;;;;;OAKG;IACH,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IAsC5D;;;;;;;OAOG;IACH,uBAAuB,CACnB,MAAM,EAAE,MAAM,EACd,aAAa,CAAC,EAAE,MAAM,EACtB,MAAM,GAAE,QAAQ,GAAG,WAAsB,GAC1C,uBAAuB,EAAE;IA6D5B;;;;;;;;;;OAUG;IACG,oBAAoB,CACtB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,CAAC,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,uBAAuB,EAAE,CAAC;IA2CrC;;;;;;;;OAQG;IACH,uBAAuB,CACnB,MAAM,EAAE,MAAM,EACd,KAAK,GAAE,OAAc,GACtB,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC;IAsDtB;;;;;;OAMG;IACH,OAAO,CAAC,YAAY;IA4BpB;;;;OAIG;IACH,WAAW,IAAI,MAAM,EAAE;IAOvB;;;;;OAKG;IACH,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAOrC;;;;;;;;OAQG;IACH,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAepC;;OAEG;IACM,OAAO,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAqB9C"}