@compilr-dev/agents 0.0.1 → 0.2.0

package/dist/providers/gemini.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Google Gemini LLM Provider
+ *
+ * Implements LLMProvider interface for Google Gemini models using
+ * the OpenAI-compatible endpoint for maximum compatibility.
+ *
+ * @example
+ * ```typescript
+ * const provider = createGeminiProvider({
+ *   model: 'gemini-2.0-flash',
+ *   apiKey: process.env.GOOGLE_AI_API_KEY
+ * });
+ * ```
+ *
+ * @remarks
+ * - Requires valid Google AI API key
+ * - Uses OpenAI-compatible endpoint for streaming and tool calling
+ * - Default model is gemini-2.0-flash
+ * - 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 GeminiProvider
+ */
+export interface GeminiProviderConfig {
+    /** Google AI API key (falls back to GOOGLE_AI_API_KEY or GEMINI_API_KEY env var) */
+    apiKey?: string;
+    /** Base URL for Gemini API (default: https://generativelanguage.googleapis.com/v1beta/openai) */
+    baseUrl?: string;
+    /** Default model to use (default: gemini-2.0-flash) */
+    model?: string;
+    /** Default max tokens (default: 4096) */
+    maxTokens?: number;
+    /** Request timeout in milliseconds (default: 120000) */
+    timeout?: number;
+}
+/**
+ * Google Gemini LLM Provider
+ *
+ * Provides streaming chat completion using Google's Gemini models
+ * via the OpenAI-compatible API endpoint.
+ * Supports gemini-2.0-flash, gemini-1.5-flash, gemini-1.5-pro, and others.
+ */
+export declare class GeminiProvider extends OpenAICompatibleProvider {
+    readonly name = "gemini";
+    private readonly apiKey;
+    constructor(config?: GeminiProviderConfig);
+    /**
+     * Gemini authentication with Bearer token
+     */
+    protected getAuthHeaders(): Record<string, string>;
+    /**
+     * Gemini's OpenAI-compatible endpoint path
+     */
+    protected getEndpointPath(): string;
+    /**
+     * Gemini uses standard body format (no provider-specific extensions needed)
+     */
+    protected buildProviderSpecificBody(_options?: ChatOptions): Record<string, unknown>;
+    /**
+     * Map HTTP errors with Gemini-specific messages
+     */
+    protected mapHttpError(status: number, body: string, _model: string): ProviderError;
+    /**
+     * Map connection errors with Gemini-specific messages
+     */
+    protected mapConnectionError(_error: Error): ProviderError;
+}
+/**
+ * Create a Gemini provider instance
+ *
+ * @example
+ * ```typescript
+ * // Using environment variable (GOOGLE_AI_API_KEY or GEMINI_API_KEY)
+ * const provider = createGeminiProvider();
+ *
+ * // With explicit API key
+ * const provider = createGeminiProvider({ apiKey: 'AI...' });
+ *
+ * // With custom model
+ * const provider = createGeminiProvider({ model: 'gemini-1.5-pro' });
+ *
+ * // Available models:
+ * // - gemini-2.0-flash (default, fast)
+ * // - gemini-1.5-flash (faster, cheaper)
+ * // - gemini-1.5-pro (more capable)
+ * ```
+ */
+export declare function createGeminiProvider(config?: GeminiProviderConfig): GeminiProvider;

package/dist/providers/gemini.js

@@ -0,0 +1,138 @@
+/**
+ * Google Gemini LLM Provider
+ *
+ * Implements LLMProvider interface for Google Gemini models using
+ * the OpenAI-compatible endpoint for maximum compatibility.
+ *
+ * @example
+ * ```typescript
+ * const provider = createGeminiProvider({
+ *   model: 'gemini-2.0-flash',
+ *   apiKey: process.env.GOOGLE_AI_API_KEY
+ * });
+ * ```
+ *
+ * @remarks
+ * - Requires valid Google AI API key
+ * - Uses OpenAI-compatible endpoint for streaming and tool calling
+ * - Default model is gemini-2.0-flash
+ * - Extended thinking is not supported (Claude-specific feature)
+ */
+import { ProviderError } from '../errors.js';
+import { OpenAICompatibleProvider } from './openai-compatible.js';
+// Default configuration
+const DEFAULT_MODEL = 'gemini-2.0-flash';
+const DEFAULT_BASE_URL = 'https://generativelanguage.googleapis.com/v1beta/openai';
+/**
+ * Google Gemini LLM Provider
+ *
+ * Provides streaming chat completion using Google's Gemini models
+ * via the OpenAI-compatible API endpoint.
+ * Supports gemini-2.0-flash, gemini-1.5-flash, gemini-1.5-pro, and others.
+ */
+export class GeminiProvider extends OpenAICompatibleProvider {
+    name = 'gemini';
+    apiKey;
+    constructor(config = {}) {
+        const apiKey = config.apiKey ?? process.env.GOOGLE_AI_API_KEY ?? process.env.GEMINI_API_KEY;
+        if (!apiKey) {
+            throw new ProviderError('Gemini API key not found. Set GOOGLE_AI_API_KEY or GEMINI_API_KEY environment variable, or pass apiKey in config.', 'gemini');
+        }
+        const baseConfig = {
+            baseUrl: config.baseUrl ?? DEFAULT_BASE_URL,
+            model: config.model ?? DEFAULT_MODEL,
+            maxTokens: config.maxTokens,
+            timeout: config.timeout,
+        };
+        super(baseConfig);
+        this.apiKey = apiKey;
+    }
+    /**
+     * Gemini authentication with Bearer token
+     */
+    getAuthHeaders() {
+        return {
+            Authorization: `Bearer ${this.apiKey}`,
+        };
+    }
+    /**
+     * Gemini's OpenAI-compatible endpoint path
+     */
+    getEndpointPath() {
+        return '/chat/completions';
+    }
+    /**
+     * Gemini uses standard body format (no provider-specific extensions needed)
+     */
+    buildProviderSpecificBody(_options) {
+        return {};
+    }
+    /**
+     * Map HTTP errors with Gemini-specific messages
+     */
+    mapHttpError(status, body, _model) {
+        let message = `Gemini error (${String(status)})`;
+        try {
+            const parsed = JSON.parse(body);
+            // Gemini sometimes wraps errors in an array
+            if (Array.isArray(parsed)) {
+                const first = parsed[0];
+                if (first?.error?.message) {
+                    message = first.error.message;
+                }
+            }
+            else if (parsed.error?.message) {
+                message = parsed.error.message;
+            }
+        }
+        catch {
+            // If body isn't JSON, show it directly (truncated)
+            message = body ? body.slice(0, 500) : message;
+        }
+        switch (status) {
+            case 400:
+                return new ProviderError(`Invalid request to Gemini API: ${message}`, 'gemini', 400);
+            case 401:
+                return new ProviderError('Invalid Gemini API key. Check your GOOGLE_AI_API_KEY or GEMINI_API_KEY.', 'gemini', 401);
+            case 403:
+                return new ProviderError('Access denied to Gemini API. Check your API key permissions.', 'gemini', 403);
+            case 429:
+                return new ProviderError('Gemini rate limit exceeded. Please wait and try again.', 'gemini', 429);
+            case 500:
+            case 502:
+            case 503:
+                return new ProviderError('Gemini service temporarily unavailable. Please try again later.', 'gemini', status);
+            default:
+                return new ProviderError(message, 'gemini', status);
+        }
+    }
+    /**
+     * Map connection errors with Gemini-specific messages
+     */
+    mapConnectionError(_error) {
+        return new ProviderError('Failed to connect to Gemini API. Check your internet connection.', 'gemini');
+    }
+}
+/**
+ * Create a Gemini provider instance
+ *
+ * @example
+ * ```typescript
+ * // Using environment variable (GOOGLE_AI_API_KEY or GEMINI_API_KEY)
+ * const provider = createGeminiProvider();
+ *
+ * // With explicit API key
+ * const provider = createGeminiProvider({ apiKey: 'AI...' });
+ *
+ * // With custom model
+ * const provider = createGeminiProvider({ model: 'gemini-1.5-pro' });
+ *
+ * // Available models:
+ * // - gemini-2.0-flash (default, fast)
+ * // - gemini-1.5-flash (faster, cheaper)
+ * // - gemini-1.5-pro (more capable)
+ * ```
+ */
+export function createGeminiProvider(config = {}) {
+    return new GeminiProvider(config);
+}

package/dist/providers/index.d.ts

@@ -6,3 +6,11 @@ export { MockProvider, createMockProvider } from './mock.js';
 export type { MockProviderConfig, MockResponse, MockToolCall } from './mock.js';
 export { ClaudeProvider, createClaudeProvider } from './claude.js';
 export type { ClaudeProviderConfig } from './claude.js';
+export { OllamaProvider, createOllamaProvider } from './ollama.js';
+export type { OllamaProviderConfig } from './ollama.js';
+export { OpenAICompatibleProvider } from './openai-compatible.js';
+export type { OpenAICompatibleConfig, OpenAIMessage, OpenAIToolCall, OpenAITool, OpenAIStreamChunk, } from './openai-compatible.js';
+export { OpenAIProvider, createOpenAIProvider } from './openai.js';
+export type { OpenAIProviderConfig } from './openai.js';
+export { GeminiProvider, createGeminiProvider } from './gemini.js';
+export type { GeminiProviderConfig } from './gemini.js';

package/dist/providers/index.js

@@ -6,6 +6,10 @@ export * from './types.js';
 export { MockProvider, createMockProvider } from './mock.js';
 // Provider implementations
 export { ClaudeProvider, createClaudeProvider } from './claude.js';
-// Future providers
-// export { OpenAIProvider } from './openai.js';
-// export { GeminiProvider } from './gemini.js';
+export { OllamaProvider, createOllamaProvider } from './ollama.js';
+// Base class for OpenAI-compatible providers
+export { OpenAICompatibleProvider } from './openai-compatible.js';
+// OpenAI provider
+export { OpenAIProvider, createOpenAIProvider } from './openai.js';
+// Gemini provider
+export { GeminiProvider, createGeminiProvider } from './gemini.js';

package/dist/providers/mock.js

@@ -185,6 +185,14 @@ export class MockProvider {
                     if (block.type === 'text') {
                         charCount += block.text.length;
                     }
+                    else if (block.type === 'tool_result') {
+                        // Count tool result content (always a string per our type definition)
+                        charCount += block.content.length;
+                    }
+                    else if (block.type === 'tool_use') {
+                        // Count tool use input
+                        charCount += JSON.stringify(block.input).length;
+                    }
                 }
             }
         }

package/dist/providers/ollama.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Ollama LLM Provider
+ *
+ * Implements LLMProvider interface for local Ollama models.
+ * Extends OpenAICompatibleProvider for shared functionality.
+ *
+ * @example
+ * ```typescript
+ * const provider = createOllamaProvider({
+ *   model: 'llama3.1',
+ *   baseUrl: 'http://localhost:11434'
+ * });
+ * ```
+ *
+ * @remarks
+ * - Requires Ollama to be running locally
+ * - Default model is llama3.1 (supports tool calling)
+ * - 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 OllamaProvider
+ */
+export interface OllamaProviderConfig {
+    /** Base URL for Ollama server (default: http://localhost:11434) */
+    baseUrl?: string;
+    /** Default model to use (default: llama3.1) */
+    model?: string;
+    /** Default max tokens (default: 4096) */
+    maxTokens?: number;
+    /** Request timeout in milliseconds (default: 120000) */
+    timeout?: number;
+    /** Keep alive duration for model in memory (default: '5m') */
+    keepAlive?: string;
+}
+/**
+ * Ollama LLM Provider
+ *
+ * Provides streaming chat completion using local Ollama models.
+ * Supports tool calling with compatible models (llama3.1, mistral, etc.)
+ */
+export declare class OllamaProvider extends OpenAICompatibleProvider {
+    readonly name = "ollama";
+    private readonly keepAlive;
+    constructor(config?: OllamaProviderConfig);
+    /**
+     * Ollama has no authentication by default
+     */
+    protected getAuthHeaders(): Record<string, string>;
+    /**
+     * Ollama's OpenAI-compatible endpoint
+     */
+    protected getEndpointPath(): string;
+    /**
+     * Add Ollama-specific request options
+     */
+    protected buildProviderSpecificBody(options?: ChatOptions): Record<string, unknown>;
+    /**
+     * Map HTTP errors with Ollama-specific messages
+     */
+    protected mapHttpError(status: number, body: string, model: string): ProviderError;
+    /**
+     * Map connection errors with Ollama-specific messages
+     */
+    protected mapConnectionError(_error: Error): ProviderError;
+}
+/**
+ * Create an Ollama provider instance
+ *
+ * @example
+ * ```typescript
+ * // Default configuration (llama3.1 on localhost:11434)
+ * const provider = createOllamaProvider();
+ *
+ * // Custom model
+ * const provider = createOllamaProvider({ model: 'mistral' });
+ *
+ * // Custom server
+ * const provider = createOllamaProvider({
+ *   baseUrl: 'http://192.168.1.100:11434',
+ *   model: 'llama3.1:70b'
+ * });
+ * ```
+ */
+export declare function createOllamaProvider(config?: OllamaProviderConfig): OllamaProvider;

package/dist/providers/ollama.js

@@ -0,0 +1,133 @@
+/**
+ * Ollama LLM Provider
+ *
+ * Implements LLMProvider interface for local Ollama models.
+ * Extends OpenAICompatibleProvider for shared functionality.
+ *
+ * @example
+ * ```typescript
+ * const provider = createOllamaProvider({
+ *   model: 'llama3.1',
+ *   baseUrl: 'http://localhost:11434'
+ * });
+ * ```
+ *
+ * @remarks
+ * - Requires Ollama to be running locally
+ * - Default model is llama3.1 (supports tool calling)
+ * - Extended thinking is not supported (Claude-specific feature)
+ */
+import { ProviderError } from '../errors.js';
+import { OpenAICompatibleProvider } from './openai-compatible.js';
+// Default configuration
+const DEFAULT_MODEL = 'llama3.1';
+const DEFAULT_BASE_URL = 'http://localhost:11434';
+/**
+ * Ollama LLM Provider
+ *
+ * Provides streaming chat completion using local Ollama models.
+ * Supports tool calling with compatible models (llama3.1, mistral, etc.)
+ */
+export class OllamaProvider extends OpenAICompatibleProvider {
+    name = 'ollama';
+    keepAlive;
+    constructor(config = {}) {
+        const baseConfig = {
+            baseUrl: config.baseUrl ?? DEFAULT_BASE_URL,
+            model: config.model ?? DEFAULT_MODEL,
+            maxTokens: config.maxTokens,
+            timeout: config.timeout,
+        };
+        super(baseConfig);
+        this.keepAlive = config.keepAlive ?? '5m';
+    }
+    /**
+     * Ollama has no authentication by default
+     */
+    getAuthHeaders() {
+        return {};
+    }
+    /**
+     * Ollama's OpenAI-compatible endpoint
+     */
+    getEndpointPath() {
+        return '/v1/chat/completions';
+    }
+    /**
+     * Add Ollama-specific request options
+     */
+    buildProviderSpecificBody(options) {
+        const body = {
+            keep_alive: this.keepAlive,
+        };
+        // Ollama uses 'options' wrapper for model parameters
+        const modelOptions = {};
+        if (options?.maxTokens !== undefined) {
+            modelOptions.num_predict = options.maxTokens;
+        }
+        if (options?.temperature !== undefined) {
+            modelOptions.temperature = options.temperature;
+        }
+        if (Object.keys(modelOptions).length > 0) {
+            body.options = modelOptions;
+        }
+        return body;
+    }
+    /**
+     * Map HTTP errors with Ollama-specific messages
+     */
+    mapHttpError(status, body, model) {
+        let message = `Ollama error (${String(status)})`;
+        try {
+            const parsed = JSON.parse(body);
+            if (typeof parsed.error === 'string') {
+                message = parsed.error;
+            }
+            else if (parsed.error?.message) {
+                message = parsed.error.message;
+            }
+        }
+        catch {
+            message = body || message;
+        }
+        switch (status) {
+            case 404:
+                return new ProviderError(`Model "${model}" not found. Run: ollama pull ${model}`, 'ollama', 404);
+            case 429:
+                return new ProviderError('Rate limited', 'ollama', 429);
+            case 500:
+            case 502:
+            case 503:
+                return new ProviderError(message, 'ollama', status);
+            default:
+                return new ProviderError(message, 'ollama', status);
+        }
+    }
+    /**
+     * Map connection errors with Ollama-specific messages
+     */
+    mapConnectionError(_error) {
+        return new ProviderError(`Failed to connect to Ollama at ${this.baseUrl}. Is Ollama running? Try: ollama serve`, 'ollama');
+    }
+}
+/**
+ * Create an Ollama provider instance
+ *
+ * @example
+ * ```typescript
+ * // Default configuration (llama3.1 on localhost:11434)
+ * const provider = createOllamaProvider();
+ *
+ * // Custom model
+ * const provider = createOllamaProvider({ model: 'mistral' });
+ *
+ * // Custom server
+ * const provider = createOllamaProvider({
+ *   baseUrl: 'http://192.168.1.100:11434',
+ *   model: 'llama3.1:70b'
+ * });
+ * ```
+ */
+export function createOllamaProvider(config = {}) {
+    return new OllamaProvider(config);
+}

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>;
+}