adk-llm-bridge 0.5.2 → 0.5.3

package/README.md

@@ -67,10 +67,10 @@ model: OpenRouter('anthropic/claude-sonnet-4')
 model: OpenAI('gpt-4.1')
 
 // Anthropic - Direct API  
-model: Anthropic('claude-sonnet-4-5')
+model: Anthropic('claude-sonnet-4-6')
 
 // xAI - Direct API
-model: XAI('grok-3-beta')
+model: XAI('grok-4.3')
 
 // Local models (LM Studio, Ollama, etc.)
 model: Custom('your-model', { baseURL: 'http://localhost:1234/v1' })
@@ -90,7 +90,7 @@ LLMRegistry.register(AnthropicLlm);
 
 const agent = new LlmAgent({
   name: 'assistant',
-  model: 'claude-sonnet-4-5',  // String-based model name
+  model: 'claude-sonnet-4-6',  // String-based model name
   instruction: 'You are a helpful assistant.',
 });
 ```
@@ -140,7 +140,7 @@ model: OpenRouter('anthropic/claude-sonnet-4', {
 })
 
 // Anthropic with custom max tokens
-model: Anthropic('claude-sonnet-4-5', {
+model: Anthropic('claude-sonnet-4-6', {
   apiKey: process.env.ANTHROPIC_API_KEY,
   maxTokens: 8192,
 })
@@ -205,7 +205,7 @@ const getWeather = new FunctionTool({
 
 const agent = new LlmAgent({
   name: 'weather-assistant',
-  model: Anthropic('claude-sonnet-4-5'),
+  model: Anthropic('claude-sonnet-4-6'),
   instruction: 'You help users check the weather.',
   tools: [getWeather],
 });
@@ -298,12 +298,13 @@ See the [examples](./examples) directory:
 - **[basic-agent-anthropic](./examples/basic-agent-anthropic)** - Multi-agent HelpDesk with Anthropic
 - **[basic-agent-xai](./examples/basic-agent-xai)** - Multi-agent HelpDesk with xAI
 - **[basic-agent-lmstudio](./examples/basic-agent-lmstudio)** - Multi-agent HelpDesk with LM Studio
+- **[native-features](./examples/native-features)** - Showcase of native model capabilities (sampling, reasoning, structured output, multimodal, tool_choice, streaming) across all 5 providers
 - **[express-server](./examples/express-server)** - Production HTTP API with sessions, streaming, tools
 
 ## Requirements
 
 - Node.js >= 18.0.0
-- `@google/adk` >= 0.2.2
+- `@google/adk` >= 0.5.0 (peer range `>=0.5.0 <2`; tested against 1.2.0)
 
 ## Contributing
 

package/dist/index.d.ts

@@ -470,6 +470,22 @@ interface AnthropicProviderConfig extends BaseProviderConfig {
 	* @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.
@@ -497,6 +513,17 @@ interface AnthropicRegisterOptions {
 	* @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.
@@ -538,8 +565,23 @@ interface ToolCallAccumulator {
 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<number, ToolCallAccumulator>;
+	/**
+	* 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.
@@ -858,6 +900,12 @@ declare class AnthropicLlm extends BaseProviderLlm {
 	*/
 	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
@@ -886,6 +934,9 @@ declare class AnthropicLlm extends BaseProviderLlm {
 	/**
 	* 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;
@@ -1373,6 +1424,19 @@ interface ConvertedRequest {
 	* 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<string, unknown>;
+	/**
+	* 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.
@@ -1423,7 +1487,48 @@ interface ConvertedRequest {
 * // tools[0].function.parameters.type = "object" (normalized from "OBJECT")
 * ```
 */
-declare function convertRequest(llmRequest: LlmRequest5): ConvertedRequest;
+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<string, unknown>;
+/**
+* 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<string, unknown>;
 import { LlmResponse as LlmResponse6 } from "@google/adk";
 import OpenAI4 from "openai";
 /**
@@ -1512,4 +1617,35 @@ declare function convertStreamChunk(chunk: OpenAI4.ChatCompletionChunk, acc: Str
 * ```
 */
 declare function createStreamAccumulator(): StreamAccumulator;
-export { setProviderConfig, setConfig, resetProviderConfig, resetConfig, resetAllConfigs, registerXAI, registerOpenRouter, registerOpenAI, registerAnthropic, registerAIGateway, isXAIRegistered, isOpenRouterRegistered, isOpenAIRegistered, isAnthropicRegistered, isAIGatewayRegistered, getProviderConfig, getConfig, createStreamAccumulator, createCustomLlm, convertStreamChunk, convertResponse, convertRequest, 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 };
+/**
+* @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<string, unknown> | 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 };