@199-bio/engram 0.2.0 → 0.3.1

package/src/web/server.ts

@@ -0,0 +1,280 @@
+/**
+ * Engram Web Interface
+ * Local web server for browsing, searching, and editing memories
+ */
+
+import http from "http";
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import { EngramDatabase } from "../storage/database.js";
+import { KnowledgeGraph } from "../graph/knowledge-graph.js";
+import { HybridSearch } from "../retrieval/hybrid.js";
+import { ColBERTRetriever, SimpleRetriever } from "../retrieval/colbert.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const STATIC_DIR = path.join(__dirname, "..", "..", "src", "web", "static");
+
+const MIME_TYPES: Record<string, string> = {
+  ".html": "text/html",
+  ".css": "text/css",
+  ".js": "application/javascript",
+  ".json": "application/json",
+  ".png": "image/png",
+  ".svg": "image/svg+xml",
+};
+
+interface WebServerOptions {
+  db: EngramDatabase;
+  graph: KnowledgeGraph;
+  search: HybridSearch;
+  port?: number;
+}
+
+export class EngramWebServer {
+  private server: http.Server | null = null;
+  private db: EngramDatabase;
+  private graph: KnowledgeGraph;
+  private search: HybridSearch;
+  private port: number;
+
+  constructor(options: WebServerOptions) {
+    this.db = options.db;
+    this.graph = options.graph;
+    this.search = options.search;
+    this.port = options.port || 3847;
+  }
+
+  async start(): Promise<string> {
+    if (this.server) {
+      return `http://localhost:${this.port}`;
+    }
+
+    this.server = http.createServer((req, res) => this.handleRequest(req, res));
+
+    return new Promise((resolve, reject) => {
+      this.server!.listen(this.port, () => {
+        const url = `http://localhost:${this.port}`;
+        console.error(`[Engram] Web interface running at ${url}`);
+        resolve(url);
+      });
+
+      this.server!.on("error", reject);
+    });
+  }
+
+  stop(): void {
+    if (this.server) {
+      this.server.close();
+      this.server = null;
+    }
+  }
+
+  private async handleRequest(req: http.IncomingMessage, res: http.ServerResponse): Promise<void> {
+    const url = new URL(req.url || "/", `http://localhost:${this.port}`);
+    const pathname = url.pathname;
+
+    // CORS headers for local development
+    res.setHeader("Access-Control-Allow-Origin", "*");
+    res.setHeader("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS");
+    res.setHeader("Access-Control-Allow-Headers", "Content-Type");
+
+    if (req.method === "OPTIONS") {
+      res.writeHead(204);
+      res.end();
+      return;
+    }
+
+    try {
+      // API routes
+      if (pathname.startsWith("/api/")) {
+        await this.handleAPI(req, res, pathname, url);
+        return;
+      }
+
+      // Static files
+      await this.serveStatic(req, res, pathname);
+    } catch (error) {
+      console.error("[Engram Web] Error:", error);
+      res.writeHead(500, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Internal server error" }));
+    }
+  }
+
+  private async handleAPI(
+    req: http.IncomingMessage,
+    res: http.ServerResponse,
+    pathname: string,
+    url: URL
+  ): Promise<void> {
+    const method = req.method || "GET";
+    const body = method !== "GET" ? await this.parseBody(req) : null;
+
+    res.setHeader("Content-Type", "application/json");
+
+    // GET /api/stats
+    if (pathname === "/api/stats" && method === "GET") {
+      const stats = this.db.getStats();
+      res.end(JSON.stringify(stats));
+      return;
+    }
+
+    // GET /api/memories
+    if (pathname === "/api/memories" && method === "GET") {
+      const query = url.searchParams.get("q");
+      const limit = parseInt(url.searchParams.get("limit") || "50");
+
+      if (query) {
+        const results = await this.search.search(query, { limit });
+        res.end(JSON.stringify({
+          memories: results.map(r => ({
+            ...r.memory,
+            score: r.score,
+            sources: r.sources,
+          })),
+        }));
+      } else {
+        const memories = this.db.getAllMemories(limit);
+        res.end(JSON.stringify({ memories }));
+      }
+      return;
+    }
+
+    // POST /api/memories
+    if (pathname === "/api/memories" && method === "POST") {
+      const { content, source, importance } = body as any;
+      const memory = this.db.createMemory(content, source || "web", importance || 0.5);
+      await this.search.indexMemory(memory);
+      const { entities, observations } = this.graph.extractAndStore(content, memory.id);
+      res.writeHead(201);
+      res.end(JSON.stringify({ memory, entities_extracted: entities.length, observations_created: observations.length }));
+      return;
+    }
+
+    // PUT /api/memories/:id
+    const memoryMatch = pathname.match(/^\/api\/memories\/([a-f0-9-]+)$/);
+    if (memoryMatch && method === "PUT") {
+      const id = memoryMatch[1];
+      const { content, importance } = body as any;
+      const updated = this.db.updateMemory(id, { content, importance });
+      if (updated) {
+        res.end(JSON.stringify({ memory: updated }));
+      } else {
+        res.writeHead(404);
+        res.end(JSON.stringify({ error: "Memory not found" }));
+      }
+      return;
+    }
+
+    // DELETE /api/memories/:id
+    if (memoryMatch && method === "DELETE") {
+      const id = memoryMatch[1];
+      await this.search.removeFromIndex(id);
+      const deleted = this.db.deleteMemory(id);
+      res.end(JSON.stringify({ success: deleted }));
+      return;
+    }
+
+    // GET /api/entities
+    if (pathname === "/api/entities" && method === "GET") {
+      const type = url.searchParams.get("type") as any;
+      const limit = parseInt(url.searchParams.get("limit") || "100");
+      const entities = this.graph.listEntities(type || undefined, limit);
+      res.end(JSON.stringify({ entities }));
+      return;
+    }
+
+    // GET /api/entities/:name
+    const entityMatch = pathname.match(/^\/api\/entities\/(.+)$/);
+    if (entityMatch && method === "GET") {
+      const name = decodeURIComponent(entityMatch[1]);
+      const details = this.graph.getEntityDetails(name);
+      if (details) {
+        res.end(JSON.stringify(details));
+      } else {
+        res.writeHead(404);
+        res.end(JSON.stringify({ error: "Entity not found" }));
+      }
+      return;
+    }
+
+    // GET /api/graph
+    if (pathname === "/api/graph" && method === "GET") {
+      const entities = this.graph.listEntities(undefined, 500);
+      const nodes = entities.map(e => ({
+        id: e.id,
+        label: e.name,
+        type: e.type,
+      }));
+
+      // Get all relations
+      const edges: Array<{ from: string; to: string; label: string }> = [];
+      for (const entity of entities) {
+        const relations = this.db.getEntityRelations(entity.id, "from");
+        for (const rel of relations) {
+          edges.push({
+            from: rel.from_entity,
+            to: rel.to_entity,
+            label: rel.type,
+          });
+        }
+      }
+
+      res.end(JSON.stringify({ nodes, edges }));
+      return;
+    }
+
+    // 404 for unknown API routes
+    res.writeHead(404);
+    res.end(JSON.stringify({ error: "Not found" }));
+  }
+
+  private async serveStatic(
+    req: http.IncomingMessage,
+    res: http.ServerResponse,
+    pathname: string
+  ): Promise<void> {
+    // Default to index.html
+    if (pathname === "/" || pathname === "") {
+      pathname = "/index.html";
+    }
+
+    const filePath = path.join(STATIC_DIR, pathname);
+
+    // Security: prevent directory traversal
+    if (!filePath.startsWith(STATIC_DIR)) {
+      res.writeHead(403);
+      res.end("Forbidden");
+      return;
+    }
+
+    try {
+      const content = fs.readFileSync(filePath);
+      const ext = path.extname(filePath);
+      const contentType = MIME_TYPES[ext] || "application/octet-stream";
+
+      res.writeHead(200, { "Content-Type": contentType });
+      res.end(content);
+    } catch {
+      res.writeHead(404);
+      res.end("Not found");
+    }
+  }
+
+  private parseBody(req: http.IncomingMessage): Promise<unknown> {
+    return new Promise((resolve, reject) => {
+      let data = "";
+      req.on("data", (chunk) => (data += chunk));
+      req.on("end", () => {
+        try {
+          resolve(data ? JSON.parse(data) : {});
+        } catch (e) {
+          reject(e);
+        }
+      });
+      req.on("error", reject);
+    });
+  }
+}

package/src/web/static/app.js

@@ -0,0 +1,362 @@
+/**
+ * Engram Web Interface
+ * Vanilla JavaScript - no build step required
+ */
+
+const API_BASE = '';
+
+// State
+let currentView = 'memories';
+let editingMemoryId = null;
+
+// DOM Elements
+const views = {
+  memories: document.getElementById('memories-view'),
+  entities: document.getElementById('entities-view'),
+  graph: document.getElementById('graph-view'),
+};
+
+const statsEl = document.getElementById('stats');
+const memoriesList = document.getElementById('memories-list');
+const entitiesList = document.getElementById('entities-list');
+const graphContainer = document.getElementById('graph-container');
+const searchInput = document.getElementById('search-input');
+const entityTypeFilter = document.getElementById('entity-type-filter');
+
+// Modal elements
+const modal = document.getElementById('modal');
+const modalTitle = document.getElementById('modal-title');
+const modalForm = document.getElementById('modal-form');
+const modalContentInput = document.getElementById('modal-content-input');
+const modalSource = document.getElementById('modal-source');
+const modalImportance = document.getElementById('modal-importance');
+const importanceValue = document.getElementById('importance-value');
+
+const entityModal = document.getElementById('entity-modal');
+const entityModalTitle = document.getElementById('entity-modal-title');
+const entityModalBody = document.getElementById('entity-modal-body');
+
+// API helpers
+async function api(path, options = {}) {
+  const res = await fetch(`${API_BASE}${path}`, {
+    headers: { 'Content-Type': 'application/json' },
+    ...options,
+    body: options.body ? JSON.stringify(options.body) : undefined,
+  });
+  return res.json();
+}
+
+// Format date
+function formatDate(dateStr) {
+  const date = new Date(dateStr);
+  return date.toLocaleDateString('en-GB', {
+    day: 'numeric',
+    month: 'short',
+    year: 'numeric',
+    hour: '2-digit',
+    minute: '2-digit',
+  });
+}
+
+// Load stats
+async function loadStats() {
+  const stats = await api('/api/stats');
+  statsEl.textContent = `${stats.memories} memories \u00b7 ${stats.entities} entities \u00b7 ${stats.relations} relations`;
+}
+
+// Load memories
+async function loadMemories(query = '') {
+  const path = query ? `/api/memories?q=${encodeURIComponent(query)}` : '/api/memories';
+  const data = await api(path);
+
+  if (data.memories.length === 0) {
+    memoriesList.innerHTML = '<div class="empty-state">No memories found</div>';
+    return;
+  }
+
+  memoriesList.innerHTML = data.memories.map(m => `
+    <div class="list-item memory-item" data-id="${m.id}">
+      <div class="content">${escapeHtml(m.content)}</div>
+      <div class="meta">
+        <span>${formatDate(m.timestamp)}</span>
+        <span>${m.source}</span>
+        <span>importance: ${m.importance}</span>
+        ${m.score ? `<span class="score">${m.score.toFixed(4)}</span>` : ''}
+      </div>
+      <div class="actions">
+        <button class="edit-btn" data-id="${m.id}">Edit</button>
+        <button class="delete-btn" data-id="${m.id}">Delete</button>
+      </div>
+    </div>
+  `).join('');
+
+  // Attach event listeners
+  memoriesList.querySelectorAll('.edit-btn').forEach(btn => {
+    btn.addEventListener('click', (e) => {
+      e.stopPropagation();
+      editMemory(btn.dataset.id);
+    });
+  });
+
+  memoriesList.querySelectorAll('.delete-btn').forEach(btn => {
+    btn.addEventListener('click', (e) => {
+      e.stopPropagation();
+      deleteMemory(btn.dataset.id);
+    });
+  });
+}
+
+// Load entities
+async function loadEntities(type = '') {
+  const path = type ? `/api/entities?type=${type}` : '/api/entities';
+  const data = await api(path);
+
+  if (data.entities.length === 0) {
+    entitiesList.innerHTML = '<div class="empty-state">No entities found</div>';
+    return;
+  }
+
+  entitiesList.innerHTML = data.entities.map(e => `
+    <div class="list-item entity-item" data-name="${escapeHtml(e.name)}">
+      <div class="name">${escapeHtml(e.name)}</div>
+      <div class="type">${e.type}</div>
+    </div>
+  `).join('');
+
+  // Attach event listeners
+  entitiesList.querySelectorAll('.entity-item').forEach(item => {
+    item.addEventListener('click', () => {
+      showEntityDetails(item.dataset.name);
+    });
+  });
+}
+
+// Show entity details
+async function showEntityDetails(name) {
+  const data = await api(`/api/entities/${encodeURIComponent(name)}`);
+
+  entityModalTitle.textContent = data.name;
+
+  let html = `<p><strong>Type:</strong> ${data.type}</p>`;
+
+  if (data.observations && data.observations.length > 0) {
+    html += `<h3>Observations</h3><ul>`;
+    data.observations.forEach(o => {
+      html += `<li>${escapeHtml(o.content)}</li>`;
+    });
+    html += `</ul>`;
+  }
+
+  if (data.relationsFrom && data.relationsFrom.length > 0) {
+    html += `<h3>Relationships (outgoing)</h3><ul>`;
+    data.relationsFrom.forEach(r => {
+      html += `<li>${r.type} \u2192 ${escapeHtml(r.targetEntity?.name || r.to)}</li>`;
+    });
+    html += `</ul>`;
+  }
+
+  if (data.relationsTo && data.relationsTo.length > 0) {
+    html += `<h3>Relationships (incoming)</h3><ul>`;
+    data.relationsTo.forEach(r => {
+      html += `<li>${escapeHtml(r.sourceEntity?.name || r.from)} \u2192 ${r.type}</li>`;
+    });
+    html += `</ul>`;
+  }
+
+  entityModalBody.innerHTML = html;
+  entityModal.classList.remove('hidden');
+}
+
+// Load graph
+async function loadGraph() {
+  const data = await api('/api/graph');
+
+  // Simple visualization using CSS
+  if (data.nodes.length === 0) {
+    graphContainer.innerHTML = '<div class="empty-state">No entities in graph</div>';
+    return;
+  }
+
+  // Create a simple text-based visualization
+  let html = '<div style="padding: 2rem; font-size: 0.875rem;">';
+  html += '<p style="margin-bottom: 1rem; color: var(--text-muted);">Knowledge graph visualization. Click entities to see details.</p>';
+
+  // Group by type
+  const byType = {};
+  data.nodes.forEach(n => {
+    if (!byType[n.type]) byType[n.type] = [];
+    byType[n.type].push(n);
+  });
+
+  for (const [type, nodes] of Object.entries(byType)) {
+    html += `<div style="margin-bottom: 1.5rem;">`;
+    html += `<h3 style="font-size: 0.75rem; text-transform: uppercase; letter-spacing: 0.1em; color: var(--text-muted); margin-bottom: 0.5rem;">${type}</h3>`;
+    html += `<div style="display: flex; flex-wrap: wrap; gap: 0.5rem;">`;
+    nodes.forEach(n => {
+      html += `<span class="graph-node" data-name="${escapeHtml(n.label)}" style="padding: 0.375rem 0.75rem; background: var(--bg-tertiary); cursor: pointer;">${escapeHtml(n.label)}</span>`;
+    });
+    html += `</div></div>`;
+  }
+
+  if (data.edges.length > 0) {
+    html += `<div style="margin-top: 2rem;">`;
+    html += `<h3 style="font-size: 0.75rem; text-transform: uppercase; letter-spacing: 0.1em; color: var(--text-muted); margin-bottom: 0.5rem;">Relationships</h3>`;
+    html += `<ul style="list-style: none;">`;
+    data.edges.forEach(e => {
+      const fromNode = data.nodes.find(n => n.id === e.from);
+      const toNode = data.nodes.find(n => n.id === e.to);
+      if (fromNode && toNode) {
+        html += `<li style="padding: 0.25rem 0; color: var(--text-secondary);">${escapeHtml(fromNode.label)} <span style="color: var(--accent);">\u2192 ${e.label} \u2192</span> ${escapeHtml(toNode.label)}</li>`;
+      }
+    });
+    html += `</ul></div>`;
+  }
+
+  html += '</div>';
+  graphContainer.innerHTML = html;
+
+  // Attach click handlers
+  graphContainer.querySelectorAll('.graph-node').forEach(node => {
+    node.addEventListener('click', () => {
+      showEntityDetails(node.dataset.name);
+    });
+  });
+}
+
+// Edit memory
+async function editMemory(id) {
+  const data = await api('/api/memories');
+  const memory = data.memories.find(m => m.id === id);
+  if (!memory) return;
+
+  editingMemoryId = id;
+  modalTitle.textContent = 'Edit Memory';
+  modalContentInput.value = memory.content;
+  modalSource.value = memory.source;
+  modalImportance.value = memory.importance;
+  importanceValue.textContent = memory.importance;
+  modal.classList.remove('hidden');
+}
+
+// Delete memory
+async function deleteMemory(id) {
+  if (!confirm('Delete this memory?')) return;
+
+  await api(`/api/memories/${id}`, { method: 'DELETE' });
+  await loadMemories(searchInput.value);
+  await loadStats();
+}
+
+// Save memory
+async function saveMemory() {
+  const content = modalContentInput.value.trim();
+  if (!content) return;
+
+  const body = {
+    content,
+    source: modalSource.value || 'web',
+    importance: parseFloat(modalImportance.value),
+  };
+
+  if (editingMemoryId) {
+    await api(`/api/memories/${editingMemoryId}`, { method: 'PUT', body });
+  } else {
+    await api('/api/memories', { method: 'POST', body });
+  }
+
+  closeModal();
+  await loadMemories(searchInput.value);
+  await loadStats();
+}
+
+// Close modal
+function closeModal() {
+  modal.classList.add('hidden');
+  editingMemoryId = null;
+  modalContentInput.value = '';
+  modalSource.value = 'web';
+  modalImportance.value = '0.5';
+  importanceValue.textContent = '0.5';
+}
+
+// Escape HTML
+function escapeHtml(str) {
+  if (!str) return '';
+  return str
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#039;');
+}
+
+// Switch view
+function switchView(view) {
+  currentView = view;
+
+  // Update nav buttons
+  document.querySelectorAll('.nav-btn').forEach(btn => {
+    btn.classList.toggle('active', btn.dataset.view === view);
+  });
+
+  // Update views
+  Object.entries(views).forEach(([name, el]) => {
+    el.classList.toggle('active', name === view);
+  });
+
+  // Load data for view
+  if (view === 'memories') loadMemories(searchInput.value);
+  if (view === 'entities') loadEntities(entityTypeFilter.value);
+  if (view === 'graph') loadGraph();
+}
+
+// Event listeners
+document.querySelectorAll('.nav-btn').forEach(btn => {
+  btn.addEventListener('click', () => switchView(btn.dataset.view));
+});
+
+document.getElementById('search-btn').addEventListener('click', () => {
+  loadMemories(searchInput.value);
+});
+
+searchInput.addEventListener('keypress', (e) => {
+  if (e.key === 'Enter') loadMemories(searchInput.value);
+});
+
+entityTypeFilter.addEventListener('change', () => {
+  loadEntities(entityTypeFilter.value);
+});
+
+document.getElementById('add-memory-btn').addEventListener('click', () => {
+  editingMemoryId = null;
+  modalTitle.textContent = 'Add Memory';
+  modal.classList.remove('hidden');
+});
+
+document.getElementById('modal-cancel').addEventListener('click', closeModal);
+
+modalForm.addEventListener('submit', (e) => {
+  e.preventDefault();
+  saveMemory();
+});
+
+modalImportance.addEventListener('input', () => {
+  importanceValue.textContent = modalImportance.value;
+});
+
+document.getElementById('entity-modal-close').addEventListener('click', () => {
+  entityModal.classList.add('hidden');
+});
+
+// Close modals on backdrop click
+modal.addEventListener('click', (e) => {
+  if (e.target === modal) closeModal();
+});
+
+entityModal.addEventListener('click', (e) => {
+  if (e.target === entityModal) entityModal.classList.add('hidden');
+});
+
+// Initialize
+loadStats();
+loadMemories();