@compilr-dev/agents 0.0.1 → 0.1.0

package/dist/providers/openai-compatible.d.ts

@@ -0,0 +1,182 @@
+/**
+ * OpenAI-Compatible LLM Provider Base Class
+ *
+ * Abstract base class for LLM providers that use OpenAI-compatible REST APIs.
+ * Provides shared implementation for:
+ * - Message conversion (library format → OpenAI format)
+ * - Tool definition conversion
+ * - SSE stream parsing
+ * - Tool call delta accumulation
+ * - Token counting (approximation)
+ *
+ * Extended by: OllamaProvider, OpenAIProvider, GeminiProvider
+ *
+ * @example
+ * ```typescript
+ * class MyProvider extends OpenAICompatibleProvider {
+ *   readonly name = 'my-provider';
+ *   protected getAuthHeaders() { return { 'Authorization': 'Bearer xxx' }; }
+ *   protected getEndpointPath() { return '/v1/chat/completions'; }
+ *   // ... other abstract methods
+ * }
+ * ```
+ */
+import type { LLMProvider, Message, StreamChunk, ChatOptions, ToolDefinition } from './types.js';
+import { ProviderError } from '../errors.js';
+/**
+ * OpenAI-compatible message format
+ */
+export interface OpenAIMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: string | null;
+    tool_calls?: OpenAIToolCall[];
+    tool_call_id?: string;
+}
+/**
+ * OpenAI-compatible tool call format
+ */
+export interface OpenAIToolCall {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+/**
+ * OpenAI-compatible tool definition format
+ */
+export interface OpenAITool {
+    type: 'function';
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+}
+/**
+ * OpenAI streaming response chunk format
+ */
+export interface OpenAIStreamChunk {
+    id: string;
+    object: string;
+    created: number;
+    model: string;
+    choices: Array<{
+        index: number;
+        delta: {
+            role?: string;
+            content?: string | null;
+            tool_calls?: Array<{
+                index: number;
+                id?: string;
+                type?: string;
+                function?: {
+                    name?: string;
+                    arguments?: string;
+                };
+            }>;
+        };
+        finish_reason: string | null;
+    }>;
+    usage?: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+    };
+}
+/**
+ * Base configuration for OpenAI-compatible providers
+ */
+export interface OpenAICompatibleConfig {
+    /** Base URL for the API */
+    baseUrl: string;
+    /** Default model to use */
+    model: string;
+    /** Default max tokens (default: 4096) */
+    maxTokens?: number;
+    /** Request timeout in milliseconds (default: 120000) */
+    timeout?: number;
+}
+/**
+ * Abstract base class for OpenAI-compatible LLM providers
+ *
+ * Provides shared implementation for providers that use the OpenAI
+ * chat completions API format (OpenAI, Ollama, Azure OpenAI, Gemini).
+ */
+export declare abstract class OpenAICompatibleProvider implements LLMProvider {
+    /**
+     * Provider name (e.g., 'openai', 'ollama', 'gemini')
+     */
+    abstract readonly name: string;
+    protected readonly baseUrl: string;
+    protected readonly defaultModel: string;
+    protected readonly defaultMaxTokens: number;
+    protected readonly timeout: number;
+    constructor(config: OpenAICompatibleConfig);
+    /**
+     * Get authentication headers for API requests
+     * @returns Headers object with auth credentials
+     */
+    protected abstract getAuthHeaders(): Record<string, string>;
+    /**
+     * Get the API endpoint path (e.g., '/v1/chat/completions')
+     * @returns API endpoint path
+     */
+    protected abstract getEndpointPath(): string;
+    /**
+     * Build provider-specific request body extensions
+     * @param options Chat options
+     * @returns Additional body fields for the request
+     */
+    protected abstract buildProviderSpecificBody(options?: ChatOptions): Record<string, unknown>;
+    /**
+     * Map HTTP error to ProviderError with provider-specific messages
+     * @param status HTTP status code
+     * @param body Response body
+     * @param model Model name
+     * @returns ProviderError with appropriate message
+     */
+    protected abstract mapHttpError(status: number, body: string, model: string): ProviderError;
+    /**
+     * Map connection errors with provider-specific messages
+     * @param error Original error
+     * @returns ProviderError with appropriate message
+     */
+    protected abstract mapConnectionError(error: Error): ProviderError;
+    /**
+     * Stream chat completion from the provider
+     *
+     * @param messages - Conversation messages
+     * @param options - Chat options (thinking is ignored for non-Claude providers)
+     */
+    chat(messages: Message[], options?: ChatOptions): AsyncIterable<StreamChunk>;
+    /**
+     * Convert library messages to OpenAI format
+     */
+    protected convertMessages(messages: Message[]): OpenAIMessage[];
+    /**
+     * Map library role to OpenAI role
+     */
+    protected mapRole(role: string): 'system' | 'user' | 'assistant' | 'tool';
+    /**
+     * Convert tool definitions to OpenAI format
+     */
+    protected convertTools(tools: ToolDefinition[]): OpenAITool[];
+    /**
+     * Process a stream chunk into StreamChunk events
+     */
+    protected processStreamChunk(chunk: OpenAIStreamChunk, toolCalls: Map<number, {
+        id: string;
+        name: string;
+        arguments: string;
+    }>): StreamChunk[];
+    /**
+     * Estimate token count (rough approximation)
+     *
+     * @remarks
+     * Most providers don't have a native token counting endpoint.
+     * This uses a rough approximation of ~4 characters per token.
+     */
+    countTokens(messages: Message[]): Promise<number>;
+}

package/dist/providers/openai-compatible.js

@@ -0,0 +1,359 @@
+/**
+ * OpenAI-Compatible LLM Provider Base Class
+ *
+ * Abstract base class for LLM providers that use OpenAI-compatible REST APIs.
+ * Provides shared implementation for:
+ * - Message conversion (library format → OpenAI format)
+ * - Tool definition conversion
+ * - SSE stream parsing
+ * - Tool call delta accumulation
+ * - Token counting (approximation)
+ *
+ * Extended by: OllamaProvider, OpenAIProvider, GeminiProvider
+ *
+ * @example
+ * ```typescript
+ * class MyProvider extends OpenAICompatibleProvider {
+ *   readonly name = 'my-provider';
+ *   protected getAuthHeaders() { return { 'Authorization': 'Bearer xxx' }; }
+ *   protected getEndpointPath() { return '/v1/chat/completions'; }
+ *   // ... other abstract methods
+ * }
+ * ```
+ */
+import { ProviderError } from '../errors.js';
+// Default configuration
+const DEFAULT_MAX_TOKENS = 4096;
+const DEFAULT_TIMEOUT = 120000;
+/**
+ * Abstract base class for OpenAI-compatible LLM providers
+ *
+ * Provides shared implementation for providers that use the OpenAI
+ * chat completions API format (OpenAI, Ollama, Azure OpenAI, Gemini).
+ */
+export class OpenAICompatibleProvider {
+    baseUrl;
+    defaultModel;
+    defaultMaxTokens;
+    timeout;
+    constructor(config) {
+        this.baseUrl = config.baseUrl;
+        this.defaultModel = config.model;
+        this.defaultMaxTokens = config.maxTokens ?? DEFAULT_MAX_TOKENS;
+        this.timeout = config.timeout ?? DEFAULT_TIMEOUT;
+    }
+    // ==================== SHARED IMPLEMENTATION ====================
+    /**
+     * Stream chat completion from the provider
+     *
+     * @param messages - Conversation messages
+     * @param options - Chat options (thinking is ignored for non-Claude providers)
+     */
+    async *chat(messages, options) {
+        const model = options?.model ?? this.defaultModel;
+        const maxTokens = options?.maxTokens ?? this.defaultMaxTokens;
+        // Note: options.thinking is ignored - it's a Claude-specific feature
+        // Convert messages to OpenAI format
+        const openaiMessages = this.convertMessages(messages);
+        // Convert tools if provided
+        const tools = options?.tools ? this.convertTools(options.tools) : undefined;
+        // Build request body
+        const body = {
+            model,
+            messages: openaiMessages,
+            stream: true,
+            stream_options: { include_usage: true }, // Request usage stats in stream
+            max_tokens: maxTokens,
+            ...this.buildProviderSpecificBody(options),
+        };
+        if (options?.temperature !== undefined) {
+            body.temperature = options.temperature;
+        }
+        if (options?.stopSequences && options.stopSequences.length > 0) {
+            body.stop = options.stopSequences;
+        }
+        if (tools && tools.length > 0) {
+            body.tools = tools;
+        }
+        // Track tool calls being assembled
+        const toolCalls = new Map();
+        let usage;
+        try {
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => {
+                controller.abort();
+            }, this.timeout);
+            const response = await fetch(`${this.baseUrl}${this.getEndpointPath()}`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    ...this.getAuthHeaders(),
+                },
+                body: JSON.stringify(body),
+                signal: controller.signal,
+            });
+            clearTimeout(timeoutId);
+            if (!response.ok) {
+                const errorBody = await response.text();
+                throw this.mapHttpError(response.status, errorBody, model);
+            }
+            const reader = response.body?.getReader();
+            if (!reader) {
+                throw new ProviderError('No response body', this.name);
+            }
+            const decoder = new TextDecoder();
+            let buffer = '';
+            let streamDone = false;
+            while (!streamDone) {
+                const readResult = (await reader.read());
+                if (readResult.done) {
+                    streamDone = true;
+                    continue;
+                }
+                buffer += decoder.decode(readResult.value, { stream: true });
+                const lines = buffer.split('\n');
+                buffer = lines.pop() ?? '';
+                for (const line of lines) {
+                    if (!line.trim() || line.startsWith(':'))
+                        continue;
+                    if (line === 'data: [DONE]')
+                        continue;
+                    const data = line.replace(/^data: /, '');
+                    if (!data.trim())
+                        continue;
+                    try {
+                        const chunk = JSON.parse(data);
+                        const chunks = this.processStreamChunk(chunk, toolCalls);
+                        for (const streamChunk of chunks) {
+                            yield streamChunk;
+                        }
+                        // Track usage from final chunk
+                        if (chunk.usage) {
+                            usage = {
+                                inputTokens: chunk.usage.prompt_tokens,
+                                outputTokens: chunk.usage.completion_tokens,
+                            };
+                        }
+                    }
+                    catch {
+                        // Skip malformed JSON chunks
+                    }
+                }
+            }
+            // Yield done chunk with usage
+            yield {
+                type: 'done',
+                usage,
+            };
+        }
+        catch (error) {
+            if (error instanceof ProviderError) {
+                throw error;
+            }
+            if (error instanceof Error) {
+                if (error.name === 'AbortError') {
+                    throw new ProviderError('Request timeout', this.name, 408);
+                }
+                // Check for connection errors
+                if (error.message.includes('fetch') ||
+                    error.message.includes('ECONNREFUSED') ||
+                    error.message.includes('network')) {
+                    throw this.mapConnectionError(error);
+                }
+                throw new ProviderError(error.message, this.name);
+            }
+            throw new ProviderError('Unknown error', this.name);
+        }
+    }
+    /**
+     * Convert library messages to OpenAI format
+     */
+    convertMessages(messages) {
+        const result = [];
+        for (const msg of messages) {
+            if (typeof msg.content === 'string') {
+                result.push({
+                    role: this.mapRole(msg.role),
+                    content: msg.content,
+                });
+            }
+            else if (Array.isArray(msg.content)) {
+                // Handle content blocks
+                const blocks = msg.content;
+                const textParts = [];
+                const toolCallsList = [];
+                const toolResults = [];
+                for (const block of blocks) {
+                    if (block.type === 'text') {
+                        textParts.push(block.text);
+                    }
+                    else if (block.type === 'tool_use') {
+                        toolCallsList.push({
+                            id: block.id,
+                            type: 'function',
+                            function: {
+                                name: block.name,
+                                arguments: JSON.stringify(block.input),
+                            },
+                        });
+                    }
+                    else if (block.type === 'tool_result') {
+                        const content = typeof block.content === 'string'
+                            ? block.content
+                            : JSON.stringify(block.content);
+                        toolResults.push({
+                            id: block.toolUseId,
+                            content,
+                        });
+                    }
+                    // Note: 'thinking' blocks are ignored (Claude-specific)
+                }
+                // Handle tool results - each needs its own message
+                if (toolResults.length > 0) {
+                    for (const tr of toolResults) {
+                        result.push({
+                            role: 'tool',
+                            content: tr.content,
+                            tool_call_id: tr.id,
+                        });
+                    }
+                }
+                else if (toolCallsList.length > 0) {
+                    // Assistant message with tool calls
+                    result.push({
+                        role: 'assistant',
+                        content: textParts.length > 0 ? textParts.join('\n') : null,
+                        tool_calls: toolCallsList,
+                    });
+                }
+                else if (textParts.length > 0) {
+                    // Regular text message
+                    result.push({
+                        role: this.mapRole(msg.role),
+                        content: textParts.join('\n'),
+                    });
+                }
+            }
+        }
+        return result;
+    }
+    /**
+     * Map library role to OpenAI role
+     */
+    mapRole(role) {
+        switch (role) {
+            case 'system':
+                return 'system';
+            case 'user':
+                return 'user';
+            case 'assistant':
+                return 'assistant';
+            default:
+                return 'user';
+        }
+    }
+    /**
+     * Convert tool definitions to OpenAI format
+     */
+    convertTools(tools) {
+        return tools.map((tool) => ({
+            type: 'function',
+            function: {
+                name: tool.name,
+                description: tool.description,
+                parameters: tool.inputSchema,
+            },
+        }));
+    }
+    /**
+     * Process a stream chunk into StreamChunk events
+     */
+    processStreamChunk(chunk, toolCalls) {
+        const results = [];
+        const choices = chunk.choices;
+        if (choices.length === 0)
+            return results;
+        const choice = choices[0];
+        const delta = choice.delta;
+        // Handle text content
+        if (delta.content) {
+            results.push({
+                type: 'text',
+                text: delta.content,
+            });
+        }
+        // Handle tool calls
+        if (delta.tool_calls) {
+            for (const tc of delta.tool_calls) {
+                const index = tc.index;
+                let call = toolCalls.get(index);
+                // New tool call
+                const fn = tc.function;
+                if (tc.id && fn?.name) {
+                    call = {
+                        id: tc.id,
+                        name: fn.name,
+                        arguments: fn.arguments ?? '',
+                    };
+                    toolCalls.set(index, call);
+                    results.push({
+                        type: 'tool_use_start',
+                        toolUse: {
+                            id: tc.id,
+                            name: fn.name,
+                        },
+                    });
+                }
+                // Streaming arguments
+                if (call && fn?.arguments) {
+                    call.arguments += fn.arguments;
+                    results.push({
+                        type: 'tool_use_delta',
+                        text: fn.arguments,
+                    });
+                }
+            }
+        }
+        // Handle finish reason - emit tool_use_end for completed tool calls
+        // Note: The agent accumulates tool_use_delta chunks and parses the JSON
+        if (choice.finish_reason === 'tool_calls' || choice.finish_reason === 'stop') {
+            for (const [,] of toolCalls) {
+                results.push({ type: 'tool_use_end' });
+            }
+            toolCalls.clear();
+        }
+        return results;
+    }
+    /**
+     * Estimate token count (rough approximation)
+     *
+     * @remarks
+     * Most providers don't have a native token counting endpoint.
+     * This uses a rough approximation of ~4 characters per token.
+     */
+    countTokens(messages) {
+        let charCount = 0;
+        for (const msg of messages) {
+            if (typeof msg.content === 'string') {
+                charCount += msg.content.length;
+            }
+            else if (Array.isArray(msg.content)) {
+                for (const block of msg.content) {
+                    if (block.type === 'text') {
+                        charCount += block.text.length;
+                    }
+                    else if (block.type === 'tool_use') {
+                        charCount += JSON.stringify(block.input).length;
+                    }
+                    else if (block.type === 'tool_result') {
+                        charCount +=
+                            typeof block.content === 'string'
+                                ? block.content.length
+                                : JSON.stringify(block.content).length;
+                    }
+                }
+            }
+        }
+        return Promise.resolve(Math.ceil(charCount / 4));
+    }
+}

package/dist/providers/openai.d.ts

@@ -0,0 +1,93 @@
+/**
+ * OpenAI LLM Provider
+ *
+ * Implements LLMProvider interface for OpenAI models (GPT-4o, GPT-4o-mini, etc.)
+ * Extends OpenAICompatibleProvider for shared functionality.
+ *
+ * @example
+ * ```typescript
+ * const provider = createOpenAIProvider({
+ *   model: 'gpt-4o',
+ *   apiKey: process.env.OPENAI_API_KEY
+ * });
+ * ```
+ *
+ * @remarks
+ * - Requires valid OpenAI API key
+ * - Default model is gpt-4o
+ * - Extended thinking is not supported (Claude-specific feature)
+ */
+import type { ChatOptions } from './types.js';
+import { ProviderError } from '../errors.js';
+import { OpenAICompatibleProvider } from './openai-compatible.js';
+/**
+ * Configuration for OpenAIProvider
+ */
+export interface OpenAIProviderConfig {
+    /** OpenAI API key (falls back to OPENAI_API_KEY env var) */
+    apiKey?: string;
+    /** Base URL for OpenAI API (default: https://api.openai.com) */
+    baseUrl?: string;
+    /** Default model to use (default: gpt-4o) */
+    model?: string;
+    /** Default max tokens (default: 4096) */
+    maxTokens?: number;
+    /** Request timeout in milliseconds (default: 120000) */
+    timeout?: number;
+    /** OpenAI organization ID (optional) */
+    organization?: string;
+}
+/**
+ * OpenAI LLM Provider
+ *
+ * Provides streaming chat completion using OpenAI models.
+ * Supports GPT-4o, GPT-4o-mini, and other compatible models.
+ */
+export declare class OpenAIProvider extends OpenAICompatibleProvider {
+    readonly name = "openai";
+    private readonly apiKey;
+    private readonly organization?;
+    constructor(config?: OpenAIProviderConfig);
+    /**
+     * OpenAI authentication with Bearer token
+     */
+    protected getAuthHeaders(): Record<string, string>;
+    /**
+     * OpenAI chat completions endpoint
+     */
+    protected getEndpointPath(): string;
+    /**
+     * OpenAI uses standard body format (no provider-specific extensions needed)
+     */
+    protected buildProviderSpecificBody(_options?: ChatOptions): Record<string, unknown>;
+    /**
+     * Map HTTP errors with OpenAI-specific messages
+     */
+    protected mapHttpError(status: number, body: string, _model: string): ProviderError;
+    /**
+     * Map connection errors with OpenAI-specific messages
+     */
+    protected mapConnectionError(_error: Error): ProviderError;
+}
+/**
+ * Create an OpenAI provider instance
+ *
+ * @example
+ * ```typescript
+ * // Using environment variable (OPENAI_API_KEY)
+ * const provider = createOpenAIProvider();
+ *
+ * // With explicit API key
+ * const provider = createOpenAIProvider({ apiKey: 'sk-...' });
+ *
+ * // With custom model
+ * const provider = createOpenAIProvider({ model: 'gpt-4o-mini' });
+ *
+ * // With organization
+ * const provider = createOpenAIProvider({
+ *   apiKey: 'sk-...',
+ *   organization: 'org-...'
+ * });
+ * ```
+ */
+export declare function createOpenAIProvider(config?: OpenAIProviderConfig): OpenAIProvider;