import { BaseLlm as BaseLlm2 } from "@google/adk"; import { BaseLlmConnection, LlmRequest, LlmResponse as LlmResponse2 } from "@google/adk"; import { BaseLlm } from "@google/adk"; import { LlmResponse } from "@google/adk"; /** * Base configuration shared by all LLM providers. * * All provider-specific configurations extend this interface. * * @example * ```typescript * const config: BaseProviderConfig = { * model: "anthropic/claude-sonnet-4", * apiKey: "your-api-key", * timeout: 30000 * }; * ``` */ interface BaseProviderConfig { /** * The model identifier in provider/model format. * * @example "anthropic/claude-sonnet-4" * @example "openai/gpt-4o" */ model: string; /** * Base URL for the API endpoint. * * @defaultValue Provider-specific default URL */ baseURL?: string; /** * API key for authentication. * * @defaultValue Value from environment variables */ apiKey?: string; /** * Request timeout in milliseconds. * * @defaultValue 60000 (60 seconds) */ timeout?: number; /** * Maximum number of retry attempts for failed requests. * * @defaultValue 2 */ maxRetries?: number; } /** * Configuration options for the AI Gateway (Vercel) provider. * * Extends {@link BaseProviderConfig} with no additional options. * AI Gateway uses standard OpenAI-compatible configuration. * * @example * ```typescript * const config: AIGatewayConfig = { * model: "anthropic/claude-sonnet-4", * apiKey: process.env.AI_GATEWAY_API_KEY * }; * ``` * * @see {@link BaseProviderConfig} for inherited options */ interface AIGatewayConfig extends BaseProviderConfig {} /** * Options for registering AI Gateway with ADK's LLMRegistry. * * These options apply to all models created through the registry. * * @example * ```typescript * registerAIGateway({ * apiKey: process.env.AI_GATEWAY_API_KEY, * baseURL: "https://custom-gateway.example.com/v1" * }); * ``` */ interface RegisterOptions { /** * Base URL for the API endpoint. * * @defaultValue "https://ai-gateway.vercel.sh/v1" */ baseURL?: string; /** * API key for authentication. * * @defaultValue process.env.AI_GATEWAY_API_KEY || process.env.OPENAI_API_KEY */ apiKey?: string; } /** * OpenRouter provider routing preferences. * * Controls how OpenRouter selects and routes requests to underlying providers. * These preferences are sent as part of the request body. * * @see {@link https://openrouter.ai/docs#provider-routing|OpenRouter Provider Routing} * * @example * ```typescript * const preferences: OpenRouterProviderPreferences = { * order: ["Anthropic", "Google"], * allow_fallbacks: true, * sort: "price" * }; * ``` */ interface OpenRouterProviderPreferences { /** * Preferred provider order. * * Providers are tried in this order before falling back to others. * * @example ["Anthropic", "Google", "OpenAI"] */ order?: string[]; /** * Allow fallback to other providers if preferred ones are unavailable. * * @defaultValue true */ allow_fallbacks?: boolean; /** * Require providers to support all parameters in the request. * * If true, providers that don't support certain parameters will be skipped. */ require_parameters?: boolean; /** * Data collection policy for the request. * * - `"allow"`: Allow providers to use data for training * - `"deny"`: Prevent data collection */ data_collection?: "allow" | "deny"; /** * Sort available providers by criteria. * * - `"price"`: Cheapest first * - `"throughput"`: Highest throughput first * - `"latency"`: Lowest latency first */ sort?: "price" | "throughput" | "latency"; /** * Only use these providers. * * Requests will fail if none of these providers are available. * * @example ["Anthropic"] */ only?: string[]; /** * Never use these providers. * * @example ["Together", "Fireworks"] */ ignore?: string[]; } /** * Configuration options for the OpenRouter provider. * * Extends {@link BaseProviderConfig} with OpenRouter-specific options * for site attribution and provider routing. * * @example * ```typescript * const config: OpenRouterConfig = { * model: "anthropic/claude-sonnet-4", * apiKey: process.env.OPENROUTER_API_KEY, * siteUrl: "https://myapp.com", * appName: "My Application", * provider: { * sort: "price", * allow_fallbacks: true * } * }; * ``` * * @see {@link BaseProviderConfig} for inherited options * @see {@link OpenRouterProviderPreferences} for routing options */ interface OpenRouterConfig extends BaseProviderConfig { /** * Your site URL for OpenRouter leaderboard rankings. * * Sent as the `HTTP-Referer` header. Sites with more usage rank higher. * * @example "https://myapp.com" */ siteUrl?: string; /** * Your application name for OpenRouter leaderboard rankings. * * Sent as the `X-Title` header. Appears in OpenRouter's app rankings. * * @example "My AI Assistant" */ appName?: string; /** * Provider routing preferences. * * Controls how OpenRouter selects providers for this request. * * @see {@link OpenRouterProviderPreferences} */ provider?: OpenRouterProviderPreferences; } /** * Options for registering OpenRouter with ADK's LLMRegistry. * * These options apply to all models created through the registry. * * @example * ```typescript * registerOpenRouter({ * apiKey: process.env.OPENROUTER_API_KEY, * siteUrl: "https://myapp.com", * appName: "My Application" * }); * ``` */ interface OpenRouterRegisterOptions { /** * Base URL for the API endpoint. * * @defaultValue "https://openrouter.ai/api/v1" */ baseURL?: string; /** * API key for authentication. * * @defaultValue process.env.OPENROUTER_API_KEY */ apiKey?: string; /** * Your site URL for OpenRouter leaderboard rankings. * * @example "https://myapp.com" */ siteUrl?: string; /** * Your application name for OpenRouter leaderboard rankings. * * @example "My AI Assistant" */ appName?: string; } /** * Configuration options for custom LLM providers. * * Use this to connect any API that implements the OpenAI chat completions * interface, such as Ollama, LM Studio, vLLM, Azure OpenAI, or self-hosted models. * * @example * ```typescript * // Ollama * const config: CustomLlmConfig = { * name: "ollama", * model: "llama3", * baseURL: "http://localhost:11434/v1" * }; * ``` * * @example * ```typescript * // Azure OpenAI * const config: CustomLlmConfig = { * name: "azure", * model: "gpt-4", * baseURL: "https://my-resource.openai.azure.com/openai/deployments/gpt-4", * headers: { "api-key": process.env.AZURE_API_KEY }, * queryParams: { "api-version": "2024-02-01" } * }; * ``` * * @see {@link BaseProviderConfig} for inherited options * @see {@link createCustomLlm} for the factory function */ interface CustomLlmConfig extends BaseProviderConfig { /** * Provider name for identification in logs and error messages. * * Used to generate error codes like `OLLAMA_ERROR` or `AZURE_ERROR`. * * @defaultValue "CUSTOM" * @example "ollama" * @example "azure" * @example "vllm" */ name?: string; /** * Additional HTTP headers to include in all requests. * * Useful for custom authentication schemes or provider-specific headers. * * @example * ```typescript * headers: { * "api-key": process.env.AZURE_API_KEY, * "X-Custom-Header": "value" * } * ``` */ headers?: Record; /** * Query parameters to append to all API requests. * * Required by some providers like Azure OpenAI for API versioning. * * @example * ```typescript * queryParams: { * "api-version": "2024-02-01" * } * ``` */ queryParams?: Record; /** * Additional options to include in the request body. * * These are spread into the chat completion request, allowing * provider-specific parameters beyond the standard OpenAI API. * * @example * ```typescript * providerOptions: { * temperature: 0.7, * custom_field: "value" * } * ``` */ providerOptions?: Record; } /** * Configuration options for the OpenAI provider. * * Extends {@link BaseProviderConfig} with OpenAI-specific options * for organization and project identification. * * @example * ```typescript * const config: OpenAIProviderConfig = { * model: "gpt-4.1", * apiKey: process.env.OPENAI_API_KEY, * organization: "org-xxx", * project: "proj-xxx" * }; * ``` * * @see {@link BaseProviderConfig} for inherited options * @see {@link OpenAI} for the factory function */ interface OpenAIProviderConfig extends BaseProviderConfig { /** * OpenAI organization ID. * * Sent as the `OpenAI-Organization` header for organization-scoped requests. * * @example "org-xxx" */ organization?: string; /** * OpenAI project ID. * * Sent as the `OpenAI-Project` header for project-scoped requests. * * @example "proj-xxx" */ project?: string; } /** * Options for registering OpenAI with ADK's LLMRegistry. * * These options apply to all models created through the registry. * * @example * ```typescript * registerOpenAI({ * apiKey: process.env.OPENAI_API_KEY, * organization: "org-xxx" * }); * ``` */ interface OpenAIRegisterOptions { /** * API key for authentication. * * @defaultValue process.env.OPENAI_API_KEY */ apiKey?: string; /** * OpenAI organization ID. * * @example "org-xxx" */ organization?: string; /** * OpenAI project ID. * * @example "proj-xxx" */ project?: string; } /** * Configuration options for the xAI (Grok) provider. * * Extends {@link BaseProviderConfig} with no additional options. * xAI uses standard OpenAI-compatible configuration. * * @example * ```typescript * const config: XAIProviderConfig = { * model: "grok-4", * apiKey: process.env.XAI_API_KEY * }; * ``` * * @see {@link BaseProviderConfig} for inherited options * @see {@link XAI} for the factory function */ interface XAIProviderConfig extends BaseProviderConfig {} /** * Options for registering xAI with ADK's LLMRegistry. * * These options apply to all models created through the registry. * * @example * ```typescript * registerXAI({ * apiKey: process.env.XAI_API_KEY * }); * ``` */ interface XAIRegisterOptions { /** * API key for authentication. * * @defaultValue process.env.XAI_API_KEY */ apiKey?: string; } /** * Configuration options for the Anthropic (Claude) provider. * * Extends {@link BaseProviderConfig} with Anthropic-specific options. * * @example * ```typescript * const config: AnthropicProviderConfig = { * model: "claude-sonnet-4-5-20250929", * apiKey: process.env.ANTHROPIC_API_KEY, * maxTokens: 4096 * }; * ``` * * @see {@link BaseProviderConfig} for inherited options * @see {@link Anthropic} for the factory function */ interface AnthropicProviderConfig extends BaseProviderConfig { /** * Maximum number of tokens to generate. * * Required by Anthropic API. If not provided, defaults to 4096. * * @defaultValue 4096 */ maxTokens?: number; /** * Opt-in Anthropic prompt caching. * * When `true`, attaches `cache_control: { type: "ephemeral" }` to the * system prompt block and the last tool definition, marking the largely * static prefix of the request (system instruction + tool schemas) as * cacheable. This can substantially reduce cost and latency for prompts * that reuse the same system instruction and tools across turns. * * This is a bridge-level instance setting, NOT derived from ADK's * `config.cachedContent` (which is a non-portable Gemini resource name). * * @defaultValue false * @see {@link https://platform.claude.com/docs/en/docs/build-with-claude/prompt-caching|Anthropic Prompt Caching} */ promptCaching?: boolean; } /** * Options for registering Anthropic with ADK's LLMRegistry. * * These options apply to all models created through the registry. * * @example * ```typescript * registerAnthropic({ * apiKey: process.env.ANTHROPIC_API_KEY, * maxTokens: 8192 * }); * ``` */ interface AnthropicRegisterOptions { /** * API key for authentication. * * @defaultValue process.env.ANTHROPIC_API_KEY */ apiKey?: string; /** * Maximum number of tokens to generate. * * @defaultValue 4096 */ maxTokens?: number; /** * Opt-in Anthropic prompt caching for all models created through the * registry. * * When `true`, attaches `cache_control: { type: "ephemeral" }` to the * system prompt block and the last tool definition. * * @defaultValue false * @see {@link AnthropicProviderConfig.promptCaching} */ promptCaching?: boolean; } /** * Accumulator for tool call data during streaming. * * Used internally to collect partial tool call information * as chunks arrive from the API. * * @internal */ interface ToolCallAccumulator { /** Unique identifier for the tool call */ id: string; /** Name of the function being called */ name: string; /** JSON string of accumulated function arguments */ arguments: string; } /** * Accumulator state for streaming responses. * * Tracks the accumulated text and tool calls across multiple stream chunks. * Created using {@link createStreamAccumulator}. * * @example * ```typescript * const accumulator = createStreamAccumulator(); * * for await (const chunk of stream) { * const result = convertStreamChunk(chunk, accumulator); * if (result.isComplete) { * return result.response; * } * } * ``` * * @see {@link createStreamAccumulator} * @see {@link convertStreamChunk} */ interface StreamAccumulator { /** Accumulated text content from all chunks */ text: string; /** * Accumulated reasoning/thinking text from all chunks. * * Populated from provider `delta.reasoning` / `delta.reasoning_content` * fields. Emitted as a `{ thought: true }` part. */ reasoning: string; /** Map of tool call index to accumulated tool call data */ toolCalls: Map; /** * Token usage captured from the final OpenAI streaming chunk. * * Populated when `stream_options.include_usage` is enabled; emitted as * `usageMetadata` on the final response. Includes `thoughtsTokenCount` when * the provider reports `completion_tokens_details.reasoning_tokens`. */ usage?: LlmResponse["usageMetadata"]; } /** * Result from processing a stream chunk. * * Contains either a partial update or the final complete response. * * @see {@link convertStreamChunk} */ interface StreamChunkResult { /** * The LLM response, present when chunk contains meaningful content. * * For intermediate chunks, this may be a partial response. * For the final chunk, this is the complete accumulated response. */ response?: LlmResponse; /** * Whether the stream has completed. * * When `true`, the `response` contains the final accumulated result. */ isComplete: boolean; } /** * Abstract base class for all LLM providers in adk-llm-bridge. * * Extends ADK's `BaseLlm` and provides common infrastructure for error handling * and configuration management. All provider implementations (AI Gateway, * OpenRouter, custom providers) should extend this class. * * @abstract * * @example * ```typescript * class CustomLlm extends BaseProviderLlm { * static supportedModels = [/^custom\/.+$/]; * * async *generateContentAsync( * llmRequest: LlmRequest, * stream?: boolean * ): AsyncGenerator { * try { * // Implementation here * yield response; * } catch (error) { * yield this.createErrorResponse(error, "CUSTOM"); * } * } * } * ``` * * @see {@link OpenAICompatibleLlm} for OpenAI-compatible API implementations */ declare abstract class BaseProviderLlm extends BaseLlm { /** * Provider configuration. * * Contains the resolved configuration including model, API key, base URL, etc. * * @protected */ protected readonly config: BaseProviderConfig; /** * Creates a new BaseProviderLlm instance. * * @param config - Provider configuration options */ constructor(config: BaseProviderConfig); /** * Establishes a bidirectional streaming connection. * * This method is required by ADK's BaseLlm interface but is not supported * by OpenAI-compatible APIs. It always throws an error. * * @param _ - The LLM request (unused) * @returns Never - always throws * @throws Error indicating bidirectional streaming is not supported */ connect(_: LlmRequest): Promise; /** * Creates a standardized error response for ADK. * * Converts JavaScript errors into ADK-compatible LlmResponse objects * with appropriate error codes and messages. * * @param error - The error that occurred (Error instance or any value) * @param prefix - Provider-specific error prefix (e.g., "AI_GATEWAY", "OPENROUTER") * @returns An LlmResponse with error information and turnComplete: true * * @protected * * @example * ```typescript * try { * // API call * } catch (error) { * yield this.createErrorResponse(error, "MY_PROVIDER"); * // Returns: { errorCode: "MY_PROVIDER_ERROR", errorMessage: "...", turnComplete: true } * } * ``` */ protected createErrorResponse(error: unknown, prefix: string): LlmResponse2; } import { LlmRequest as LlmRequest2, LlmResponse as LlmResponse3 } from "@google/adk"; import OpenAI from "openai"; /** * @license * Copyright 2025 PAI * SPDX-License-Identifier: MIT */ /** * Declarative provider definition interface. * * Providers that use OpenAI-compatible APIs differ only in configuration * (URLs, env vars, headers), not behavior. This interface captures those * differences as data instead of requiring class inheritance. * * @module core/provider-definition */ /** * Environment variable keys for resolving provider configuration. */ interface ProviderEnvKeys { /** Env var names to check for API key, in priority order */ apiKey: string[]; /** Env var names to check for base URL, in priority order */ baseURL?: string[]; } /** * Declarative definition for an OpenAI-compatible LLM provider. * * Instead of creating a subclass for each provider, define the provider * as a configuration object. The core infrastructure handles the rest. * * @example * ```typescript * const MY_PROVIDER: ProviderDefinition = { * id: "my-provider", * errorPrefix: "MY_PROVIDER", * defaultBaseURL: "https://api.myprovider.com/v1", * envKeys: { apiKey: ["MY_PROVIDER_API_KEY"] }, * modelPatterns: [/.+\/.+/], * }; * ``` */ interface ProviderDefinition { /** Provider ID for the config system (e.g. "ai-gateway", "openrouter") */ id: string; /** Error prefix for error codes (e.g. "AI_GATEWAY" → "AI_GATEWAY_ERROR") */ errorPrefix: string; /** Default base URL when not specified in config or env vars */ defaultBaseURL: string; /** Environment variable names to resolve for apiKey and baseURL */ envKeys: ProviderEnvKeys; /** Model patterns for LLMRegistry matching */ modelPatterns: (string | RegExp)[]; /** Build custom HTTP headers from the instance config */ buildHeaders?: (config: Record) => Record; /** Build provider-specific options to merge into request body */ buildRequestOptions?: (config: Record) => Record; /** * Whether this provider requires an API key at construction time. * * Cloud providers (AI Gateway, OpenRouter, OpenAI, xAI) should set this * to true. Local/self-hosted providers that may not need auth can omit it. * * @default false */ requireApiKey?: boolean; } /** * Configuration for the underlying OpenAI client. * * These options are passed directly to the OpenAI SDK constructor. */ interface OpenAIClientConfig { /** Base URL for the API endpoint. */ baseURL: string; /** API key for authentication. */ apiKey: string; /** Request timeout in milliseconds. */ timeout: number; /** Maximum number of retry attempts. */ maxRetries: number; /** Additional HTTP headers to include in all requests. */ defaultHeaders?: Record; } /** * Base class for LLM providers that use OpenAI-compatible APIs. * * Supports two construction modes: * * 1. **Declarative** (recommended): Pass a {@link ProviderDefinition} that * describes the provider's configuration. Config resolution is automatic. * * 2. **Manual**: Pass a {@link BaseProviderConfig} + {@link OpenAIClientConfig} * with pre-resolved values. Used by CustomLlm which has unique URL logic. * * @example * ```typescript * // Declarative (most providers) * const llm = new OpenAICompatibleLlm(MY_DEFINITION, { model: "gpt-4o" }); * * // Manual (Custom provider) * class CustomLlm extends OpenAICompatibleLlm { * constructor(config) { * super(config, { baseURL, apiKey, timeout, maxRetries }); * } * } * ``` */ declare class OpenAICompatibleLlm extends BaseProviderLlm { /** Model patterns for LLMRegistry — set by createProviderClass(). */ static supportedModels: (string | RegExp)[]; /** @protected */ protected readonly client: OpenAI; private readonly _errorPrefix; private readonly _getRequestOptions?; /** Declarative constructor: definition + config */ constructor(definition: ProviderDefinition, config: BaseProviderConfig); /** Manual constructor: config + clientConfig (for CustomLlm) */ constructor(config: BaseProviderConfig, clientConfig: OpenAIClientConfig); /** Returns the provider error prefix. */ protected getErrorPrefix(): string; /** Returns provider-specific request options. */ protected getProviderRequestOptions(): Record; generateContentAsync(llmRequest: LlmRequest2, stream?: boolean): AsyncGenerator; private singleResponse; private streamResponse; } import { BaseLlm as BaseLlm_m11s8s } from "@google/adk"; declare const AIGatewayLlm: (new (params: { model: string; }) => BaseLlm_m11s8s) & { readonly supportedModels: (string | RegExp)[]; }; declare const AIGateway: (model: string, options?: Partial>) => OpenAICompatibleLlm; declare const registerAIGateway: (options?: Record) => void; declare const isAIGatewayRegistered: () => boolean; import { BaseLlm as BaseLlm_m11s8s2 } from "@google/adk"; declare const OpenRouterLlm: (new (params: { model: string; }) => BaseLlm_m11s8s2) & { readonly supportedModels: (string | RegExp)[]; }; declare const OpenRouter: (model: string, options?: Partial>) => OpenAICompatibleLlm; declare const registerOpenRouter: (options?: Record) => void; declare const isOpenRouterRegistered: () => boolean; import { BaseLlm as BaseLlm_m11s8s3 } from "@google/adk"; declare const OpenAILlm: (new (params: { model: string; }) => BaseLlm_m11s8s3) & { readonly supportedModels: (string | RegExp)[]; }; declare const OpenAI2: (model: string, options?: Partial>) => OpenAICompatibleLlm; declare const registerOpenAI: (options?: Record) => void; declare const isOpenAIRegistered: () => boolean; import { BaseLlm as BaseLlm_m11s8s4 } from "@google/adk"; declare const XAILlm: (new (params: { model: string; }) => BaseLlm_m11s8s4) & { readonly supportedModels: (string | RegExp)[]; }; declare const XAI: (model: string, options?: Partial>) => OpenAICompatibleLlm; declare const registerXAI: (options?: Record) => void; declare const isXAIRegistered: () => boolean; import { LlmRequest as LlmRequest3, LlmResponse as LlmResponse4 } from "@google/adk"; /** * Anthropic (Claude) LLM provider. * * Provides direct access to Anthropic's Messages API for Claude models. * Unlike OpenAI-compatible providers, this uses the native Anthropic SDK * with custom request/response converters. * * Configuration priority (highest to lowest): * 1. Instance configuration (passed to constructor) * 2. Global configuration (via `setProviderConfig("anthropic", {...})`) * 3. Environment variables (`ANTHROPIC_API_KEY`) * * @example * ```typescript * // Basic usage * const llm = new AnthropicLlm({ model: "claude-sonnet-4-5-20250929" }); * * // With max tokens * const llm = new AnthropicLlm({ * model: "claude-sonnet-4-5-20250929", * apiKey: "...", * maxTokens: 8192 * }); * ``` * * @see {@link Anthropic} for the recommended factory function * @see {@link registerAnthropic} for LLMRegistry integration */ declare class AnthropicLlm extends BaseProviderLlm { /** * Model patterns supported by this provider. * * Used by ADK's LLMRegistry to match model strings to this provider. * Matches: claude-* * * @static */ static readonly supportedModels: RegExp[]; /** * The Anthropic SDK client instance. * * @private */ private readonly client; /** * Maximum tokens to generate in responses. * * @private */ private readonly maxTokens; /** * Whether opt-in prompt caching is enabled for this instance. * * @private */ private readonly promptCaching; /** * Creates a new Anthropic LLM instance. * * @param config - Configuration options for the Anthropic provider * * @example * ```typescript * const llm = new AnthropicLlm({ * model: "claude-sonnet-4-5-20250929", * apiKey: process.env.ANTHROPIC_API_KEY, * maxTokens: 4096 * }); * ``` */ constructor(config: AnthropicProviderConfig); /** * Generates content from the Anthropic API. * * Converts the ADK request to Anthropic format, makes the API call, * and converts the response back to ADK format. * * @param llmRequest - The ADK LLM request * @param stream - Whether to stream the response (default: false) * @returns An async generator yielding LLM responses */ generateContentAsync(llmRequest: LlmRequest3, stream?: boolean): AsyncGenerator; /** * Builds the shared request parameters for the Anthropic API. * * Per-request `config.maxOutputTokens` (params.max_tokens) overrides the * instance default. Anthropic requires `max_tokens` to always be present. * * @private */ private buildRequestParams; /** * Makes a single (non-streaming) API request. * * @private */ private singleResponse; /** * Makes a streaming API request and yields responses as they arrive. * * @private */ private streamResponse; } /** * Creates an Anthropic (Claude) LLM instance. * * @param model - The Claude model to use * @param options - Optional configuration options * @returns A configured Anthropic LLM instance */ declare function Anthropic3(model: string, options?: Omit): AnthropicLlm; declare function registerAnthropic(options?: AnthropicRegisterOptions): void; declare function isAnthropicRegistered(): boolean; /** * Configuration type with required baseURL for custom providers. * * Unlike built-in providers (AI Gateway, OpenRouter) which have default URLs, * custom providers require an explicit baseURL. */ type CustomLlmProviderConfig = CustomLlmConfig & { /** * Base URL for the API endpoint (required). * * @example "http://localhost:11434/v1" // Ollama * @example "http://localhost:8000/v1" // vLLM * @example "https://my-resource.openai.azure.com/openai/deployments/gpt-4" // Azure */ baseURL: string; }; /** * LLM implementation for any API that supports the chat completions interface. * * This provider allows connecting to any API that implements the OpenAI * chat completions interface. Use this for: * * - **Local models**: Ollama, LM Studio, vLLM, llama.cpp * - **Cloud providers**: Azure OpenAI, Together AI, Anyscale * - **Self-hosted**: Any compatible server * * Unlike AI Gateway and OpenRouter, this provider: * - Requires explicit `baseURL` configuration * - Does not use environment variables for defaults * - Supports custom headers and query parameters * * @example * ```typescript * // Ollama * const llm = new CustomLlm({ * name: "ollama", * model: "llama3", * baseURL: "http://localhost:11434/v1" * }); * ``` * * @example * ```typescript * // Azure OpenAI * const llm = new CustomLlm({ * name: "azure", * model: "gpt-4", * baseURL: "https://my-resource.openai.azure.com/openai/deployments/gpt-4", * headers: { "api-key": process.env.AZURE_API_KEY }, * queryParams: { "api-version": "2024-02-01" } * }); * ``` * * @see {@link createCustomLlm} for the factory function * @see {@link Custom} for the shorthand alias */ declare class CustomLlm extends OpenAICompatibleLlm { /** * Model patterns supported by this provider. * * Accepts any model identifier since different APIs use different naming conventions. * * @static */ static readonly supportedModels: RegExp[]; /** * Provider name used for error prefixes. * * @private */ private readonly providerName; /** * Provider-specific options to include in requests. * * @private */ private readonly providerOptionsConfig?; /** * Creates a new custom LLM provider instance. * * @param config - Configuration options including model, baseURL, and optional settings * * @example * ```typescript * const llm = new CustomLlm({ * name: "vllm", * model: "meta-llama/Llama-3-8b", * baseURL: "http://localhost:8000/v1" * }); * ``` */ constructor(config: CustomLlmProviderConfig); /** * Returns the error prefix for this provider. * * Sanitizes the provider name to create a valid error code prefix. * For example, "my-provider" becomes "MY_PROVIDER". * * @returns The sanitized provider name in uppercase * @protected */ protected getErrorPrefix(): string; /** * Returns provider-specific options to include in requests. * * These options are spread into the chat completion request body, * allowing custom parameters beyond the standard OpenAI API. * * @returns The configured provider options or an empty object * @protected */ protected getProviderRequestOptions(): Record; } /** * Creates a custom LLM instance. * * This is the recommended way to connect to any API that implements * the chat completions interface. It provides a clean, functional API. * * @param config - Configuration options including model, baseURL, and optional settings * @returns A configured CustomLlm instance * * @example * ```typescript * // Ollama * const llm = createCustomLlm({ * name: "ollama", * model: "llama3", * baseURL: "http://localhost:11434/v1" * }); * ``` * * @example * ```typescript * // Azure OpenAI * const llm = createCustomLlm({ * name: "azure", * model: "gpt-4", * baseURL: "https://my-resource.openai.azure.com/openai/deployments/gpt-4", * apiKey: process.env.AZURE_API_KEY, * headers: { "api-key": process.env.AZURE_API_KEY }, * queryParams: { "api-version": "2024-02-01" } * }); * ``` * * @example * ```typescript * // vLLM / LM Studio * const llm = createCustomLlm({ * baseURL: "http://localhost:8000/v1", * model: "meta-llama/Llama-3-8b" * }); * ``` * * @example * ```typescript * // With provider-specific options * const llm = createCustomLlm({ * name: "custom", * model: "my-model", * baseURL: "https://api.example.com/v1", * apiKey: "sk-...", * providerOptions: { * temperature: 0.7, * custom_param: "value" * } * }); * ``` * * @example * ```typescript * // Use with ADK agent * import { LlmAgent } from "@google/adk"; * * const agent = new LlmAgent({ * name: "assistant", * model: createCustomLlm({ * name: "ollama", * model: "llama3", * baseURL: "http://localhost:11434/v1" * }), * instruction: "You are a helpful assistant." * }); * ``` * * @see {@link CustomLlm} for direct class usage * @see {@link Custom} for a shorthand alias */ declare function createCustomLlm(config: CustomLlmProviderConfig): CustomLlm; /** * Configuration options for the Custom factory (model is specified separately). */ type CustomOptions = Omit & { /** * Base URL for the API endpoint (required). */ baseURL: string; }; /** * Creates a custom LLM instance with a shorthand syntax. * * This is an alias for `createCustomLlm` that takes the model * as the first argument, similar to the `AIGateway` and `OpenRouter` * factory functions. * * @param model - The model identifier * @param options - Configuration options including baseURL and optional settings * @returns A configured CustomLlm instance * * @example * ```typescript * // Simple usage * const llm = Custom("llama3", { * baseURL: "http://localhost:11434/v1" * }); * ``` * * @example * ```typescript * // With full options * const llm = Custom("gpt-4", { * name: "azure", * baseURL: "https://my-resource.openai.azure.com/openai/deployments/gpt-4", * apiKey: process.env.AZURE_API_KEY, * headers: { "api-key": process.env.AZURE_API_KEY }, * queryParams: { "api-version": "2024-02-01" } * }); * ``` * * @example * ```typescript * // Use with ADK agent * import { LlmAgent } from "@google/adk"; * * const agent = new LlmAgent({ * name: "assistant", * model: Custom("llama3", { baseURL: "http://localhost:11434/v1" }), * instruction: "You are a helpful assistant." * }); * ``` * * @see {@link createCustomLlm} for the full configuration syntax */ declare function Custom(model: string, options: CustomOptions): CustomLlm; /** * @license * Copyright 2025 PAI * SPDX-License-Identifier: MIT */ /** * Constants and default values for adk-llm-bridge. * * This module contains all constant values including default URLs, * timeouts, environment variable names, and model patterns. * * @module constants */ /** * Default base URL for the Vercel AI Gateway API. * * @constant * @see {@link https://vercel.com/ai-gateway|Vercel AI Gateway} */ declare const DEFAULT_BASE_URL = "https://ai-gateway.vercel.sh/v1"; /** * Model patterns for AI Gateway model validation. * * Matches any model identifier with the format "provider/model". * AI Gateway validates actual model availability at runtime. * * Note: Do not include ^ or $ anchors - ADK's LLMRegistry adds them automatically. * * @constant * @example * ```typescript * MODEL_PATTERNS[0].test("anthropic/claude-sonnet-4"); // true * MODEL_PATTERNS[0].test("invalid"); // false * ``` */ declare const MODEL_PATTERNS: (string | RegExp)[]; /** * Default base URL for the OpenRouter API. * * @constant * @see {@link https://openrouter.ai/docs|OpenRouter Documentation} */ declare const OPENROUTER_BASE_URL = "https://openrouter.ai/api/v1"; /** * Model patterns for OpenRouter model validation. * * Uses the same "provider/model" format as AI Gateway. * * Note: Do not include ^ or $ anchors - ADK's LLMRegistry adds them automatically. * * @constant * @example * ```typescript * OPENROUTER_MODEL_PATTERNS[0].test("anthropic/claude-sonnet-4"); // true * ``` */ declare const OPENROUTER_MODEL_PATTERNS: (string | RegExp)[]; /** * Unique identifiers for each provider. * * Used internally for configuration management and registry operations. * * @constant */ declare const PROVIDER_IDS: { /** Identifier for the AI Gateway provider */ readonly AI_GATEWAY: "ai-gateway"; /** Identifier for the OpenRouter provider */ readonly OPENROUTER: "openrouter"; }; /** * Mapping of provider identifiers to their configuration types. * * @internal */ type ProviderConfigMap = { "ai-gateway": RegisterOptions; openrouter: OpenRouterRegisterOptions; openai: OpenAIRegisterOptions; xai: XAIRegisterOptions; anthropic: AnthropicRegisterOptions; }; /** * Valid provider type identifiers. * * @internal */ type ProviderType = keyof ProviderConfigMap; /** * Sets global configuration for a specific provider. * * This configuration is used as a fallback when creating LLM instances * without explicit configuration. Instance configuration always takes * precedence over global configuration. * * @param provider - The provider identifier ("ai-gateway" or "openrouter") * @param options - Configuration options for the provider * * @example * ```typescript * // Configure AI Gateway globally * setProviderConfig("ai-gateway", { * apiKey: "your-api-key", * baseURL: "https://custom-gateway.example.com/v1" * }); * ``` * * @example * ```typescript * // Configure OpenRouter with site attribution * setProviderConfig("openrouter", { * apiKey: "your-api-key", * siteUrl: "https://myapp.com", * appName: "My Application" * }); * ``` */ declare function setProviderConfig(provider: T, options: ProviderConfigMap[T]): void; /** * Gets the current global configuration for a specific provider. * * @param provider - The provider identifier ("ai-gateway" or "openrouter") * @returns The current configuration, or `undefined` if not set * * @example * ```typescript * const config = getProviderConfig("ai-gateway"); * if (config?.apiKey) { * console.log("AI Gateway is configured"); * } * ``` */ declare function getProviderConfig(provider: T): Readonly | undefined; /** * Resets the global configuration for a specific provider. * * After calling this, the provider will fall back to environment variables * or default values. * * @param provider - The provider identifier ("ai-gateway" or "openrouter") * * @example * ```typescript * resetProviderConfig("ai-gateway"); * ``` */ declare function resetProviderConfig(provider: ProviderType): void; /** * Resets all provider configurations. * * Useful for testing or when you need to clear all global state. * * @example * ```typescript * // In test teardown * afterEach(() => { * resetAllConfigs(); * }); * ``` */ declare function resetAllConfigs(): void; /** * Sets global configuration for AI Gateway. * * @param options - Configuration options * * @deprecated Use {@link setProviderConfig | setProviderConfig("ai-gateway", options)} instead. * This function will be removed in a future major version. * * @example * ```typescript * // Old way (deprecated) * setConfig({ apiKey: "..." }); * * // New way * setProviderConfig("ai-gateway", { apiKey: "..." }); * ``` */ declare function setConfig(options: RegisterOptions): void; /** * Gets global configuration for AI Gateway. * * @returns The current AI Gateway configuration * * @deprecated Use {@link getProviderConfig | getProviderConfig("ai-gateway")} instead. * This function will be removed in a future major version. */ declare function getConfig(): Readonly; /** * Resets global configuration for AI Gateway. * * @deprecated Use {@link resetProviderConfig | resetProviderConfig("ai-gateway")} instead. * This function will be removed in a future major version. */ declare function resetConfig(): void; import { LlmRequest as LlmRequest5 } from "@google/adk"; import OpenAI3 from "openai"; /** * Result of converting an ADK LlmRequest to OpenAI format. * * Contains the converted messages array and optional tools array * ready for use with the OpenAI chat completions API. */ interface ConvertedRequest { /** * Array of OpenAI-format chat messages. * * Includes system, user, assistant, and tool messages * converted from ADK Content objects. */ messages: OpenAI3.ChatCompletionMessageParam[]; /** * Array of OpenAI-format tool definitions. * * Converted from ADK function declarations with schema normalization. */ tools?: OpenAI3.ChatCompletionTool[]; /** * Generation + structured-output parameters mapped from `config`. * * Built from a strict allowlist (temperature, top_p, max_tokens, etc. plus * response_format). Spread directly into the chat completion request body. */ params?: Record; /** * OpenAI `tool_choice` mapped from `config.toolConfig.functionCallingConfig`. * * Only meaningful when tools are present. */ toolChoice?: OpenAI3.ChatCompletionToolChoiceOption; } /** * Converts an ADK LlmRequest to OpenAI chat completion format. * * This function handles: * - System instruction extraction * - User and model message conversion * - Function call and response handling * - Tool/function declaration conversion * - Schema normalization (Gemini UPPERCASE to OpenAI lowercase types) * * @param llmRequest - The ADK LlmRequest to convert * @returns The converted request with messages and optional tools * * @example * ```typescript * import { convertRequest } from "adk-llm-bridge"; * * const adkRequest: LlmRequest = { * contents: [{ role: "user", parts: [{ text: "Hello!" }] }], * config: { systemInstruction: "You are a helpful assistant." } * }; * * const { messages, tools } = convertRequest(adkRequest); * // messages = [ * // { role: "system", content: "You are a helpful assistant." }, * // { role: "user", content: "Hello!" } * // ] * ``` * * @example * ```typescript * // With tools/functions * const adkRequest: LlmRequest = { * contents: [...], * config: { * tools: [{ * functionDeclarations: [{ * name: "get_weather", * description: "Get current weather", * parameters: { type: "OBJECT", properties: { city: { type: "STRING" } } } * }] * }] * } * }; * * const { messages, tools } = convertRequest(adkRequest); * // tools[0].function.parameters.type = "object" (normalized from "OBJECT") * ``` */ declare function convertRequest(llmRequest: LlmRequest5, model?: string): ConvertedRequest; /** * Maps ADK generation config to OpenAI chat completion params. * * Uses a STRICT allowlist — the ADK `config` is never blind-spread, so * Gemini-only knobs (safetySettings, responseModalities, etc.) cannot leak * into the OpenAI request body. `topK` is intentionally dropped (no OpenAI * Chat Completions equivalent). * * @param req - The LLM request * @returns An OpenAI params object, or `{}` when no fields are set */ declare function convertGenerationConfig(req: LlmRequest5, model?: string): Record; /** * Maps ADK `functionCallingConfig` to an OpenAI `tool_choice`. * * - AUTO -> "auto" * - NONE -> "none" * - ANY / VALIDATED -> "required" (or a specific function when exactly one * allowedFunctionName is given) * * @param req - The LLM request * @returns The OpenAI tool_choice, or undefined when no toolConfig is present */ declare function convertToolChoice(req: LlmRequest5): OpenAI3.ChatCompletionToolChoiceOption | undefined; /** * Maps ADK structured-output config to an OpenAI `response_format`. * * - `responseJsonSchema` -> json_schema (passthrough, already JSON Schema) * - `responseSchema` -> json_schema (normalized from Gemini types) * - `responseMimeType === "application/json"` only -> json_object * * `strict` is intentionally `false`. OpenAI strict mode imposes hard structural * requirements (every object must set `additionalProperties: false` and list * ALL properties in `required`) that Gemini-derived / arbitrary caller schemas * routinely violate, producing a 400. Lenient (`strict: false`) accepts partial * schemas, which is the lower-risk default for caller-supplied schemas. * * @param req - The LLM request * @returns A params object with `response_format`, or `{}` when not applicable */ declare function convertStructuredOutput(req: LlmRequest5): Record; import { LlmResponse as LlmResponse6 } from "@google/adk"; import OpenAI4 from "openai"; /** * Converts an OpenAI chat completion response to ADK LlmResponse format. * * Handles: * - Text content extraction * - Tool/function call conversion * - Usage metadata mapping * * @param response - The OpenAI ChatCompletion response * @returns The converted ADK LlmResponse * * @example * ```typescript * import { convertResponse } from "adk-llm-bridge"; * * const openaiResponse = await client.chat.completions.create({...}); * const adkResponse = convertResponse(openaiResponse); * * if (adkResponse.content?.parts) { * for (const part of adkResponse.content.parts) { * if (part.text) console.log(part.text); * if (part.functionCall) console.log("Tool call:", part.functionCall.name); * } * } * ``` */ declare function convertResponse(response: OpenAI4.ChatCompletion): LlmResponse6; /** * Processes a streaming chunk and returns the appropriate response. * * This function accumulates partial data (text and tool calls) across * multiple chunks and returns: * - Partial responses for text content (streamed immediately) * - Complete responses when finish_reason is received * * Tool calls are accumulated and only returned in the final response * because their arguments arrive in fragments across multiple chunks. * * @param chunk - The OpenAI streaming chunk * @param acc - The stream accumulator for tracking partial data * @returns Object containing optional response and completion status * * @example * ```typescript * import { createStreamAccumulator, convertStreamChunk } from "adk-llm-bridge"; * * const accumulator = createStreamAccumulator(); * * for await (const chunk of stream) { * const { response, isComplete } = convertStreamChunk(chunk, accumulator); * * if (response?.content?.parts?.[0]?.text) { * // Stream text to user immediately * process.stdout.write(response.content.parts[0].text); * } * * if (isComplete) { * // Final response with complete tool calls * return response; * } * } * ``` */ declare function convertStreamChunk(chunk: OpenAI4.ChatCompletionChunk, acc: StreamAccumulator): StreamChunkResult; /** * Creates a new stream accumulator for tracking partial responses. * * The accumulator stores: * - Accumulated text content * - Partial tool call data (indexed by position) * * Use with {@link convertStreamChunk} to process streaming responses. * * @returns A fresh StreamAccumulator instance * * @example * ```typescript * const accumulator = createStreamAccumulator(); * * for await (const chunk of stream) { * const result = convertStreamChunk(chunk, accumulator); * // accumulator state is updated automatically * } * ``` */ declare function createStreamAccumulator(): StreamAccumulator; /** * @license * Copyright 2025 PAI * SPDX-License-Identifier: MIT */ /** * Shared schema normalization. * * Converts Gemini-style schemas (UPPERCASE type names) to the lowercase * JSON-Schema-style types expected by OpenAI and Anthropic. Used by tool * conversion and structured-output mapping across providers. * * @module converters/schema */ /** * Normalizes a Gemini-style schema to a JSON-Schema-style schema. * * Converts UPPERCASE type names (Gemini format) to lowercase, recursing into * nested objects and preserving arrays. Already-lowercase types are left * unchanged, making the function idempotent. * * @param schema - The schema object to normalize * @returns The normalized schema, or undefined if the input is not an object * * @example * ```typescript * normalizeSchema({ type: "OBJECT", properties: { name: { type: "STRING" } } }); * // Returns: { type: "object", properties: { name: { type: "string" } } } * ``` */ declare function normalizeSchema(schema: unknown): Record | undefined; export { setProviderConfig, setConfig, resetProviderConfig, resetConfig, resetAllConfigs, registerXAI, registerOpenRouter, registerOpenAI, registerAnthropic, registerAIGateway, normalizeSchema, isXAIRegistered, isOpenRouterRegistered, isOpenAIRegistered, isAnthropicRegistered, isAIGatewayRegistered, getProviderConfig, getConfig, createStreamAccumulator, createCustomLlm, convertToolChoice, convertStructuredOutput, convertStreamChunk, convertResponse, convertRequest, convertGenerationConfig, XAIRegisterOptions, XAIProviderConfig, XAILlm, XAI, ToolCallAccumulator, StreamChunkResult, StreamAccumulator, RegisterOptions, PROVIDER_IDS, OpenRouterRegisterOptions, OpenRouterProviderPreferences, OpenRouterLlm, OpenRouterConfig, OpenRouter, OpenAIRegisterOptions, OpenAIProviderConfig, OpenAILlm, OpenAICompatibleLlm, OpenAIClientConfig, OpenAI2 as OpenAI, OPENROUTER_MODEL_PATTERNS, OPENROUTER_BASE_URL, MODEL_PATTERNS, DEFAULT_BASE_URL, CustomLlmProviderConfig, CustomLlmConfig, CustomLlm, Custom, BaseProviderLlm, BaseProviderConfig, BaseLlm2 as BaseLlm, AnthropicRegisterOptions, AnthropicProviderConfig, AnthropicLlm, Anthropic3 as Anthropic, AIGatewayLlm, AIGatewayConfig, AIGateway };