agentic-ai-framework 1.0.0

package/src/llm/BaseLLMProvider.js

@@ -0,0 +1,78 @@
+/**
+ * Abstract base class defining the interface all LLM providers must implement.
+ *
+ * Message format (OpenAI-style) — all providers receive and return messages in this format:
+ *
+ *   System:    { role: 'system',    content: string }
+ *   User:      { role: 'user',      content: string }
+ *   Assistant: { role: 'assistant', content: string | null, tool_calls?: ToolCall[] }
+ *   Tool:      { role: 'tool',      tool_call_id: string, name: string, content: string }
+ *
+ * Providers that use a different native format (e.g., Anthropic) must convert
+ * internally before making API calls and convert back before returning.
+ *
+ * @typedef {Object} ToolCall
+ * @property {string} id         - Provider-assigned tool call ID
+ * @property {string} name       - Tool name
+ * @property {Object} arguments  - Parsed arguments object
+ *
+ * @typedef {Object} CompletionResponse
+ * @property {string}          content      - Text content of the response
+ * @property {Object|null}     parsed       - Parsed JSON (when schema mode used)
+ * @property {Object}          usage        - { promptTokens, completionTokens, totalTokens }
+ * @property {string}          model        - Model ID that produced the response
+ * @property {string}          finishReason - 'stop', 'tool_calls', 'length', etc.
+ * @property {ToolCall[]|undefined} toolCalls  - Present when LLM requests tool execution
+ * @property {Array|undefined} messages     - Updated message array for loop continuation
+ */
+export class BaseLLMProvider {
+    /**
+     * Generate a completion.
+     *
+     * @param {string} prompt         - User prompt (ignored when options.messages is set)
+     * @param {Object} [options={}]
+     * @param {string}  [options.systemPrompt]   - System prompt text
+     * @param {Array}   [options.messages]        - Full message array (takes precedence)
+     * @param {number}  [options.temperature]
+     * @param {number}  [options.maxTokens]
+     * @param {boolean} [options.enableTools]
+     * @param {Array}   [options.tools]           - Tool definitions [{name, description, parameters}]
+     * @param {boolean} [options.jsonMode]
+     * @returns {Promise<CompletionResponse>}
+     */
+    async complete(prompt, options = {}) {
+        throw new Error(`${this.constructor.name}.complete() is not implemented`);
+    }
+
+    /**
+     * Generate a completion with a JSON schema for structured output.
+     * The provider must parse the response as JSON and validate required fields.
+     *
+     * @param {string} prompt
+     * @param {Object} schema   - JSON Schema { type, properties, required }
+     * @param {Object} [options={}]
+     * @returns {Promise<CompletionResponse>}
+     */
+    async completeWithSchema(prompt, schema, options = {}) {
+        throw new Error(`${this.constructor.name}.completeWithSchema() is not implemented`);
+    }
+
+    /**
+     * Test connectivity to the provider API.
+     * @returns {Promise<boolean>}
+     */
+    async testConnection() {
+        throw new Error(`${this.constructor.name}.testConnection() is not implemented`);
+    }
+
+    /**
+     * Return provider metadata.
+     * @returns {{ provider: string, model: string }}
+     */
+    getInfo() {
+        return {
+            provider: this.constructor.name,
+            model: this.model ?? 'unknown',
+        };
+    }
+}

package/src/llm/LLMRouter.js

@@ -0,0 +1,80 @@
+import { createHash } from 'crypto';
+import { GrokProvider } from './providers/GrokProvider.js';
+import { ClaudeProvider } from './providers/ClaudeProvider.js';
+import { OpenAIProvider } from './providers/OpenAIProvider.js';
+import { LLMError } from '../utils/errors.js';
+
+// Built-in provider registry
+const REGISTRY = new Map([
+    ['grok',   GrokProvider],
+    ['claude', ClaudeProvider],
+    ['openai', OpenAIProvider],
+]);
+
+// Instance cache: "providerName:model:apiKeyHash" → provider instance
+const _cache = new Map();
+
+/**
+ * Creates and caches LLM provider instances by name, model, and API key.
+ *
+ * Usage:
+ *   const llm = LLMRouter.get('grok', 'grok-code-fast-1', process.env.GROK_API_KEY);
+ *   const llm = LLMRouter.get('claude', null, process.env.ANTHROPIC_API_KEY); // uses default model
+ */
+export class LLMRouter {
+    /**
+     * Get a cached provider instance.
+     * The cache key includes a hash of the API key so different keys produce separate instances.
+     *
+     * @param {string} providerName - 'grok' | 'claude' | 'openai' | custom registered name
+     * @param {string | null} model - Model ID (null = provider default)
+     * @param {string} apiKey       - API key for the provider
+     * @returns {import('./BaseLLMProvider.js').BaseLLMProvider}
+     */
+    static get(providerName, model, apiKey) {
+        const keyHash = createHash('sha256').update(apiKey).digest('hex').slice(0, 8);
+        const cacheKey = `${providerName}:${model ?? 'default'}:${keyHash}`;
+
+        if (!_cache.has(cacheKey)) {
+            const ProviderClass = REGISTRY.get(providerName);
+            if (!ProviderClass) {
+                throw new LLMError(
+                    `Unknown LLM provider: "${providerName}". ` +
+                    `Registered providers: ${[...REGISTRY.keys()].join(', ')}`
+                );
+            }
+            const instance = model
+                ? new ProviderClass(apiKey, model)
+                : new ProviderClass(apiKey);
+            _cache.set(cacheKey, instance);
+        }
+
+        return _cache.get(cacheKey);
+    }
+
+    /**
+     * Register a custom provider class under a name.
+     * Call this before creating agents that use the custom provider.
+     *
+     * @param {string} name
+     * @param {typeof import('./BaseLLMProvider.js').BaseLLMProvider} ProviderClass
+     */
+    static register(name, ProviderClass) {
+        REGISTRY.set(name, ProviderClass);
+    }
+
+    /**
+     * Clear the instance cache. Useful in tests.
+     */
+    static clearCache() {
+        _cache.clear();
+    }
+
+    /**
+     * List all registered provider names.
+     * @returns {string[]}
+     */
+    static listProviders() {
+        return [...REGISTRY.keys()];
+    }
+}

package/src/llm/providers/ClaudeProvider.js

@@ -0,0 +1,307 @@
+// Claude (Anthropic) LLM Provider
+// Uses Anthropic Messages API with full tool-calling support
+
+import { BaseLLMProvider } from '../BaseLLMProvider.js';
+
+const ANTHROPIC_API_BASE = 'https://api.anthropic.com/v1';
+const DEFAULT_MODEL = 'claude-sonnet-4-20250514';
+const DEFAULT_TIMEOUT = 120000; // 120 seconds
+const ANTHROPIC_VERSION = '2023-06-01';
+
+export class ClaudeProvider extends BaseLLMProvider {
+    /**
+     * @param {string} apiKey   - Anthropic API key
+     * @param {string} [model]  - Model to use
+     * @param {number} [timeout]- Request timeout in ms
+     */
+    constructor(apiKey, model = DEFAULT_MODEL, timeout = DEFAULT_TIMEOUT) {
+        super();
+        if (!apiKey) throw new Error('ClaudeProvider: apiKey is required');
+        this.apiKey = apiKey;
+        this.model = model;
+        this.timeout = timeout;
+        this.baseUrl = ANTHROPIC_API_BASE;
+    }
+
+    async _makeRequest(endpoint, body) {
+        const url = `${this.baseUrl}${endpoint}`;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+
+        try {
+            const response = await fetch(url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'x-api-key': this.apiKey,
+                    'anthropic-version': ANTHROPIC_VERSION,
+                },
+                body: JSON.stringify(body),
+                signal: controller.signal,
+            });
+            clearTimeout(timeoutId);
+
+            if (!response.ok) {
+                const errorBody = await response.text();
+                let errorMessage;
+                try {
+                    const errorJson = JSON.parse(errorBody);
+                    errorMessage = errorJson.error?.message || errorJson.message || errorBody;
+                } catch {
+                    errorMessage = errorBody;
+                }
+                throw new Error(`Anthropic API error (${response.status}): ${errorMessage}`);
+            }
+
+            return response.json();
+        } catch (error) {
+            clearTimeout(timeoutId);
+            if (error.name === 'AbortError') throw new Error('Anthropic API request timed out');
+            throw error;
+        }
+    }
+
+    /**
+     * Convert OpenAI-format messages to Anthropic format.
+     *
+     * Differences:
+     *   - System messages are extracted (returned separately as the system field)
+     *   - role:'tool' messages become role:'user' with content array [{type:'tool_result',...}]
+     *   - Consecutive tool results are merged into one user message
+     *   - Assistant messages with tool_calls become content array [{type:'tool_use',...}]
+     *
+     * @param {Array} messages - OpenAI-format messages
+     * @returns {{ system: string, messages: Array }}
+     */
+    _convertMessages(messages) {
+        let system = '';
+        const converted = [];
+
+        for (const msg of messages) {
+            if (msg.role === 'system') {
+                system = system ? `${system}\n\n${msg.content}` : msg.content;
+                continue;
+            }
+
+            if (msg.role === 'tool') {
+                // Tool result → append to last user message if it's already a content array,
+                // or create a new user message
+                const toolResult = {
+                    type: 'tool_result',
+                    tool_use_id: msg.tool_call_id,
+                    content: msg.content,
+                };
+
+                const last = converted[converted.length - 1];
+                if (last && last.role === 'user' && Array.isArray(last.content)) {
+                    last.content.push(toolResult);
+                } else {
+                    converted.push({ role: 'user', content: [toolResult] });
+                }
+                continue;
+            }
+
+            if (msg.role === 'assistant' && msg.tool_calls?.length > 0) {
+                // Assistant message with tool calls → content array with tool_use blocks
+                const content = [];
+                if (msg.content) {
+                    content.push({ type: 'text', text: msg.content });
+                }
+                for (const tc of msg.tool_calls) {
+                    let input;
+                    try {
+                        input = typeof tc.function?.arguments === 'string'
+                            ? JSON.parse(tc.function.arguments)
+                            : (tc.function?.arguments ?? tc.arguments ?? {});
+                    } catch {
+                        input = {};
+                    }
+                    content.push({
+                        type: 'tool_use',
+                        id: tc.id,
+                        name: tc.function?.name ?? tc.name,
+                        input,
+                    });
+                }
+                converted.push({ role: 'assistant', content });
+                continue;
+            }
+
+            // Regular user or assistant message
+            converted.push({ role: msg.role, content: msg.content });
+        }
+
+        return { system, messages: converted };
+    }
+
+    /**
+     * Convert tool definitions from framework format to Anthropic format.
+     * Framework: { name, description, parameters }  (parameters = JSON Schema)
+     * Anthropic:  { name, description, input_schema } (same schema, different key)
+     */
+    _formatTools(tools) {
+        if (!tools || !Array.isArray(tools)) return [];
+        return tools.map(tool => ({
+            name: tool.name,
+            description: tool.description,
+            input_schema: tool.parameters || { type: 'object', properties: {} },
+        }));
+    }
+
+    /**
+     * Convert Anthropic response to standardized format + update messages array.
+     * @param {Object} response    - Raw Anthropic API response
+     * @param {Array}  messages    - OpenAI-format messages array (for continuation)
+     * @returns {import('../BaseLLMProvider.js').CompletionResponse}
+     */
+    _processResponse(response, messages) {
+        const textBlocks = response.content.filter(b => b.type === 'text');
+        const toolUseBlocks = response.content.filter(b => b.type === 'tool_use');
+
+        const content = textBlocks.map(b => b.text).join('');
+        const hasToolCalls = toolUseBlocks.length > 0;
+
+        // Extract tool calls in standardized format (arguments always an object)
+        const toolCalls = hasToolCalls
+            ? toolUseBlocks.map(b => ({
+                id: b.id,
+                name: b.name,
+                arguments: b.input,
+            }))
+            : undefined;
+
+        // Build updated OpenAI-format message array
+        // Store arguments as objects (not strings) so _convertMessages doesn't need to JSON.parse
+        const updatedMessages = [...messages];
+        if (hasToolCalls) {
+            updatedMessages.push({
+                role: 'assistant',
+                content: content || null,
+                tool_calls: toolUseBlocks.map(b => ({
+                    id: b.id,
+                    type: 'function',
+                    function: {
+                        name: b.name,
+                        arguments: b.input, // keep as object — _convertMessages handles both
+                    },
+                })),
+            });
+        } else {
+            updatedMessages.push({ role: 'assistant', content });
+        }
+
+        return {
+            content,
+            parsed: null,
+            usage: {
+                promptTokens: response.usage?.input_tokens || 0,
+                completionTokens: response.usage?.output_tokens || 0,
+                totalTokens: (response.usage?.input_tokens || 0) + (response.usage?.output_tokens || 0),
+            },
+            model: response.model || this.model,
+            finishReason: response.stop_reason || 'unknown',
+            toolCalls,
+            messages: updatedMessages,
+        };
+    }
+
+    async complete(prompt, options = {}) {
+        // Build OpenAI-format message array, then convert to Anthropic format
+        let openAiMessages;
+        if (options.messages && Array.isArray(options.messages)) {
+            openAiMessages = options.messages;
+        } else {
+            openAiMessages = [];
+            if (options.systemPrompt) {
+                openAiMessages.push({ role: 'system', content: options.systemPrompt });
+            }
+            openAiMessages.push({ role: 'user', content: prompt });
+        }
+
+        const { system, messages: anthropicMessages } = this._convertMessages(openAiMessages);
+
+        const requestBody = {
+            model: options.model || this.model,
+            max_tokens: options.maxTokens ?? 4096,
+            temperature: options.temperature ?? 0.1,
+            messages: anthropicMessages,
+        };
+
+        if (system) requestBody.system = system;
+
+        if (options.enableTools && options.tools) {
+            requestBody.tools = this._formatTools(options.tools);
+        }
+
+        const response = await this._makeRequest('/messages', requestBody);
+        return this._processResponse(response, openAiMessages);
+    }
+
+    async completeWithSchema(prompt, schema, options = {}) {
+        // For tool-calling mode, schema is used for the final answer — don't add schema to prompt
+        if (options.enableTools) {
+            const response = await this.complete(prompt, options);
+            // If we got a final text answer (no tool calls), parse it as JSON
+            if (response.content && !response.toolCalls) {
+                response.parsed = this._parseJsonContent(response.content);
+                if (schema?.required && response.parsed) {
+                    const missing = schema.required.filter(f => !(f in response.parsed));
+                    if (missing.length > 0) {
+                        console.warn(`[ClaudeProvider] Response missing fields: ${missing.join(', ')}`);
+                    }
+                }
+            }
+            return response;
+        }
+
+        // Standard schema completion (no tools)
+        const schemaPrompt = `${prompt}\n\n## Required JSON Schema:\n\`\`\`json\n${JSON.stringify(schema, null, 2)}\n\`\`\`\n\nRespond with a JSON object that matches this schema exactly.`;
+
+        const systemPrompt = options.systemPrompt
+            ? `${options.systemPrompt}\n\nIMPORTANT: You must respond with valid JSON only. No markdown, no code blocks, no explanation — just the JSON object.`
+            : 'You must respond with valid JSON only. No markdown, no code blocks, no explanation — just the JSON object.';
+
+        const response = await this.complete(schemaPrompt, { ...options, systemPrompt });
+        response.parsed = this._parseJsonContent(response.content);
+        return response;
+    }
+
+    /**
+     * Parse content string as JSON, stripping markdown code fences if present.
+     */
+    _parseJsonContent(content) {
+        let text = content.trim();
+        if (text.startsWith('```json')) text = text.slice(7);
+        else if (text.startsWith('```')) text = text.slice(3);
+        if (text.endsWith('```')) text = text.slice(0, -3);
+        text = text.trim();
+
+        try {
+            return JSON.parse(text);
+        } catch (err) {
+            throw new Error(`ClaudeProvider: invalid JSON response — ${err.message}`);
+        }
+    }
+
+    async testConnection() {
+        try {
+            const response = await this.complete("Say 'ok'", { maxTokens: 10, temperature: 0 });
+            return !!response.content;
+        } catch {
+            return false;
+        }
+    }
+
+    listModels() {
+        return [
+            'claude-sonnet-4-20250514',
+            'claude-opus-4-20250514',
+            'claude-3-5-sonnet-20241022',
+            'claude-3-5-haiku-20241022',
+            'claude-3-opus-20240229',
+            'claude-3-haiku-20240307',
+        ];
+    }
+}
+
+export default ClaudeProvider;

package/src/llm/providers/GrokProvider.js

@@ -0,0 +1,208 @@
+// Grok (xAI) LLM Provider
+// Uses OpenAI-compatible API format
+
+import { BaseLLMProvider } from '../BaseLLMProvider.js';
+
+const GROK_API_BASE = 'https://api.x.ai/v1';
+const DEFAULT_MODEL = 'grok-code-fast-1';
+const DEFAULT_TIMEOUT = 60000; // 60 seconds
+
+export class GrokProvider extends BaseLLMProvider {
+    /**
+     * @param {string} apiKey - xAI API key
+     * @param {string} [model] - Model to use
+     * @param {number} [timeout] - Request timeout in ms
+     */
+    constructor(apiKey, model = DEFAULT_MODEL, timeout = DEFAULT_TIMEOUT) {
+        super();
+        if (!apiKey) throw new Error('GrokProvider: apiKey is required');
+        this.apiKey = apiKey;
+        this.model = model;
+        this.timeout = timeout;
+        this.baseUrl = GROK_API_BASE;
+    }
+
+    async _makeRequest(endpoint, body) {
+        const url = `${this.baseUrl}${endpoint}`;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+
+        try {
+            const response = await fetch(url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${this.apiKey}`,
+                },
+                body: JSON.stringify(body),
+                signal: controller.signal,
+            });
+            clearTimeout(timeoutId);
+
+            if (!response.ok) {
+                const errorBody = await response.text();
+                let errorMessage;
+                try {
+                    const errorJson = JSON.parse(errorBody);
+                    errorMessage = errorJson.error?.message || errorJson.message || errorBody;
+                } catch {
+                    errorMessage = errorBody;
+                }
+                throw new Error(`Grok API error (${response.status}): ${errorMessage}`);
+            }
+
+            return response.json();
+        } catch (error) {
+            clearTimeout(timeoutId);
+            if (error.name === 'AbortError') throw new Error('Grok API request timed out');
+            throw error;
+        }
+    }
+
+    _buildMessages(prompt, options) {
+        if (options.messages && Array.isArray(options.messages)) {
+            return options.messages;
+        }
+        const messages = [];
+        if (options.systemPrompt) {
+            messages.push({ role: 'system', content: options.systemPrompt });
+        }
+        messages.push({ role: 'user', content: prompt });
+        return messages;
+    }
+
+    _formatTools(tools) {
+        if (!tools || !Array.isArray(tools)) return [];
+        return tools.map(tool => ({
+            type: 'function',
+            function: {
+                name: tool.name,
+                description: tool.description,
+                parameters: tool.parameters || { type: 'object', properties: {} },
+            },
+        }));
+    }
+
+    _hasToolCalls(choice) {
+        return !!(choice?.message?.tool_calls?.length > 0);
+    }
+
+    _extractToolCalls(choice) {
+        if (!this._hasToolCalls(choice)) return [];
+        return choice.message.tool_calls.map(tc => {
+            let args;
+            try {
+                args = typeof tc.function.arguments === 'string'
+                    ? JSON.parse(tc.function.arguments)
+                    : tc.function.arguments ?? {};
+            } catch {
+                args = {};
+            }
+            return { id: tc.id, name: tc.function.name, arguments: args };
+        });
+    }
+
+    async complete(prompt, options = {}) {
+        const messages = this._buildMessages(prompt, options);
+
+        const requestBody = {
+            model: options.model || this.model,
+            messages,
+            temperature: options.temperature ?? 0.1,
+            max_tokens: options.maxTokens ?? 2048,
+        };
+
+        if (options.enableTools && options.tools) {
+            requestBody.tools = this._formatTools(options.tools);
+        }
+
+        if (options.jsonMode && !options.enableTools) {
+            requestBody.response_format = { type: 'json_object' };
+        }
+
+        const response = await this._makeRequest('/chat/completions', requestBody);
+        const choice = response.choices?.[0];
+        if (!choice) throw new Error('No completion returned from Grok API');
+
+        const content = choice.message?.content || '';
+        const hasToolCalls = this._hasToolCalls(choice);
+        let toolCalls = [];
+        const updatedMessages = [...messages];
+
+        if (hasToolCalls) {
+            toolCalls = this._extractToolCalls(choice);
+            updatedMessages.push({
+                role: 'assistant',
+                content: content || null,
+                tool_calls: choice.message.tool_calls,
+            });
+        } else {
+            updatedMessages.push({ role: 'assistant', content });
+        }
+
+        let parsed = null;
+        if (options.jsonMode && content && !hasToolCalls) {
+            try {
+                parsed = JSON.parse(content);
+            } catch (error) {
+                throw new Error(`Failed to parse JSON response: ${error.message}`);
+            }
+        }
+
+        return {
+            content,
+            parsed,
+            usage: {
+                promptTokens: response.usage?.prompt_tokens || 0,
+                completionTokens: response.usage?.completion_tokens || 0,
+                totalTokens: response.usage?.total_tokens || 0,
+            },
+            model: response.model || this.model,
+            finishReason: choice.finish_reason || 'unknown',
+            toolCalls: toolCalls.length > 0 ? toolCalls : undefined,
+            messages: updatedMessages,
+        };
+    }
+
+    async completeWithSchema(prompt, schema, options = {}) {
+        if (options.enableTools) {
+            const response = await this.complete(prompt, { ...options, jsonMode: false });
+            if (response.content && !response.toolCalls) {
+                try {
+                    response.parsed = JSON.parse(response.content);
+                } catch {
+                    // non-fatal in tool-calling mode
+                }
+            }
+            return response;
+        }
+
+        const schemaPrompt = `${prompt}\n\nYou MUST respond with a valid JSON object that matches this structure:\n${JSON.stringify(schema, null, 2)}\n\nRespond ONLY with the JSON object, no additional text.`;
+
+        const response = await this.complete(schemaPrompt, { ...options, jsonMode: true });
+
+        if (response.parsed && schema?.required) {
+            const missing = schema.required.filter(f => !(f in response.parsed));
+            if (missing.length > 0) {
+                throw new Error(`Response missing required fields: ${missing.join(', ')}`);
+            }
+        }
+
+        return response;
+    }
+
+    async testConnection() {
+        try {
+            const response = await this.complete("Say 'ok'", { maxTokens: 10, temperature: 0 });
+            return !!response.content;
+        } catch {
+            return false;
+        }
+    }
+
+    listModels() {
+        return ['grok-code-fast-1', 'grok-2', 'grok-2-mini'];
+    }
+}
+
+export default GrokProvider;