@199-bio/engram 0.7.4 → 0.8.1

package/src/web/chat-handler.ts

@@ -1,6 +1,6 @@
 /**
  * Chat Handler for Engram Web Interface
- * Uses Claude Haiku 4.5 with tools for entity/memory management
+ * Uses Claude Opus 4.5 with tools for entity/memory management
  */
 
 import Anthropic from "@anthropic-ai/sdk";
@@ -9,22 +9,22 @@ import { KnowledgeGraph } from "../graph/knowledge-graph.js";
 import { HybridSearch } from "../retrieval/hybrid.js";
 import { getAnthropicApiKey } from "../settings.js";
 
-// Tool definitions for Claude
+// Tool definitions for Claude - optimized for LLM consumption
 const TOOLS: Anthropic.Tool[] = [
   {
     name: "list_entities",
-    description: "List all entities in the knowledge graph. Use this to see what people, organizations, and places are stored.",
+    description: "Returns array of {name, type, id}. Filters: type (person|organization|place), limit. Default limit=50.",
     input_schema: {
       type: "object" as const,
       properties: {
         type: {
           type: "string",
           enum: ["person", "organization", "place"],
-          description: "Filter by entity type (optional)",
+          description: "Filter: person, organization, or place",
         },
         limit: {
-          type: "number",
-          description: "Maximum number of entities to return (default: 50)",
+          type: "integer",
+          description: "Max results (default: 50)",
         },
       },
       required: [],
@@ -32,13 +32,13 @@ const TOOLS: Anthropic.Tool[] = [
   },
   {
     name: "get_entity",
-    description: "Get detailed information about an entity including its observations and relationships.",
+    description: "Returns {name, type, observations[], relationships_from[], relationships_to[]} or {error}.",
     input_schema: {
       type: "object" as const,
       properties: {
         name: {
           type: "string",
-          description: "The entity name to look up",
+          description: "Exact entity name (case-sensitive)",
         },
       },
       required: ["name"],
@@ -46,13 +46,13 @@ const TOOLS: Anthropic.Tool[] = [
   },
   {
     name: "delete_entity",
-    description: "Delete an entity and all its observations and relationships. Use this to remove incorrect or duplicate entities.",
+    description: "Permanently removes entity + all observations + all relationships. Returns {success, deleted} or {error}.",
     input_schema: {
       type: "object" as const,
       properties: {
         name: {
           type: "string",
-          description: "The entity name to delete",
+          description: "Exact entity name to delete",
         },
       },
       required: ["name"],
@@ -60,17 +60,17 @@ const TOOLS: Anthropic.Tool[] = [
   },
   {
     name: "merge_entities",
-    description: "Merge one entity into another. All observations and relationships from the source will be moved to the target, then the source is deleted. Use this to fix duplicates.",
+    description: "Moves all data from 'merge' into 'keep', then deletes 'merge'. Use for deduplication. Returns {success, kept, merged, observations_moved, relations_moved} or {error}.",
     input_schema: {
       type: "object" as const,
       properties: {
         keep: {
           type: "string",
-          description: "The entity name to keep (target)",
+          description: "Entity name to preserve (target)",
         },
         merge: {
           type: "string",
-          description: "The entity name to merge and delete (source)",
+          description: "Entity name to merge then delete (source)",
         },
       },
       required: ["keep", "merge"],
@@ -78,17 +78,17 @@ const TOOLS: Anthropic.Tool[] = [
   },
   {
     name: "rename_entity",
-    description: "Rename an entity to a new name.",
+    description: "Changes entity name. Returns {success, old_name, new_name} or {error}.",
     input_schema: {
       type: "object" as const,
       properties: {
         old_name: {
           type: "string",
-          description: "Current entity name",
+          description: "Current exact name",
         },
         new_name: {
           type: "string",
-          description: "New entity name",
+          description: "New name",
         },
       },
       required: ["old_name", "new_name"],
@@ -96,7 +96,7 @@ const TOOLS: Anthropic.Tool[] = [
   },
   {
     name: "delete_relationship",
-    description: "Delete a relationship between two entities.",
+    description: "Removes specific relationship. All 3 params must match exactly. Returns {success, deleted} or {error}.",
     input_schema: {
       type: "object" as const,
       properties: {
@@ -110,7 +110,7 @@ const TOOLS: Anthropic.Tool[] = [
         },
         type: {
           type: "string",
-          description: "Relationship type (e.g., 'works_at', 'knows')",
+          description: "Relationship type (e.g., works_at, knows, lives_in)",
         },
       },
       required: ["from", "to", "type"],
@@ -118,17 +118,17 @@ const TOOLS: Anthropic.Tool[] = [
   },
   {
     name: "search_memories",
-    description: "Search through stored memories.",
+    description: "Hybrid BM25+semantic search. Returns {results[{id, content, timestamp, score}], count}.",
     input_schema: {
       type: "object" as const,
       properties: {
         query: {
           type: "string",
-          description: "Search query",
+          description: "Search query (keywords or natural language)",
         },
         limit: {
-          type: "number",
-          description: "Maximum results (default: 10)",
+          type: "integer",
+          description: "Max results (default: 10)",
         },
       },
       required: ["query"],
@@ -136,13 +136,13 @@ const TOOLS: Anthropic.Tool[] = [
   },
   {
     name: "delete_memory",
-    description: "Delete a memory by its ID (soft-delete, can be recovered).",
+    description: "Soft-delete (recoverable). Returns {success, disabled_id} or {error}.",
     input_schema: {
       type: "object" as const,
       properties: {
         id: {
           type: "string",
-          description: "The memory ID to delete",
+          description: "Memory UUID",
         },
       },
       required: ["id"],
@@ -150,13 +150,13 @@ const TOOLS: Anthropic.Tool[] = [
   },
   {
     name: "edit_memory",
-    description: "Edit an existing memory's content or importance.",
+    description: "Updates content and/or importance. Returns {success, memory_id, updated_fields[]} or {error}.",
     input_schema: {
       type: "object" as const,
       properties: {
         id: {
           type: "string",
-          description: "The memory ID to edit",
+          description: "Memory UUID",
         },
         content: {
           type: "string",
@@ -164,7 +164,9 @@ const TOOLS: Anthropic.Tool[] = [
         },
         importance: {
           type: "number",
-          description: "New importance (0-1): 0.9=core identity, 0.8=major, 0.5=normal, 0.3=minor",
+          minimum: 0,
+          maximum: 1,
+          description: "0-1: 0.9=identity, 0.8=major, 0.5=normal, 0.3=minor",
         },
       },
       required: ["id"],
@@ -172,17 +174,19 @@ const TOOLS: Anthropic.Tool[] = [
   },
   {
     name: "create_memory",
-    description: "Create a new memory. Use for storing user information, preferences, or facts.",
+    description: "Stores new memory. Returns {success, memory_id, content}.",
     input_schema: {
       type: "object" as const,
       properties: {
         content: {
           type: "string",
-          description: "The information to store",
+          description: "Information to store",
         },
         importance: {
           type: "number",
-          description: "0-1 score: 0.9=core identity, 0.8=major, 0.5=normal (default), 0.3=minor",
+          minimum: 0,
+          maximum: 1,
+          description: "0-1: 0.9=identity, 0.8=major, 0.5=normal (default), 0.3=minor",
         },
       },
       required: ["content"],
@@ -190,13 +194,13 @@ const TOOLS: Anthropic.Tool[] = [
   },
   {
     name: "create_entity",
-    description: "Create a new entity (person, organization, or place).",
+    description: "Creates new entity. Returns {success, entity_id, name, type} or {error} if exists.",
     input_schema: {
       type: "object" as const,
       properties: {
         name: {
           type: "string",
-          description: "The entity name",
+          description: "Entity name",
         },
         type: {
           type: "string",
@@ -209,7 +213,7 @@ const TOOLS: Anthropic.Tool[] = [
   },
   {
     name: "create_relationship",
-    description: "Create a relationship between two entities.",
+    description: "Links two entities. Auto-creates entities as 'person' if missing. Returns {success, relationship}.",
     input_schema: {
       type: "object" as const,
       properties: {
@@ -223,7 +227,7 @@ const TOOLS: Anthropic.Tool[] = [
         },
         type: {
           type: "string",
-          description: "Relationship type (e.g., 'works_at', 'lives_in', 'knows', 'sibling_of')",
+          description: "Relationship type (e.g., works_at, lives_in, knows, sibling_of, parent_of)",
         },
       },
       required: ["from", "to", "type"],
@@ -231,7 +235,7 @@ const TOOLS: Anthropic.Tool[] = [
   },
   {
     name: "find_duplicates",
-    description: "Find potential duplicate entities that could be merged.",
+    description: "Detects similar entity names. Returns {groups[{keep, duplicates[]}], total_duplicates}.",
     input_schema: {
       type: "object" as const,
       properties: {},
@@ -240,7 +244,7 @@ const TOOLS: Anthropic.Tool[] = [
   },
   {
     name: "auto_tidy",
-    description: "Automatically merge all detected duplicate entities.",
+    description: "Auto-merges all detected duplicates. Returns {entities_merged, observations_moved, relations_moved}.",
     input_schema: {
       type: "object" as const,
       properties: {},
@@ -301,6 +305,9 @@ export class ChatHandler {
   refreshClient(): void {
     const apiKey = getAnthropicApiKey();
     if (apiKey) {
+      if (!this.client) {
+        console.error("[Engram] ChatHandler: API key configured");
+      }
       this.client = new Anthropic({ apiKey });
     } else {
       this.client = null;
@@ -308,6 +315,8 @@ export class ChatHandler {
   }
 
   isConfigured(): boolean {
+    // Re-check API key in case it was added after startup
+    this.refreshClient();
     return this.client !== null;
   }
 
@@ -341,6 +350,7 @@ export class ChatHandler {
 
   // Queue-aware chat method
   async chat(userMessage: string): Promise<string> {
+    this.refreshClient();
     if (!this.client) {
       return "Chat is not configured. Set ANTHROPIC_API_KEY environment variable.";
     }
@@ -357,6 +367,7 @@ export class ChatHandler {
 
   // Streaming chat with callbacks for real-time updates
   async *chatStream(userMessage: string): AsyncGenerator<StreamEvent> {
+    this.refreshClient();
     if (!this.client) {
       yield { type: "error", content: "Chat is not configured. Set ANTHROPIC_API_KEY environment variable." };
       return;
@@ -377,11 +388,10 @@ export class ChatHandler {
       }
 
       let continueLoop = true;
-      let fullResponse = "";
 
       while (continueLoop) {
         const stream = this.client.messages.stream({
-          model: "claude-haiku-4-5-20241022",
+          model: "claude-opus-4-5-20251101",
           max_tokens: 1024,
           system: SYSTEM_PROMPT,
           tools: TOOLS,
@@ -402,25 +412,13 @@ export class ChatHandler {
             }
           } else if (event.type === "content_block_delta") {
             if (event.delta.type === "text_delta") {
-              fullResponse += event.delta.text;
               yield { type: "text", content: event.delta.text };
             } else if (event.delta.type === "input_json_delta" && currentToolUse) {
               currentToolUse.input += event.delta.partial_json;
             }
           } else if (event.type === "content_block_stop") {
-            if (currentToolUse) {
-              // Execute the tool
-              let toolInput: Record<string, unknown> = {};
-              try {
-                toolInput = JSON.parse(currentToolUse.input || "{}");
-              } catch {
-                toolInput = {};
-              }
-
-              const result = await this.executeTool(currentToolUse.name, toolInput);
-              yield { type: "tool_end", tool: currentToolUse.name, result };
-              currentToolUse = null;
-            }
+            // Don't execute tools here - wait for finalMessage to avoid double execution
+            currentToolUse = null;
           }
         }
 
@@ -428,7 +426,7 @@ export class ChatHandler {
         const finalMessage = await stream.finalMessage();
 
         if (finalMessage.stop_reason === "tool_use") {
-          // Process tool results and continue
+          // Process tool results (execute only once, here)
           const toolUseBlocks = finalMessage.content.filter(
             (block): block is Anthropic.ToolUseBlock => block.type === "tool_use"
           );
@@ -436,10 +434,13 @@ export class ChatHandler {
           const toolResults: Anthropic.ToolResultBlockParam[] = [];
           for (const toolUse of toolUseBlocks) {
             const result = await this.executeTool(toolUse.name, toolUse.input as Record<string, unknown>);
+            const isError = typeof result === "object" && result !== null && "error" in result;
+            yield { type: "tool_end", tool: toolUse.name, result };
             toolResults.push({
               type: "tool_result",
               tool_use_id: toolUse.id,
               content: JSON.stringify(result),
+              is_error: isError,
             });
           }
 
@@ -492,7 +493,7 @@ export class ChatHandler {
       }
 
       let response = await this.client.messages.create({
-        model: "claude-haiku-4-5-20241022",
+        model: "claude-opus-4-5-20251101",
         max_tokens: 1024,
         system: SYSTEM_PROMPT,
         tools: TOOLS,
@@ -508,10 +509,12 @@ export class ChatHandler {
         const toolResults: Anthropic.ToolResultBlockParam[] = [];
         for (const toolUse of toolUseBlocks) {
           const result = await this.executeTool(toolUse.name, toolUse.input as Record<string, unknown>);
+          const isError = typeof result === "object" && result !== null && "error" in result;
           toolResults.push({
             type: "tool_result",
             tool_use_id: toolUse.id,
             content: JSON.stringify(result),
+            is_error: isError,
           });
         }
 
@@ -527,7 +530,7 @@ export class ChatHandler {
 
         // Continue the conversation
         response = await this.client.messages.create({
-          model: "claude-haiku-4-5-20241022",
+          model: "claude-opus-4-5-20251101",
           max_tokens: 1024,
           system: SYSTEM_PROMPT,
           tools: TOOLS,
@@ -669,15 +672,15 @@ export class ChatHandler {
         const query = input.query as string;
         const limit = (input.limit as number) || 10;
 
-        const results = await this.search.search(query, { limit });
+        const response = await this.search.search(query, { limit });
         return {
-          results: results.map((r) => ({
+          results: response.results.map((r) => ({
             id: r.memory.id,
             content: r.memory.content.substring(0, 300) + (r.memory.content.length > 300 ? "..." : ""),
             timestamp: r.memory.timestamp.toISOString(),
             score: r.score.toFixed(3),
           })),
-          count: results.length,
+          count: response.results.length,
         };
       }
 

package/src/web/server.ts

@@ -241,9 +241,9 @@ export class EngramWebServer {
       const offset = parseInt(url.searchParams.get("offset") || "0");
 
       if (query) {
-        const results = await this.search.search(query, { limit });
+        const response = await this.search.search(query, { limit });
         res.end(JSON.stringify({
-          memories: results.map(r => ({
+          memories: response.results.map(r => ({
             ...r.memory,
             score: r.score,
             sources: r.sources,