@compilr-dev/agents 0.3.2 → 0.3.5

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

@@ -19,3 +19,13 @@ 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

@@ -18,3 +18,9 @@ export { GeminiNativeProvider, createGeminiNativeProvider } from './gemini-nativ
 // 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) {

package/dist/providers/openrouter.d.ts

@@ -0,0 +1,95 @@
+/**
+ * OpenRouter LLM Provider
+ *
+ * Implements LLMProvider interface for OpenRouter's unified API.
+ * Extends OpenAICompatibleProvider for shared functionality.
+ *
+ * @example
+ * ```typescript
+ * const provider = createOpenRouterProvider({
+ *   model: 'anthropic/claude-3.5-sonnet',
+ *   apiKey: process.env.OPENROUTER_API_KEY
+ * });
+ * ```
+ *
+ * @remarks
+ * - Requires valid OpenRouter API key
+ * - Default model is meta-llama/llama-3.1-8b-instruct
+ * - Provides access to 100+ models from multiple providers
+ * - Includes custom headers for ranking and attribution
+ */
+import type { ChatOptions } from './types.js';
+import { ProviderError } from '../errors.js';
+import { OpenAICompatibleProvider } from './openai-compatible.js';
+/**
+ * Configuration for OpenRouterProvider
+ */
+export interface OpenRouterProviderConfig {
+    /** OpenRouter API key (falls back to OPENROUTER_API_KEY env var) */
+    apiKey?: string;
+    /** Base URL for OpenRouter API (default: https://openrouter.ai/api) */
+    baseUrl?: string;
+    /** Default model to use (default: meta-llama/llama-3.1-8b-instruct) */
+    model?: string;
+    /** Default max tokens (default: 4096) */
+    maxTokens?: number;
+    /** Request timeout in milliseconds (default: 120000) */
+    timeout?: number;
+    /** Site URL for OpenRouter rankings (optional) */
+    siteUrl?: string;
+    /** Site name for OpenRouter rankings (optional) */
+    siteName?: string;
+}
+/**
+ * OpenRouter LLM Provider
+ *
+ * Provides streaming chat completion via OpenRouter's unified API.
+ * Access 100+ models from Claude, GPT, Llama, Mistral, and more.
+ */
+export declare class OpenRouterProvider extends OpenAICompatibleProvider {
+    readonly name = "openrouter";
+    private readonly apiKey;
+    private readonly siteUrl?;
+    private readonly siteName?;
+    constructor(config?: OpenRouterProviderConfig);
+    /**
+     * OpenRouter authentication with Bearer token and custom headers
+     */
+    protected getAuthHeaders(): Record<string, string>;
+    /**
+     * OpenRouter chat completions endpoint (OpenAI-compatible)
+     */
+    protected getEndpointPath(): string;
+    /**
+     * OpenRouter uses standard OpenAI body format
+     */
+    protected buildProviderSpecificBody(_options?: ChatOptions): Record<string, unknown>;
+    /**
+     * Map HTTP errors with OpenRouter-specific messages
+     */
+    protected mapHttpError(status: number, body: string, _model: string): ProviderError;
+    /**
+     * Map connection errors with OpenRouter-specific messages
+     */
+    protected mapConnectionError(_error: Error): ProviderError;
+}
+/**
+ * Create an OpenRouter provider instance
+ *
+ * @example
+ * ```typescript
+ * // Using environment variable (OPENROUTER_API_KEY)
+ * const provider = createOpenRouterProvider();
+ *
+ * // With explicit API key
+ * const provider = createOpenRouterProvider({ apiKey: 'sk-or-...' });
+ *
+ * // With custom model and site attribution
+ * const provider = createOpenRouterProvider({
+ *   model: 'anthropic/claude-3.5-sonnet',
+ *   siteUrl: 'https://myapp.com',
+ *   siteName: 'My App'
+ * });
+ * ```
+ */
+export declare function createOpenRouterProvider(config?: OpenRouterProviderConfig): OpenRouterProvider;

package/dist/providers/openrouter.js

@@ -0,0 +1,138 @@
+/**
+ * OpenRouter LLM Provider
+ *
+ * Implements LLMProvider interface for OpenRouter's unified API.
+ * Extends OpenAICompatibleProvider for shared functionality.
+ *
+ * @example
+ * ```typescript
+ * const provider = createOpenRouterProvider({
+ *   model: 'anthropic/claude-3.5-sonnet',
+ *   apiKey: process.env.OPENROUTER_API_KEY
+ * });
+ * ```
+ *
+ * @remarks
+ * - Requires valid OpenRouter API key
+ * - Default model is meta-llama/llama-3.1-8b-instruct
+ * - Provides access to 100+ models from multiple providers
+ * - Includes custom headers for ranking and attribution
+ */
+import { ProviderError } from '../errors.js';
+import { OpenAICompatibleProvider } from './openai-compatible.js';
+// Default configuration
+const DEFAULT_MODEL = 'meta-llama/llama-3.1-8b-instruct';
+const DEFAULT_BASE_URL = 'https://openrouter.ai/api';
+/**
+ * OpenRouter LLM Provider
+ *
+ * Provides streaming chat completion via OpenRouter's unified API.
+ * Access 100+ models from Claude, GPT, Llama, Mistral, and more.
+ */
+export class OpenRouterProvider extends OpenAICompatibleProvider {
+    name = 'openrouter';
+    apiKey;
+    siteUrl;
+    siteName;
+    constructor(config = {}) {
+        const apiKey = config.apiKey ?? process.env.OPENROUTER_API_KEY;
+        if (!apiKey) {
+            throw new ProviderError('OpenRouter API key not found. Set OPENROUTER_API_KEY environment variable or pass apiKey in config.', 'openrouter');
+        }
+        const baseConfig = {
+            baseUrl: config.baseUrl ?? DEFAULT_BASE_URL,
+            model: config.model ?? DEFAULT_MODEL,
+            maxTokens: config.maxTokens,
+            timeout: config.timeout,
+        };
+        super(baseConfig);
+        this.apiKey = apiKey;
+        this.siteUrl = config.siteUrl;
+        this.siteName = config.siteName;
+    }
+    /**
+     * OpenRouter authentication with Bearer token and custom headers
+     */
+    getAuthHeaders() {
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+        };
+        // OpenRouter-specific headers for ranking and attribution
+        if (this.siteUrl) {
+            headers['HTTP-Referer'] = this.siteUrl;
+        }
+        if (this.siteName) {
+            headers['X-Title'] = this.siteName;
+        }
+        return headers;
+    }
+    /**
+     * OpenRouter chat completions endpoint (OpenAI-compatible)
+     */
+    getEndpointPath() {
+        return '/v1/chat/completions';
+    }
+    /**
+     * OpenRouter uses standard OpenAI body format
+     */
+    buildProviderSpecificBody(_options) {
+        return {};
+    }
+    /**
+     * Map HTTP errors with OpenRouter-specific messages
+     */
+    mapHttpError(status, body, _model) {
+        let message = `OpenRouter 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 OpenRouter API key. Check your OPENROUTER_API_KEY.', 'openrouter', 401);
+            case 403:
+                return new ProviderError('Access denied. Check your OpenRouter API key permissions or credits.', 'openrouter', 403);
+            case 429:
+                return new ProviderError('OpenRouter rate limit exceeded. Please wait and try again.', 'openrouter', 429);
+            case 500:
+            case 502:
+            case 503:
+                return new ProviderError('OpenRouter service temporarily unavailable. Please try again later.', 'openrouter', status);
+            default:
+                return new ProviderError(message, 'openrouter', status);
+        }
+    }
+    /**
+     * Map connection errors with OpenRouter-specific messages
+     */
+    mapConnectionError(_error) {
+        return new ProviderError('Failed to connect to OpenRouter API. Check your internet connection.', 'openrouter');
+    }
+}
+/**
+ * Create an OpenRouter provider instance
+ *
+ * @example
+ * ```typescript
+ * // Using environment variable (OPENROUTER_API_KEY)
+ * const provider = createOpenRouterProvider();
+ *
+ * // With explicit API key
+ * const provider = createOpenRouterProvider({ apiKey: 'sk-or-...' });
+ *
+ * // With custom model and site attribution
+ * const provider = createOpenRouterProvider({
+ *   model: 'anthropic/claude-3.5-sonnet',
+ *   siteUrl: 'https://myapp.com',
+ *   siteName: 'My App'
+ * });
+ * ```
+ */
+export function createOpenRouterProvider(config = {}) {
+    return new OpenRouterProvider(config);
+}

package/dist/providers/perplexity.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Perplexity LLM Provider
+ *
+ * Implements LLMProvider interface for Perplexity models.
+ * Extends OpenAICompatibleProvider for shared functionality.
+ *
+ * @example
+ * ```typescript
+ * const provider = createPerplexityProvider({
+ *   model: 'llama-3.1-sonar-large-128k-online',
+ *   apiKey: process.env.PERPLEXITY_API_KEY
+ * });
+ * ```
+ *
+ * @remarks
+ * - Requires valid Perplexity API key
+ * - Default model is llama-3.1-sonar-small-128k-online
+ * - Sonar models have built-in web search capabilities
+ */
+import type { ChatOptions } from './types.js';
+import { ProviderError } from '../errors.js';
+import { OpenAICompatibleProvider } from './openai-compatible.js';
+/**
+ * Configuration for PerplexityProvider
+ */
+export interface PerplexityProviderConfig {
+    /** Perplexity API key (falls back to PERPLEXITY_API_KEY env var) */
+    apiKey?: string;
+    /** Base URL for Perplexity API (default: https://api.perplexity.ai) */
+    baseUrl?: string;
+    /** Default model to use (default: llama-3.1-sonar-small-128k-online) */
+    model?: string;
+    /** Default max tokens (default: 4096) */
+    maxTokens?: number;
+    /** Request timeout in milliseconds (default: 120000) */
+    timeout?: number;
+}
+/**
+ * Perplexity LLM Provider
+ *
+ * Provides streaming chat completion using Perplexity's API.
+ * Sonar models include real-time web search capabilities.
+ */
+export declare class PerplexityProvider extends OpenAICompatibleProvider {
+    readonly name = "perplexity";
+    private readonly apiKey;
+    constructor(config?: PerplexityProviderConfig);
+    /**
+     * Perplexity authentication with Bearer token
+     */
+    protected getAuthHeaders(): Record<string, string>;
+    /**
+     * Perplexity chat completions endpoint (OpenAI-compatible)
+     */
+    protected getEndpointPath(): string;
+    /**
+     * Perplexity uses standard OpenAI body format
+     */
+    protected buildProviderSpecificBody(_options?: ChatOptions): Record<string, unknown>;
+    /**
+     * Map HTTP errors with Perplexity-specific messages
+     */
+    protected mapHttpError(status: number, body: string, _model: string): ProviderError;
+    /**
+     * Map connection errors with Perplexity-specific messages
+     */
+    protected mapConnectionError(_error: Error): ProviderError;
+}
+/**
+ * Create a Perplexity provider instance
+ *
+ * @example
+ * ```typescript
+ * // Using environment variable (PERPLEXITY_API_KEY)
+ * const provider = createPerplexityProvider();
+ *
+ * // With explicit API key
+ * const provider = createPerplexityProvider({ apiKey: 'pplx-...' });
+ *
+ * // With custom model (sonar models have web search)
+ * const provider = createPerplexityProvider({
+ *   model: 'llama-3.1-sonar-large-128k-online'
+ * });
+ * ```
+ */
+export declare function createPerplexityProvider(config?: PerplexityProviderConfig): PerplexityProvider;