@tanstack/ai 0.25.0 → 0.26.1

package/dist/esm/extend-adapter.d.ts

@@ -13,13 +13,24 @@ import { Modality } from './types.js';
  * ] as const
  * ```
  */
-export interface ExtendedModelDef<TName extends string = string, TInput extends ReadonlyArray<Modality> = ReadonlyArray<Modality>, TOptions = unknown> {
+export interface ExtendedModelDef<TName extends string = string, TInput extends ReadonlyArray<Modality> = ReadonlyArray<Modality>, TOptions = unknown, TFeatures extends ReadonlyArray<string> = ReadonlyArray<string>, TTools extends ReadonlyArray<string> = ReadonlyArray<string>> {
     /** The model name identifier */
     name: TName;
     /** Supported input modalities for this model */
     input: TInput;
     /** Type brand for provider options - use `{} as YourOptionsType` */
     modelOptions: TOptions;
+    /** Optional declared features (e.g. 'reasoning', 'structured_outputs') */
+    features?: TFeatures;
+    /** Optional declared provider tools (e.g. 'web_search') */
+    tools?: TTools;
+}
+/** Capability bag accepted by the object form of `createModel`. */
+export interface ModelCapabilities<TInput extends ReadonlyArray<Modality> = ReadonlyArray<Modality>, TFeatures extends ReadonlyArray<string> = ReadonlyArray<string>, TTools extends ReadonlyArray<string> = ReadonlyArray<string>, TOptions = unknown> {
+    input?: TInput;
+    features?: TFeatures;
+    tools?: TTools;
+    modelOptions?: TOptions;
 }
 /**
  * Creates a custom model definition for use with `extendAdapter`.
@@ -47,8 +58,19 @@ export interface ExtendedModelDef<TName extends string = string, TInput extends
  *
  * const myOpenai = extendAdapter(openaiText, customModels)
  * ```
+ *
+ * @example
+ * ```typescript
+ * // Capabilities object form - declare features and provider tools
+ * const reasoner = createModel('reasoner', {
+ *   input: ['text'],
+ *   features: ['reasoning', 'structured_outputs'],
+ *   tools: ['web_search'],
+ * })
+ * ```
  */
 export declare function createModel<const TName extends string, const TInput extends ReadonlyArray<Modality>>(name: TName, input: TInput): ExtendedModelDef<TName, TInput>;
+export declare function createModel<const TName extends string, const TCaps extends ModelCapabilities>(name: TName, capabilities: TCaps): ExtendedModelDef<TName, TCaps['input'] extends ReadonlyArray<Modality> ? TCaps['input'] : ReadonlyArray<Modality>, TCaps['modelOptions'], TCaps['features'] extends ReadonlyArray<string> ? TCaps['features'] : ReadonlyArray<string>, TCaps['tools'] extends ReadonlyArray<string> ? TCaps['tools'] : ReadonlyArray<string>>;
 /**
  * Extract the model name union from an array of model definitions.
  */

package/dist/esm/extend-adapter.js

@@ -1,8 +1,14 @@
-function createModel(name, input) {
+function createModel(name, second) {
+  if (Array.isArray(second)) {
+    return { name, input: second, modelOptions: {} };
+  }
+  const caps = second;
   return {
     name,
-    input,
-    modelOptions: {}
+    input: caps.input ?? ["text"],
+    modelOptions: caps.modelOptions ?? {},
+    features: caps.features,
+    tools: caps.tools
   };
 }
 function extendAdapter(factory, _customModels) {

package/dist/esm/extend-adapter.js.map

@@ -1 +1 @@
-{"version":3,"file":"extend-adapter.js","sources":["../../src/extend-adapter.ts"],"sourcesContent":["import type { Modality } from './types'\n\n// ===========================\n// Extended Model Definition\n// ===========================\n\n/**\n * Definition for a custom model to add to an adapter.\n *\n * @template TName - The model name as a literal string type\n * @template TInput - Array of supported input modalities\n * @template TOptions - Provider options type for this model\n *\n * @example\n * ```typescript\n * const customModels = [\n *   createModel('my-custom-model', ['text', 'image']),\n * ] as const\n * ```\n */\nexport interface ExtendedModelDef<\n  TName extends string = string,\n  TInput extends ReadonlyArray<Modality> = ReadonlyArray<Modality>,\n  TOptions = unknown,\n> {\n  /** The model name identifier */\n  name: TName\n  /** Supported input modalities for this model */\n  input: TInput\n  /** Type brand for provider options - use `{} as YourOptionsType` */\n  modelOptions: TOptions\n}\n\n/**\n * Creates a custom model definition for use with `extendAdapter`.\n *\n * This is a helper function that provides proper type inference without\n * requiring manual `as const` casts on individual properties.\n *\n * @template TName - The model name (inferred from argument)\n * @template TInput - The input modalities array (inferred from argument)\n *\n * @param name - The model name identifier (literal string)\n * @param input - Array of supported input modalities\n * @returns A properly typed model definition for use with `extendAdapter`\n *\n * @example\n * ```typescript\n * import { extendAdapter, createModel } from '@tanstack/ai'\n * import { openaiText } from '@tanstack/ai-openai'\n *\n * // Define custom models with full type inference\n * const customModels = [\n *   createModel('my-fine-tuned-gpt4', ['text', 'image']),\n *   createModel('local-llama', ['text']),\n * ] as const\n *\n * const myOpenai = extendAdapter(openaiText, customModels)\n * ```\n */\nexport function createModel<\n  const TName extends string,\n  const TInput extends ReadonlyArray<Modality>,\n>(name: TName, input: TInput): ExtendedModelDef<TName, TInput> {\n  return {\n    name,\n    input,\n    modelOptions: {},\n  }\n}\n\n// ===========================\n// Type Extraction Utilities\n// ===========================\n\n/**\n * Extract the model name union from an array of model definitions.\n */\ntype ExtractCustomModelNames<TDefs extends ReadonlyArray<ExtendedModelDef>> =\n  TDefs[number]['name']\n\n// ===========================\n// Factory Type Inference\n// ===========================\n\n/**\n * Infer the model parameter type from an adapter factory function.\n * For generic functions like `<T extends Union>(model: T)`, this gets `T` which\n * TypeScript treats as the constraint union when used in parameter position.\n */\ntype InferFactoryModels<TFactory> = TFactory extends (\n  model: infer TModel,\n  ...args: Array<any>\n) => any\n  ? TModel extends string\n    ? TModel\n    : string\n  : string\n\n/**\n * Infer the config parameter type from an adapter factory function.\n */\ntype InferConfig<TFactory> = TFactory extends (\n  model: any,\n  config?: infer TConfig,\n) => any\n  ? TConfig\n  : undefined\n\n/**\n * Infer the adapter return type from a factory function.\n */\ntype InferAdapterReturn<TFactory> = TFactory extends (\n  ...args: Array<any>\n) => infer TReturn\n  ? TReturn\n  : never\n\n// ===========================\n// extendAdapter Function\n// ===========================\n\n/**\n * Extends an existing adapter factory with additional custom models.\n *\n * The extended adapter accepts both original models (with full original type inference)\n * and custom models (with types from your definitions).\n *\n * At runtime, this simply passes through to the original factory - no validation is performed.\n * The original factory's signature is fully preserved, including any config parameters.\n *\n * @param factory - The original adapter factory function (e.g., `openaiText`, `anthropicText`)\n * @param models - Array of custom model definitions with `name` and `input`\n * @returns A new factory function that accepts both original and custom models\n *\n * @example\n * ```typescript\n * import { extendAdapter, createModel } from '@tanstack/ai'\n * import { openaiText } from '@tanstack/ai-openai'\n *\n * // Define custom models\n * const customModels = [\n *   createModel('my-fine-tuned-gpt4', ['text', 'image']),\n *   createModel('local-llama', ['text']),\n * ] as const\n *\n * // Create extended adapter\n * const myOpenai = extendAdapter(openaiText, customModels)\n *\n * // Use with original models - full type inference preserved\n * const gpt4 = myOpenai('gpt-4o')\n *\n * // Use with custom models\n * const custom = myOpenai('my-fine-tuned-gpt4')\n *\n * // Type error: 'invalid-model' is not a valid model\n * // myOpenai('invalid-model')\n *\n * // Works with chat()\n * chat({\n *   adapter: myOpenai('my-fine-tuned-gpt4'),\n *   messages: [...]\n * })\n * ```\n */\nexport function extendAdapter<\n  TFactory extends (...args: Array<any>) => any,\n  const TDefs extends ReadonlyArray<ExtendedModelDef>,\n>(\n  factory: TFactory,\n  _customModels: TDefs,\n): (\n  model: InferFactoryModels<TFactory> | ExtractCustomModelNames<TDefs>,\n  ...args: InferConfig<TFactory> extends undefined\n    ? []\n    : [config?: InferConfig<TFactory>]\n) => InferAdapterReturn<TFactory> {\n  // At runtime, we simply pass through to the original factory.\n  // The _customModels parameter is only used for type inference.\n  // No runtime validation - users are trusted to pass valid model names.\n  return factory as any\n}\n"],"names":[],"mappings":"AA4DO,SAAS,YAGd,MAAa,OAAgD;AAC7D,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA,cAAc,CAAA;AAAA,EAAC;AAEnB;AAgGO,SAAS,cAId,SACA,eAMgC;AAIhC,SAAO;AACT;"}
+{"version":3,"file":"extend-adapter.js","sources":["../../src/extend-adapter.ts"],"sourcesContent":["import type { Modality } from './types'\n\n// ===========================\n// Extended Model Definition\n// ===========================\n\n/**\n * Definition for a custom model to add to an adapter.\n *\n * @template TName - The model name as a literal string type\n * @template TInput - Array of supported input modalities\n * @template TOptions - Provider options type for this model\n *\n * @example\n * ```typescript\n * const customModels = [\n *   createModel('my-custom-model', ['text', 'image']),\n * ] as const\n * ```\n */\nexport interface ExtendedModelDef<\n  TName extends string = string,\n  TInput extends ReadonlyArray<Modality> = ReadonlyArray<Modality>,\n  TOptions = unknown,\n  TFeatures extends ReadonlyArray<string> = ReadonlyArray<string>,\n  TTools extends ReadonlyArray<string> = ReadonlyArray<string>,\n> {\n  /** The model name identifier */\n  name: TName\n  /** Supported input modalities for this model */\n  input: TInput\n  /** Type brand for provider options - use `{} as YourOptionsType` */\n  modelOptions: TOptions\n  /** Optional declared features (e.g. 'reasoning', 'structured_outputs') */\n  features?: TFeatures\n  /** Optional declared provider tools (e.g. 'web_search') */\n  tools?: TTools\n}\n\n/** Capability bag accepted by the object form of `createModel`. */\nexport interface ModelCapabilities<\n  TInput extends ReadonlyArray<Modality> = ReadonlyArray<Modality>,\n  TFeatures extends ReadonlyArray<string> = ReadonlyArray<string>,\n  TTools extends ReadonlyArray<string> = ReadonlyArray<string>,\n  TOptions = unknown,\n> {\n  input?: TInput\n  features?: TFeatures\n  tools?: TTools\n  modelOptions?: TOptions\n}\n\n/**\n * Creates a custom model definition for use with `extendAdapter`.\n *\n * This is a helper function that provides proper type inference without\n * requiring manual `as const` casts on individual properties.\n *\n * @template TName - The model name (inferred from argument)\n * @template TInput - The input modalities array (inferred from argument)\n *\n * @param name - The model name identifier (literal string)\n * @param input - Array of supported input modalities\n * @returns A properly typed model definition for use with `extendAdapter`\n *\n * @example\n * ```typescript\n * import { extendAdapter, createModel } from '@tanstack/ai'\n * import { openaiText } from '@tanstack/ai-openai'\n *\n * // Define custom models with full type inference\n * const customModels = [\n *   createModel('my-fine-tuned-gpt4', ['text', 'image']),\n *   createModel('local-llama', ['text']),\n * ] as const\n *\n * const myOpenai = extendAdapter(openaiText, customModels)\n * ```\n *\n * @example\n * ```typescript\n * // Capabilities object form - declare features and provider tools\n * const reasoner = createModel('reasoner', {\n *   input: ['text'],\n *   features: ['reasoning', 'structured_outputs'],\n *   tools: ['web_search'],\n * })\n * ```\n */\n// Overload 1 — legacy positional input array (unchanged behavior)\nexport function createModel<\n  const TName extends string,\n  const TInput extends ReadonlyArray<Modality>,\n>(name: TName, input: TInput): ExtendedModelDef<TName, TInput>\n// Overload 2 — capabilities object\nexport function createModel<\n  const TName extends string,\n  const TCaps extends ModelCapabilities,\n>(\n  name: TName,\n  capabilities: TCaps,\n): ExtendedModelDef<\n  TName,\n  TCaps['input'] extends ReadonlyArray<Modality>\n    ? TCaps['input']\n    : ReadonlyArray<Modality>,\n  TCaps['modelOptions'],\n  TCaps['features'] extends ReadonlyArray<string>\n    ? TCaps['features']\n    : ReadonlyArray<string>,\n  TCaps['tools'] extends ReadonlyArray<string>\n    ? TCaps['tools']\n    : ReadonlyArray<string>\n>\n// Implementation\nexport function createModel(\n  name: string,\n  second: ReadonlyArray<Modality> | ModelCapabilities,\n): ExtendedModelDef {\n  if (Array.isArray(second)) {\n    return { name, input: second, modelOptions: {} }\n  }\n  const caps = second as ModelCapabilities\n  return {\n    name,\n    input: caps.input ?? (['text'] as ReadonlyArray<Modality>),\n    modelOptions: caps.modelOptions ?? {},\n    features: caps.features,\n    tools: caps.tools,\n  }\n}\n\n// ===========================\n// Type Extraction Utilities\n// ===========================\n\n/**\n * Extract the model name union from an array of model definitions.\n */\ntype ExtractCustomModelNames<TDefs extends ReadonlyArray<ExtendedModelDef>> =\n  TDefs[number]['name']\n\n// ===========================\n// Factory Type Inference\n// ===========================\n\n/**\n * Infer the model parameter type from an adapter factory function.\n * For generic functions like `<T extends Union>(model: T)`, this gets `T` which\n * TypeScript treats as the constraint union when used in parameter position.\n */\ntype InferFactoryModels<TFactory> = TFactory extends (\n  model: infer TModel,\n  ...args: Array<any>\n) => any\n  ? TModel extends string\n    ? TModel\n    : string\n  : string\n\n/**\n * Infer the config parameter type from an adapter factory function.\n */\ntype InferConfig<TFactory> = TFactory extends (\n  model: any,\n  config?: infer TConfig,\n) => any\n  ? TConfig\n  : undefined\n\n/**\n * Infer the adapter return type from a factory function.\n */\ntype InferAdapterReturn<TFactory> = TFactory extends (\n  ...args: Array<any>\n) => infer TReturn\n  ? TReturn\n  : never\n\n// ===========================\n// extendAdapter Function\n// ===========================\n\n/**\n * Extends an existing adapter factory with additional custom models.\n *\n * The extended adapter accepts both original models (with full original type inference)\n * and custom models (with types from your definitions).\n *\n * At runtime, this simply passes through to the original factory - no validation is performed.\n * The original factory's signature is fully preserved, including any config parameters.\n *\n * @param factory - The original adapter factory function (e.g., `openaiText`, `anthropicText`)\n * @param models - Array of custom model definitions with `name` and `input`\n * @returns A new factory function that accepts both original and custom models\n *\n * @example\n * ```typescript\n * import { extendAdapter, createModel } from '@tanstack/ai'\n * import { openaiText } from '@tanstack/ai-openai'\n *\n * // Define custom models\n * const customModels = [\n *   createModel('my-fine-tuned-gpt4', ['text', 'image']),\n *   createModel('local-llama', ['text']),\n * ] as const\n *\n * // Create extended adapter\n * const myOpenai = extendAdapter(openaiText, customModels)\n *\n * // Use with original models - full type inference preserved\n * const gpt4 = myOpenai('gpt-4o')\n *\n * // Use with custom models\n * const custom = myOpenai('my-fine-tuned-gpt4')\n *\n * // Type error: 'invalid-model' is not a valid model\n * // myOpenai('invalid-model')\n *\n * // Works with chat()\n * chat({\n *   adapter: myOpenai('my-fine-tuned-gpt4'),\n *   messages: [...]\n * })\n * ```\n */\nexport function extendAdapter<\n  TFactory extends (...args: Array<any>) => any,\n  const TDefs extends ReadonlyArray<ExtendedModelDef>,\n>(\n  factory: TFactory,\n  _customModels: TDefs,\n): (\n  model: InferFactoryModels<TFactory> | ExtractCustomModelNames<TDefs>,\n  ...args: InferConfig<TFactory> extends undefined\n    ? []\n    : [config?: InferConfig<TFactory>]\n) => InferAdapterReturn<TFactory> {\n  // At runtime, we simply pass through to the original factory.\n  // The _customModels parameter is only used for type inference.\n  // No runtime validation - users are trusted to pass valid model names.\n  return factory as any\n}\n"],"names":[],"mappings":"AAmHO,SAAS,YACd,MACA,QACkB;AAClB,MAAI,MAAM,QAAQ,MAAM,GAAG;AACzB,WAAO,EAAE,MAAM,OAAO,QAAQ,cAAc,CAAA,EAAC;AAAA,EAC/C;AACA,QAAM,OAAO;AACb,SAAO;AAAA,IACL;AAAA,IACA,OAAO,KAAK,SAAU,CAAC,MAAM;AAAA,IAC7B,cAAc,KAAK,gBAAgB,CAAA;AAAA,IACnC,UAAU,KAAK;AAAA,IACf,OAAO,KAAK;AAAA,EAAA;AAEhB;AAgGO,SAAS,cAId,SACA,eAMgC;AAIhC,SAAO;AACT;"}

package/dist/esm/index.d.ts

@@ -31,6 +31,6 @@ export { uiMessagesToWire } from './utilities/ag-ui-wire.js';
 export type { WireMessage } from './utilities/ag-ui-wire.js';
 export { isContentPart, isContentPartArray, normalizeToolResult, } from './utilities/tool-result.js';
 export { createModel, extendAdapter } from './extend-adapter.js';
-export type { ExtendedModelDef } from './extend-adapter.js';
+export type { ExtendedModelDef, ModelCapabilities } from './extend-adapter.js';
 export type { Logger, DebugCategories, DebugConfig, DebugOption, } from './logger/types.js';
 export { ConsoleLogger } from './logger/console-logger.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai",
-  "version": "0.25.0",
+  "version": "0.26.1",
   "description": "Type-safe TypeScript AI SDK for streaming chat, tool calling, agents, structured outputs, and multimodal generation.",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -68,7 +68,7 @@
     "@ag-ui/core": "^0.0.52",
     "@standard-schema/spec": "^1.1.0",
     "partial-json": "^0.1.7",
-    "@tanstack/ai-event-client": "0.5.0"
+    "@tanstack/ai-event-client": "0.5.2"
   },
   "peerDependencies": {
     "@opentelemetry/api": ">=1.9.0"

package/skills/ai-core/adapter-configuration/SKILL.md

@@ -2,9 +2,11 @@
 name: ai-core/adapter-configuration
 description: >
   Provider adapter selection and configuration: openaiText, anthropicText,
-  geminiText, ollamaText, grokText, groqText, openRouterText. Per-model
+  geminiText, ollamaText, grokText, groqText, openRouterText, openaiCompatible. Per-model
   type safety with modelOptions, reasoning/thinking configuration,
   runtime adapter switching, extendAdapter() for custom models, createModel().
+  Generic OpenAI-compatible providers (DeepSeek, Together, Fireworks, etc.) via
+  openaiCompatible({ baseURL, apiKey, models }) from @tanstack/ai-openai/compatible.
   API key env vars: OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_API_KEY/GEMINI_API_KEY,
   XAI_API_KEY, GROQ_API_KEY, OPENROUTER_API_KEY, OLLAMA_HOST.
 type: sub-skill
@@ -60,15 +62,16 @@ into the factory, not into `chat()`.
 Each provider has a dedicated package with tree-shakeable adapter factories.
 The text adapter is the primary one for chat/completions:
 
-| Provider   | Package                   | Factory          | Env Var                                           |
-| ---------- | ------------------------- | ---------------- | ------------------------------------------------- |
-| OpenAI     | `@tanstack/ai-openai`     | `openaiText`     | `OPENAI_API_KEY`                                  |
-| Anthropic  | `@tanstack/ai-anthropic`  | `anthropicText`  | `ANTHROPIC_API_KEY`                               |
-| Gemini     | `@tanstack/ai-gemini`     | `geminiText`     | `GOOGLE_API_KEY` or `GEMINI_API_KEY`              |
-| Grok (xAI) | `@tanstack/ai-grok`       | `grokText`       | `XAI_API_KEY`                                     |
-| Groq       | `@tanstack/ai-groq`       | `groqText`       | `GROQ_API_KEY`                                    |
-| OpenRouter | `@tanstack/ai-openrouter` | `openRouterText` | `OPENROUTER_API_KEY`                              |
-| Ollama     | `@tanstack/ai-ollama`     | `ollamaText`     | `OLLAMA_HOST` (default: `http://localhost:11434`) |
+| Provider          | Package                          | Factory                                     | Env Var                                           |
+| ----------------- | -------------------------------- | ------------------------------------------- | ------------------------------------------------- |
+| OpenAI            | `@tanstack/ai-openai`            | `openaiText`                                | `OPENAI_API_KEY`                                  |
+| Anthropic         | `@tanstack/ai-anthropic`         | `anthropicText`                             | `ANTHROPIC_API_KEY`                               |
+| Gemini            | `@tanstack/ai-gemini`            | `geminiText`                                | `GOOGLE_API_KEY` or `GEMINI_API_KEY`              |
+| Grok (xAI)        | `@tanstack/ai-grok`              | `grokText`                                  | `XAI_API_KEY`                                     |
+| Groq              | `@tanstack/ai-groq`              | `groqText`                                  | `GROQ_API_KEY`                                    |
+| OpenRouter        | `@tanstack/ai-openrouter`        | `openRouterText`                            | `OPENROUTER_API_KEY`                              |
+| Ollama            | `@tanstack/ai-ollama`            | `ollamaText`                                | `OLLAMA_HOST` (default: `http://localhost:11434`) |
+| OpenAI-compatible | `@tanstack/ai-openai/compatible` | `openaiCompatible` / `openaiCompatibleText` | provider-specific (passed via `apiKey`)           |
 
 ```typescript
 // Each factory takes model as first arg, optional config as second
@@ -252,6 +255,63 @@ Subclasses can override to narrow the capability. When extending an
 adapter for a custom model that doesn't support the combination, return
 `false` explicitly.
 
+### 6. OpenAI-Compatible Providers
+
+Any provider that implements the OpenAI **Chat Completions** API (DeepSeek,
+Moonshot/Kimi, Together, Fireworks, Cerebras, Qwen/DashScope, Perplexity,
+NVIDIA NIM, LM Studio, etc.) can be used through the generic
+`openaiCompatible` factory from `@tanstack/ai-openai/compatible` — no
+dedicated package required.
+
+```typescript
+import { openaiCompatible } from '@tanstack/ai-openai/compatible'
+import { createModel } from '@tanstack/ai'
+
+// Provider-factory: configure baseURL + apiKey + models ONCE,
+// then select a model per call (the model arg is a type-safe union).
+const deepseek = openaiCompatible({
+  name: 'deepseek', // optional label for devtools/errors (default 'openai-compatible')
+  baseURL: 'https://api.deepseek.com/v1',
+  apiKey: process.env.DEEPSEEK_API_KEY!,
+  models: [
+    'deepseek-chat', // bare string → optimistic defaults: text/image in, streaming, tools, structured output
+    createModel('deepseek-reasoner', {
+      // rich def → precise per-model capabilities
+      input: ['text'],
+      features: ['reasoning', 'structured_outputs'],
+    }),
+  ],
+})
+
+chat({ adapter: deepseek('deepseek-chat'), messages })
+chat({ adapter: deepseek('deepseek-reasoner'), messages })
+```
+
+`config` also accepts any OpenAI SDK `ClientOptions` (notably `defaultHeaders`
+and `defaultQuery`) for providers that need extra auth headers or query params.
+
+For a single model, use the one-shot helper:
+
+```typescript
+import { openaiCompatibleText } from '@tanstack/ai-openai/compatible'
+
+chat({
+  adapter: openaiCompatibleText('deepseek-chat', {
+    baseURL: 'https://api.deepseek.com/v1',
+    apiKey: process.env.DEEPSEEK_API_KEY!,
+  }),
+  messages,
+})
+```
+
+Pass `api: 'responses'` to target the OpenAI **Responses** API instead of Chat
+Completions (only for the rare compatible provider that implements it, e.g.
+Azure OpenAI); the default is `'chat-completions'`, which is what nearly all
+compatible providers speak.
+
+> Verify the provider's current `baseURL` and model ids against its live docs —
+> they drift. See `docs/adapters/openai-compatible.md` for the full provider table.
+
 ## Common Mistakes
 
 ### a. HIGH: Confusing legacy monolithic with tree-shakeable adapter

package/src/extend-adapter.ts

@@ -22,6 +22,8 @@ export interface ExtendedModelDef<
   TName extends string = string,
   TInput extends ReadonlyArray<Modality> = ReadonlyArray<Modality>,
   TOptions = unknown,
+  TFeatures extends ReadonlyArray<string> = ReadonlyArray<string>,
+  TTools extends ReadonlyArray<string> = ReadonlyArray<string>,
 > {
   /** The model name identifier */
   name: TName
@@ -29,6 +31,23 @@ export interface ExtendedModelDef<
   input: TInput
   /** Type brand for provider options - use `{} as YourOptionsType` */
   modelOptions: TOptions
+  /** Optional declared features (e.g. 'reasoning', 'structured_outputs') */
+  features?: TFeatures
+  /** Optional declared provider tools (e.g. 'web_search') */
+  tools?: TTools
+}
+
+/** Capability bag accepted by the object form of `createModel`. */
+export interface ModelCapabilities<
+  TInput extends ReadonlyArray<Modality> = ReadonlyArray<Modality>,
+  TFeatures extends ReadonlyArray<string> = ReadonlyArray<string>,
+  TTools extends ReadonlyArray<string> = ReadonlyArray<string>,
+  TOptions = unknown,
+> {
+  input?: TInput
+  features?: TFeatures
+  tools?: TTools
+  modelOptions?: TOptions
 }
 
 /**
@@ -57,15 +76,57 @@ export interface ExtendedModelDef<
  *
  * const myOpenai = extendAdapter(openaiText, customModels)
  * ```
+ *
+ * @example
+ * ```typescript
+ * // Capabilities object form - declare features and provider tools
+ * const reasoner = createModel('reasoner', {
+ *   input: ['text'],
+ *   features: ['reasoning', 'structured_outputs'],
+ *   tools: ['web_search'],
+ * })
+ * ```
  */
+// Overload 1 — legacy positional input array (unchanged behavior)
 export function createModel<
   const TName extends string,
   const TInput extends ReadonlyArray<Modality>,
->(name: TName, input: TInput): ExtendedModelDef<TName, TInput> {
+>(name: TName, input: TInput): ExtendedModelDef<TName, TInput>
+// Overload 2 — capabilities object
+export function createModel<
+  const TName extends string,
+  const TCaps extends ModelCapabilities,
+>(
+  name: TName,
+  capabilities: TCaps,
+): ExtendedModelDef<
+  TName,
+  TCaps['input'] extends ReadonlyArray<Modality>
+    ? TCaps['input']
+    : ReadonlyArray<Modality>,
+  TCaps['modelOptions'],
+  TCaps['features'] extends ReadonlyArray<string>
+    ? TCaps['features']
+    : ReadonlyArray<string>,
+  TCaps['tools'] extends ReadonlyArray<string>
+    ? TCaps['tools']
+    : ReadonlyArray<string>
+>
+// Implementation
+export function createModel(
+  name: string,
+  second: ReadonlyArray<Modality> | ModelCapabilities,
+): ExtendedModelDef {
+  if (Array.isArray(second)) {
+    return { name, input: second, modelOptions: {} }
+  }
+  const caps = second as ModelCapabilities
   return {
     name,
-    input,
-    modelOptions: {},
+    input: caps.input ?? (['text'] as ReadonlyArray<Modality>),
+    modelOptions: caps.modelOptions ?? {},
+    features: caps.features,
+    tools: caps.tools,
   }
 }
 

package/src/index.ts

@@ -200,7 +200,7 @@ export {
 
 // Adapter extension utilities
 export { createModel, extendAdapter } from './extend-adapter'
-export type { ExtendedModelDef } from './extend-adapter'
+export type { ExtendedModelDef, ModelCapabilities } from './extend-adapter'
 
 // Logger
 export type {