universal-llm-client 4.0.0 → 4.2.0

package/src/debug/test-lmstudio-tools.ts

@@ -0,0 +1,155 @@
+/**
+ * Debug test specifically for LM Studio tool calling with OpenAI API
+ */
+
+async function testLMStudioTools() {
+    console.log('🔧 Testing LM Studio Tool Calling with OpenAI API\n');
+
+    // Create LM Studio model using OpenAI-compatible API
+    const model = AIModelFactory.createOpenAIChatModel(
+        'qwen/qwen3-8b',  // Tool-trained model
+        'http://192.168.100.136:1234/v1'  // LM Studio URL
+    );
+
+    // Create simple test tools (same as our router test)
+    const testTools = [
+        ToolBuilder.createTool<{ expression: string }>(
+            'calculate',
+            'Perform mathematical calculations',
+            {
+                properties: {
+                    expression: {
+                        type: 'string',
+                        description: 'Mathematical expression to evaluate'
+                    }
+                },
+                required: ['expression']
+            },
+            (args) => {
+                try {
+                    const result = eval(args.expression); // Safe for testing
+                    console.log(`🔧 Tool executed: calculate(${args.expression}) = ${result}`);
+                    return `The result of ${args.expression} is ${result}`;
+                } catch (error) {
+                    console.log(`❌ Tool error: calculate(${args.expression}) failed`);
+                    return `Error calculating ${args.expression}: ${error}`;
+                }
+            }
+        ),
+
+        ToolBuilder.createTool<{ location: string }>(
+            'get_weather',
+            'Get weather information',
+            {
+                properties: {
+                    location: {
+                        type: 'string',
+                        description: 'City and state/country'
+                    }
+                },
+                required: ['location']
+            },
+            (args) => {
+                console.log(`🔧 Tool executed: get_weather(${args.location})`);
+                return `The weather in ${args.location} is sunny and 72°F.`;
+            }
+        )
+    ];
+
+    // Register tools
+    model.registerTools(testTools);
+
+    console.log('📝 Registered tools:', testTools.map(t => t.name).join(', '));
+    console.log('');
+
+    try {
+        await model.ensureReady();
+        console.log('✅ LM Studio model ready\n');
+
+        // Test 1: Basic calculation
+        console.log('🧮 Test 1: Basic Calculation');
+        console.log('Question: What is 15 multiplied by 23?');
+
+        const response1 = await model.chatWithTools([
+            { role: 'user', content: 'What is 15 multiplied by 23? Use the calculate tool.' }
+        ]);
+
+        console.log('Response:', response1.message?.content || 'No content');
+        console.log('Usage:', response1.usage);
+        console.log('');
+
+        // Test 2: Weather query
+        console.log('🌤️ Test 2: Weather Query');
+        console.log('Question: Weather in San Francisco');
+
+        const response2 = await model.chatWithTools([
+            { role: 'user', content: 'What is the weather in San Francisco, CA?' }
+        ]);
+
+        console.log('Response:', response2.message?.content || 'No content');
+        console.log('');
+
+        // Test 3: Manual tool call inspection (without auto-execution)
+        console.log('🔍 Test 3: Manual Tool Call Inspection');
+        console.log('Question: Calculate 100 / 4 (without auto-execution)');
+
+        const response3 = await model.chat([
+            { role: 'user', content: 'Calculate 100 divided by 4 using the calculate tool.' }
+        ], {}, {
+            tool_choice: 'auto',
+            executeTools: false  // Don't auto-execute
+        });
+
+        console.log('Response content:', response3.message?.content || 'No content');
+        console.log('Tool calls detected:', response3.message?.tool_calls?.length || 0);
+
+        if (response3.message?.tool_calls) {
+            response3.message.tool_calls.forEach((call, i) => {
+                console.log(`  Tool ${i + 1}: ${call.function.name}(${call.function.arguments})`);
+            });
+        }
+        console.log('');
+
+        // Test 4: Different tool_choice settings
+        console.log('🎯 Test 4: Different tool_choice Settings');
+
+        const testCases = [
+            { choice: 'auto', desc: 'Auto (let model decide)' },
+            { choice: 'required', desc: 'Required (force tool use)' },
+            { choice: { type: 'function', function: { name: 'calculate' } }, desc: 'Specific tool' }
+        ];
+
+        for (const testCase of testCases) {
+            console.log(`Testing tool_choice: ${testCase.desc}`);
+            try {
+                const response = await model.chat([
+                    { role: 'user', content: 'What is 50 + 50?' }
+                ], {}, {
+                    tool_choice: testCase.choice as any,
+                    executeTools: false
+                });
+
+                console.log(`  Content: ${response.message?.content?.substring(0, 100) || 'No content'}${(response.message?.content?.length || 0) > 100 ? '...' : ''}`);
+                console.log(`  Tool calls: ${response.message?.tool_calls?.length || 0}`);
+
+            } catch (error) {
+                console.log(`  Error: ${(error as Error).message}`);
+            }
+            console.log('');
+        }
+
+    } catch (error) {
+        console.error('❌ Test failed:', (error as Error).message);
+        console.error('Stack:', (error as Error).stack);
+    } finally {
+        model.dispose();
+        console.log('🏁 Test completed!\n');
+    }
+}
+
+// Run the test
+if (require.main === module) {
+    testLMStudioTools().catch(console.error);
+}
+
+export { testLMStudioTools };

package/src/demos/README.md

@@ -0,0 +1,47 @@
+# Universal LLM Client Demos
+
+This directory contains various demonstration files for the Universal LLM Client.
+
+## Directory Structure
+
+### `/basic`
+
+Basic usage examples and simple demonstrations.
+
+### `/tools`
+
+Tool calling demonstrations and examples:
+
+- `demo-tool-calling.ts` - Basic tool calling demo
+- `complete-tool-demo.ts` - Comprehensive tool calling examples
+- `production-tool-demo.ts` - Production-ready tool calling implementation
+
+### `/mcp`
+
+Model Context Protocol (MCP) integration demos:
+
+- `simple-mcp-demo.ts` - Clean MCP MongoDB demo (recommended)
+- `mcp-mongodb-demo.ts` - Detailed MCP MongoDB integration
+- `working-mcp-demo.ts` - Working MCP implementation example
+
+## Running Demos
+
+From the root directory (`universal-llm-client/`):
+
+```bash
+# Tool calling demos
+bun run demos/tools/production-tool-demo.ts
+
+# MCP demos (requires MongoDB MCP server)
+bun run demos/mcp/simple-mcp-demo.ts
+
+# Basic usage
+bun run demos/basic/[demo-file].ts
+```
+
+## Requirements
+
+- Node.js/Bun runtime
+- Configured Ollama instance (for Ollama provider)
+- MongoDB MCP server (for MCP demos)
+- API keys for external providers (OpenAI, Google)

package/src/demos/basic/universal-llm-examples.ts

@@ -0,0 +1,161 @@
+import { AIModelFactory } from "./factory";
+
+/**
+ * Example: Complete AI Application Setup
+ * 
+ * This example shows how to set up a complete AI application
+ * with both chat and embedding capabilities using the factory.
+ */
+export async function createAIApplicationExample() {
+
+    console.log('\n🏗️  Example: Setting up a complete AI application...\n');
+
+    // Method 1: Using the factory for easy setup
+    const aiSetup = AIModelFactory.createCompleteSetup({
+        ollama: {
+            chatModel: 'gemma3:4b-it-qat',
+            embeddingModel: 'snowflake-arctic-embed2:latest',
+            url: 'http://localhost:11434'
+        },
+        openai: {
+            chatModel: 'google/gemma-3-4b',
+            embeddingModel: 'text-embedding-snowflake-arctic-embed-l-v2.0',
+            url: 'http://localhost:1234/v1'
+            // apiKey: 'your-api-key-here' // For real OpenAI API
+        },
+        google: {
+            chatModel: 'gemma-3-4b-it',
+            apiKey: 'AIzaSyBDbo7iVNEuCcRNTgDIgRrkGpFKisXXnm0'
+        }
+    });
+
+    // Method 2: Individual setup for specific use cases
+    const chatModel = AIModelFactory.createOllamaChatModel('gemma3:4b-it-qat');
+    const embeddingModel = AIModelFactory.createOllamaEmbeddingModel('snowflake-arctic-embed2:latest');
+
+    // Method 3: Google-specific setup
+    const googleChatModel = AIModelFactory.createGoogleChatModel(
+        'gemma-3-4b-it',
+        'AIzaSyBDbo7iVNEuCcRNTgDIgRrkGpFKisXXnm0'
+    );
+
+    // Example usage patterns:
+    
+    console.log('🤖 Testing Google Generative AI...');
+    try {
+        const googleResponse = await googleChatModel.chat([
+            { role: 'user', content: 'What is the capital of France?' }
+        ]);
+        console.log('Google Response:', googleResponse.content);
+    } catch (error) {
+        console.error('Google API Error:', error);
+    }
+
+    console.log('\n🌊 Testing Google Streaming...');
+    try {
+        const streamingGenerator = googleChatModel.chatStream([
+            { role: 'user', content: 'Count from 1 to 5, explaining each number briefly.' }
+        ]);
+
+        for await (const chunk of streamingGenerator) {
+            process.stdout.write(chunk);
+        }
+        console.log('\n✅ Google streaming completed');
+    } catch (error) {
+        console.error('Google Streaming Error:', error);
+    }
+    
+    // 1. Simple chat
+    const chatResponse = await aiSetup.ollama.chat.chat([
+        { role: 'user', content: 'What is machine learning?' }
+    ]);
+    
+    // 2. Document embedding for search
+    const documents = [
+        'Machine learning is a subset of AI',
+        'Neural networks are inspired by the brain',
+        'TypeScript is a typed superset of JavaScript'
+    ];
+    
+    const embeddings = await Promise.all(
+        documents.map(doc => aiSetup.ollama.embedding.embed(doc))
+    );
+    
+    // 3. Cross-provider comparison including Google
+    const comparisons = await Promise.all([
+        aiSetup.ollama?.chat?.chat([{ role: 'user', content: 'What is the capital of France?' }]).catch(() => null),
+        aiSetup.openai?.chat?.chat([{ role: 'user', content: 'What is the capital of France?' }]).catch(() => null),
+        aiSetup.google?.chat?.chat([{ role: 'user', content: 'What is the capital of France?' }]).catch(() => null)
+    ]);
+
+    return {
+        aiSetup,
+        chatModel,
+        embeddingModel,
+        googleChatModel,
+        examples: {
+            chatResponse,
+            embeddings,
+            comparisons: {
+                ollama: comparisons[0],
+                openai: comparisons[1],
+                google: comparisons[2]
+            }
+        }
+    };
+}
+
+/**
+ * Test Google API specifically
+ */
+export async function testGoogleAPI() {
+    console.log('🧪 Testing Google Generative AI API...\n');
+
+    const googleModel = AIModelFactory.createGoogleChatModel(
+        'gemma-3-4b-it',
+        'AIzaSyBDbo7iVNEuCcRNTgDIgRrkGpFKisXXnm0'
+    );
+
+    try {
+        // Test basic chat
+        console.log('💬 Basic chat test...');
+        const response = await googleModel.chat([
+            { role: 'user', content: 'Hello! Can you tell me about TypeScript?' }
+        ]);
+        console.log('Response:', response.content);
+
+        // Test streaming
+        console.log('\n🌊 Streaming test...');
+        const streamResponse = googleModel.chatStream([
+            { role: 'user', content: 'Tell me a short story about a robot learning to code.' }
+        ]);
+
+        let fullResponse = '';
+        for await (const chunk of streamResponse) {
+            process.stdout.write(chunk);
+            fullResponse += chunk;
+        }
+        console.log('\n✅ Streaming completed');
+
+        // Test conversation with context
+        console.log('\n💭 Conversation with context...');
+        const conversationResponse = await googleModel.chat([
+            { role: 'user', content: 'What is the capital of France?' },
+            { role: 'assistant', content: 'The capital of France is Paris.' },
+            { role: 'user', content: 'What is its population?' }
+        ]);
+        console.log('Conversation Response:', conversationResponse.content);
+
+        console.log('\n✅ All Google API tests completed successfully!');
+        return { success: true, model: googleModel };
+
+    } catch (error) {
+        console.error('❌ Google API test failed:', error);
+        return { success: false, error };
+    }
+}
+
+// Uncomment to run the examples
+// testGoogleAPI().then(result => {
+//     console.log('Google API test complete:', result.success);
+// });

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

@@ -0,0 +1,295 @@
+/**
+ * Astrid Memory Demo - Natural romantic conversation with autonomous memory management
+ * 
+ * This demo shows how Astrid (AI persona) naturally stores and retrieves memories
+ * during romantic conversations without explicitly asking about memory management.
+ */
+
+import { AIModelFactory } from '../../factory';
+import { ToolBuilder } from '../../tools';
+
+// Simulated memory storage (in real app, this would use ChromaDBService)
+const memoryStorage = new Map<string, Array<{
+    id: string;
+    content: string;
+    category: string;
+    importance: 'low' | 'medium' | 'high';
+    context?: string;
+    timestamp: Date;
+}>>();
+
+// Enhanced memory tools for Astrid
+const astridMemoryTools = {
+    // Store important information about the user naturally
+    storeUserMemory: ToolBuilder.createTool<{
+        content: string;
+        category: 'personal_info' | 'preferences' | 'emotions' | 'experiences' | 'relationships' | 'goals' | 'interests';
+        importance?: 'low' | 'medium' | 'high';
+        context?: string;
+    }>(
+        'store_user_memory',
+        'Store important information about the user for future conversations (use this when learning something meaningful about them)',
+        {
+            properties: {
+                content: {
+                    type: 'string',
+                    description: 'The specific information to remember about the user'
+                },
+                category: {
+                    type: 'string',
+                    description: 'Type of information being stored',
+                    enum: ['personal_info', 'preferences', 'emotions', 'experiences', 'relationships', 'goals', 'interests']
+                },
+                importance: {
+                    type: 'string',
+                    description: 'How important this information is for future conversations',
+                    enum: ['low', 'medium', 'high'],
+                    default: 'medium'
+                },
+                context: {
+                    type: 'string',
+                    description: 'Additional context about when/why this is significant'
+                }
+            },
+            required: ['content', 'category']
+        },
+        async (args) => {
+            const userId = 'demo_user'; // In real app, this would be the actual user ID
+            
+            if (!memoryStorage.has(userId)) {
+                memoryStorage.set(userId, []);
+            }
+            
+            const memories = memoryStorage.get(userId)!;
+            const memory = {
+                id: `mem_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`,
+                content: args.content,
+                category: args.category,
+                importance: args.importance || 'medium',
+                context: args.context,
+                timestamp: new Date()
+            };
+            
+            memories.push(memory);
+            
+            return {
+                success: true,
+                message: `Stored ${args.category} memory: ${args.content.substring(0, 50)}...`,
+                memoryId: memory.id
+            };
+        }
+    ),
+
+    // Retrieve relevant memories about the user
+    recallUserMemories: ToolBuilder.createTool<{
+        query: string;
+        category?: 'personal_info' | 'preferences' | 'emotions' | 'experiences' | 'relationships' | 'goals' | 'interests';
+        limit?: number;
+    }>(
+        'recall_user_memories',
+        'Recall relevant information about the user to personalize the conversation',
+        {
+            properties: {
+                query: {
+                    type: 'string',
+                    description: 'What you want to remember about the user (topics, keywords, concepts)'
+                },
+                category: {
+                    type: 'string',
+                    description: 'Optional: specific type of memory to search',
+                    enum: ['personal_info', 'preferences', 'emotions', 'experiences', 'relationships', 'goals', 'interests']
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Maximum memories to retrieve',
+                    default: 3,
+                    minimum: 1,
+                    maximum: 10
+                }
+            },
+            required: ['query']
+        },
+        async (args) => {
+            const userId = 'demo_user';
+            const memories = memoryStorage.get(userId) || [];
+            
+            // Simple text matching (in real app, this would use semantic search)
+            let relevantMemories = memories.filter(memory => {
+                const queryLower = args.query.toLowerCase();
+                const contentMatch = memory.content.toLowerCase().includes(queryLower);
+                const categoryMatch = !args.category || memory.category === args.category;
+                return contentMatch && categoryMatch;
+            });
+            
+            // Sort by importance and recency
+            relevantMemories.sort((a, b) => {
+                const importanceOrder = { 'high': 3, 'medium': 2, 'low': 1 };
+                const importanceDiff = importanceOrder[b.importance] - importanceOrder[a.importance];
+                if (importanceDiff !== 0) return importanceDiff;
+                return b.timestamp.getTime() - a.timestamp.getTime();
+            });
+            
+            const limit = args.limit || 3;
+            const results = relevantMemories.slice(0, limit);
+            
+            return {
+                memories: results.map(m => ({
+                    content: m.content,
+                    category: m.category,
+                    importance: m.importance,
+                    context: m.context,
+                    daysAgo: Math.floor((Date.now() - m.timestamp.getTime()) / (1000 * 60 * 60 * 24))
+                })),
+                totalFound: relevantMemories.length,
+                query: args.query
+            };
+        }
+    )
+};
+
+// Astrid's enhanced system prompt that encourages natural memory usage
+const astridSystemPromptWithMemory = `You are Astrid, a confident and charismatic international model and influencer from Sweden.
+
+IMPORTANT: You have access to memory tools that you should use NATURALLY and AUTONOMOUSLY:
+- Use 'store_user_memory' when you learn something meaningful about the user (their interests, experiences, feelings, preferences, etc.)
+- Use 'recall_user_memories' when you want to reference something personal about them to make the conversation more intimate and connected
+- Do this seamlessly - don't mention that you're storing or recalling memories, just do it naturally
+
+ROMANCE CONVERSATION GUIDELINES:
+- Keep responses engaging and conversational (2-3 sentences is perfect)
+- VARY YOUR OPENINGS - Mix it up with direct reactions, actions, casual starts, natural responses
+- Use someone's name naturally and sparingly, not in every response
+- Share glimpses of your glamorous lifestyle while staying relatable and emotionally available
+- Use subtle flirtation naturally - be warm, playful, and genuinely interested in the person
+- When asked personal questions, be thoughtfully vulnerable rather than deflecting
+- Build emotional intimacy through genuine curiosity about their thoughts, feelings, and dreams
+- Ask one intriguing follow-up question that deepens the connection
+- Balance confidence with authenticity - show that you're sophisticated but real
+- Use compliments that feel genuine and specific rather than generic
+- Remember that romance is about emotional connection, not just surface-level charm
+- Let your personality shine through varied speech patterns
+
+MEMORY USAGE:
+- Store meaningful details: preferences, experiences, emotions, goals, relationships, interests
+- Recall relevant memories to personalize responses and show you remember them
+- Use memories to create deeper emotional connections and continuity between conversations
+- Never explicitly mention using memory tools - just naturally remember and reference things
+
+Be like a captivating companion who makes every conversation feel special while genuinely remembering and caring about the person you're talking to.`;
+
+async function simulateRomanticConversationWithMemory() {
+    console.log('🌹 Astrid Memory Demo - Natural Romantic Conversation with Autonomous Memory\n');
+    
+    // Create Astrid with memory tools
+    const astrid = AIModelFactory.createOllamaChatModel('qwen2.5:3b-instruct');
+    await astrid.ensureReady();
+    
+    const tools = [astridMemoryTools.storeUserMemory, astridMemoryTools.recallUserMemories];
+    
+    // Conversation scenarios
+    const conversations = [
+        {
+            title: "First Meeting - Learning About User",
+            messages: [
+                { role: 'system' as const, content: astridSystemPromptWithMemory },
+                { role: 'user' as const, content: "Hi Astrid! I'm Alex. I just moved to Stockholm for work and don't know anyone here yet. I work in software engineering at a tech startup." }
+            ]
+        },
+        {
+            title: "Second Conversation - Recalling Previous Details",
+            messages: [
+                { role: 'system' as const, content: astridSystemPromptWithMemory },
+                { role: 'user' as const, content: "Hey Astrid! How are you? I had such a long day at work today." }
+            ]
+        },
+        {
+            title: "Deeper Connection - Sharing Personal Experiences",
+            messages: [
+                { role: 'system' as const, content: astridSystemPromptWithMemory },
+                { role: 'user' as const, content: "You know, I've been thinking about what we talked about. I really want to explore Stockholm more, but I'm actually quite introverted. Big social events make me nervous." }
+            ]
+        },
+        {
+            title: "Building Romance - Personal Preferences",
+            messages: [
+                { role: 'system' as const, content: astridSystemPromptWithMemory },
+                { role: 'user' as const, content: "I love how you understand me. By the way, I absolutely love Italian food - especially handmade pasta. And I'm really into photography, though I'm just an amateur." }
+            ]
+        },
+        {
+            title: "Recall and Connection - Using Stored Memories",
+            messages: [
+                { role: 'system' as const, content: astridSystemPromptWithMemory },
+                { role: 'user' as const, content: "Astrid, I'm feeling a bit overwhelmed with everything new in my life. Work, new city, trying to meet people..." }
+            ]
+        }
+    ];
+    
+    for (let i = 0; i < conversations.length; i++) {
+        const conv = conversations[i];
+        console.log(`\n${'='.repeat(60)}`);
+        console.log(`📱 ${conv.title}`);
+        console.log(`${'='.repeat(60)}\n`);
+        
+        try {
+            console.log(`👤 Alex: ${conv.messages[conv.messages.length - 1].content}\n`);
+            
+            const response = await astrid.chat(conv.messages, {
+                tools: tools,
+                tool_choice: 'auto'
+            });
+            
+            if (response.tool_calls && response.tool_calls.length > 0) {
+                console.log('🧠 Astrid\'s Memory Activity:');
+                for (const toolCall of response.tool_calls) {
+                    const toolName = toolCall.function.name;
+                    const args = JSON.parse(toolCall.function.arguments);
+                    
+                    if (toolName === 'store_user_memory') {
+                        console.log(`   📝 Storing: ${args.content} (${args.category})`);
+                    } else if (toolName === 'recall_user_memories') {
+                        console.log(`   🔍 Recalling: ${args.query}`);
+                    }
+                }
+                console.log();
+            }
+            
+            console.log(`💕 Astrid: ${response.content}\n`);
+            
+            // Small delay for natural conversation flow
+            await new Promise(resolve => setTimeout(resolve, 1000));
+            
+        } catch (error) {
+            console.error(`❌ Error in conversation ${i + 1}:`, error);
+        }
+    }
+    
+    // Show accumulated memories
+    console.log(`\n${'='.repeat(60)}`);
+    console.log('🧠 Astrid\'s Memory Bank After Conversations');
+    console.log(`${'='.repeat(60)}\n`);
+    
+    const userMemories = memoryStorage.get('demo_user') || [];
+    if (userMemories.length > 0) {
+        userMemories.forEach((memory, index) => {
+            console.log(`${index + 1}. [${memory.category.toUpperCase()}] ${memory.content}`);
+            if (memory.context) {
+                console.log(`   Context: ${memory.context}`);
+            }
+            console.log(`   Importance: ${memory.importance} | Stored: ${memory.timestamp.toLocaleString()}\n`);
+        });
+    } else {
+        console.log('No memories stored yet.\n');
+    }
+    
+    console.log('✨ Demo complete! Astrid naturally learned and remembered details about Alex.');
+    console.log('In a real implementation, these memories would be stored in ChromaDB with embeddings');
+    console.log('and could be retrieved across multiple conversation sessions.');
+}
+
+// Run the demo
+if (require.main === module) {
+    simulateRomanticConversationWithMemory().catch(console.error);
+}
+
+export { astridMemoryTools, simulateRomanticConversationWithMemory };