@compilr-dev/agents 0.3.1 → 0.3.4

package/dist/providers/gemini-native.js

@@ -0,0 +1,374 @@
+/**
+ * GeminiNativeProvider - Native Google Gen AI SDK implementation
+ *
+ * Uses the native @google/genai SDK instead of OpenAI-compatible endpoint.
+ * This enables proper support for Gemini 3 models with thought signatures.
+ *
+ * @example
+ * ```typescript
+ * const provider = new GeminiNativeProvider({
+ *   apiKey: process.env.GOOGLE_AI_API_KEY,
+ * });
+ *
+ * const agent = new Agent({ provider });
+ * ```
+ */
+import { GoogleGenAI } from '@google/genai';
+import { ProviderError } from '../errors.js';
+/**
+ * Default model for Gemini API
+ */
+const DEFAULT_MODEL = 'gemini-2.5-flash';
+/**
+ * Default max tokens
+ */
+const DEFAULT_MAX_TOKENS = 4096;
+/**
+ * GeminiNativeProvider implements LLMProvider using the native Google Gen AI SDK
+ *
+ * Benefits over OpenAI-compatible endpoint:
+ * - Automatic thought signature handling for Gemini 3
+ * - Native streaming support
+ * - Full access to Gemini-specific features
+ */
+export class GeminiNativeProvider {
+    name = 'gemini';
+    client;
+    defaultModel;
+    defaultMaxTokens;
+    constructor(config) {
+        this.client = new GoogleGenAI({ apiKey: config.apiKey });
+        this.defaultModel = config.model ?? DEFAULT_MODEL;
+        this.defaultMaxTokens = config.maxTokens ?? DEFAULT_MAX_TOKENS;
+    }
+    /**
+     * Send messages and stream the response
+     */
+    async *chat(messages, options) {
+        const { systemInstruction, contents } = this.convertMessages(messages);
+        const tools = this.convertTools(options?.tools);
+        const model = options?.model ?? this.defaultModel;
+        // Calculate payload sizes for debugging
+        const debugPayload = {
+            systemChars: systemInstruction?.length ?? 0,
+            contentsChars: JSON.stringify(contents).length,
+            toolsChars: JSON.stringify(tools).length,
+        };
+        try {
+            // Build config
+            const config = {
+                systemInstruction,
+                maxOutputTokens: options?.maxTokens ?? this.defaultMaxTokens,
+                temperature: options?.temperature,
+                stopSequences: options?.stopSequences,
+            };
+            // Add tools if any
+            if (tools.length > 0) {
+                config.tools = [{ functionDeclarations: tools }];
+            }
+            // Request streaming response
+            const streamResponse = await this.client.models.generateContentStream({
+                model,
+                contents,
+                config,
+            });
+            // Track state for tool calls
+            let currentToolId = '';
+            let currentToolName = '';
+            let toolInputJson = '';
+            let inThinkingBlock = false;
+            // Track the last usage metadata (Gemini sends it in EVERY chunk, not just the final one)
+            let lastUsageMetadata;
+            // Process stream chunks
+            for await (const chunk of streamResponse) {
+                const streamChunks = this.processChunk(chunk, currentToolId, currentToolName, toolInputJson, inThinkingBlock);
+                for (const streamChunk of streamChunks) {
+                    // Update tracking state
+                    if (streamChunk.type === 'tool_use_start' && streamChunk.toolUse) {
+                        currentToolId = streamChunk.toolUse.id;
+                        currentToolName = streamChunk.toolUse.name;
+                        toolInputJson = '';
+                    }
+                    else if (streamChunk.type === 'tool_use_delta' && streamChunk.text) {
+                        toolInputJson += streamChunk.text;
+                    }
+                    else if (streamChunk.type === 'tool_use_end') {
+                        currentToolId = '';
+                        currentToolName = '';
+                        toolInputJson = '';
+                    }
+                    else if (streamChunk.type === 'thinking_start') {
+                        inThinkingBlock = true;
+                    }
+                    else if (streamChunk.type === 'thinking_end') {
+                        inThinkingBlock = false;
+                    }
+                    yield streamChunk;
+                }
+                // Track usage metadata (update on every chunk, yield only once at end)
+                if (chunk.usageMetadata) {
+                    lastUsageMetadata = chunk.usageMetadata;
+                }
+            }
+            // Yield 'done' only ONCE after stream completes with the final usage
+            if (lastUsageMetadata) {
+                yield {
+                    type: 'done',
+                    model,
+                    usage: {
+                        inputTokens: lastUsageMetadata.promptTokenCount ?? 0,
+                        outputTokens: lastUsageMetadata.candidatesTokenCount ?? 0,
+                        // Gemini 2.5+ models report thinking tokens separately
+                        ...(lastUsageMetadata.thoughtsTokenCount
+                            ? { thinkingTokens: lastUsageMetadata.thoughtsTokenCount }
+                            : {}),
+                        // Gemini reports cached content tokens
+                        ...(lastUsageMetadata.cachedContentTokenCount
+                            ? { cacheReadTokens: lastUsageMetadata.cachedContentTokenCount }
+                            : {}),
+                        // Debug payload info
+                        debugPayload,
+                    },
+                };
+            }
+        }
+        catch (error) {
+            throw this.mapError(error);
+        }
+    }
+    /**
+     * Count tokens in messages (approximation)
+     */
+    countTokens(messages) {
+        // Approximation: ~4 characters per token
+        let charCount = 0;
+        for (const msg of messages) {
+            if (typeof msg.content === 'string') {
+                charCount += msg.content.length;
+            }
+            else {
+                for (const block of msg.content) {
+                    switch (block.type) {
+                        case 'text':
+                            charCount += block.text.length;
+                            break;
+                        case 'tool_use':
+                            charCount += JSON.stringify(block.input).length;
+                            break;
+                        case 'tool_result':
+                            charCount += block.content.length;
+                            break;
+                    }
+                }
+            }
+        }
+        return Promise.resolve(Math.ceil(charCount / 4));
+    }
+    /**
+     * Convert our Message format to Google's format
+     */
+    convertMessages(messages) {
+        let systemInstruction;
+        const contents = [];
+        for (const msg of messages) {
+            if (msg.role === 'system') {
+                // Google uses systemInstruction in config, not a message
+                systemInstruction = typeof msg.content === 'string' ? msg.content : '';
+            }
+            else {
+                // user → user, assistant → model
+                const role = msg.role === 'assistant' ? 'model' : 'user';
+                const parts = this.convertContent(msg.content);
+                contents.push({ role, parts });
+            }
+        }
+        return { systemInstruction, contents };
+    }
+    /**
+     * Convert content to Google's Part format
+     */
+    convertContent(content) {
+        if (typeof content === 'string') {
+            return [{ text: content }];
+        }
+        const parts = [];
+        for (const block of content) {
+            switch (block.type) {
+                case 'text':
+                    parts.push({ text: block.text });
+                    break;
+                case 'tool_use':
+                    // Convert to functionCall with thought signature if present
+                    // Gemini 3 requires thought signatures on function calls
+                    // Note: No 'id' field - Gemini uses 'name' for matching
+                    parts.push({
+                        functionCall: {
+                            name: block.name,
+                            args: block.input,
+                        },
+                        // Include thought signature if present (required for Gemini 3)
+                        ...(block.signature ? { thoughtSignature: block.signature } : {}),
+                    });
+                    break;
+                case 'tool_result': {
+                    // Convert to functionResponse
+                    // block.content is a JSON string from the agent - parse it for the API
+                    let responseData;
+                    try {
+                        responseData = JSON.parse(block.content);
+                    }
+                    catch {
+                        // If not valid JSON, wrap the string in a result object
+                        responseData = { result: block.content };
+                    }
+                    parts.push({
+                        functionResponse: {
+                            // Note: No 'id' field - Gemini matches by 'name' only
+                            name: this.extractToolName(content, block.toolUseId),
+                            response: responseData,
+                        },
+                    });
+                    break;
+                }
+                case 'thinking':
+                    // Thinking blocks should NOT be sent back to Gemini.
+                    // They are internal model reasoning. Only the signature on function calls matters.
+                    // Skip - do not add to parts.
+                    break;
+                default: {
+                    // Exhaustive check
+                    const _exhaustive = block;
+                    throw new Error(`Unknown content block type: ${_exhaustive.type}`);
+                }
+            }
+        }
+        return parts;
+    }
+    /**
+     * Extract tool name from tool_use block that matches the given toolUseId
+     */
+    extractToolName(content, toolUseId) {
+        for (const block of content) {
+            if (block.type === 'tool_use' && block.id === toolUseId) {
+                return block.name;
+            }
+        }
+        // Fallback if not found in same message - this shouldn't happen normally
+        return 'unknown_function';
+    }
+    /**
+     * Convert our ToolDefinition to Google's FunctionDeclaration format
+     */
+    convertTools(tools) {
+        if (!tools || tools.length === 0) {
+            return [];
+        }
+        return tools.map((tool) => ({
+            name: tool.name,
+            description: tool.description,
+            // Use parametersJsonSchema for raw JSON schema (more flexible than typed Schema)
+            parametersJsonSchema: {
+                type: 'object',
+                properties: tool.inputSchema.properties,
+                required: tool.inputSchema.required,
+            },
+        }));
+    }
+    /**
+     * Process a streaming chunk into StreamChunks
+     */
+    processChunk(chunk, _currentToolId, _currentToolName, _toolInputJson, inThinkingBlock) {
+        const chunks = [];
+        // Get the first candidate's content
+        const candidate = chunk.candidates?.[0];
+        if (!candidate?.content?.parts) {
+            return chunks;
+        }
+        for (const part of candidate.content.parts) {
+            // Text content
+            if (part.text !== undefined && !part.thought) {
+                chunks.push({
+                    type: 'text',
+                    text: part.text,
+                });
+            }
+            // Thinking content (Gemini 3)
+            if (part.thought && part.text !== undefined) {
+                if (!inThinkingBlock) {
+                    chunks.push({ type: 'thinking_start' });
+                }
+                chunks.push({
+                    type: 'thinking_delta',
+                    text: part.text,
+                    thinking: {
+                        thinking: part.text,
+                        signature: part.thoughtSignature,
+                    },
+                });
+            }
+            // Function call
+            if (part.functionCall) {
+                const funcCall = part.functionCall;
+                const toolId = funcCall.id ?? `tool_${String(Date.now())}_${Math.random().toString(36).slice(2, 9)}`;
+                // Capture thought signature if present (Gemini 3 attaches it to function calls)
+                // Note: thoughtSignature is not in the SDK types yet but exists on the response
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access
+                const signature = part.thoughtSignature;
+                chunks.push({
+                    type: 'tool_use_start',
+                    toolUse: {
+                        id: toolId,
+                        name: funcCall.name ?? 'unknown',
+                        signature, // Pass through the thought signature
+                    },
+                });
+                // Emit the arguments as delta
+                if (funcCall.args) {
+                    chunks.push({
+                        type: 'tool_use_delta',
+                        text: JSON.stringify(funcCall.args),
+                    });
+                }
+                chunks.push({ type: 'tool_use_end' });
+            }
+        }
+        // Check for finish reason to end thinking block
+        if (inThinkingBlock && candidate.finishReason) {
+            chunks.push({ type: 'thinking_end' });
+        }
+        return chunks;
+    }
+    /**
+     * Map errors to ProviderError
+     */
+    mapError(error) {
+        if (error instanceof Error) {
+            const message = error.message;
+            // Check for common error patterns
+            if (message.includes('API key')) {
+                return new ProviderError('Invalid Gemini API key. Check your GOOGLE_AI_API_KEY or GEMINI_API_KEY.', 'gemini', 401, error);
+            }
+            if (message.includes('rate limit') || message.includes('429')) {
+                return new ProviderError('Gemini rate limit exceeded. Please wait and try again.', 'gemini', 429, error);
+            }
+            if (message.includes('not found') || message.includes('404')) {
+                return new ProviderError(`Gemini model not found: ${message}`, 'gemini', 404, error);
+            }
+            return new ProviderError(message, 'gemini', undefined, error);
+        }
+        return new ProviderError(String(error), 'gemini');
+    }
+}
+/**
+ * Create a GeminiNativeProvider with API key from environment
+ */
+export function createGeminiNativeProvider(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');
+    }
+    return new GeminiNativeProvider({
+        ...config,
+        apiKey,
+    });
+}

package/dist/providers/groq.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Groq LLM Provider
+ *
+ * Implements LLMProvider interface for Groq models.
+ * Extends OpenAICompatibleProvider for shared functionality.
+ *
+ * @example
+ * ```typescript
+ * const provider = createGroqProvider({
+ *   model: 'llama-3.2-90b-vision-preview',
+ *   apiKey: process.env.GROQ_API_KEY
+ * });
+ * ```
+ *
+ * @remarks
+ * - Requires valid Groq API key
+ * - Default model is llama-3.2-8b-preview
+ * - Known for extremely fast inference speeds
+ */
+import type { ChatOptions } from './types.js';
+import { ProviderError } from '../errors.js';
+import { OpenAICompatibleProvider } from './openai-compatible.js';
+/**
+ * Configuration for GroqProvider
+ */
+export interface GroqProviderConfig {
+    /** Groq API key (falls back to GROQ_API_KEY env var) */
+    apiKey?: string;
+    /** Base URL for Groq API (default: https://api.groq.com/openai) */
+    baseUrl?: string;
+    /** Default model to use (default: llama-3.2-8b-preview) */
+    model?: string;
+    /** Default max tokens (default: 4096) */
+    maxTokens?: number;
+    /** Request timeout in milliseconds (default: 120000) */
+    timeout?: number;
+}
+/**
+ * Groq LLM Provider
+ *
+ * Provides streaming chat completion using Groq's ultra-fast inference.
+ * Supports Llama, Mixtral, and other models optimized for speed.
+ */
+export declare class GroqProvider extends OpenAICompatibleProvider {
+    readonly name = "groq";
+    private readonly apiKey;
+    constructor(config?: GroqProviderConfig);
+    /**
+     * Groq authentication with Bearer token
+     */
+    protected getAuthHeaders(): Record<string, string>;
+    /**
+     * Groq chat completions endpoint (OpenAI-compatible)
+     */
+    protected getEndpointPath(): string;
+    /**
+     * Groq uses standard OpenAI body format
+     */
+    protected buildProviderSpecificBody(_options?: ChatOptions): Record<string, unknown>;
+    /**
+     * Map HTTP errors with Groq-specific messages
+     */
+    protected mapHttpError(status: number, body: string, _model: string): ProviderError;
+    /**
+     * Map connection errors with Groq-specific messages
+     */
+    protected mapConnectionError(_error: Error): ProviderError;
+}
+/**
+ * Create a Groq provider instance
+ *
+ * @example
+ * ```typescript
+ * // Using environment variable (GROQ_API_KEY)
+ * const provider = createGroqProvider();
+ *
+ * // With explicit API key
+ * const provider = createGroqProvider({ apiKey: 'gsk_...' });
+ *
+ * // With custom model
+ * const provider = createGroqProvider({
+ *   model: 'llama-3.2-90b-vision-preview'
+ * });
+ * ```
+ */
+export declare function createGroqProvider(config?: GroqProviderConfig): GroqProvider;

package/dist/providers/groq.js

@@ -0,0 +1,123 @@
+/**
+ * Groq LLM Provider
+ *
+ * Implements LLMProvider interface for Groq models.
+ * Extends OpenAICompatibleProvider for shared functionality.
+ *
+ * @example
+ * ```typescript
+ * const provider = createGroqProvider({
+ *   model: 'llama-3.2-90b-vision-preview',
+ *   apiKey: process.env.GROQ_API_KEY
+ * });
+ * ```
+ *
+ * @remarks
+ * - Requires valid Groq API key
+ * - Default model is llama-3.2-8b-preview
+ * - Known for extremely fast inference speeds
+ */
+import { ProviderError } from '../errors.js';
+import { OpenAICompatibleProvider } from './openai-compatible.js';
+// Default configuration
+const DEFAULT_MODEL = 'llama-3.2-8b-preview';
+const DEFAULT_BASE_URL = 'https://api.groq.com/openai';
+/**
+ * Groq LLM Provider
+ *
+ * Provides streaming chat completion using Groq's ultra-fast inference.
+ * Supports Llama, Mixtral, and other models optimized for speed.
+ */
+export class GroqProvider extends OpenAICompatibleProvider {
+    name = 'groq';
+    apiKey;
+    constructor(config = {}) {
+        const apiKey = config.apiKey ?? process.env.GROQ_API_KEY;
+        if (!apiKey) {
+            throw new ProviderError('Groq API key not found. Set GROQ_API_KEY environment variable or pass apiKey in config.', 'groq');
+        }
+        const baseConfig = {
+            baseUrl: config.baseUrl ?? DEFAULT_BASE_URL,
+            model: config.model ?? DEFAULT_MODEL,
+            maxTokens: config.maxTokens,
+            timeout: config.timeout,
+        };
+        super(baseConfig);
+        this.apiKey = apiKey;
+    }
+    /**
+     * Groq authentication with Bearer token
+     */
+    getAuthHeaders() {
+        return {
+            Authorization: `Bearer ${this.apiKey}`,
+        };
+    }
+    /**
+     * Groq chat completions endpoint (OpenAI-compatible)
+     */
+    getEndpointPath() {
+        return '/v1/chat/completions';
+    }
+    /**
+     * Groq uses standard OpenAI body format
+     */
+    buildProviderSpecificBody(_options) {
+        return {};
+    }
+    /**
+     * Map HTTP errors with Groq-specific messages
+     */
+    mapHttpError(status, body, _model) {
+        let message = `Groq error (${String(status)})`;
+        try {
+            const parsed = JSON.parse(body);
+            if (parsed.error?.message) {
+                message = parsed.error.message;
+            }
+        }
+        catch {
+            message = body || message;
+        }
+        switch (status) {
+            case 401:
+                return new ProviderError('Invalid Groq API key. Check your GROQ_API_KEY.', 'groq', 401);
+            case 403:
+                return new ProviderError('Access denied. Check your Groq API key permissions.', 'groq', 403);
+            case 429:
+                return new ProviderError('Groq rate limit exceeded. Please wait and try again.', 'groq', 429);
+            case 500:
+            case 502:
+            case 503:
+                return new ProviderError('Groq service temporarily unavailable. Please try again later.', 'groq', status);
+            default:
+                return new ProviderError(message, 'groq', status);
+        }
+    }
+    /**
+     * Map connection errors with Groq-specific messages
+     */
+    mapConnectionError(_error) {
+        return new ProviderError('Failed to connect to Groq API. Check your internet connection.', 'groq');
+    }
+}
+/**
+ * Create a Groq provider instance
+ *
+ * @example
+ * ```typescript
+ * // Using environment variable (GROQ_API_KEY)
+ * const provider = createGroqProvider();
+ *
+ * // With explicit API key
+ * const provider = createGroqProvider({ apiKey: 'gsk_...' });
+ *
+ * // With custom model
+ * const provider = createGroqProvider({
+ *   model: 'llama-3.2-90b-vision-preview'
+ * });
+ * ```
+ */
+export function createGroqProvider(config = {}) {
+    return new GroqProvider(config);
+}

package/dist/providers/index.d.ts

@@ -12,5 +12,20 @@ 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';
+export { GeminiProvider as GeminiLegacyProvider, createGeminiProvider as createGeminiLegacyProvider, } from './gemini.js';
+export type { GeminiProviderConfig as GeminiLegacyProviderConfig } from './gemini.js';
+export { GeminiNativeProvider, createGeminiNativeProvider } from './gemini-native.js';
+export type { GeminiNativeProviderConfig } from './gemini-native.js';
+export { GeminiNativeProvider as GeminiProvider } from './gemini-native.js';
+export { createGeminiNativeProvider as createGeminiProvider } from './gemini-native.js';
+export type { GeminiNativeProviderConfig as GeminiProviderConfig } from './gemini-native.js';
+export { TogetherProvider, createTogetherProvider } from './together.js';
+export type { TogetherProviderConfig } from './together.js';
+export { GroqProvider, createGroqProvider } from './groq.js';
+export type { GroqProviderConfig } from './groq.js';
+export { FireworksProvider, createFireworksProvider } from './fireworks.js';
+export type { FireworksProviderConfig } from './fireworks.js';
+export { PerplexityProvider, createPerplexityProvider } from './perplexity.js';
+export type { PerplexityProviderConfig } from './perplexity.js';
+export { OpenRouterProvider, createOpenRouterProvider } from './openrouter.js';
+export type { OpenRouterProviderConfig } from './openrouter.js';

package/dist/providers/index.js

@@ -11,5 +11,16 @@ export { OllamaProvider, createOllamaProvider } from './ollama.js';
 export { OpenAICompatibleProvider } from './openai-compatible.js';
 // OpenAI provider
 export { OpenAIProvider, createOpenAIProvider } from './openai.js';
-// Gemini provider
-export { GeminiProvider, createGeminiProvider } from './gemini.js';
+// Gemini provider (legacy OpenAI-compatible endpoint)
+export { GeminiProvider as GeminiLegacyProvider, createGeminiProvider as createGeminiLegacyProvider, } from './gemini.js';
+// Gemini native provider (recommended - supports Gemini 3 thought signatures)
+export { GeminiNativeProvider, createGeminiNativeProvider } from './gemini-native.js';
+// Re-export native as default Gemini provider
+export { GeminiNativeProvider as GeminiProvider } from './gemini-native.js';
+export { createGeminiNativeProvider as createGeminiProvider } from './gemini-native.js';
+// "Others" providers - OpenAI-compatible cloud APIs
+export { TogetherProvider, createTogetherProvider } from './together.js';
+export { GroqProvider, createGroqProvider } from './groq.js';
+export { FireworksProvider, createFireworksProvider } from './fireworks.js';
+export { PerplexityProvider, createPerplexityProvider } from './perplexity.js';
+export { OpenRouterProvider, createOpenRouterProvider } from './openrouter.js';

package/dist/providers/openai-compatible.js

@@ -57,6 +57,15 @@ export class OpenAICompatibleProvider {
         const openaiMessages = this.convertMessages(messages);
         // Convert tools if provided
         const tools = options?.tools ? this.convertTools(options.tools) : undefined;
+        // Calculate payload sizes for debugging
+        // Note: OpenAI format has system message in messages array, not separate
+        const systemMsg = openaiMessages.find((m) => m.role === 'system');
+        const systemChars = systemMsg && typeof systemMsg.content === 'string' ? systemMsg.content.length : 0;
+        const debugPayload = {
+            systemChars,
+            contentsChars: JSON.stringify(openaiMessages).length,
+            toolsChars: tools ? JSON.stringify(tools).length : 0,
+        };
         // Build request body
         const body = {
             model,
@@ -143,7 +152,9 @@ export class OpenAICompatibleProvider {
             // Yield done chunk with usage
             yield {
                 type: 'done',
-                usage,
+                usage: usage
+                    ? { ...usage, debugPayload }
+                    : { inputTokens: 0, outputTokens: 0, debugPayload },
             };
         }
         catch (error) {