amalfa 1.0.26 → 1.0.27

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "amalfa",
-	"version": "1.0.26",
+	"version": "1.0.27",
 	"description": "Local-first knowledge graph engine for AI agents. Transforms markdown into searchable memory with MCP protocol.",
 	"license": "MIT",
 	"homepage": "https://github.com/pjsvis/amalfa#readme",

package/src/config/defaults.ts

@@ -115,10 +115,28 @@ export interface SonarConfig {
 			schedule: string;
 		};
 	};
+	/** Cloud inference configuration (dev-cloud/prod-local strategy) */
+	cloud?: {
+		/** Enable cloud inference (overrides local Ollama) */
+		enabled: boolean;
+		/** Provider type: 'ollama' for self-hosted, 'openrouter' for OpenRouter.ai */
+		provider: "ollama" | "openrouter";
+		/** API endpoint (e.g., your-gpu-server:11434 or openrouter.ai/api/v1) */
+		host: string;
+		/** Model to use on cloud (can be larger than local) */
+		model: string;
+		/** API key for authenticated endpoints (required for OpenRouter) */
+		apiKey?: string;
+	};
 }
 
 export const DEFAULT_CONFIG: AmalfaConfig = {
-	sources: ["./docs"],
+	sources: [
+		"./docs",
+		"./*.md", // Root documentation (README.md, _CURRENT_TASK.md, etc.)
+		"./src/**/*.md", // Documentation co-located with code
+		"./scripts/**/*.md", // Documentation in scripts
+	],
 	database: ".amalfa/resonance.db",
 	embeddings: {
 		model: "BAAI/bge-small-en-v1.5",
@@ -150,11 +168,11 @@ export const DEFAULT_CONFIG: AmalfaConfig = {
 		autoDiscovery: true,
 		discoveryMethod: "cli",
 		inferenceMethod: "http",
-		model: "phi3:latest",
+		model: "qwen2.5:1.5b",
 		modelPriority: [
+			"qwen2.5:1.5b", // Best-in-class reasoning for size
 			"tinydolphin:latest",
 			"tinyllama:latest",
-			"phi3:latest",
 			"mistral:7b-instruct-v0.3-q4_K_M",
 			"llama3.1:8b",
 		],

package/src/daemon/sonar-agent.ts

@@ -21,6 +21,7 @@ const log = getLogger("SonarAgent");
 
 // Database initialization
 import { ResonanceDB } from "@src/resonance/db";
+import { VectorEngine } from "@src/core/VectorEngine";
 let DB_PATH: string;
 
 // Service lifecycle management
@@ -62,6 +63,7 @@ interface RequestOptions {
 	num_predict?: number;
 	stream?: boolean;
 	format?: "json"; // Enable GBNF-constrained JSON output
+	model?: string; // Override model for this specific call (tiered strategy)
 }
 
 /**
@@ -73,36 +75,116 @@ async function callOllama(
 	options: RequestOptions = {},
 ): Promise<{ message: Message }> {
 	const config = await loadConfig();
-	// @ts-ignore
+	// @ts-ignore - backward compatibility with phi3 config
 	const hostArgs = config.sonar || config.phi3 || {};
-	const host = hostArgs.host || "localhost:11434";
-	// Use discovered model if available, otherwise config or default
-	const model = ollamaModel || hostArgs.model || "phi3:latest";
 
-	// Extract format from options to put at root level of request
-	const { format, ...modelOptions } = options;
+	// Cloud toggle: dev-cloud/prod-local strategy
+	const cloudConfig = hostArgs.cloud;
+	const useCloud = cloudConfig?.enabled === true;
+	const provider = useCloud ? cloudConfig.provider || "ollama" : "ollama";
+
+	// Tiered model strategy: options.model > cloud.model > discovered > config > default
+	const { format, model: overrideModel, ...modelOptions } = options;
+	const model =
+		overrideModel ||
+		(useCloud ? cloudConfig.model : null) ||
+		ollamaModel ||
+		hostArgs.model ||
+		"qwen2.5:1.5b";
+
+	// Build headers
+	const headers: Record<string, string> = {
+		"Content-Type": "application/json",
+	};
+	// API key: prefer env var (OPENROUTER_API_KEY) over config
+	const apiKey = process.env.OPENROUTER_API_KEY || cloudConfig?.apiKey;
+	if (useCloud && apiKey) {
+		headers["Authorization"] = `Bearer ${apiKey}`;
+		log.info(
+			{ provider, hasKey: !!apiKey, keyLength: apiKey?.length },
+			"Cloud request with API key",
+		);
+	} else if (useCloud) {
+		log.warn("Cloud enabled but no API key found in env or config!");
+	}
+	// OpenRouter requires site headers for tracking
+	if (provider === "openrouter") {
+		headers["HTTP-Referer"] = "https://github.com/pjsvis/amalfa";
+		headers["X-Title"] = "AMALFA Knowledge Graph";
+	}
+
+	// Determine endpoint and request format based on provider
+	let endpoint: string;
+	let body: string;
 
-	const response = await fetch(`http://${host}/api/chat`, {
-		method: "POST",
-		headers: { "Content-Type": "application/json" },
-		body: JSON.stringify({
+	if (provider === "openrouter") {
+		// OpenRouter uses OpenAI-compatible format at openrouter.ai/api/v1
+		endpoint = "https://openrouter.ai/api/v1/chat/completions";
+		body = JSON.stringify({
 			model,
 			messages,
 			stream: false,
-			format, // Pass format (e.g. "json") to enable GBNF grammar
+			temperature: modelOptions.temperature ?? 0.1,
+			max_tokens: modelOptions.num_predict ?? 500,
+		});
+	} else {
+		// Ollama format (local or cloud Ollama server)
+		const host = useCloud
+			? cloudConfig.host
+			: hostArgs.host || "localhost:11434";
+		endpoint = `http://${host}/api/chat`;
+		body = JSON.stringify({
+			model,
+			messages,
+			stream: false,
+			format, // Pass format (e.g. "json") for GBNF grammar
 			options: {
 				temperature: 0.1,
 				num_predict: 200,
 				...modelOptions,
 			},
-		}),
+		});
+	}
+
+	const response = await fetch(endpoint, {
+		method: "POST",
+		headers,
+		body,
 	});
 
 	if (!response.ok) {
-		throw new Error(`Ollama API error: ${response.statusText}`);
+		// Try to get error details from response body
+		let errorBody = "";
+		try {
+			errorBody = await response.text();
+		} catch {}
+		log.error(
+			{
+				status: response.status,
+				statusText: response.statusText,
+				body: errorBody,
+			},
+			"API request failed",
+		);
+		throw new Error(`${provider} API error: ${response.statusText}`);
 	}
 
-	return (await response.json()) as { message: Message };
+	const result = await response.json();
+
+	// Normalize response format (OpenRouter uses OpenAI format)
+	if (provider === "openrouter") {
+		// OpenAI format: { choices: [{ message: { role, content } }] }
+		const openaiResult = result as { choices: { message: Message }[] };
+		return {
+			message: openaiResult.choices[0]?.message || {
+				role: "assistant",
+				content: "",
+			},
+		};
+	}
+
+	// Ollama format: { message: { role, content } }
+	return result as { message: Message };
 }
 
 /**
@@ -382,6 +464,7 @@ Return JSON array with relevance scores (0.0 to 1.0):
 async function handleChat(
 	sessionId: string,
 	userMessage: string,
+	modelOverride?: string, // Optional: Use specific model (e.g., mistral-nemo for research)
 ): Promise<{ message: Message; sessionId: string }> {
 	if (!ollamaAvailable) {
 		throw new Error("Sonar is not available");
@@ -412,7 +495,37 @@ User can ask you about:
 	}
 
 	// Add user message
-	session.messages.push({ role: "user", content: userMessage });
+
+	// RAG: Perform vector search to augment context
+	const db = new ResonanceDB(DB_PATH);
+	const vectors = new VectorEngine(db.getRawDb());
+	try {
+		const results = await vectors.search(userMessage, 3);
+
+		let augmentContext = "";
+		if (results.length > 0) {
+			augmentContext = `\n\nRELEVANT CONTEXT FROM KNOWLEDGE BASE:\n`;
+			results.forEach((r: { id: string; score: number }, i: number) => {
+				// Read full node content if possible, or just use what we have
+				const node = db.getNode(r.id);
+				// Truncate content to avoid blowing up context window
+				const content = node?.content ?? "";
+				const snippet = content.slice(0, 1000);
+				augmentContext += `[Document ${i + 1}: ${r.id}] (Score: ${r.score.toFixed(2)})\n${snippet}\n\n`;
+			});
+			augmentContext += `INSTRUCTIONS: Use the above context to answer the user's question. Cite sources if possible.\n`;
+		}
+
+		// Append context to user message
+		session.messages.push({
+			role: "user",
+			content: userMessage + augmentContext,
+		});
+	} catch (e) {
+		// Fallback to ignoring RAG on error
+		log.warn({ err: e }, "RAG search failed, proceeding without context");
+		session.messages.push({ role: "user", content: userMessage });
+	}
 
 	// Maintain context window (keep system msg + last 10 messages)
 	const contextMessages = [
@@ -422,9 +535,11 @@ User can ask you about:
 
 	try {
 		// NOTE: No format: "json" for chat! We want natural language.
+		// Use modelOverride if provided (e.g., mistral-nemo for research)
 		const response = await callOllama(contextMessages, {
 			temperature: 0.7,
 			num_predict: 500,
+			model: modelOverride,
 		});
 
 		// Add assistant response to history
@@ -861,6 +976,24 @@ async function executeTask(task: any): Promise<string> {
 		output += `- Failed: ${result.failed}\n\n`;
 
 		output += `Check daemon logs for detailed errors per document.\n`;
+	} else if (task.type === "research") {
+		output += `## Objective\nResearch Query: "${task.query}"\n\n`;
+
+		try {
+			const sessionId = `task-${Date.now()}`;
+			// For research: use task.model if specified, otherwise let the cloud/local config decide
+			// Don't hardcode mistral-nemo since it's not valid on OpenRouter
+			const researchModel = task.model || undefined;
+			const response = await handleChat(sessionId, task.query, researchModel);
+
+			output += `## Analysis\n${response.message.content}\n\n`;
+			output += `(Model: ${researchModel || "default"})\n`;
+
+			// Note: chat doesn't return structured sources yet
+			output += `(Source citation not available in simple research task)\n`;
+		} catch (e) {
+			output += `## Error\nResearch failed: ${e instanceof Error ? e.message : String(e)}\n`;
+		}
 	} else {
 		output += `Error: Unknown task type '${task.type}'\n`;
 	}

package/src/utils/ServiceLifecycle.ts

@@ -4,202 +4,203 @@ import { join } from "path";
 import { AMALFA_DIRS, initAmalfaDirs } from "@src/config/defaults";
 
 export interface ServiceConfig {
-  name: string; // e.g. "Daemon"
-  pidFile: string; // e.g. ".daemon.pid"
-  logFile: string; // e.g. ".daemon.log"
-  entryPoint: string; // e.g. "src/resonance/daemon.ts"
+	name: string; // e.g. "Daemon"
+	pidFile: string; // e.g. ".daemon.pid"
+	logFile: string; // e.g. ".daemon.log"
+	entryPoint: string; // e.g. "src/resonance/daemon.ts"
 }
 
 export class ServiceLifecycle {
-  constructor(private config: ServiceConfig) {}
-
-  private async isRunning(pid: number): Promise<boolean> {
-    try {
-      process.kill(pid, 0);
-      return true;
-    } catch (_e) {
-      return false;
-    }
-  }
-
-  /**
-   * Start the service in the background (detached).
-   */
-  async start() {
-    // Ensure .amalfa directories exist
-    initAmalfaDirs();
-
-    // Check if already running based on PID file
-    if (await Bun.file(this.config.pidFile).exists()) {
-      const pid = parseInt(await Bun.file(this.config.pidFile).text(), 10);
-      if (await this.isRunning(pid)) {
-        console.log(`⚠️  ${this.config.name} is already running (PID: ${pid})`);
-        return;
-      }
-      console.log(
-        `⚠️  Found stale PID file for ${this.config.name}. Clearing...`,
-      );
-      await unlink(this.config.pidFile);
-    }
-
-    const logFile = Bun.file(this.config.logFile);
-    await Bun.write(logFile, ""); // Truncate logs
-
-    // Spawn subprocess
-    const subprocess = Bun.spawn(
-      ["bun", "run", this.config.entryPoint, "serve"],
-      {
-        cwd: process.cwd(),
-        detached: true,
-        stdout: logFile,
-        stderr: logFile,
-      },
-    );
-
-    await Bun.write(this.config.pidFile, subprocess.pid.toString());
-    subprocess.unref();
-
-    console.log(
-      `✅ ${this.config.name} started in background (PID: ${subprocess.pid})`,
-    );
-    console.log(`📝 Logs: ${this.config.logFile}`);
-  }
-
-  /**
-   * Stop the service using the PID file.
-   */
-  async stop() {
-    if (!(await Bun.file(this.config.pidFile).exists())) {
-      console.log(`ℹ️  ${this.config.name} is not running.`);
-      return;
-    }
-
-    const pid = parseInt(await Bun.file(this.config.pidFile).text(), 10);
-
-    if (await this.isRunning(pid)) {
-      console.log(`🛑 Stopping ${this.config.name} (PID: ${pid})...`);
-      process.kill(pid, "SIGTERM");
-
-      let attempts = 0;
-      // Wait up to 1 second
-      while ((await this.isRunning(pid)) && attempts < 10) {
-        await new Promise((r) => setTimeout(r, 100));
-        attempts++;
-      }
-
-      if (await this.isRunning(pid)) {
-        console.log("⚠️  Process did not exit gracefully. Force killing...");
-        process.kill(pid, "SIGKILL");
-      }
-      console.log(`✅ ${this.config.name} stopped.`);
-    } else {
-      console.log("⚠️  Stale PID file found. Cleaning up.");
-    }
-
-    try {
-      await unlink(this.config.pidFile);
-    } catch (e: unknown) {
-      const err = e as { code?: string; message: string };
-      if (err.code !== "ENOENT") {
-        console.warn(`⚠️ Failed to remove PID file: ${err.message}`);
-      }
-    }
-  }
-
-  /**
-   * Check status of the service.
-   */
-  async status() {
-    if (await Bun.file(this.config.pidFile).exists()) {
-      const pid = parseInt(await Bun.file(this.config.pidFile).text(), 10);
-      if (await this.isRunning(pid)) {
-        console.log(`🟢 ${this.config.name} is RUNNING (PID: ${pid})`);
-        return;
-      }
-      console.log(`🔴 ${this.config.name} is NOT RUNNING (Stale PID: ${pid})`);
-    } else {
-      console.log(`⚪️ ${this.config.name} is STOPPED`);
-    }
-  }
-
-  /**
-   * Wrapper for the foreground 'serve' command logic.
-   * Use this to wrap your actual server startup code.
-   */
-  async serve(serverLogic: () => Promise<void>) {
-    // Ensure .amalfa directories exist
-    initAmalfaDirs();
-
-    // Write PID file for this serving process
-    await Bun.write(this.config.pidFile, process.pid.toString());
-
-    // Register cleanup handlers to remove PID file on exit/crash/kill
-    let cleanupCalled = false;
-    const cleanup = async (signal?: string) => {
-      if (cleanupCalled) return; // Prevent double cleanup
-      cleanupCalled = true;
-
-      try {
-        if (await Bun.file(this.config.pidFile).exists()) {
-          await unlink(this.config.pidFile);
-          if (signal) {
-            console.error(
-              `\n🧹 ${this.config.name}: PID file cleaned up on ${signal}`,
-            );
-          }
-        }
-      } catch (_e) {
-        // Ignore cleanup errors (file might already be deleted)
-      }
-    };
-
-    // Register signal handlers
-    process.on("SIGINT", () => cleanup("SIGINT").then(() => process.exit(0)));
-    process.on("SIGTERM", () => cleanup("SIGTERM").then(() => process.exit(0)));
-    process.on("exit", () => {
-      // Note: exit event is synchronous, so we do sync cleanup
-      if (!cleanupCalled && existsSync(this.config.pidFile)) {
-        cleanupCalled = true;
-        try {
-          Bun.write(this.config.pidFile, ""); // Truncate to mark as stale
-        } catch {}
-      }
-    });
-
-    await serverLogic();
-  }
-
-  /**
-   * Main CLI dispatch logic.
-   */
-  async run(command: string, serverLogic: () => Promise<void>) {
-    switch (command) {
-      case "start":
-        await this.start();
-        process.exit(0);
-        break;
-      case "stop":
-        await this.stop();
-        process.exit(0);
-        break;
-      case "status":
-        await this.status();
-        process.exit(0);
-        break;
-      case "restart":
-        await this.stop();
-        await new Promise((r) => setTimeout(r, 500));
-        await this.start();
-        process.exit(0);
-        break;
-      case "serve":
-        await this.serve(serverLogic);
-        break;
-      default:
-        console.log(
-          `Unknown command '${command}'. Use: start, stop, status, restart, or serve`,
-        );
-        process.exit(1);
-    }
-  }
+	constructor(private config: ServiceConfig) {}
+
+	private async isRunning(pid: number): Promise<boolean> {
+		try {
+			process.kill(pid, 0);
+			return true;
+		} catch (_e) {
+			return false;
+		}
+	}
+
+	/**
+	 * Start the service in the background (detached).
+	 */
+	async start() {
+		// Ensure .amalfa directories exist
+		initAmalfaDirs();
+
+		// Check if already running based on PID file
+		if (await Bun.file(this.config.pidFile).exists()) {
+			const pid = parseInt(await Bun.file(this.config.pidFile).text(), 10);
+			if (await this.isRunning(pid)) {
+				console.log(`⚠️  ${this.config.name} is already running (PID: ${pid})`);
+				return;
+			}
+			console.log(
+				`⚠️  Found stale PID file for ${this.config.name}. Clearing...`,
+			);
+			await unlink(this.config.pidFile);
+		}
+
+		const logFile = Bun.file(this.config.logFile);
+		await Bun.write(logFile, ""); // Truncate logs
+
+		// Spawn subprocess with explicit env inheritance for .env vars
+		const subprocess = Bun.spawn(
+			["bun", "run", this.config.entryPoint, "serve"],
+			{
+				cwd: process.cwd(),
+				detached: true,
+				stdout: logFile,
+				stderr: logFile,
+				env: process.env, // Explicitly inherit env (including .env loaded by parent)
+			},
+		);
+
+		await Bun.write(this.config.pidFile, subprocess.pid.toString());
+		subprocess.unref();
+
+		console.log(
+			`✅ ${this.config.name} started in background (PID: ${subprocess.pid})`,
+		);
+		console.log(`📝 Logs: ${this.config.logFile}`);
+	}
+
+	/**
+	 * Stop the service using the PID file.
+	 */
+	async stop() {
+		if (!(await Bun.file(this.config.pidFile).exists())) {
+			console.log(`ℹ️  ${this.config.name} is not running.`);
+			return;
+		}
+
+		const pid = parseInt(await Bun.file(this.config.pidFile).text(), 10);
+
+		if (await this.isRunning(pid)) {
+			console.log(`🛑 Stopping ${this.config.name} (PID: ${pid})...`);
+			process.kill(pid, "SIGTERM");
+
+			let attempts = 0;
+			// Wait up to 1 second
+			while ((await this.isRunning(pid)) && attempts < 10) {
+				await new Promise((r) => setTimeout(r, 100));
+				attempts++;
+			}
+
+			if (await this.isRunning(pid)) {
+				console.log("⚠️  Process did not exit gracefully. Force killing...");
+				process.kill(pid, "SIGKILL");
+			}
+			console.log(`✅ ${this.config.name} stopped.`);
+		} else {
+			console.log("⚠️  Stale PID file found. Cleaning up.");
+		}
+
+		try {
+			await unlink(this.config.pidFile);
+		} catch (e: unknown) {
+			const err = e as { code?: string; message: string };
+			if (err.code !== "ENOENT") {
+				console.warn(`⚠️ Failed to remove PID file: ${err.message}`);
+			}
+		}
+	}
+
+	/**
+	 * Check status of the service.
+	 */
+	async status() {
+		if (await Bun.file(this.config.pidFile).exists()) {
+			const pid = parseInt(await Bun.file(this.config.pidFile).text(), 10);
+			if (await this.isRunning(pid)) {
+				console.log(`🟢 ${this.config.name} is RUNNING (PID: ${pid})`);
+				return;
+			}
+			console.log(`🔴 ${this.config.name} is NOT RUNNING (Stale PID: ${pid})`);
+		} else {
+			console.log(`⚪️ ${this.config.name} is STOPPED`);
+		}
+	}
+
+	/**
+	 * Wrapper for the foreground 'serve' command logic.
+	 * Use this to wrap your actual server startup code.
+	 */
+	async serve(serverLogic: () => Promise<void>) {
+		// Ensure .amalfa directories exist
+		initAmalfaDirs();
+
+		// Write PID file for this serving process
+		await Bun.write(this.config.pidFile, process.pid.toString());
+
+		// Register cleanup handlers to remove PID file on exit/crash/kill
+		let cleanupCalled = false;
+		const cleanup = async (signal?: string) => {
+			if (cleanupCalled) return; // Prevent double cleanup
+			cleanupCalled = true;
+
+			try {
+				if (await Bun.file(this.config.pidFile).exists()) {
+					await unlink(this.config.pidFile);
+					if (signal) {
+						console.error(
+							`\n🧹 ${this.config.name}: PID file cleaned up on ${signal}`,
+						);
+					}
+				}
+			} catch (_e) {
+				// Ignore cleanup errors (file might already be deleted)
+			}
+		};
+
+		// Register signal handlers
+		process.on("SIGINT", () => cleanup("SIGINT").then(() => process.exit(0)));
+		process.on("SIGTERM", () => cleanup("SIGTERM").then(() => process.exit(0)));
+		process.on("exit", () => {
+			// Note: exit event is synchronous, so we do sync cleanup
+			if (!cleanupCalled && existsSync(this.config.pidFile)) {
+				cleanupCalled = true;
+				try {
+					Bun.write(this.config.pidFile, ""); // Truncate to mark as stale
+				} catch {}
+			}
+		});
+
+		await serverLogic();
+	}
+
+	/**
+	 * Main CLI dispatch logic.
+	 */
+	async run(command: string, serverLogic: () => Promise<void>) {
+		switch (command) {
+			case "start":
+				await this.start();
+				process.exit(0);
+				break;
+			case "stop":
+				await this.stop();
+				process.exit(0);
+				break;
+			case "status":
+				await this.status();
+				process.exit(0);
+				break;
+			case "restart":
+				await this.stop();
+				await new Promise((r) => setTimeout(r, 500));
+				await this.start();
+				process.exit(0);
+				break;
+			case "serve":
+				await this.serve(serverLogic);
+				break;
+			default:
+				console.log(
+					`Unknown command '${command}'. Use: start, stop, status, restart, or serve`,
+				);
+				process.exit(1);
+		}
+	}
 }

package/src/utils/ollama-discovery.ts

@@ -102,11 +102,13 @@ export async function discoverOllamaCapabilities(): Promise<OllamaCapabilities>
 			`📦 Found ${models.length} model(s): ${models.map((m) => m.name).join(", ")}`,
 		);
 
+		// Model priority order for search tasks (from brief)
 		// Model priority order for search tasks (from brief)
 		const modelPriority = [
+			"qwen2.5:1.5b", // Best-in-class reasoning for size
+			"phi3:mini", // 3.8B but optimized
 			"tinydolphin:latest",
 			"tinyllama:latest",
-			"phi3:latest",
 			"mistral:7b-instruct-v0.3-q4_K_M",
 			"llama3.1:8b",
 		];