adk-llm-bridge 0.2.0 → 0.3.0

package/README.md

@@ -7,22 +7,20 @@ Use **any LLM** with [Google ADK TypeScript](https://github.com/google/adk-js) i
 
 ## Why?
 
-Google ADK TypeScript [only supports Gemini models natively](https://github.com/google/adk-js/blob/main/core/src/models/registry.ts#L113) (unlike the Python version which has LiteLLM integration). This lightweight bridge lets you use **any model** from providers like Anthropic, OpenAI, Meta, and more—while keeping all ADK features like multi-agent orchestration, tool calling, and streaming.
+Google ADK TypeScript comes with built-in Gemini support. This lightweight bridge extends it to work with **any model** from providers like Anthropic, OpenAI, Meta, and more—while keeping all ADK features like multi-agent orchestration, tool calling, and streaming.
 
 ### Key Benefits
 
-| | |
-|---|---|
-| **Minimal** | ~13KB bundle, single dependency (`openai`) |
-| **Simple** | 3 lines to integrate any model |
-| **Secure** | No complex dependency tree, just the battle-tested OpenAI SDK |
-| **Compatible** | Works with any OpenAI-compatible API (AI Gateway, OpenRouter, etc.) |
+- **Minimal** — ~13KB bundle, single dependency (`openai`)
+- **Simple** — 3 lines to integrate any model
+- **Secure** — No complex dependency tree, just the battle-tested OpenAI SDK
+- **Compatible** — Works with any OpenAI-compatible API (AI Gateway, OpenRouter, etc.)
 
 ## Supported Providers
 
 | Provider | Models | Features |
 |----------|--------|----------|
-| **[Vercel AI Gateway](https://vercel.com/ai-gateway)** | 100+ models (Claude, GPT-4, Llama, Mistral, etc.) | Simple, fast |
+| **[Vercel AI Gateway](https://vercel.com/ai-gateway)** | 100+ models (Claude, GPT, Llama, Gemini, etc.) | Simple, fast |
 | **[OpenRouter](https://openrouter.ai/)** | 100+ models | Provider routing, fallbacks, price optimization |
 
 ## How It Works
@@ -63,7 +61,7 @@ npm install adk-llm-bridge @google/adk
 
 ## Quick Start
 
-Just 3 lines to use Claude, GPT-4, or any model with ADK:
+Just 3 lines to use Claude, GPT, Gemini, or any model with ADK:
 
 ```typescript
 import { LlmAgent, LLMRegistry } from '@google/adk';
@@ -73,7 +71,7 @@ LLMRegistry.register(AIGatewayLlm);              // 2. Register
 
 const agent = new LlmAgent({                     // 3. Use any model
   name: 'assistant',
-  model: 'anthropic/claude-sonnet-4',            // Claude, GPT-4, Llama, etc.
+  model: 'anthropic/claude-sonnet-4.5',          // Claude, GPT, Llama, etc.
   instruction: 'You are a helpful assistant.',
 });
 ```
@@ -90,7 +88,7 @@ LLMRegistry.register(OpenRouterLlm);
 
 const agent = new LlmAgent({
   name: 'assistant',
-  model: 'anthropic/claude-sonnet-4',
+  model: 'anthropic/claude-sonnet-4.5',
   instruction: 'You are a helpful assistant.',
 });
 ```
@@ -140,14 +138,14 @@ import { AIGateway, OpenRouter } from 'adk-llm-bridge';
 // AI Gateway
 const agent1 = new LlmAgent({
   name: 'assistant',
-  model: AIGateway('anthropic/claude-sonnet-4', { timeout: 30000 }),
+  model: AIGateway('anthropic/claude-sonnet-4.5', { timeout: 30000 }),
   instruction: 'You are helpful.',
 });
 
 // OpenRouter with provider routing
 const agent2 = new LlmAgent({
   name: 'fast-assistant',
-  model: OpenRouter('anthropic/claude-sonnet-4', {
+  model: OpenRouter('anthropic/claude-sonnet-4.5', {
     provider: {
       sort: 'latency',
       allow_fallbacks: true,
@@ -164,7 +162,7 @@ OpenRouter provides additional features not available in AI Gateway:
 ```typescript
 import { OpenRouter } from 'adk-llm-bridge';
 
-const llm = OpenRouter('anthropic/claude-sonnet-4', {
+const llm = OpenRouter('anthropic/claude-sonnet-4.5', {
   // Ranking headers (improves your rate limits)
   siteUrl: 'https://your-site.com',
   appName: 'Your App',
@@ -184,26 +182,26 @@ const llm = OpenRouter('anthropic/claude-sonnet-4', {
 Use the `provider/model` format:
 
 ```
-anthropic/claude-sonnet-4
-openai/gpt-4o
-google/gemini-2.0-flash
-meta/llama-3.1-70b
-mistral/mistral-large
-xai/grok-2
-deepseek/deepseek-chat
+anthropic/claude-opus-4.5
+openai/gpt-5.2-pro
+google/gemini-3-pro
+meta/llama-3.3-70b-instruct
+mistral/mistral-large-3
+xai/grok-4.1
+deepseek/deepseek-r1
 ```
 
 ### Popular Models
 
 | Provider | Models |
 |----------|--------|
-| Anthropic | `anthropic/claude-opus-4`, `anthropic/claude-sonnet-4` |
-| OpenAI | `openai/gpt-4.1`, `openai/o3`, `openai/gpt-4o` |
-| Google | `google/gemini-2.5-pro`, `google/gemini-2.5-flash` |
-| Meta | `meta/llama-4-scout`, `meta/llama-4-maverick` |
-| Mistral | `mistral/mistral-large-2411`, `mistral/pixtral-large` |
-| xAI | `xai/grok-3`, `xai/grok-3-mini` |
-| DeepSeek | `deepseek/deepseek-v3`, `deepseek/deepseek-r1` |
+| Anthropic | `anthropic/claude-sonnet-4.5`, `anthropic/claude-opus-4.5` |
+| OpenAI | `openai/gpt-5.2-pro`, `openai/gpt-4.1`, `openai/o3-mini` |
+| Google | `google/gemini-3-pro`, `google/gemini-3-flash`, `google/gemini-2.5-pro` |
+| Meta | `meta/llama-3.3-70b-instruct`, `meta/llama-3.1-405b-instruct` |
+| Mistral | `mistral/mistral-large-3`, `mistral/mistral-large-2411` |
+| xAI | `xai/grok-4.1`, `xai/grok-4-fast`, `xai/grok-3` |
+| DeepSeek | `deepseek/deepseek-v3.2`, `deepseek/deepseek-r1` |
 
 Browse all models:
 - [Vercel AI Gateway Models](https://vercel.com/ai-gateway/models)
@@ -240,7 +238,7 @@ const getWeather = new FunctionTool({
 
 const agent = new LlmAgent({
   name: 'weather-assistant',
-  model: 'anthropic/claude-sonnet-4',
+  model: 'anthropic/claude-sonnet-4.5',
   instruction: 'You help users check the weather.',
   tools: [getWeather],
 });
@@ -261,7 +259,7 @@ LLMRegistry.register(OpenRouterLlm);
 
 export const rootAgent = new LlmAgent({
   name: 'assistant',
-  model: 'anthropic/claude-sonnet-4',
+  model: 'anthropic/claude-sonnet-4.5',
   instruction: 'You are helpful.',
 });
 ```

package/dist/config.d.ts

@@ -1,44 +1,160 @@
+/**
+ * @license
+ * Copyright 2025 PAI
+ * SPDX-License-Identifier: MIT
+ */
+/**
+ * Global configuration management for LLM providers.
+ *
+ * This module provides functions to set, get, and reset global configuration
+ * that applies to all instances of a provider. Configuration set here acts
+ * as a fallback when instance-specific configuration is not provided.
+ *
+ * Configuration priority (highest to lowest):
+ * 1. Instance configuration (passed to constructor or factory)
+ * 2. Global configuration (set via this module)
+ * 3. Environment variables
+ * 4. Default values
+ *
+ * @module config
+ *
+ * @example
+ * ```typescript
+ * import { setProviderConfig } from "adk-llm-bridge";
+ *
+ * // Set global config for AI Gateway
+ * setProviderConfig("ai-gateway", {
+ *   apiKey: process.env.AI_GATEWAY_API_KEY
+ * });
+ *
+ * // Set global config for OpenRouter
+ * setProviderConfig("openrouter", {
+ *   apiKey: process.env.OPENROUTER_API_KEY,
+ *   siteUrl: "https://myapp.com"
+ * });
+ * ```
+ */
 import type { RegisterOptions, OpenRouterRegisterOptions } from "./types";
+/**
+ * Mapping of provider identifiers to their configuration types.
+ *
+ * @internal
+ */
 type ProviderConfigMap = {
     "ai-gateway": RegisterOptions;
     openrouter: OpenRouterRegisterOptions;
 };
+/**
+ * Valid provider type identifiers.
+ *
+ * @internal
+ */
 type ProviderType = keyof ProviderConfigMap;
 /**
- * Sets configuration for a specific provider.
+ * 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
- * setProviderConfig("ai-gateway", { apiKey: "..." });
- * setProviderConfig("openrouter", { apiKey: "...", siteUrl: "https://myapp.com" });
+ * // 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"
+ * });
  * ```
  */
 export declare function setProviderConfig<T extends ProviderType>(provider: T, options: ProviderConfigMap[T]): void;
 /**
- * Gets configuration for a specific provider.
+ * 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");
+ * }
+ * ```
  */
 export declare function getProviderConfig<T extends ProviderType>(provider: T): Readonly<ProviderConfigMap[T]> | undefined;
 /**
- * Resets configuration for a specific provider.
+ * 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");
+ * ```
  */
 export 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();
+ * });
+ * ```
  */
 export declare function resetAllConfigs(): void;
 /**
  * Sets global configuration for AI Gateway.
- * @deprecated Use `setProviderConfig("ai-gateway", options)` instead.
+ *
+ * @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: "..." });
+ * ```
  */
 export declare function setConfig(options: RegisterOptions): void;
 /**
  * Gets global configuration for AI Gateway.
- * @deprecated Use `getProviderConfig("ai-gateway")` instead.
+ *
+ * @returns The current AI Gateway configuration
+ *
+ * @deprecated Use {@link getProviderConfig | getProviderConfig("ai-gateway")} instead.
+ * This function will be removed in a future major version.
  */
 export declare function getConfig(): Readonly<RegisterOptions>;
 /**
  * Resets global configuration for AI Gateway.
- * @deprecated Use `resetProviderConfig("ai-gateway")` instead.
+ *
+ * @deprecated Use {@link resetProviderConfig | resetProviderConfig("ai-gateway")} instead.
+ * This function will be removed in a future major version.
  */
 export declare function resetConfig(): void;
 export {};

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,yBAAyB,EAAE,MAAM,SAAS,CAAC;AAE1E,KAAK,iBAAiB,GAAG;IACvB,YAAY,EAAE,eAAe,CAAC;IAC9B,UAAU,EAAE,yBAAyB,CAAC;CACvC,CAAC;AAEF,KAAK,YAAY,GAAG,MAAM,iBAAiB,CAAC;AAS5C;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,YAAY,EACtD,QAAQ,EAAE,CAAC,EACX,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAC5B,IAAI,CAEN;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,YAAY,EACtD,QAAQ,EAAE,CAAC,GACV,QAAQ,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,GAAG,SAAS,CAE5C;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAEhE;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAItC;AAMD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,CAExD;AAED;;;GAGG;AACH,wBAAgB,SAAS,IAAI,QAAQ,CAAC,eAAe,CAAC,CAErD;AAED;;;GAGG;AACH,wBAAgB,WAAW,IAAI,IAAI,CAElC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,yBAAyB,EAAE,MAAM,SAAS,CAAC;AAE1E;;;;GAIG;AACH,KAAK,iBAAiB,GAAG;IACvB,YAAY,EAAE,eAAe,CAAC;IAC9B,UAAU,EAAE,yBAAyB,CAAC;CACvC,CAAC;AAEF;;;;GAIG;AACH,KAAK,YAAY,GAAG,MAAM,iBAAiB,CAAC;AAU5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,YAAY,EACtD,QAAQ,EAAE,CAAC,EACX,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAC5B,IAAI,CAEN;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,YAAY,EACtD,QAAQ,EAAE,CAAC,GACV,QAAQ,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,GAAG,SAAS,CAE5C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAEhE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAItC;AAMD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,CAExD;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,IAAI,QAAQ,CAAC,eAAe,CAAC,CAErD;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,IAAI,IAAI,CAElC"}

package/dist/constants.d.ts

@@ -1,22 +1,126 @@
+/**
+ * @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}
+ */
 export declare const DEFAULT_BASE_URL = "https://ai-gateway.vercel.sh/v1";
+/**
+ * Default request timeout in milliseconds.
+ *
+ * @constant
+ * @defaultValue 60000 (60 seconds)
+ */
 export declare const DEFAULT_TIMEOUT = 60000;
+/**
+ * Default maximum number of retry attempts for failed requests.
+ *
+ * @constant
+ * @defaultValue 2
+ */
 export declare const DEFAULT_MAX_RETRIES = 2;
+/**
+ * Model patterns for AI Gateway model validation.
+ *
+ * Matches any model identifier with the format "provider/model".
+ * AI Gateway validates actual model availability at runtime.
+ *
+ * @constant
+ * @example
+ * ```typescript
+ * MODEL_PATTERNS[0].test("anthropic/claude-sonnet-4"); // true
+ * MODEL_PATTERNS[0].test("invalid"); // false
+ * ```
+ */
 export declare const MODEL_PATTERNS: (string | RegExp)[];
+/**
+ * Environment variable names for AI Gateway configuration.
+ *
+ * These environment variables are checked in order when resolving configuration.
+ *
+ * @constant
+ *
+ * @example
+ * ```bash
+ * # Set in your environment or .env file
+ * export AI_GATEWAY_API_KEY="your-api-key"
+ * export AI_GATEWAY_URL="https://custom-gateway.example.com/v1"
+ * ```
+ */
 export declare const ENV: {
+    /** Environment variable for AI Gateway URL override */
     readonly AI_GATEWAY_URL: "AI_GATEWAY_URL";
+    /** Environment variable for AI Gateway API key */
     readonly AI_GATEWAY_API_KEY: "AI_GATEWAY_API_KEY";
+    /** Fallback environment variable for base URL (OpenAI compatibility) */
     readonly OPENAI_BASE_URL: "OPENAI_BASE_URL";
+    /** Fallback environment variable for API key (OpenAI compatibility) */
     readonly OPENAI_API_KEY: "OPENAI_API_KEY";
 };
+/**
+ * Default base URL for the OpenRouter API.
+ *
+ * @constant
+ * @see {@link https://openrouter.ai/docs|OpenRouter Documentation}
+ */
 export 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.
+ *
+ * @constant
+ * @example
+ * ```typescript
+ * OPENROUTER_MODEL_PATTERNS[0].test("anthropic/claude-sonnet-4"); // true
+ * ```
+ */
 export declare const OPENROUTER_MODEL_PATTERNS: (string | RegExp)[];
+/**
+ * Environment variable names for OpenRouter configuration.
+ *
+ * @constant
+ *
+ * @example
+ * ```bash
+ * # Set in your environment or .env file
+ * export OPENROUTER_API_KEY="your-api-key"
+ * export OPENROUTER_SITE_URL="https://myapp.com"
+ * export OPENROUTER_APP_NAME="My Application"
+ * ```
+ */
 export declare const OPENROUTER_ENV: {
+    /** Environment variable for OpenRouter API key */
     readonly API_KEY: "OPENROUTER_API_KEY";
+    /** Environment variable for site URL (used for rankings) */
     readonly SITE_URL: "OPENROUTER_SITE_URL";
+    /** Environment variable for app name (used for rankings) */
     readonly APP_NAME: "OPENROUTER_APP_NAME";
 };
+/**
+ * Unique identifiers for each provider.
+ *
+ * Used internally for configuration management and registry operations.
+ *
+ * @constant
+ */
 export declare const PROVIDER_IDS: {
+    /** Identifier for the AI Gateway provider */
     readonly AI_GATEWAY: "ai-gateway";
+    /** Identifier for the OpenRouter provider */
     readonly OPENROUTER: "openrouter";
 };
 //# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,gBAAgB,oCAAoC,CAAC;AAClE,eAAO,MAAM,eAAe,QAAS,CAAC;AACtC,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAIrC,eAAO,MAAM,cAAc,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAiB,CAAC;AAEhE,eAAO,MAAM,GAAG;;;;;CAKN,CAAC;AAMX,eAAO,MAAM,mBAAmB,iCAAiC,CAAC;AAGlE,eAAO,MAAM,yBAAyB,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAiB,CAAC;AAE3E,eAAO,MAAM,cAAc;;;;CAIjB,CAAC;AAMX,eAAO,MAAM,YAAY;;;CAGf,CAAC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;GAOG;AAMH;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,oCAAoC,CAAC;AAElE;;;;;GAKG;AACH,eAAO,MAAM,eAAe,QAAS,CAAC;AAEtC;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,cAAc,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAiB,CAAC;AAEhE;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,GAAG;IACd,uDAAuD;;IAGvD,kDAAkD;;IAGlD,wEAAwE;;IAGxE,uEAAuE;;CAE/D,CAAC;AAMX;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,iCAAiC,CAAC;AAElE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,yBAAyB,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAiB,CAAC;AAE3E;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,cAAc;IACzB,kDAAkD;;IAGlD,4DAA4D;;IAG5D,4DAA4D;;CAEpD,CAAC;AAMX;;;;;;GAMG;AACH,eAAO,MAAM,YAAY;IACvB,6CAA6C;;IAG7C,6CAA6C;;CAErC,CAAC"}

package/dist/converters/index.d.ts

@@ -1,3 +1,32 @@
+/**
+ * @license
+ * Copyright 2025 PAI
+ * SPDX-License-Identifier: MIT
+ */
+/**
+ * Request and response converters for ADK ↔ OpenAI format.
+ *
+ * This module exports functions for converting between ADK's LlmRequest/LlmResponse
+ * format and OpenAI's chat completion API format.
+ *
+ * @module converters
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   convertRequest,
+ *   convertResponse,
+ *   convertStreamChunk,
+ *   createStreamAccumulator
+ * } from "adk-llm-bridge";
+ *
+ * // Convert ADK request to OpenAI format
+ * const { messages, tools } = convertRequest(adkRequest);
+ *
+ * // Convert OpenAI response to ADK format
+ * const adkResponse = convertResponse(openaiResponse);
+ * ```
+ */
 export { convertRequest } from "./request";
 export { convertResponse, convertStreamChunk, createStreamAccumulator, } from "./response";
 //# sourceMappingURL=index.d.ts.map

package/dist/converters/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/converters/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EACL,eAAe,EACf,kBAAkB,EAClB,uBAAuB,GACxB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/converters/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EACL,eAAe,EACf,kBAAkB,EAClB,uBAAuB,GACxB,MAAM,YAAY,CAAC"}

package/dist/converters/request.d.ts

@@ -1,8 +1,87 @@
+/**
+ * @license
+ * Copyright 2025 PAI
+ * SPDX-License-Identifier: MIT
+ */
+/**
+ * Request converter for ADK to OpenAI format.
+ *
+ * This module handles the conversion of ADK LlmRequest objects to
+ * OpenAI-compatible chat completion request format.
+ *
+ * @module converters/request
+ */
 import type { LlmRequest } from "@google/adk";
 import type OpenAI 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.
+ */
 export interface ConvertedRequest {
+    /**
+     * Array of OpenAI-format chat messages.
+     *
+     * Includes system, user, assistant, and tool messages
+     * converted from ADK Content objects.
+     */
     messages: OpenAI.ChatCompletionMessageParam[];
+    /**
+     * Array of OpenAI-format tool definitions.
+     *
+     * Converted from ADK function declarations with schema normalization.
+     */
     tools?: OpenAI.ChatCompletionTool[];
 }
+/**
+ * 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")
+ * ```
+ */
 export declare function convertRequest(llmRequest: LlmRequest): ConvertedRequest;
 //# sourceMappingURL=request.d.ts.map

package/dist/converters/request.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../../src/converters/request.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AAEjC,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC,0BAA0B,EAAE,CAAC;IAC9C,KAAK,CAAC,EAAE,MAAM,CAAC,kBAAkB,EAAE,CAAC;CACrC;AAED,wBAAgB,cAAc,CAAC,UAAU,EAAE,UAAU,GAAG,gBAAgB,CAavE"}
+{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../../src/converters/request.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AAEjC;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;OAKG;IACH,QAAQ,EAAE,MAAM,CAAC,0BAA0B,EAAE,CAAC;IAE9C;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC,kBAAkB,EAAE,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,UAAU,GAAG,gBAAgB,CAavE"}

package/dist/converters/response.d.ts

@@ -1,7 +1,103 @@
+/**
+ * @license
+ * Copyright 2025 PAI
+ * SPDX-License-Identifier: MIT
+ */
+/**
+ * Response converter for OpenAI to ADK format.
+ *
+ * This module handles the conversion of OpenAI API responses to
+ * ADK LlmResponse format, supporting both single responses and streaming.
+ *
+ * @module converters/response
+ */
 import type { LlmResponse } from "@google/adk";
 import type OpenAI from "openai";
 import type { StreamAccumulator, StreamChunkResult } from "../types";
+/**
+ * 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);
+ *   }
+ * }
+ * ```
+ */
 export declare function convertResponse(response: OpenAI.ChatCompletion): LlmResponse;
+/**
+ * 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;
+ *   }
+ * }
+ * ```
+ */
 export declare function convertStreamChunk(chunk: OpenAI.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
+ * }
+ * ```
+ */
 export declare function createStreamAccumulator(): StreamAccumulator;
 //# sourceMappingURL=response.d.ts.map