adk-llm-bridge 0.3.4 → 0.5.1

package/dist/config.d.ts

@@ -34,7 +34,7 @@
  * });
  * ```
  */
-import type { AnthropicRegisterOptions, OpenAIRegisterOptions, OpenRouterRegisterOptions, RegisterOptions, XAIRegisterOptions } from "./types";
+import type { AnthropicRegisterOptions, OpenAIRegisterOptions, OpenRouterRegisterOptions, RegisterOptions, XAIRegisterOptions } from "./types.js";
 /**
  * Mapping of provider identifiers to their configuration types.
  *

package/dist/converters/index.d.ts

@@ -27,6 +27,6 @@
  * const adkResponse = convertResponse(openaiResponse);
  * ```
  */
-export { convertRequest } from "./request";
-export { convertResponse, convertStreamChunk, createStreamAccumulator, } from "./response";
+export { convertRequest } from "./request.js";
+export { convertResponse, convertStreamChunk, createStreamAccumulator, } from "./response.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/converters/response.d.ts

@@ -13,7 +13,7 @@
  */
 import type { LlmResponse } from "@google/adk";
 import type OpenAI from "openai";
-import type { StreamAccumulator, StreamChunkResult } from "../types";
+import type { StreamAccumulator, StreamChunkResult } from "../types.js";
 /**
  * Converts an OpenAI chat completion response to ADK LlmResponse format.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"response.d.ts","sourceRoot":"","sources":["../../src/converters/response.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AACjC,OAAO,KAAK,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAErE;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,CAAC,cAAc,GAAG,WAAW,CAqC5E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,CAAC,mBAAmB,EACjC,GAAG,EAAE,iBAAiB,GACrB,iBAAiB,CA2DnB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,uBAAuB,IAAI,iBAAiB,CAE3D"}
+{"version":3,"file":"response.d.ts","sourceRoot":"","sources":["../../src/converters/response.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AACjC,OAAO,KAAK,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAGrE;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,CAAC,cAAc,GAAG,WAAW,CAsC5E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,CAAC,mBAAmB,EACjC,GAAG,EAAE,iBAAiB,GACrB,iBAAiB,CA2DnB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,uBAAuB,IAAI,iBAAiB,CAE3D"}

package/dist/core/base-provider-llm.d.ts

@@ -13,7 +13,7 @@
  */
 import type { BaseLlmConnection, LlmRequest, LlmResponse } from "@google/adk";
 import { BaseLlm } from "@google/adk";
-import type { BaseProviderConfig } from "../types";
+import type { BaseProviderConfig } from "../types.js";
 /**
  * Abstract base class for all LLM providers in adk-llm-bridge.
  *

package/dist/core/base-provider-llm.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"base-provider-llm.d.ts","sourceRoot":"","sources":["../../src/core/base-provider-llm.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC9E,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACtC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,8BAAsB,eAAgB,SAAQ,OAAO;IACnD;;;;;;OAMG;IACH,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IAE9C;;;;OAIG;gBACS,MAAM,EAAE,kBAAkB;IAKtC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,oBAAoB,CAC3B,UAAU,EAAE,UAAU,EACtB,MAAM,CAAC,EAAE,OAAO,GACf,cAAc,CAAC,WAAW,EAAE,IAAI,CAAC;IAEpC;;;;;;;;;OASG;IACG,OAAO,CAAC,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAMxD;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,SAAS,CAAC,mBAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,WAAW;CAe3E"}
+{"version":3,"file":"base-provider-llm.d.ts","sourceRoot":"","sources":["../../src/core/base-provider-llm.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC9E,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACtC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,8BAAsB,eAAgB,SAAQ,OAAO;IACnD;;;;;;OAMG;IACH,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IAE9C;;;;OAIG;gBACS,MAAM,EAAE,kBAAkB;IAUtC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,oBAAoB,CAC3B,UAAU,EAAE,UAAU,EACtB,MAAM,CAAC,EAAE,OAAO,GACf,cAAc,CAAC,WAAW,EAAE,IAAI,CAAC;IAEpC;;;;;;;;;OASG;IACG,OAAO,CAAC,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAMxD;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,SAAS,CAAC,mBAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,WAAW;CAe3E"}

package/dist/core/config-resolver.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @license
+ * Copyright 2025 PAI
+ * SPDX-License-Identifier: MIT
+ */
+import type { BaseProviderConfig } from "../types.js";
+import type { ProviderDefinition } from "./provider-definition.js";
+/**
+ * Fully resolved configuration ready to create an OpenAI client.
+ */
+export interface ResolvedConfig {
+    baseURL: string;
+    apiKey: string;
+    timeout: number;
+    maxRetries: number;
+    headers: Record<string, string>;
+}
+/**
+ * Resolves the first defined environment variable from a list of keys.
+ *
+ * @param keys - Environment variable names to check, in priority order
+ * @returns The first found value, or undefined
+ */
+export declare function resolveEnvVar(keys: string[]): string | undefined;
+/**
+ * Resolves provider configuration from multiple sources.
+ *
+ * Priority order (highest to lowest):
+ * 1. Instance config (passed to constructor)
+ * 2. Global config (via setProviderConfig)
+ * 3. Environment variables
+ * 4. Default values from the provider definition
+ *
+ * @param definition - The provider definition with defaults and env var names
+ * @param instanceConfig - Instance-level configuration
+ * @returns Fully resolved configuration
+ */
+export declare function resolveConfig(definition: ProviderDefinition, instanceConfig: BaseProviderConfig): ResolvedConfig;
+//# sourceMappingURL=config-resolver.d.ts.map

package/dist/core/config-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-resolver.d.ts","sourceRoot":"","sources":["../../src/core/config-resolver.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAaH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAEnD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAEhE;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,SAAS,CAMhE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,kBAAkB,EAC9B,cAAc,EAAE,kBAAkB,GACjC,cAAc,CAiDhB"}

package/dist/core/create-provider.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @license
+ * Copyright 2025 PAI
+ * SPDX-License-Identifier: MIT
+ */
+/**
+ * Factory utilities for creating provider classes and functions
+ * from declarative provider definitions.
+ *
+ * @module core/create-provider
+ */
+import type { BaseLlm } from "@google/adk";
+import type { BaseProviderConfig } from "../types.js";
+import { OpenAICompatibleLlm } from "./openai-compatible-llm.js";
+import type { ProviderDefinition } from "./provider-definition.js";
+/** Type compatible with LLMRegistry.register(). */
+type RegisterableLlm = (new (params: {
+    model: string;
+}) => BaseLlm) & {
+    readonly supportedModels: (string | RegExp)[];
+};
+/**
+ * Creates a typed LLM class with static `supportedModels` for LLMRegistry.
+ *
+ * The returned class can be registered with ADK's LLMRegistry and
+ * instantiated by model name matching.
+ *
+ * @param definition - The provider definition
+ * @returns A concrete class extending OpenAICompatibleLlm
+ */
+export declare function createProviderClass(definition: ProviderDefinition): RegisterableLlm;
+/**
+ * Creates a factory function for convenient provider instantiation.
+ *
+ * @param definition - The provider definition
+ * @returns A factory function: `(model, options?) => OpenAICompatibleLlm`
+ */
+export declare function createProviderFactory(definition: ProviderDefinition): (model: string, options?: Partial<Omit<BaseProviderConfig, "model">>) => OpenAICompatibleLlm;
+export {};
+//# sourceMappingURL=create-provider.d.ts.map

package/dist/core/create-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-provider.d.ts","sourceRoot":"","sources":["../../src/core/create-provider.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AACnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAEhE,mDAAmD;AACnD,KAAK,eAAe,GAAG,CAAC,KAAK,MAAM,EAAE;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,KAAK,OAAO,CAAC,GAAG;IACpE,QAAQ,CAAC,eAAe,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;CAC/C,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,kBAAkB,GAC7B,eAAe,CAQjB;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,kBAAkB,IAEhE,OAAO,MAAM,EACb,UAAU,OAAO,CAAC,IAAI,CAAC,kBAAkB,EAAE,OAAO,CAAC,CAAC,KACnD,mBAAmB,CAEvB"}

package/dist/core/create-register.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @license
+ * Copyright 2025 PAI
+ * SPDX-License-Identifier: MIT
+ */
+/**
+ * Factory for creating provider registration functions.
+ *
+ * Eliminates the duplicated singleton registration pattern that was
+ * previously copy-pasted in every provider's register.ts file.
+ *
+ * @module core/create-register
+ */
+import type { BaseLlm } from "@google/adk";
+import type { ProviderDefinition } from "./provider-definition.js";
+/** Type that LLMRegistry.register() expects. */
+type RegisterableLlm = (new (params: {
+    model: string;
+}) => BaseLlm) & {
+    readonly supportedModels: (string | RegExp)[];
+};
+/**
+ * Creates registration functions for a provider.
+ *
+ * Returns an object with `register`, `isRegistered`, and `_reset` functions
+ * that implement the idempotent singleton registration pattern.
+ *
+ * @param definition - The provider definition
+ * @param ProviderClass - The LLM class to register (must have static supportedModels)
+ * @returns Registration function set
+ */
+export declare function createRegisterFunction(definition: ProviderDefinition, ProviderClass: RegisterableLlm): {
+    register(options?: Record<string, unknown>): void;
+    isRegistered(): boolean;
+    _reset(): void;
+};
+export {};
+//# sourceMappingURL=create-register.d.ts.map

package/dist/core/create-register.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-register.d.ts","sourceRoot":"","sources":["../../src/core/create-register.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAG3C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAEhE,gDAAgD;AAChD,KAAK,eAAe,GAAG,CAAC,KAAK,MAAM,EAAE;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,KAAK,OAAO,CAAC,GAAG;IACpE,QAAQ,CAAC,eAAe,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;CAC/C,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,kBAAkB,EAC9B,aAAa,EAAE,eAAe;uBAKT,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;oBAiBjC,OAAO;cAIb,IAAI;EAKjB"}

package/dist/core/index.d.ts

@@ -35,7 +35,12 @@
  * }
  * ```
  */
-export { BaseProviderLlm } from "./base-provider-llm";
-export type { OpenAIClientConfig } from "./openai-compatible-llm";
-export { OpenAICompatibleLlm } from "./openai-compatible-llm";
+export { BaseProviderLlm } from "./base-provider-llm.js";
+export { resolveConfig, resolveEnvVar } from "./config-resolver.js";
+export type { ResolvedConfig } from "./config-resolver.js";
+export { createProviderClass, createProviderFactory } from "./create-provider.js";
+export { createRegisterFunction } from "./create-register.js";
+export type { OpenAIClientConfig } from "./openai-compatible-llm.js";
+export { OpenAICompatibleLlm } from "./openai-compatible-llm.js";
+export type { ProviderDefinition, ProviderEnvKeys, } from "./provider-definition.js";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,YAAY,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACjE,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAC/E,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,YAAY,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,YAAY,EACV,kBAAkB,EAClB,eAAe,GAChB,MAAM,uBAAuB,CAAC"}

package/dist/core/openai-compatible-llm.d.ts

@@ -7,185 +7,75 @@
  * OpenAI-compatible LLM base class.
  *
  * This module provides the base class for LLM providers that use
- * OpenAI-compatible APIs (chat completions endpoint).
+ * OpenAI-compatible APIs (chat completions endpoint). Providers can
+ * be created either by extending this class or by using a declarative
+ * {@link ProviderDefinition}.
  *
  * @module core/openai-compatible-llm
  */
 import type { LlmRequest, LlmResponse } from "@google/adk";
 import OpenAI from "openai";
-import type { BaseProviderConfig } from "../types";
-import { BaseProviderLlm } from "./base-provider-llm";
+import type { BaseProviderConfig } from "../types.js";
+import { BaseProviderLlm } from "./base-provider-llm.js";
+import type { ProviderDefinition } from "./provider-definition.js";
 /**
  * Configuration for the underlying OpenAI client.
  *
  * These options are passed directly to the OpenAI SDK constructor.
  */
 export interface OpenAIClientConfig {
-    /**
-     * Base URL for the API endpoint.
-     *
-     * @example "https://ai-gateway.vercel.sh/v1"
-     * @example "https://openrouter.ai/api/v1"
-     */
+    /** Base URL for the API endpoint. */
     baseURL: string;
-    /**
-     * API key for authentication.
-     */
+    /** API key for authentication. */
     apiKey: string;
-    /**
-     * Request timeout in milliseconds.
-     */
+    /** Request timeout in milliseconds. */
     timeout: number;
-    /**
-     * Maximum number of retry attempts.
-     */
+    /** Maximum number of retry attempts. */
     maxRetries: number;
-    /**
-     * Additional HTTP headers to include in all requests.
-     *
-     * Useful for provider-specific headers like OpenRouter's site attribution.
-     */
+    /** Additional HTTP headers to include in all requests. */
     defaultHeaders?: Record<string, string>;
 }
 /**
  * Base class for LLM providers that use OpenAI-compatible APIs.
  *
- * Handles the common logic for:
- * - Converting ADK requests to OpenAI format
- * - Making chat completion API calls
- * - Processing both streaming and non-streaming responses
- * - Converting responses back to ADK format
+ * Supports two construction modes:
  *
- * Extend this class to implement support for any OpenAI-compatible API.
+ * 1. **Declarative** (recommended): Pass a {@link ProviderDefinition} that
+ *    describes the provider's configuration. Config resolution is automatic.
  *
- * @abstract
+ * 2. **Manual**: Pass a {@link BaseProviderConfig} + {@link OpenAIClientConfig}
+ *    with pre-resolved values. Used by CustomLlm which has unique URL logic.
  *
  * @example
  * ```typescript
- * class MyProviderLlm extends OpenAICompatibleLlm {
- *   static supportedModels = [/^myprovider\/.+$/];
+ * // Declarative (most providers)
+ * const llm = new OpenAICompatibleLlm(MY_DEFINITION, { model: "gpt-4o" });
  *
- *   constructor(config: MyProviderConfig) {
- *     super(config, {
- *       baseURL: "https://api.myprovider.com/v1",
- *       apiKey: config.apiKey,
- *       timeout: config.timeout ?? 60000,
- *       maxRetries: config.maxRetries ?? 2
- *     });
- *   }
- *
- *   protected getErrorPrefix(): string {
- *     return "MY_PROVIDER";
+ * // Manual (Custom provider)
+ * class CustomLlm extends OpenAICompatibleLlm {
+ *   constructor(config) {
+ *     super(config, { baseURL, apiKey, timeout, maxRetries });
  *   }
  * }
  * ```
- *
- * @see {@link BaseProviderLlm} for the parent class
- * @see {@link AIGatewayLlm} for AI Gateway implementation
- * @see {@link OpenRouterLlm} for OpenRouter implementation
  */
-export declare abstract class OpenAICompatibleLlm extends BaseProviderLlm {
-    /**
-     * The OpenAI SDK client instance.
-     *
-     * @protected
-     */
+export declare class OpenAICompatibleLlm extends BaseProviderLlm {
+    /** Model patterns for LLMRegistry — set by createProviderClass(). */
+    static supportedModels: (string | RegExp)[];
+    /** @protected */
     protected readonly client: OpenAI;
-    /**
-     * Creates a new OpenAI-compatible LLM instance.
-     *
-     * @param config - Provider configuration (model, options)
-     * @param clientConfig - OpenAI client configuration (URL, auth, timeouts)
-     */
+    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-specific error prefix for error responses.
-     *
-     * Override in subclasses to return an appropriate prefix like
-     * "AI_GATEWAY" or "OPENROUTER".
-     *
-     * @returns The error prefix string
-     *
-     * @abstract
-     * @protected
-     *
-     * @example
-     * ```typescript
-     * protected getErrorPrefix(): string {
-     *   return "MY_PROVIDER";
-     * }
-     * // Errors will have codes like "MY_PROVIDER_ERROR" or "API_ERROR_429"
-     * ```
-     */
-    protected abstract getErrorPrefix(): string;
-    /**
-     * Returns provider-specific options to merge into chat completion requests.
-     *
-     * Override in subclasses to add provider-specific parameters.
-     * The returned object is spread into the chat completion request body.
-     *
-     * @returns An object of additional request options
-     *
-     * @protected
-     *
-     * @example
-     * ```typescript
-     * protected getProviderRequestOptions(): Record<string, unknown> {
-     *   return {
-     *     provider: {
-     *       order: ["Anthropic"],
-     *       allow_fallbacks: true
-     *     }
-     *   };
-     * }
-     * ```
-     */
+    /** Returns the provider error prefix. */
+    protected getErrorPrefix(): string;
+    /** Returns provider-specific request options. */
     protected getProviderRequestOptions(): Record<string, unknown>;
-    /**
-     * Generates content from the LLM.
-     *
-     * Converts the ADK request to OpenAI 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
-     *
-     * @example
-     * ```typescript
-     * // Non-streaming
-     * for await (const response of llm.generateContentAsync(request)) {
-     *   console.log(response);
-     * }
-     *
-     * // Streaming
-     * for await (const response of llm.generateContentAsync(request, true)) {
-     *   if (response.text) {
-     *     process.stdout.write(response.text);
-     *   }
-     * }
-     * ```
-     */
     generateContentAsync(llmRequest: LlmRequest, stream?: boolean): AsyncGenerator<LlmResponse, void>;
-    /**
-     * Makes a single (non-streaming) API request.
-     *
-     * @param messages - OpenAI format messages
-     * @param tools - OpenAI format tools (optional)
-     * @returns The converted LLM response
-     *
-     * @private
-     */
     private singleResponse;
-    /**
-     * Makes a streaming API request and yields responses as they arrive.
-     *
-     * @param messages - OpenAI format messages
-     * @param tools - OpenAI format tools (optional)
-     * @returns An async generator yielding LLM responses
-     *
-     * @private
-     */
     private streamResponse;
 }
 //# sourceMappingURL=openai-compatible-llm.d.ts.map

package/dist/core/openai-compatible-llm.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"openai-compatible-llm.d.ts","sourceRoot":"","sources":["../../src/core/openai-compatible-llm.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC3D,OAAO,MAAM,MAAM,QAAQ,CAAC;AAO5B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEtD;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;OAKG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACzC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,8BAAsB,mBAAoB,SAAQ,eAAe;IAC/D;;;;OAIG;IACH,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAElC;;;;;OAKG;gBACS,MAAM,EAAE,kBAAkB,EAAE,YAAY,EAAE,kBAAkB;IAWxE;;;;;;;;;;;;;;;;;;OAkBG;IACH,SAAS,CAAC,QAAQ,CAAC,cAAc,IAAI,MAAM;IAE3C;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,SAAS,CAAC,yBAAyB,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAI9D;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACI,oBAAoB,CACzB,UAAU,EAAE,UAAU,EACtB,MAAM,UAAQ,GACb,cAAc,CAAC,WAAW,EAAE,IAAI,CAAC;IAcpC;;;;;;;;OAQG;YACW,cAAc;IAa5B;;;;;;;;OAQG;YACY,cAAc;CAoB9B"}
+{"version":3,"file":"openai-compatible-llm.d.ts","sourceRoot":"","sources":["../../src/core/openai-compatible-llm.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC3D,OAAO,MAAM,MAAM,QAAQ,CAAC;AAO5B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEtD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAEhE;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,qCAAqC;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,0DAA0D;IAC1D,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACzC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,mBAAoB,SAAQ,eAAe;IACtD,qEAAqE;IACrE,MAAM,CAAC,eAAe,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAM;IAEjD,iBAAiB;IACjB,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAElC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAC,CAAgC;IAEpE,mDAAmD;gBACvC,UAAU,EAAE,kBAAkB,EAAE,MAAM,EAAE,kBAAkB;IACtE,gEAAgE;gBACpD,MAAM,EAAE,kBAAkB,EAAE,YAAY,EAAE,kBAAkB;IA+CxE,yCAAyC;IACzC,SAAS,CAAC,cAAc,IAAI,MAAM;IAIlC,iDAAiD;IACjD,SAAS,CAAC,yBAAyB,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAIvD,oBAAoB,CACzB,UAAU,EAAE,UAAU,EACtB,MAAM,UAAQ,GACb,cAAc,CAAC,WAAW,EAAE,IAAI,CAAC;YActB,cAAc;YAab,cAAc;CAoB9B"}

package/dist/core/provider-definition.d.ts

@@ -0,0 +1,66 @@
+/**
+ * @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.
+ */
+export 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: [/.+\/.+/],
+ * };
+ * ```
+ */
+export 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<string, unknown>) => Record<string, string>;
+    /** Build provider-specific options to merge into request body */
+    buildRequestOptions?: (config: Record<string, unknown>) => Record<string, unknown>;
+    /**
+     * 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;
+}
+//# sourceMappingURL=provider-definition.d.ts.map

package/dist/core/provider-definition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-definition.d.ts","sourceRoot":"","sources":["../../src/core/provider-definition.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;GAQG;AAEH;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,4DAA4D;IAC5D,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,6DAA6D;IAC7D,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,kBAAkB;IACjC,0EAA0E;IAC1E,EAAE,EAAE,MAAM,CAAC;IAEX,4EAA4E;IAC5E,WAAW,EAAE,MAAM,CAAC;IAEpB,gEAAgE;IAChE,cAAc,EAAE,MAAM,CAAC;IAEvB,mEAAmE;IACnE,OAAO,EAAE,eAAe,CAAC;IAEzB,8CAA8C;IAC9C,aAAa,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;IAEnC,yDAAyD;IACzD,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAE3E,iEAAiE;IACjE,mBAAmB,CAAC,EAAE,CACpB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC5B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAE7B;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB"}

package/dist/index.d.ts

@@ -58,18 +58,18 @@
  * @see {@link https://google.github.io/adk-docs/|Google ADK Documentation}
  */
 export { BaseLlm } from "@google/adk";
-export { BaseProviderLlm } from "./core/base-provider-llm";
-export type { OpenAIClientConfig } from "./core/openai-compatible-llm";
-export { OpenAICompatibleLlm } from "./core/openai-compatible-llm";
-export { AIGateway, AIGatewayLlm, isAIGatewayRegistered, registerAIGateway, } from "./providers/ai-gateway";
-export { isOpenRouterRegistered, OpenRouter, OpenRouterLlm, registerOpenRouter, } from "./providers/openrouter";
-export { isOpenAIRegistered, OpenAI, OpenAILlm, registerOpenAI, } from "./providers/openai";
-export { isXAIRegistered, registerXAI, XAI, XAILlm } from "./providers/xai";
-export { Anthropic, AnthropicLlm, isAnthropicRegistered, registerAnthropic, } from "./providers/anthropic";
-export { Custom, CustomLlm, type CustomLlmProviderConfig, createCustomLlm, } from "./providers/custom";
-export type { AIGatewayConfig, AnthropicProviderConfig, AnthropicRegisterOptions, BaseProviderConfig, CustomLlmConfig, OpenAIProviderConfig, OpenAIRegisterOptions, OpenRouterConfig, OpenRouterProviderPreferences, OpenRouterRegisterOptions, RegisterOptions, StreamAccumulator, StreamChunkResult, ToolCallAccumulator, XAIProviderConfig, XAIRegisterOptions, } from "./types";
-export { DEFAULT_BASE_URL, MODEL_PATTERNS, OPENROUTER_BASE_URL, OPENROUTER_MODEL_PATTERNS, PROVIDER_IDS, } from "./constants";
-export { getConfig, getProviderConfig, resetAllConfigs, resetConfig, resetProviderConfig, setConfig, setProviderConfig, } from "./config";
-export { convertRequest } from "./converters/request";
-export { convertResponse, convertStreamChunk, createStreamAccumulator, } from "./converters/response";
+export { BaseProviderLlm } from "./core/base-provider-llm.js";
+export type { OpenAIClientConfig } from "./core/openai-compatible-llm.js";
+export { OpenAICompatibleLlm } from "./core/openai-compatible-llm.js";
+export { AIGateway, AIGatewayLlm, isAIGatewayRegistered, registerAIGateway, } from "./providers/ai-gateway/index.js";
+export { isOpenRouterRegistered, OpenRouter, OpenRouterLlm, registerOpenRouter, } from "./providers/openrouter/index.js";
+export { isOpenAIRegistered, OpenAI, OpenAILlm, registerOpenAI, } from "./providers/openai/index.js";
+export { isXAIRegistered, registerXAI, XAI, XAILlm } from "./providers/xai/index.js";
+export { Anthropic, AnthropicLlm, isAnthropicRegistered, registerAnthropic, } from "./providers/anthropic/index.js";
+export { Custom, CustomLlm, type CustomLlmProviderConfig, createCustomLlm, } from "./providers/custom/index.js";
+export type { AIGatewayConfig, AnthropicProviderConfig, AnthropicRegisterOptions, BaseProviderConfig, CustomLlmConfig, OpenAIProviderConfig, OpenAIRegisterOptions, OpenRouterConfig, OpenRouterProviderPreferences, OpenRouterRegisterOptions, RegisterOptions, StreamAccumulator, StreamChunkResult, ToolCallAccumulator, XAIProviderConfig, XAIRegisterOptions, } from "./types.js";
+export { DEFAULT_BASE_URL, MODEL_PATTERNS, OPENROUTER_BASE_URL, OPENROUTER_MODEL_PATTERNS, PROVIDER_IDS, } from "./constants.js";
+export { getConfig, getProviderConfig, resetAllConfigs, resetConfig, resetProviderConfig, setConfig, setProviderConfig, } from "./config.js";
+export { convertRequest } from "./converters/request.js";
+export { convertResponse, convertStreamChunk, createStreamAccumulator, } from "./converters/response.js";
 //# sourceMappingURL=index.d.ts.map