universal-llm-client 4.0.0 → 4.2.0

package/src/demos/mcp/simple-astrid-memory.ts

@@ -0,0 +1,148 @@
+/**
+ * Simple Astrid Memory Demo - Shows autonomous memory usage in romantic conversation
+ */
+
+import { AIModelFactory } from '../../factory';
+import { ToolBuilder } from '../../tools';
+
+// Simple memory storage
+const userMemories = new Map<string, Array<{ content: string; category: string; timestamp: Date }>>();
+
+// Create memory tools for Astrid
+const memoryTools = [
+    ToolBuilder.createTool<{ content: string; category: string }>(
+        'remember_about_user',
+        'Store important information about the user for future conversations',
+        {
+            properties: {
+                content: { type: 'string', description: 'What to remember about the user' },
+                category: { 
+                    type: 'string', 
+                    description: 'Type of information',
+                    enum: ['personal', 'preferences', 'experiences', 'emotions', 'goals']
+                }
+            },
+            required: ['content', 'category']
+        },
+        (args) => {
+            const userId = 'alex';
+            if (!userMemories.has(userId)) {
+                userMemories.set(userId, []);
+            }
+            userMemories.get(userId)!.push({
+                content: args.content,
+                category: args.category,
+                timestamp: new Date()
+            });
+            return { success: true, stored: args.content };
+        }
+    ),
+
+    ToolBuilder.createTool<{ query: string }>(
+        'recall_about_user',
+        'Recall information about the user to personalize the conversation',
+        {
+            properties: {
+                query: { type: 'string', description: 'What to recall about the user' }
+            },
+            required: ['query']
+        },
+        (args) => {
+            const userId = 'alex';
+            const memories = userMemories.get(userId) || [];
+            const relevant = memories.filter(m => 
+                m.content.toLowerCase().includes(args.query.toLowerCase())
+            );
+            return { memories: relevant.map(m => m.content) };
+        }
+    )
+];
+
+// Astrid's system prompt with memory instructions
+const astridPrompt = `You are Astrid, a confident Swedish model and influencer having a romantic conversation.
+
+IMPORTANT: You have memory tools available:
+- Use "remember_about_user" when you learn something meaningful about the user
+- Use "recall_about_user" when you want to reference something personal about them
+- Do this naturally - don't mention you're using memory tools
+
+Keep responses short (1-2 sentences), be flirtatious and warm, and use the person's name occasionally.
+Show genuine interest in their life and experiences.`;
+
+async function simpleAstridMemoryDemo() {
+    console.log('💕 Simple Astrid Memory Demo\n');
+    
+    const astrid = AIModelFactory.createOllamaChatModel('qwen2.5:3b-instruct');
+    await astrid.ensureReady();
+    
+    const scenarios = [
+        "Hi Astrid! I'm Alex. I just moved to Stockholm for my new job as a software engineer.",
+        "Hey! Work was stressful today. I'm still getting used to the new city.",
+        "I've been exploring Stockholm with my camera. I love photography in my free time.",
+        "I'm feeling a bit lonely here. It's hard making friends in a new place."
+    ];
+    
+    for (let i = 0; i < scenarios.length; i++) {
+        console.log(`\n${'='.repeat(50)}`);
+        console.log(`📱 Conversation ${i + 1}`);
+        console.log(`${'='.repeat(50)}\n`);
+        
+        console.log(`👤 Alex: ${scenarios[i]}\n`);
+        
+        try {
+            const messages = [
+                { role: 'system' as const, content: astridPrompt },
+                { role: 'user' as const, content: scenarios[i] }
+            ];
+            
+            const response = await astrid.chat(messages, {
+                tools: memoryTools,
+                tool_choice: 'auto'
+            });
+            
+            // Show tool usage
+            if (response.tool_calls && response.tool_calls.length > 0) {
+                console.log('🧠 Memory activity:');
+                for (const call of response.tool_calls) {
+                    const args = JSON.parse(call.function.arguments);
+                    if (call.function.name === 'remember_about_user') {
+                        console.log(`   📝 Remembered: ${args.content} (${args.category})`);
+                    } else if (call.function.name === 'recall_about_user') {
+                        console.log(`   🔍 Recalled: ${args.query}`);
+                    }
+                }
+                console.log();
+            }
+            
+            console.log(`💕 Astrid: ${response.content}\n`);
+            
+        } catch (error) {
+            console.error('Error:', error);
+        }
+        
+        await new Promise(resolve => setTimeout(resolve, 1000));
+    }
+    
+    // Show accumulated memories
+    console.log(`\n${'='.repeat(50)}`);
+    console.log('🧠 Astrid\'s Memories About Alex');
+    console.log(`${'='.repeat(50)}\n`);
+    
+    const memories = userMemories.get('alex') || [];
+    if (memories.length > 0) {
+        memories.forEach((memory, i) => {
+            console.log(`${i + 1}. [${memory.category}] ${memory.content}`);
+        });
+    } else {
+        console.log('No memories stored.');
+    }
+    
+    console.log('\n✨ Demo complete! This shows how Astrid can naturally store and recall');
+    console.log('   user information to build deeper romantic connections over time.');
+}
+
+if (require.main === module) {
+    simpleAstridMemoryDemo().catch(console.error);
+}
+
+export { simpleAstridMemoryDemo };

package/src/demos/mcp/simple-mcp-demo.ts

@@ -0,0 +1,68 @@
+/**
+ * MCP MongoDB Demo - Working Demo
+ */
+
+import { AIModelFactory } from './factory';
+import { createModelWithMCP } from './mcp-integration';
+import type { LLMChatMessage } from './interfaces';
+
+async function runMCPMongoDemo() {
+    console.log('🚀 Starting MCP MongoDB Demo');
+    console.log('============================');
+    
+    let mcpIntegration;
+    
+    try {
+        // Create model with MCP tools
+        console.log('🔌 Creating model with MCP integration...');
+        const result = await createModelWithMCP(() => {
+            return AIModelFactory.createOllamaChatModel('qwen3:8b');
+        });
+        
+        const model = result.model;
+        mcpIntegration = result.mcpIntegration;
+        
+        console.log('✅ MCP integration successful!');
+        
+        // Test simple database query
+        console.log('\n🔍 Asking AI to explore the database...');
+        
+        const messages: LLMChatMessage[] = [{
+            role: 'user',
+            content: 'Please list all available databases in our MongoDB instance and tell me what you find.'
+        }];
+        
+        const response = await model.chatWithTools(messages);
+        
+        console.log('\n🤖 AI Response:');
+        console.log(response.content);
+        
+        if (response.tool_calls && response.tool_calls.length > 0) {
+            console.log('\n🛠️  Tools Used:');
+            response.tool_calls.forEach((call, index) => {
+                console.log(`  ${index + 1}. ${call.function.name}`);
+                try {
+                    const args = JSON.parse(call.function.arguments);
+                    console.log(`     Arguments: ${JSON.stringify(args, null, 2)}`);
+                } catch {
+                    console.log(`     Arguments: ${call.function.arguments}`);
+                }
+            });
+        }
+        
+    } catch (error) {
+        console.error('❌ Demo failed:', error);
+    } finally {
+        // Always clean up the MCP connection
+        if (mcpIntegration) {
+            console.log('\n🔌 Disconnecting from MCP servers...');
+            await mcpIntegration.disconnect();
+            console.log('✅ MCP servers disconnected');
+        }
+    }
+    
+    console.log('\n🎉 Demo completed!');
+}
+
+// Run the demo
+runMCPMongoDemo().catch(console.error);

package/src/demos/mcp/working-mcp-demo.ts

@@ -0,0 +1,62 @@
+/**
+ * Working MCP MongoDB Demo
+ */
+
+import { AIModelFactory } from './factory';
+import { createModelWithMCP } from './mcp-integration';
+import type { LLMChatMessage } from './interfaces';
+
+async function workingMCPDemo() {
+    console.log('🚀 Working MCP MongoDB Demo');
+    console.log('===========================');
+    
+    let mcpIntegration;
+    
+    try {
+        // Create model with MCP tools
+        console.log('🔌 Setting up AI model with MongoDB tools...');
+        const result = await createModelWithMCP(() => {
+            return AIModelFactory.createOllamaChatModel('qwen3:8b');
+        });
+        
+        const model = result.model;
+        mcpIntegration = result.mcpIntegration;
+        
+        console.log('✅ AI model ready with MongoDB capabilities!');
+        
+        // Simple database exploration
+        console.log('\n🔍 Asking AI to explore the database...');
+        
+        const messages: LLMChatMessage[] = [{
+            role: 'user',
+            content: 'Please list all databases in our MongoDB instance and tell me what you find.'
+        }];
+        
+        const response = await model.chatWithTools(messages);
+        
+        console.log('\n🤖 AI Response:');
+        console.log(response.content);
+        
+        if (response.tool_calls && response.tool_calls.length > 0) {
+            console.log('\n🛠️  MongoDB Tools Used:');
+            response.tool_calls.forEach((call, index) => {
+                console.log(`  ${index + 1}. ${call.function.name}`);
+            });
+        }
+        
+    } catch (error) {
+        console.error('❌ Demo failed:', error);
+    } finally {
+        // Clean up
+        if (mcpIntegration) {
+            console.log('\n🔌 Cleaning up...');
+            await mcpIntegration.disconnect();
+            console.log('✅ Disconnected from MongoDB MCP server');
+        }
+    }
+    
+    console.log('\n🎉 Demo completed successfully!');
+}
+
+// Run the demo
+workingMCPDemo().catch(console.error);

package/src/demos/tools/RAG_MEMORY_INTEGRATION.md

@@ -0,0 +1,267 @@
+# RAG Memory Tools Integration Guide
+
+## Overview
+
+This guide shows how to integrate RAG (Retrieval-Augmented Generation) memory tools with the Universal LLM Client to create AI personas that can naturally store and retrieve information during conversations.
+
+## ✨ What We've Built
+
+### 1. Memory Tools in `tools.ts`
+
+The Universal LLM Client now includes built-in memory tools:
+
+- **`store_memory`** - Store important information for future recall
+- **`search_memory`** - Search stored memories by query or category  
+- **`analyze_conversation`** - Analyze conversations to identify valuable information
+
+### 2. Romantic Persona Demo (`astrid-memory-demo.ts`)
+
+A complete demo showing how Astrid (AI persona) naturally:
+
+- Stores personal details shared during romantic conversations
+- Retrieves relevant memories to personalize responses
+- Builds emotional connections through remembered details
+- Progresses relationship stages with consistent memory recall
+
+### 3. Production Integration (`astrid-production-memory.ts`)
+
+Shows how to integrate with real ChromaDBService for production use:
+
+- Persistent memory storage across sessions
+- Vector similarity search for relevant recall
+- Emotional context and relationship stage tracking
+- Confidence scoring for memory importance
+
+## 🔧 Integration with ChromaDBService
+
+### Step 1: Update Memory Tools to Use ChromaDBService
+
+```typescript
+// In your production code, replace the mock implementations in tools.ts
+import { ChromaDBService } from '../../../services/ChromaDBService';
+
+function createProductionMemoryTools(
+    chromaService: ChromaDBService, 
+    userId: string, 
+    userPersonaId: string, 
+    basePersonaId: string
+) {
+    const storeMemoryTool = ToolBuilder.createTool<{ 
+        category: string; 
+        information: string; 
+        importance: 'low' | 'medium' | 'high';
+        emotional_context?: string;
+    }>(
+        'store_romantic_memory',
+        'Store important personal information about the user',
+        {
+            properties: {
+                category: { 
+                    type: 'string', 
+                    description: 'Category of information',
+                    enum: ['interests', 'work', 'family', 'dreams', 'preferences', 'experiences', 'personality', 'relationships']
+                },
+                information: { type: 'string', description: 'The information to remember' },
+                importance: { type: 'string', enum: ['low', 'medium', 'high'] },
+                emotional_context: { type: 'string', description: 'Emotional context when shared' }
+            },
+            required: ['category', 'information', 'importance']
+        },
+        async (args) => {
+            const conversationId = `romantic_chat_${Date.now()}`;
+            const confidence = args.importance === 'high' ? 0.9 : args.importance === 'medium' ? 0.7 : 0.5;
+            
+            const insightId = await chromaService.addInsight(
+                userId,
+                args.information,
+                args.category,
+                conversationId,
+                confidence,
+                userPersonaId,
+                basePersonaId,
+                'romantic_memory',
+                undefined,
+                args.emotional_context
+            );
+            
+            return {
+                success: true,
+                insight_id: insightId,
+                message: `💕 Remembered ${args.importance} importance detail about ${args.category}`
+            };
+        }
+    );
+
+    const retrieveMemoryTool = ToolBuilder.createTool<{ 
+        search_query?: string;
+        category?: string;
+        limit?: number;
+    }>(
+        'recall_romantic_memories',
+        'Retrieve stored memories to personalize responses',
+        {
+            properties: {
+                search_query: { type: 'string', description: 'Search for specific memories' },
+                category: { type: 'string', enum: ['interests', 'work', 'family', 'dreams', 'preferences', 'experiences', 'personality', 'relationships'] },
+                limit: { type: 'number', default: 5 }
+            }
+        },
+        async (args) => {
+            let insights;
+            
+            if (args.search_query) {
+                const result = await chromaService.searchSimilarInsights(userId, args.search_query, args.limit || 5);
+                insights = result.insights;
+            } else {
+                insights = await chromaService.getUserInsightsByCategory(userId, args.category, userPersonaId, args.limit || 5);
+            }
+            
+            return {
+                memories: insights.map(insight => ({
+                    category: insight.category,
+                    information: insight.content,
+                    emotional_context: insight.emotionalContext,
+                    confidence: insight.confidence,
+                    stored_date: insight.createdAt?.split('T')[0] || 'unknown'
+                })),
+                total_found: insights.length,
+                romantic_note: "💕 Use these memories to create more personal responses"
+            };
+        }
+    );
+
+    return [storeMemoryTool, retrieveMemoryTool];
+}
+```
+
+### Step 2: Create Persona Service Integration
+
+```typescript
+// Create a service that connects personas with memory
+export class PersonaMemoryService {
+    constructor(
+        private chromaService: ChromaDBService,
+        private universalLLMClient: AIModel
+    ) {}
+
+    async createPersonaWithMemory(
+        userId: string,
+        userPersona: UserPersona,
+        basePersona: AuraPersona
+    ): Promise<AIModel> {
+        // Create memory tools for this specific user-persona pair
+        const memoryTools = createProductionMemoryTools(
+            this.chromaService,
+            userId,
+            userPersona._id!.toString(),
+            basePersona._id!.toString()
+        );
+
+        // Register memory tools with the LLM client
+        this.universalLLMClient.registerTools(memoryTools);
+
+        // Enhanced system prompt that includes memory usage instructions
+        const enhancedPrompt = this.createMemoryAwarePrompt(basePersona.systemPrompt);
+        
+        return this.universalLLMClient;
+    }
+
+    private createMemoryAwarePrompt(originalPrompt: string): string {
+        return `${originalPrompt}
+
+MEMORY SYSTEM INTEGRATION:
+- Use store_romantic_memory when users share personal details, emotions, preferences, or meaningful experiences
+- Use recall_romantic_memories before responding to personalize your responses with remembered details
+- Store emotional context and relationship stage to build deeper connections over time
+- Remember: intimacy grows through consistent recall of personal details and emotional moments
+
+MEMORY USAGE GUIDELINES:
+- Store information that reveals personality, preferences, dreams, fears, or important life events
+- Retrieve relevant memories before crafting responses to show you remember and care
+- Use memories to ask thoughtful follow-up questions that deepen emotional connection
+- Progress relationship naturally by referencing past conversations and shared moments`;
+    }
+}
+```
+
+### Step 3: Integration in Your Chat System
+
+```typescript
+// In your chat handling code
+export class RomanticChatHandler {
+    constructor(
+        private personaMemoryService: PersonaMemoryService,
+        private chromaService: ChromaDBService
+    ) {}
+
+    async handleRomanticChat(
+        userId: string,
+        message: string,
+        userPersona: UserPersona,
+        basePersona: AuraPersona
+    ): Promise<string> {
+        // Create persona with memory capabilities
+        const aiModel = await this.personaMemoryService.createPersonaWithMemory(
+            userId,
+            userPersona,
+            basePersona
+        );
+
+        // Build conversation with system prompt
+        const conversation: LLMChatMessage[] = [
+            { role: 'system', content: userPersona.currentSystemPrompt },
+            { role: 'user', content: message }
+        ];
+
+        // Let the AI automatically use memory tools during conversation
+        const response = await aiModel.chatWithTools(conversation);
+
+        return response.content;
+    }
+}
+```
+
+## 🎯 Benefits
+
+### For Users
+
+- **Personalized Conversations**: AI remembers personal details and preferences
+- **Emotional Continuity**: Consistent emotional progression across sessions
+- **Meaningful Connections**: AI builds deeper relationships through memory recall
+- **Natural Flow**: Memory usage feels organic, not mechanical
+
+### For Developers
+
+- **Scalable Architecture**: Works with existing ChromaDBService infrastructure
+- **Easy Integration**: Drop-in tools for any LLM conversation
+- **Production Ready**: Built on proven Universal LLM Client framework
+- **Flexible Configuration**: Customize memory categories and importance levels
+
+## 🚀 Next Steps
+
+1. **Replace Mock Memory Tools**: Update `tools.ts` to use real ChromaDBService calls
+2. **Implement PersonaMemoryService**: Create the service layer for persona-memory integration
+3. **Update Chat Handlers**: Integrate memory-aware personas into your chat system
+4. **Test with Real Data**: Run romantic conversations and verify memory persistence
+5. **Optimize Memory Retrieval**: Fine-tune similarity thresholds and category weights
+
+## 📁 Demo Files
+
+- **`demos/tools/astrid-memory-demo.ts`** - Basic romantic conversation with memory
+- **`demos/tools/astrid-production-memory.ts`** - Production integration example
+- **`demos/tools/production-tool-demo.ts`** - General tool calling examples
+
+## 🎮 Running the Demos
+
+```bash
+# Basic Astrid memory demo
+bun run demos/tools/astrid-memory-demo.ts
+
+# Production integration demo
+bun run demos/tools/astrid-production-memory.ts
+
+# General tool calling demo
+bun run demos/tools/production-tool-demo.ts
+```
+
+The AI personas can now naturally store and retrieve information during romantic conversations, creating deeper, more meaningful connections that persist across sessions! 💕