causantic 0.2.0

package/dist/mcp/tools.js

@@ -0,0 +1,292 @@
+/**
+ * MCP tool definitions for memory operations.
+ */
+import { recall, explain, predict } from '../retrieval/context-assembler.js';
+import { getConfig } from '../config/memory-config.js';
+import { getDistinctProjects, getSessionsForProject } from '../storage/chunk-store.js';
+import { reconstructSession, formatReconstruction } from '../retrieval/session-reconstructor.js';
+/**
+ * Format retrieval response as text output.
+ */
+function formatResponse(response) {
+    if (response.chunks.length === 0) {
+        return 'No relevant memory found.';
+    }
+    const header = `Found ${response.chunks.length} relevant memory chunks (${response.tokenCount} tokens):\n\n`;
+    return header + response.text;
+}
+/**
+ * Recall tool: retrieve relevant context from memory.
+ */
+export const recallTool = {
+    name: 'recall',
+    description: 'Retrieve relevant context from memory based on a query. Use this to recall past conversations, decisions, or context that might be relevant to the current task.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            query: {
+                type: 'string',
+                description: 'What to look up in memory. Be specific about what context you need.',
+            },
+            range: {
+                type: 'string',
+                description: 'Time range hint: "short" for recent context (last few turns), "long" for historical/cross-session context. Default: "short".',
+            },
+            project: {
+                type: 'string',
+                description: 'Filter to a specific project. Omit to search all. Use list-projects to see available projects.',
+            },
+        },
+        required: ['query'],
+    },
+    handler: async (args) => {
+        const query = args.query;
+        const range = args.range || 'short';
+        const project = args.project;
+        const config = getConfig();
+        const response = await recall(query, {
+            maxTokens: config.mcpMaxResponseTokens,
+            range,
+            projectFilter: project,
+        });
+        return formatResponse(response);
+    },
+};
+/**
+ * Explain tool: get explanation of what led to current state.
+ */
+export const explainTool = {
+    name: 'explain',
+    description: 'Get an explanation of the context and history behind a topic. Use this to understand how we got to the current state or why certain decisions were made. Uses long-range retrieval by default for historical context.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            topic: {
+                type: 'string',
+                description: 'What topic or aspect to explain. E.g., "the authentication system" or "why we chose React".',
+            },
+            range: {
+                type: 'string',
+                description: 'Time range: "short" for recent context, "long" for full history. Default: "long".',
+            },
+            project: {
+                type: 'string',
+                description: 'Filter to a specific project. Omit to search all. Use list-projects to see available projects.',
+            },
+        },
+        required: ['topic'],
+    },
+    handler: async (args) => {
+        const topic = args.topic;
+        const range = args.range || 'long'; // Default to long for explain
+        const project = args.project;
+        const config = getConfig();
+        const response = await explain(topic, {
+            maxTokens: config.mcpMaxResponseTokens,
+            range,
+            projectFilter: project,
+        });
+        return formatResponse(response);
+    },
+};
+/**
+ * Predict tool: predict what might be relevant next.
+ */
+export const predictTool = {
+    name: 'predict',
+    description: 'Predict what context or topics might be relevant based on current discussion. Use this proactively to surface potentially useful past context.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            context: {
+                type: 'string',
+                description: 'Current context or topic being discussed.',
+            },
+            project: {
+                type: 'string',
+                description: 'Filter to a specific project. Omit to search all. Use list-projects to see available projects.',
+            },
+        },
+        required: ['context'],
+    },
+    handler: async (args) => {
+        const context = args.context;
+        const project = args.project;
+        const config = getConfig();
+        const response = await predict(context, {
+            maxTokens: Math.floor(config.mcpMaxResponseTokens / 2), // Smaller for predictions
+            projectFilter: project,
+        });
+        if (response.chunks.length === 0) {
+            return 'No predictions available based on current context.';
+        }
+        const header = `Potentially relevant context (${response.chunks.length} items):\n\n`;
+        return header + response.text;
+    },
+};
+/**
+ * List projects tool: discover available projects for filtering.
+ */
+export const listProjectsTool = {
+    name: 'list-projects',
+    description: 'List all projects in memory with chunk counts and date ranges. Use to discover available project names for filtering recall/explain/predict.',
+    inputSchema: {
+        type: 'object',
+        properties: {},
+        required: [],
+    },
+    handler: async () => {
+        const projects = getDistinctProjects();
+        if (projects.length === 0) {
+            return 'No projects found in memory.';
+        }
+        const lines = projects.map((p) => {
+            const first = new Date(p.firstSeen).toLocaleDateString('en-US', { month: 'short', year: 'numeric' });
+            const last = new Date(p.lastSeen).toLocaleDateString('en-US', { month: 'short', year: 'numeric' });
+            const range = first === last ? first : `${first} – ${last}`;
+            return `- ${p.slug} (${p.chunkCount} chunks, ${range})`;
+        });
+        return `Projects in memory:\n${lines.join('\n')}`;
+    },
+};
+/**
+ * List sessions tool: browse available sessions for a project.
+ */
+export const listSessionsTool = {
+    name: 'list-sessions',
+    description: 'List sessions for a project with chunk counts, time ranges, and token totals. Use to browse available sessions before reconstructing context.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            project: {
+                type: 'string',
+                description: 'Project slug (required). Use list-projects to discover available projects.',
+            },
+            from: {
+                type: 'string',
+                description: 'Start date filter (ISO 8601). Optional.',
+            },
+            to: {
+                type: 'string',
+                description: 'End date filter (ISO 8601). Optional.',
+            },
+            days_back: {
+                type: 'number',
+                description: 'Look back N days from now. Alternative to from/to.',
+            },
+        },
+        required: ['project'],
+    },
+    handler: async (args) => {
+        const project = args.project;
+        let from = args.from;
+        let to = args.to;
+        const daysBack = args.days_back;
+        if (daysBack !== null && daysBack !== undefined) {
+            to = new Date().toISOString();
+            from = new Date(Date.now() - daysBack * 24 * 60 * 60 * 1000).toISOString();
+        }
+        const sessions = getSessionsForProject(project, from, to);
+        if (sessions.length === 0) {
+            return `No sessions found for project "${project}".`;
+        }
+        const lines = sessions.map((s) => {
+            const start = new Date(s.firstChunkTime).toLocaleDateString('en-US', {
+                month: 'short',
+                day: 'numeric',
+                hour: 'numeric',
+                minute: '2-digit',
+            });
+            const end = new Date(s.lastChunkTime).toLocaleTimeString('en-US', {
+                hour: 'numeric',
+                minute: '2-digit',
+            });
+            return `- ${s.sessionId.slice(0, 8)} (${start} – ${end}, ${s.chunkCount} chunks, ${s.totalTokens} tokens)`;
+        });
+        return `Sessions for "${project}" (${sessions.length} total):\n${lines.join('\n')}`;
+    },
+};
+/**
+ * Reconstruct tool: rebuild session context by time range.
+ */
+export const reconstructTool = {
+    name: 'reconstruct',
+    description: 'Rebuild session context for a project by time range. Returns chronological chunks with session boundary markers. Use for "what did I work on yesterday?", "show me the last session", etc.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            project: {
+                type: 'string',
+                description: 'Project slug (required). Use list-projects to discover available projects.',
+            },
+            session_id: {
+                type: 'string',
+                description: 'Specific session ID to reconstruct.',
+            },
+            from: {
+                type: 'string',
+                description: 'Start date (ISO 8601).',
+            },
+            to: {
+                type: 'string',
+                description: 'End date (ISO 8601).',
+            },
+            days_back: {
+                type: 'number',
+                description: 'Look back N days from now.',
+            },
+            previous_session: {
+                type: 'boolean',
+                description: 'Get the session before the current one.',
+            },
+            current_session_id: {
+                type: 'string',
+                description: 'Current session ID (required when previous_session is true).',
+            },
+            keep_newest: {
+                type: 'boolean',
+                description: 'Keep newest chunks when truncating to fit token budget (default: true).',
+            },
+        },
+        required: ['project'],
+    },
+    handler: async (args) => {
+        const project = args.project;
+        const config = getConfig();
+        try {
+            const result = reconstructSession({
+                project,
+                sessionId: args.session_id,
+                from: args.from,
+                to: args.to,
+                daysBack: args.days_back,
+                previousSession: args.previous_session,
+                currentSessionId: args.current_session_id,
+                maxTokens: config.mcpMaxResponseTokens,
+                keepNewest: args.keep_newest ?? true,
+            });
+            return formatReconstruction(result);
+        }
+        catch (error) {
+            return `Error: ${error instanceof Error ? error.message : String(error)}`;
+        }
+    },
+};
+/**
+ * All available tools.
+ */
+export const tools = [
+    recallTool,
+    explainTool,
+    predictTool,
+    listProjectsTool,
+    listSessionsTool,
+    reconstructTool,
+];
+/**
+ * Get tool by name.
+ */
+export function getTool(name) {
+    return tools.find((t) => t.name === name);
+}
+//# sourceMappingURL=tools.js.map

package/dist/mcp/tools.js.map

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

package/dist/models/device-detector.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Runtime detection of optimal ONNX execution provider for embedding inference.
+ *
+ * Detects hardware capabilities and returns the best execution provider chain.
+ * All accelerated devices use onnxruntime-node (device: 'cpu' in transformers.js)
+ * with execution providers overridden via session_options.
+ */
+export type DeviceName = 'coreml' | 'cuda' | 'cpu' | 'wasm';
+export interface DeviceDetectionResult {
+    /** The detected/selected device name. */
+    device: DeviceName;
+    /** Ordered execution provider list for onnxruntime session_options. */
+    executionProviders: string[];
+    /** Human-readable label for CLI display (e.g. "CoreML (Apple Silicon)"). */
+    label: string;
+    /** How this device was selected. */
+    source: 'override' | 'env' | 'auto';
+    /** Optional notes (e.g. "coreml available — set CAUSANTIC_EMBEDDING_DEVICE to enable"). */
+    notes?: string;
+    /** Accelerators detected as available but not activated by default. */
+    available?: AvailableAccelerator[];
+}
+/** Accelerators that are available but not defaulted (opt-in). */
+export type AvailableAccelerator = 'coreml' | 'cuda';
+/**
+ * Detect the optimal ONNX execution provider for the current system.
+ *
+ * @param override - Explicit device selection (from config or CLI flag).
+ *   Takes priority over env var and auto-detection.
+ */
+export declare function detectDevice(override?: string): DeviceDetectionResult;
+//# sourceMappingURL=device-detector.d.ts.map

package/dist/models/device-detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"device-detector.d.ts","sourceRoot":"","sources":["../../src/models/device-detector.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAOH,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,CAAC;AAE5D,MAAM,WAAW,qBAAqB;IACpC,yCAAyC;IACzC,MAAM,EAAE,UAAU,CAAC;IACnB,uEAAuE;IACvE,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,4EAA4E;IAC5E,KAAK,EAAE,MAAM,CAAC;IACd,oCAAoC;IACpC,MAAM,EAAE,UAAU,GAAG,KAAK,GAAG,MAAM,CAAC;IACpC,2FAA2F;IAC3F,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,SAAS,CAAC,EAAE,oBAAoB,EAAE,CAAC;CACpC;AA8CD,kEAAkE;AAClE,MAAM,MAAM,oBAAoB,GAAG,QAAQ,GAAG,MAAM,CAAC;AA6BrD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,qBAAqB,CAwCrE"}

package/dist/models/device-detector.js

@@ -0,0 +1,123 @@
+/**
+ * Runtime detection of optimal ONNX execution provider for embedding inference.
+ *
+ * Detects hardware capabilities and returns the best execution provider chain.
+ * All accelerated devices use onnxruntime-node (device: 'cpu' in transformers.js)
+ * with execution providers overridden via session_options.
+ */
+import { execSync } from 'node:child_process';
+import { createLogger } from '../utils/logger.js';
+const log = createLogger('device-detector');
+/** Cached nvidia-smi result to avoid repeated subprocess spawns. */
+let nvidiaSmiCache = null;
+function hasNvidiaSmi() {
+    if (nvidiaSmiCache !== null)
+        return nvidiaSmiCache;
+    try {
+        execSync('nvidia-smi', { timeout: 2000, stdio: 'ignore' });
+        nvidiaSmiCache = true;
+    }
+    catch {
+        nvidiaSmiCache = false;
+    }
+    return nvidiaSmiCache;
+}
+function normalizeDevice(raw) {
+    const lower = raw.trim().toLowerCase();
+    if (lower === 'coreml')
+        return 'coreml';
+    if (lower === 'cuda')
+        return 'cuda';
+    if (lower === 'wasm')
+        return 'wasm';
+    if (lower === 'cpu')
+        return 'cpu';
+    if (lower === 'auto')
+        return 'auto'; // sentinel, resolved below
+    return 'cpu'; // unknown → safe fallback
+}
+function buildProviderList(device) {
+    switch (device) {
+        case 'coreml': return ['coreml', 'cpu'];
+        case 'cuda': return ['cuda', 'cpu'];
+        case 'cpu': return ['cpu'];
+        case 'wasm': return []; // WASM uses transformers.js built-in, no onnxruntime providers
+        default: return ['cpu'];
+    }
+}
+function deviceLabel(device) {
+    switch (device) {
+        case 'coreml': return 'CoreML (Apple Silicon)';
+        case 'cuda': return 'CUDA (NVIDIA GPU)';
+        case 'cpu': return 'CPU (native)';
+        case 'wasm': return 'WASM (fallback)';
+        default: return 'CPU (native)';
+    }
+}
+function detectAvailableAccelerators() {
+    const accelerators = [];
+    if (process.platform === 'darwin') {
+        accelerators.push('coreml');
+    }
+    if (process.platform === 'linux' && process.arch === 'x64' && hasNvidiaSmi()) {
+        accelerators.push('cuda');
+    }
+    return accelerators;
+}
+function autoDetect() {
+    // Default to CPU — accelerated EPs are opt-in because:
+    // - CoreML: partitions models with large vocab embeddings (>16384 dims),
+    //   causing 30+ context switches per inference and OOM kills
+    // - CUDA: requires compatible driver/runtime, untested model combinations
+    const available = detectAvailableAccelerators();
+    const hints = available.length > 0
+        ? `${available.join(', ')} available — set CAUSANTIC_EMBEDDING_DEVICE to enable`
+        : undefined;
+    return { device: 'cpu', notes: hints, available };
+}
+/**
+ * Detect the optimal ONNX execution provider for the current system.
+ *
+ * @param override - Explicit device selection (from config or CLI flag).
+ *   Takes priority over env var and auto-detection.
+ */
+export function detectDevice(override) {
+    // 1. Explicit override from caller (config/CLI)
+    if (override && override !== 'auto') {
+        const device = normalizeDevice(override);
+        const result = {
+            device,
+            executionProviders: buildProviderList(device),
+            label: deviceLabel(device),
+            source: 'override',
+        };
+        log.info(`Device override: ${result.label}`);
+        return result;
+    }
+    // 2. Environment variable
+    const envDevice = process.env.CAUSANTIC_EMBEDDING_DEVICE;
+    if (envDevice && envDevice !== 'auto') {
+        const device = normalizeDevice(envDevice);
+        const result = {
+            device,
+            executionProviders: buildProviderList(device),
+            label: deviceLabel(device),
+            source: 'env',
+        };
+        log.info(`Device from env: ${result.label}`);
+        return result;
+    }
+    // 3. Auto-detect from platform (defaults to CPU, accelerators are opt-in)
+    const { device, notes, available } = autoDetect();
+    const result = {
+        device,
+        executionProviders: buildProviderList(device),
+        label: deviceLabel(device),
+        source: 'auto',
+        notes,
+        available,
+    };
+    log.info(`Device auto-detected: ${result.label}${notes ? ` (${notes})` : ''}`);
+    return result;
+}
+//# sourceMappingURL=device-detector.js.map

package/dist/models/device-detector.js.map

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

package/dist/models/embedder.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Embedding pipeline wrapper around @huggingface/transformers.
+ *
+ * Loads models sequentially and provides a simple embed() interface.
+ * Handles task prefixes for models that need them (nomic).
+ * Tracks memory usage for benchmark reporting.
+ * Supports true batch embedding for performance.
+ */
+import type { ModelConfig } from './model-registry.js';
+import { type DeviceDetectionResult } from './device-detector.js';
+export interface EmbedResult {
+    /** The embedding vector. */
+    embedding: number[];
+    /** Inference time in ms. */
+    inferenceMs: number;
+}
+export interface ModelStats {
+    modelId: string;
+    loadTimeMs: number;
+    heapUsedMB: number;
+}
+export interface EmbedderLoadOptions {
+    /** Override device selection ('auto' | 'coreml' | 'cuda' | 'cpu' | 'wasm'). */
+    device?: string;
+}
+export declare class Embedder {
+    private pipe;
+    private config;
+    private _device;
+    /**
+     * Load a model. Disposes any previously loaded model first.
+     */
+    load(config: ModelConfig, options?: EmbedderLoadOptions): Promise<ModelStats>;
+    /**
+     * Embed a single text. Applies document prefix if the model needs it.
+     */
+    embed(text: string, isQuery?: boolean): Promise<EmbedResult>;
+    /**
+     * Embed multiple texts. Returns embeddings in the same order.
+     * @deprecated Use embedBatchTrue() for better performance.
+     */
+    embedBatch(texts: string[], isQuery?: boolean): Promise<EmbedResult[]>;
+    /**
+     * Embed multiple texts using true batch processing.
+     * Passes arrays directly to the HuggingFace pipeline for better performance.
+     * Processes in configurable batch sizes to avoid OOM on large batches.
+     *
+     * @param texts - Array of texts to embed
+     * @param isQuery - Whether these are query texts (affects prefix for some models)
+     * @param batchSize - Maximum texts per batch (default 32)
+     */
+    embedBatchTrue(texts: string[], isQuery?: boolean, batchSize?: number): Promise<EmbedResult[]>;
+    /**
+     * Dispose the current model to free memory.
+     */
+    dispose(): Promise<void>;
+    get currentModel(): ModelConfig | null;
+    get currentDevice(): DeviceDetectionResult | null;
+}
+//# sourceMappingURL=embedder.d.ts.map

package/dist/models/embedder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedder.d.ts","sourceRoot":"","sources":["../../src/models/embedder.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAgB,KAAK,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAShF,MAAM,WAAW,WAAW;IAC1B,4BAA4B;IAC5B,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,4BAA4B;IAC5B,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,mBAAmB;IAClC,+EAA+E;IAC/E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,QAAQ;IACnB,OAAO,CAAC,IAAI,CAA0C;IACtD,OAAO,CAAC,MAAM,CAA4B;IAC1C,OAAO,CAAC,OAAO,CAAsC;IAErD;;OAEG;IACG,IAAI,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,UAAU,CAAC;IAkEvF;;OAEG;IACG,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,OAAe,GAAG,OAAO,CAAC,WAAW,CAAC;IAyBzE;;;OAGG;IACG,UAAU,CACd,KAAK,EAAE,MAAM,EAAE,EACf,OAAO,GAAE,OAAe,GACvB,OAAO,CAAC,WAAW,EAAE,CAAC;IAQzB;;;;;;;;OAQG;IACG,cAAc,CAClB,KAAK,EAAE,MAAM,EAAE,EACf,OAAO,GAAE,OAAe,EACxB,SAAS,GAAE,MAA2B,GACrC,OAAO,CAAC,WAAW,EAAE,CAAC;IA4CzB;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAW9B,IAAI,YAAY,IAAI,WAAW,GAAG,IAAI,CAErC;IAED,IAAI,aAAa,IAAI,qBAAqB,GAAG,IAAI,CAEhD;CACF"}