universal-llm-client 4.0.0 → 4.2.0

package/src/client.ts

@@ -0,0 +1,402 @@
+/**
+ * Universal LLM Client v3 — Base LLM Client
+ *
+ * Abstract base class for all LLM providers.
+ * Handles tool registration, execution, and the autonomous
+ * multi-turn tool execution loop.
+ */
+
+import type {
+    LLMClientOptions,
+    LLMChatMessage,
+    LLMChatResponse,
+    LLMToolDefinition,
+    LLMToolCall,
+    LLMFunction,
+    ToolRegistry,
+    ToolHandler,
+    ToolExecutionResult,
+    ChatOptions,
+    ModelMetadata,
+} from './interfaces.js';
+import {
+    StructuredOutputError,
+    type StructuredOutputOptions,
+    type SchemaConfig,
+} from './structured-output.js';
+import type { DecodedEvent } from './stream-decoder.js';
+import type { Auditor } from './auditor.js';
+import { NoopAuditor } from './auditor.js';
+
+// ============================================================================
+// Abstract Base Client
+// ============================================================================
+
+export abstract class BaseLLMClient {
+    protected options: LLMClientOptions;
+    protected toolRegistry: ToolRegistry = {};
+    protected auditor: Auditor;
+    protected debug: boolean;
+
+    constructor(options: LLMClientOptions, auditor?: Auditor) {
+        this.options = options;
+        this.auditor = auditor ?? new NoopAuditor();
+        this.debug = options.debug ?? false;
+    }
+
+    // ========================================================================
+    // Abstract Methods (implemented by providers)
+    // ========================================================================
+
+    /** Send a chat request and get a response */
+    abstract chat(
+        messages: LLMChatMessage[],
+        options?: ChatOptions,
+    ): Promise<LLMChatResponse>;
+
+    /** Stream a chat response as decoded events */
+    abstract chatStream(
+        messages: LLMChatMessage[],
+        options?: ChatOptions,
+    ): AsyncGenerator<DecodedEvent, LLMChatResponse | void, unknown>;
+
+    /** Get available models */
+    abstract getModels(): Promise<string[]>;
+
+    /** Generate embeddings for text */
+    abstract embed(text: string): Promise<number[]>;
+
+    /** Generate embeddings for multiple texts */
+    async embedArray(texts: string[]): Promise<number[][]> {
+        return Promise.all(texts.map(t => this.embed(t)));
+    }
+
+    /**
+     * Get metadata about a model (context length, architecture, etc.)
+     * Override per-provider for accurate data.
+     */
+    async getModelInfo(_modelName?: string): Promise<ModelMetadata> {
+        return { contextLength: 8192 }; // Conservative default
+    }
+
+    // ========================================================================
+    // Tool Registration
+    // ========================================================================
+
+    /**
+     * Sanitize tool name for LLM compatibility.
+     * LLM APIs require function names matching [a-zA-Z0-9_-].
+     * Module-prefixed names like "@core/computer:list_windows" are cleaned.
+     */
+    private sanitizeToolName(name: string): string {
+        return name
+            .replace(/^@[^:]+:/, '')           // Strip module prefix
+            .replace(/[^a-zA-Z0-9_-]/g, '_')   // Replace illegal chars
+            .replace(/_+/g, '_')               // Collapse
+            .replace(/^_|_$/g, '');            // Trim
+    }
+
+    /** Register a tool/function callable by the model */
+    registerTool(
+        name: string,
+        description: string,
+        parameters: LLMFunction['parameters'],
+        handler: ToolHandler,
+    ): void {
+        const safeName = this.sanitizeToolName(name);
+        this.toolRegistry[name] = {
+            definition: { name: safeName, description, parameters },
+            handler,
+        };
+        // Index by sanitized name for reverse lookup
+        if (safeName !== name && !this.toolRegistry[safeName]) {
+            this.toolRegistry[safeName] = this.toolRegistry[name]!;
+        }
+        this.debugLog(`Registered tool: ${name} (LLM name: ${safeName})`);
+    }
+
+    /** Register multiple tools at once */
+    registerTools(
+        tools: Array<{
+            name: string;
+            description: string;
+            parameters: LLMFunction['parameters'];
+            handler: ToolHandler;
+        }>,
+    ): void {
+        for (const tool of tools) {
+            this.registerTool(tool.name, tool.description, tool.parameters, tool.handler);
+        }
+    }
+
+    /** Get all registered tool definitions (deduplicated by sanitized name) */
+    getToolDefinitions(): LLMToolDefinition[] {
+        const seen = new Set<string>();
+        const defs: LLMToolDefinition[] = [];
+        for (const { definition } of Object.values(this.toolRegistry)) {
+            if (seen.has(definition.name)) continue;
+            seen.add(definition.name);
+            defs.push({ type: 'function' as const, function: definition });
+        }
+        return defs;
+    }
+
+    // ========================================================================
+    // Tool Execution
+    // ========================================================================
+
+    /** Execute a single tool call with fuzzy name matching */
+    async executeTool(toolCall: LLMToolCall): Promise<ToolExecutionResult> {
+        const toolName = toolCall.function.name;
+        const start = Date.now();
+        let tool = this.toolRegistry[toolName];
+
+        // Fuzzy lookup: try suffix match (LLM stripped module prefix)
+        if (!tool) {
+            const entries = Object.entries(this.toolRegistry);
+            const bySuffix = entries.find(([k]) => k.endsWith(`:${toolName}`));
+            if (bySuffix) {
+                tool = bySuffix[1];
+                this.debugLog(`Fuzzy tool match: "${toolName}" → "${bySuffix[0]}"`);
+            }
+
+            // Try prefix match: if only one tool in that module, use it
+            if (!tool) {
+                const byPrefix = entries.filter(([k]) => k.startsWith(`${toolName}:`));
+                if (byPrefix.length === 1) {
+                    tool = byPrefix[0]![1];
+                    this.debugLog(`Fuzzy tool match (single): "${toolName}" → "${byPrefix[0]![0]}"`);
+                }
+            }
+        }
+
+        if (!tool) {
+            const result: ToolExecutionResult = {
+                tool_call_id: toolCall.id,
+                output: null,
+                error: `Unknown tool: ${toolName}`,
+                duration: Date.now() - start,
+            };
+            this.auditor.record({
+                timestamp: Date.now(),
+                type: 'tool_result',
+                toolExecution: result,
+                error: result.error,
+            });
+            return result;
+        }
+
+        this.auditor.record({
+            timestamp: Date.now(),
+            type: 'tool_call',
+            metadata: { toolName, arguments: toolCall.function.arguments },
+        });
+
+        try {
+            const args = JSON.parse(toolCall.function.arguments);
+            const output = await tool.handler(args);
+            const result: ToolExecutionResult = {
+                tool_call_id: toolCall.id,
+                output,
+                duration: Date.now() - start,
+            };
+            this.auditor.record({
+                timestamp: Date.now(),
+                type: 'tool_result',
+                toolExecution: result,
+            });
+            return result;
+        } catch (error) {
+            const result: ToolExecutionResult = {
+                tool_call_id: toolCall.id,
+                output: null,
+                error: error instanceof Error ? error.message : String(error),
+                duration: Date.now() - start,
+            };
+            this.auditor.record({
+                timestamp: Date.now(),
+                type: 'tool_result',
+                toolExecution: result,
+                error: result.error,
+            });
+            return result;
+        }
+    }
+
+    /** Execute multiple tool calls in parallel */
+    async executeTools(toolCalls: LLMToolCall[]): Promise<ToolExecutionResult[]> {
+        return Promise.all(toolCalls.map(tc => this.executeTool(tc)));
+    }
+
+    // ========================================================================
+    // Chat with Tools (multi-turn autonomous loop)
+    // ========================================================================
+
+    /**
+     * Chat with automatic tool execution.
+     * Continues until the model stops calling tools or max iterations reached.
+     * Returns the complete execution trace in `toolExecutions`.
+     */
+    async chatWithTools(
+        messages: LLMChatMessage[],
+        options?: ChatOptions & { maxIterations?: number },
+    ): Promise<LLMChatResponse> {
+        const maxIterations = options?.maxIterations ?? 10;
+        const conversationMessages = [...messages];
+        const allToolExecutions: ToolExecutionResult[] = [];
+        let iterations = 0;
+
+        while (iterations < maxIterations) {
+            const response = await this.chat(conversationMessages, {
+                ...options,
+                tools: this.getToolDefinitions(),
+            });
+
+            // If no tool calls, return with full trace
+            if (!response.message.tool_calls?.length) {
+                return {
+                    ...response,
+                    toolExecutions: allToolExecutions.length > 0 ? allToolExecutions : undefined,
+                };
+            }
+
+            // Add assistant message with tool calls
+            conversationMessages.push(response.message);
+
+            // Execute tools in parallel
+            const toolResults = await this.executeTools(response.message.tool_calls);
+            allToolExecutions.push(...toolResults);
+
+            // Add tool results as messages
+            for (const result of toolResults) {
+                conversationMessages.push({
+                    role: 'tool',
+                    content: typeof result.output === 'string'
+                        ? result.output
+                        : JSON.stringify(result.output),
+                    tool_call_id: result.tool_call_id,
+                });
+            }
+
+            iterations++;
+        }
+
+        // Max iterations — final call without tools
+        const finalResponse = await this.chat(conversationMessages);
+        return {
+            ...finalResponse,
+            toolExecutions: allToolExecutions,
+        };
+    }
+
+    // ========================================================================
+    // Helpers
+    // ========================================================================
+
+    /** Set the model name at runtime */
+    setModel(modelName: string): void {
+        this.options.model = modelName;
+        this.debugLog(`Model switched to: ${modelName}`);
+    }
+
+    /** Get the current model name */
+    get model(): string {
+        return this.options.model;
+    }
+
+    /** Get the base URL */
+    get url(): string {
+        return this.options.url;
+    }
+
+    /** Set the auditor instance */
+    setAuditor(auditor: Auditor): void {
+        this.auditor = auditor;
+    }
+
+    protected debugLog(message: string, data?: unknown): void {
+        if (this.debug) {
+            console.log(`[LLM:${this.options.model}] ${message}`, data ?? '');
+        }
+    }
+
+    /**
+     * Generate a unique ID for tool calls when the provider doesn't provide one.
+     */
+    protected generateToolCallId(): string {
+        return `call_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`;
+    }
+
+    // ========================================================================
+    // Structured Output Helpers (shared across all providers)
+    // ========================================================================
+
+    /**
+     * Extract schema options from ChatOptions.
+     * Returns null if no schema is provided.
+     * Returns a SchemaConfig if a schema was found.
+     */
+    protected extractSchemaOptions(options?: ChatOptions): (StructuredOutputOptions<unknown> & { schemaConfig: SchemaConfig<unknown> }) | null {
+        if (!options) return null;
+
+        if (options.schema) {
+            return {
+                schemaConfig: options.schema,
+                name: options.schemaName,
+                description: options.schemaDescription,
+            };
+        }
+
+        if (options.jsonSchema) {
+            // Raw JSON Schema without validation
+            const config: SchemaConfig<unknown> = {
+                jsonSchema: options.jsonSchema,
+            };
+            return {
+                schemaConfig: config,
+                name: options.schemaName,
+                description: options.schemaDescription,
+            };
+        }
+
+        return null;
+    }
+
+    /**
+     * Validate structured response using a SchemaConfig.
+     * Throws StructuredOutputError on failure.
+     */
+    protected validateStructuredResponse(content: string, config: SchemaConfig<unknown>): void {
+        if (!content) {
+            throw new StructuredOutputError(
+                'Empty response from LLM',
+                { rawOutput: content },
+            );
+        }
+
+        let parsed: unknown;
+        try {
+            parsed = JSON.parse(content);
+        } catch (error) {
+            const syntaxError = error instanceof SyntaxError
+                ? error
+                : new SyntaxError(String(error));
+            throw new StructuredOutputError(
+                `Failed to parse JSON: ${syntaxError.message}`,
+                { rawOutput: content, cause: syntaxError },
+            );
+        }
+
+        if (config.validate) {
+            try {
+                config.validate(parsed);
+            } catch (error) {
+                const validationError = error instanceof Error ? error : new Error(String(error));
+                throw new StructuredOutputError(
+                    `Validation failed: ${validationError.message}`,
+                    { rawOutput: content, cause: validationError },
+                );
+            }
+        }
+    }
+}

package/src/debug/debug-google-streaming.ts

@@ -0,0 +1,97 @@
+import {request} from 'undici';
+
+/**
+ * Debug Google streaming by examining raw responses
+ */
+async function debugGoogleStreaming() {
+    console.log('🔍 Debugging Google Generative AI Streaming...\n');
+
+    const apiKey = 'AIzaSyBDbo7iVNEuCcRNTgDIgRrkGpFKisXXnm0';
+    const model = 'gemma-3-4b-it';
+    const endpoint = `https://generativelanguage.googleapis.com/v1beta/models/${model}:streamGenerateContent`;
+
+    // First, let's try the raw Google API call to see what the response looks like
+    const url = new URL(endpoint);
+    url.searchParams.set('key', apiKey);
+
+    const requestBody = {
+        contents: [
+            {
+                role: 'user',
+                parts: [{ text: 'Count from 1 to 3 briefly.' }]
+            }
+        ],
+        generationConfig: {
+            responseMimeType: 'text/plain'
+        }
+    };
+
+    console.log('📡 Making raw request to:', url.toString());
+    console.log('📦 Request body:', JSON.stringify(requestBody, null, 2));
+
+    try {
+        const response = await request(url.toString(), {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Accept': 'text/event-stream',
+            },
+            body: JSON.stringify(requestBody)
+        });
+
+        console.log('📋 Response status:', response.statusCode);
+        console.log('📋 Response headers:', response.headers);
+
+        if (response.statusCode >= 400) {
+            const errorText = await response.body.text();
+            console.error('❌ Error response:', errorText);
+            return;
+        }
+
+        console.log('\n🌊 Raw streaming response:');
+        console.log('---');
+
+        const decoder = new TextDecoder();
+        let chunkCount = 0;
+
+        for await (const chunk of response.body) {
+            chunkCount++;
+            const text = decoder.decode(chunk, { stream: true });
+            console.log(`[Raw Chunk ${chunkCount}]:`, JSON.stringify(text));
+
+            // Parse each line
+            const lines = text.split('\n').filter(line => line.trim());
+            for (const line of lines) {
+                console.log(`[Line]: "${line}"`);
+
+                if (line.startsWith('data: ')) {
+                    const data = line.slice(6);
+                    console.log(`[Data]: "${data}"`);
+
+                    if (data !== '[DONE]') {
+                        try {
+                            const parsed = JSON.parse(data);
+                            console.log('[Parsed JSON]:', JSON.stringify(parsed, null, 2));
+
+                            // Check Google's response structure
+                            if (parsed.candidates?.[0]?.content?.parts?.[0]?.text) {
+                                console.log('[Content]:', parsed.candidates[0].content.parts[0].text);
+                            }
+                        } catch (parseError) {
+                            console.log('[Parse Error]:', parseError);
+                        }
+                    }
+                }
+            }
+        }
+
+        console.log('---');
+        console.log(`✅ Raw test completed with ${chunkCount} chunks`);
+
+    } catch (error) {
+        console.error('❌ Raw test failed:', error);
+    }
+}
+
+// Run the debug test
+debugGoogleStreaming();

package/src/debug/debug-tool-execution.ts

@@ -0,0 +1,86 @@
+/**
+ * Debug tool calling execution
+ */
+
+import { AIModelFactory, ToolBuilder } from './index';
+
+async function debugToolCalling() {
+    console.log('🔍 Debug Tool Calling Execution\n');
+
+    const model = AIModelFactory.createOllamaChatModel('qwen3:8b');
+    
+    // Simple calculator tool
+    const calcTool = ToolBuilder.createTool<{ expression: string }>(
+        'calculator',
+        'Calculate mathematical expressions',
+        {
+            properties: {
+                expression: { type: 'string', description: 'Math expression to evaluate' }
+            },
+            required: ['expression']
+        },
+        (args) => {
+            console.log('🔧 TOOL EXECUTING: calculator with', args);
+            try {
+                const result = Function(`"use strict"; return (${args.expression})`)();
+                return { expression: args.expression, result, answer: `${args.expression} = ${result}` };
+            } catch (error) {
+                return { expression: args.expression, error: 'Invalid expression', result: null };
+            }
+        }
+    );
+
+    model.registerTool(calcTool.name, calcTool.description, calcTool.parameters, calcTool.handler);
+
+    try {
+        await model.ensureReady();
+
+        console.log('📋 Test 1: Manual Tool Call Detection\n');
+        
+        const response1 = await model.chat([
+            { role: 'user', content: 'What is 5 + 3?' }
+        ], {}, { tool_choice: 'auto' });
+
+        console.log('Response content:', response1.content);
+        console.log('Tool calls detected:', response1.tool_calls?.length || 0);
+        
+        if (response1.tool_calls) {
+            console.log('Tool call details:');
+            response1.tool_calls.forEach((call, index) => {
+                console.log(`  ${index + 1}. ${call.function.name}: ${call.function.arguments}`);
+                console.log(`  Raw tool call:`, JSON.stringify(call, null, 2));
+            });
+            
+            // Manual tool execution
+            console.log('\n🔧 Manual Tool Execution:');
+            for (const toolCall of response1.tool_calls) {
+                try {
+                    const args = JSON.parse(toolCall.function.arguments);
+                    console.log('Parsed arguments:', args);
+                    const result = await calcTool.handler(args);
+                    console.log('Tool result:', result);
+                } catch (error) {
+                    console.log('Tool execution error:', error);
+                }
+            }
+        }
+
+        console.log('\n📋 Test 2: Automatic Tool Execution\n');
+        
+        const response2 = await model.chatWithTools([
+            { role: 'user', content: 'Calculate 10 * 7 for me' }
+        ]);
+
+        console.log('Automatic response:', response2.content);
+
+    } catch (error) {
+        console.error('❌ Debug failed:', error);
+    } finally {
+        model.dispose();
+    }
+}
+
+// Run the debug
+if (require.main === module) {
+    debugToolCalling().catch(console.error);
+}