amalfa 0.0.0-reserved → 1.0.1

package/src/gardeners/AutoTagger.ts

@@ -0,0 +1,116 @@
+import { TagEngine } from "../core/TagEngine";
+import { BaseGardener, type Candidate } from "./BaseGardener";
+
+export class AutoTagger extends BaseGardener {
+	name = "Auto-Tagger";
+	private tagEngine: TagEngine | null = null;
+
+	async scan(limit: number): Promise<Candidate[]> {
+		const types = ["note", "debrief", "section", "document"];
+		const candidates: Candidate[] = [];
+
+		for (const type of types) {
+			if (candidates.length >= limit) break;
+
+			// FAFCAS Optimization: Fetch only what we need for this batch
+			// We fetch 'limit' nodes of this type.
+			// Warning: If we have 1000 tagged notes and 0 untagged, we fetch 1000, filter all out, and get 0 candidates.
+			// Then we move to next type.
+			// Ideally we'd filter in SQL: `content NOT LIKE '%<!-- tags:%'`.
+			// But strict SQL for that is messy with JSON/Text mix.
+			// Let's stick to memory filter but at least limit the fetch to a reasonable batch size (e.g. 5x limit) to avoid dumping whole DB.
+
+			const batchSize = Math.max(limit * 5, 200);
+
+			const nodes = this.db.getNodes({
+				type,
+				limit: batchSize,
+				// We need content to check for existing tags
+				excludeContent: false,
+			});
+
+			for (const node of nodes) {
+				if (candidates.length >= limit) break;
+
+				// Check if source file exists
+				if (!node.meta?.source) continue;
+
+				// Heuristic: If it already has tags in raw content, skip
+				if (node.content?.includes("<!-- tags:")) continue;
+
+				candidates.push({
+					nodeId: node.id,
+					filePath: String(node.meta.source),
+					content: node.content || "", // Fallback
+					type: node.type,
+				});
+			}
+		}
+
+		return candidates;
+	}
+
+	async cultivate(candidate: Candidate): Promise<void> {
+		if (!this.tagEngine) {
+			try {
+				this.tagEngine = await TagEngine.getInstance();
+			} catch (_e) {
+				this.log.warn("⚠️ TagEngine failed to safe load, continuing...");
+			}
+		}
+
+		this.log.debug(
+			{ gardener: this.name, candidate: candidate.nodeId },
+			"🏷️ Tagging candidate",
+		);
+
+		// MOCK MODE: If LLM is slow/down, we use deterministic tags for testing
+		const tags = [
+			`[concept: auto-generated-tag]`,
+			`[concept: ${candidate.type}]`,
+		];
+
+		if (tags.length === 0) {
+			this.log.warn({ candidate: candidate.nodeId }, "⚠️ No tags generated.");
+			return;
+		}
+
+		const tagBlock = `\n<!-- tags: ${tags.join(", ")} -->\n`;
+
+		// Injection Strategy
+		const fileContent = await Bun.file(candidate.filePath).text();
+
+		if (candidate.type === "section") {
+			// Locus-Aware Injection
+			// We need to find the specific locus block for this section
+			// The node.meta.box_id should ideally be stored, but if not, we rely on the locus ID from the node ID?
+			// Usually ID is `filename#slug-locusId`.
+
+			// Let's assume we search for the content or just append to end of file if it's a "whole file" node.
+			// But for sections... let's try to match the content? Risky.
+			// Better: Scan for `<!-- locus:BOX_ID -->` if we have BOX_ID.
+			// Current DB schema might not strictly store original box_id in a queryable way unless specific meta is set.
+			// Let's check candidate.node.meta.box_id?
+
+			// For V1 Safety: We will only process "Atomic" files (Debriefs, Notes) where one file = one node.
+			// We will implementation Section injection later to avoid regex corruption risk without more robust testing.
+			this.log.warn(
+				{ candidate: candidate.nodeId },
+				"⚠️ Section injection postponed for safety.",
+			);
+			return;
+		} else {
+			// Atomic File Injection (Append)
+			// Check if file already ends with newline
+			const newContent = fileContent.endsWith("\n")
+				? fileContent + tagBlock
+				: `${fileContent}\n${tagBlock}`;
+
+			await Bun.write(candidate.filePath, newContent);
+			this.log.info(
+				{ candidate: candidate.nodeId, tagCount: tags.length },
+				"✅ Injected tags",
+			);
+		}
+	}
+}

package/src/gardeners/BaseGardener.ts

@@ -0,0 +1,55 @@
+import type { ResonanceDB } from "@src/resonance/db";
+import { getLogger, type Logger } from "@src/utils/Logger";
+
+export interface Candidate {
+	nodeId: string;
+	filePath: string;
+	content: string;
+	type: string;
+}
+
+export abstract class BaseGardener {
+	protected db: ResonanceDB;
+	protected log: Logger;
+
+	constructor(db: ResonanceDB) {
+		this.db = db;
+		// We use a generic name initially, subclasses can override or we rely on 'name' property later
+		// Actually, we can't access 'this.name' safely in constructor if it's a property.
+		// Let's use "Gardener" as the component.
+		this.log = getLogger("Gardener");
+	}
+
+	abstract name: string;
+
+	/**
+	 * Finds candidates that need attention.
+	 */
+	abstract scan(limit: number): Promise<Candidate[]>;
+
+	/**
+	 * Applies changes to a single candidate.
+	 */
+	abstract cultivate(candidate: Candidate): Promise<void>;
+
+	/**
+	 * Main loop.
+	 */
+	public async run(limit: number = 10) {
+		this.log.info({ gardener: this.name }, "🌿 Gardener starting...");
+		const candidates = await this.scan(limit);
+		this.log.info(
+			{ gardener: this.name, count: candidates.length },
+			"Found candidates",
+		);
+
+		for (const candidate of candidates) {
+			this.log.debug(
+				{ gardener: this.name, nodeId: candidate.nodeId },
+				"Processing candidate",
+			);
+			await this.cultivate(candidate);
+		}
+		this.log.info({ gardener: this.name }, "✅ Gardener finished");
+	}
+}

package/src/llm/EnlightenedProvider.ts

@@ -0,0 +1,95 @@
+// src/llm/EnlightenedProvider.ts
+
+export interface Message {
+	role: "system" | "user" | "assistant";
+	content: string;
+}
+
+export interface EnlightenmentConfig {
+	port?: number;
+	modelAlias?: string;
+	temperature?: number;
+	maxTokens?: number;
+}
+
+/**
+ * THE ENLIGHTENED PROVIDER
+ * A specialized adapter for the "Kirkcaldy Accountant" vector-steered model.
+ * Default Port: 8083
+ */
+export class EnlightenedProvider {
+	private baseUrl: string;
+	private modelAlias: string;
+	private defaultTemp: number;
+
+	constructor(config: EnlightenmentConfig = {}) {
+		this.baseUrl = `http://127.0.0.1:${config.port || 8083}/v1`;
+		this.modelAlias = config.modelAlias || "enlightened-llama";
+		this.defaultTemp = config.temperature || 0.1; // Keep it cold for logic
+	}
+
+	/**
+	 * THE RATIONALITY CHECK
+	 * Pings the server to ensure the Enlightenment engine is online.
+	 */
+	async isOnline(): Promise<boolean> {
+		try {
+			const response = await fetch(`${this.baseUrl}/models`);
+			return response.ok;
+		} catch {
+			return false;
+		}
+	}
+
+	/**
+	 * THE THINK METHOD
+	 * Sends the prompt to the vector-clamped model.
+	 */
+	async think(messages: Message[]): Promise<string> {
+		try {
+			const response = await fetch(`${this.baseUrl}/chat/completions`, {
+				method: "POST",
+				headers: {
+					"Content-Type": "application/json",
+					Authorization: "Bearer sk-dummy-key", // Required by protocol, ignored by server
+				},
+				body: JSON.stringify({
+					model: this.modelAlias,
+					messages: messages,
+					temperature: this.defaultTemp,
+					max_tokens: 1024,
+					stream: false,
+				}),
+			});
+
+			if (!response.ok) {
+				throw new Error(
+					`Enlightenment Error: ${response.status} ${response.statusText}`,
+				);
+			}
+
+			const data = (await response.json()) as {
+				choices: { message: { content: string } }[];
+			};
+			return data?.choices?.[0]?.message?.content?.trim() || "";
+		} catch (error) {
+			console.error("🏴󠁧󠁢󠁳󠁣󠁴󠁿 The Philosopher is silent (Connection Error).", error);
+			throw error;
+		}
+	}
+
+	/**
+	 * SPECIALIST METHOD: DE-FLUFF
+	 * A pre-configured routine to strip buzzwords from text.
+	 */
+	async defluff(inputText: string): Promise<string> {
+		return this.think([
+			{
+				role: "system",
+				content:
+					"You are a ruthless editor. Rewrite the following text to be concise, factual, and free of corporate buzzwords. Return ONLY the rewritten text.",
+			},
+			{ role: "user", content: inputText },
+		]);
+	}
+}

package/src/mcp/README.md

@@ -0,0 +1,6 @@
+# 🔌 MCP Server
+
+The Model Context Protocol (MCP) server implementation for Polyvis.
+
+## Contents
+- **`index.ts`**: Entry point for the MCP server. Exposes tools (`search_documents`, `read_node_content`, etc.) and resources.

package/src/mcp/index.ts

@@ -0,0 +1,341 @@
+import { appendFileSync } from "node:fs";
+import { join } from "node:path";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+	CallToolRequestSchema,
+	ListResourcesRequestSchema,
+	ListToolsRequestSchema,
+	ReadResourceRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import { VectorEngine } from "@src/core/VectorEngine";
+import { ResonanceDB } from "@src/resonance/db";
+import { EnvironmentVerifier } from "../utils/EnvironmentVerifier";
+import { getLogger } from "../utils/Logger";
+import { ServiceLifecycle } from "../utils/ServiceLifecycle";
+
+const args = process.argv.slice(2);
+const command = args[0] || "serve";
+const log = getLogger("MCP");
+
+// --- Service Lifecycle ---
+
+const lifecycle = new ServiceLifecycle({
+	name: "MCP",
+	pidFile: ".mcp.pid",
+	logFile: ".mcp.log",
+	entryPoint: "src/mcp/index.ts",
+});
+
+// --- Server Logic ---
+
+// Helper function to create fresh database connection per request
+function createConnection() {
+	const dbPath = join(import.meta.dir, "../../.amalfa/resonance.db");
+	const db = new ResonanceDB(dbPath);
+	const vectorEngine = new VectorEngine(db.getRawDb());
+	return { db, vectorEngine };
+}
+
+async function runServer() {
+	// 0. Verify Environment
+	// TODO: Update EnvironmentVerifier for AMALFA paths (not PolyVis)
+	// await EnvironmentVerifier.verifyOrExit();
+
+	log.info("🚀 AMALFA MCP Server Initializing...");
+
+	// 1. Setup Server
+	const server = new Server(
+		{ name: "amalfa-mcp", version: "1.0.0" },
+		{ capabilities: { tools: {}, resources: {} } },
+	);
+
+	// 2. Define Constants
+	const TOOLS = {
+		SEARCH: "search_documents",
+		READ: "read_node_content",
+		EXPLORE: "explore_links",
+		LIST: "list_directory_structure",
+		GARDEN: "inject_tags",
+	};
+
+	// 3. Register Handlers
+	server.setRequestHandler(ListToolsRequestSchema, async () => {
+		return {
+			tools: [
+				{
+					name: TOOLS.SEARCH,
+					description:
+						"Search the Knowledge Graph using Vector (semantic) search.",
+					inputSchema: {
+						type: "object",
+						properties: {
+							query: { type: "string" },
+							limit: { type: "number", default: 20 },
+						},
+						required: ["query"],
+					},
+				},
+				{
+					name: TOOLS.READ,
+					description: "Read the full markdown content of a specific node.",
+					inputSchema: {
+						type: "object",
+						properties: { id: { type: "string" } },
+						required: ["id"],
+					},
+				},
+				{
+					name: TOOLS.EXPLORE,
+					description: "Find related nodes (Graph Traversal).",
+					inputSchema: {
+						type: "object",
+						properties: {
+							id: { type: "string" },
+							relation: { type: "string" },
+						},
+						required: ["id"],
+					},
+				},
+				{
+					name: TOOLS.LIST,
+					description: "List the directory structure of the document set.",
+					inputSchema: { type: "object", properties: {} },
+				},
+				{
+					name: TOOLS.GARDEN,
+					description:
+						"Inject semantic tags into a source file (Gardener Agent).",
+					inputSchema: {
+						type: "object",
+						properties: {
+							file_path: { type: "string" },
+							tags: { type: "array", items: { type: "string" } },
+						},
+						required: ["file_path", "tags"],
+					},
+				},
+			],
+		};
+	});
+
+	server.setRequestHandler(CallToolRequestSchema, async (request) => {
+		const { name, arguments: args } = request.params;
+		try {
+			if (name === TOOLS.SEARCH) {
+				// Create fresh connection for this request
+				const { db, vectorEngine } = createConnection();
+				try {
+					const query = String(args?.query);
+					const limit = Number(args?.limit || 20);
+					const candidates = new Map<
+						string,
+						{ id: string; score: number; preview: string; source: string }
+					>();
+					const errors: string[] = [];
+
+					// Vector Search only (FTS removed in Hollow Node migration)
+					try {
+						const vectorResults = await vectorEngine.search(query, limit);
+						for (const r of vectorResults) {
+							candidates.set(r.id, {
+								id: r.id,
+								score: r.score,
+								preview: r.content.slice(0, 200).replace(/\n/g, " "),
+								source: "vector",
+							});
+						}
+					} catch (e: unknown) {
+						const msg = e instanceof Error ? e.message : String(e);
+						log.error({ err: e }, "Vector Search Error");
+						errors.push(msg);
+					}
+
+					const results = Array.from(candidates.values())
+						.sort((a, b) => b.score - a.score)
+						.slice(0, limit)
+						.map((r) => ({ ...r, score: r.score.toFixed(3) }));
+
+					if (results.length === 0 && errors.length > 0) {
+						return {
+							content: [
+								{ type: "text", text: `Search Error: ${errors.join(", ")}` },
+							],
+							isError: true,
+						};
+					}
+					return {
+						content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
+					};
+				} finally {
+					// Cleanup connection
+					db.close();
+				}
+			}
+
+			if (name === TOOLS.READ) {
+				// Hollow Node: Read content from filesystem via meta.source
+				const { db } = createConnection();
+				try {
+					const id = String(args?.id);
+					const row = db
+						.getRawDb()
+						.query("SELECT meta FROM nodes WHERE id = ?")
+						.get(id) as { meta: string | null } | null;
+
+					if (!row) {
+						return { content: [{ type: "text", text: "Node not found." }] };
+					}
+
+					const meta = row.meta ? JSON.parse(row.meta) : {};
+					const sourcePath = meta.source;
+
+					if (!sourcePath) {
+						return {
+							content: [
+								{ type: "text", text: `No source file for node: ${id}` },
+							],
+						};
+					}
+
+					// Read content from filesystem
+					try {
+						const content = await Bun.file(sourcePath).text();
+						return { content: [{ type: "text", text: content }] };
+					} catch {
+						return {
+							content: [
+								{ type: "text", text: `File not found: ${sourcePath}` },
+							],
+						};
+					}
+				} finally {
+					db.close();
+				}
+			}
+
+			if (name === TOOLS.EXPLORE) {
+				// Create fresh connection for this request
+				const { db } = createConnection();
+				try {
+					const id = String(args?.id);
+					const relation = args?.relation ? String(args.relation) : undefined;
+					let sql = "SELECT target, type FROM edges WHERE source = ?";
+					const params = [id];
+					if (relation) {
+						sql += " AND type = ?";
+						params.push(relation);
+					}
+					const rows = db
+						.getRawDb()
+						.query(sql)
+						.all(...params) as Record<string, unknown>[];
+					return {
+						content: [{ type: "text", text: JSON.stringify(rows, null, 2) }],
+					};
+				} finally {
+					db.close();
+				}
+			}
+
+			if (name === TOOLS.LIST) {
+				// TODO: Make this configurable via amalfa.config.ts
+				const structure = [
+					"docs/",
+					"notes/",
+				];
+				return {
+					content: [{ type: "text", text: JSON.stringify(structure, null, 2) }],
+				};
+			}
+
+			if (name === TOOLS.GARDEN) {
+				const filePath = String(args?.file_path);
+				const tags = args?.tags as string[];
+				const content = await Bun.file(filePath).text();
+				const tagBlock = `\n<!-- tags: ${tags.join(", ")} -->\n`;
+				const newContent = content.endsWith("\n")
+					? content + tagBlock
+					: `${content}\n${tagBlock}`;
+				await Bun.write(filePath, newContent);
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Injected ${tags.length} tags into ${filePath}`,
+						},
+					],
+				};
+			}
+
+			return {
+				content: [{ type: "text", text: `Tool ${name} not found.` }],
+				isError: true,
+			};
+		} catch (error) {
+			log.error({ err: error, tool: name }, "Tool execution failed");
+			return {
+				content: [{ type: "text", text: `Error: ${error}` }],
+				isError: true,
+			};
+		}
+	});
+
+	server.setRequestHandler(ListResourcesRequestSchema, async () => {
+		return {
+			resources: [
+				{
+					uri: "amalfa://stats/summary",
+					name: "System Stats",
+					mimeType: "text/plain",
+				},
+			],
+		};
+	});
+
+	server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+		if (request.params.uri === "amalfa://stats/summary") {
+			// Create fresh connection for this request
+			const { db } = createConnection();
+			try {
+				const stats = db.getStats();
+				const text = `Nodes: ${stats.nodes}\nEdges: ${stats.edges}\nVectors: ${stats.vectors}\nSize: ${(stats.db_size_bytes / 1024 / 1024).toFixed(2)} MB`;
+				return {
+					contents: [{ uri: request.params.uri, mimeType: "text/plain", text }],
+				};
+			} finally {
+				db.close();
+			}
+		}
+		throw new Error("Resource not found");
+	});
+
+	// 4. Connect Transport
+	const transport = new StdioServerTransport();
+	await server.connect(transport);
+	log.info("✅ AMALFA MCP Server Running (Per-Request Connections)");
+}
+
+// --- Global Error Handling ---
+
+process.on("uncaughtException", (error) => {
+	log.fatal({ err: error }, "UNKNOWN MCP ERROR");
+	// Original crash log logic preserved for safety? Or redundant?
+	// Let's keep specific crash log as backup for now, but log via pino too
+	const msg = `[${new Date().toISOString()}] UNKNOWN MCP ERROR: ${error instanceof Error ? error.stack : error}\n`;
+	try {
+		appendFileSync(".mcp.crash.log", msg);
+	} catch {}
+});
+
+process.on("unhandledRejection", (reason) => {
+	log.fatal({ err: reason }, "UNHANDLED REJECTION");
+	const msg = `[${new Date().toISOString()}] UNHANDLED REJECTION: ${reason}\n`;
+	try {
+		appendFileSync(".mcp.crash.log", msg);
+	} catch {}
+});
+
+// --- Dispatch ---
+
+await lifecycle.run(command, runServer, false);