@tanstack/ai 0.0.1

package/dist/esm/utilities/agent-loop-strategies.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-loop-strategies.js","sources":["../../../src/utilities/agent-loop-strategies.ts"],"sourcesContent":["import type { AgentLoopStrategy } from '../types'\n\n/**\n * Creates a strategy that continues for a maximum number of iterations\n *\n * @param max - Maximum number of iterations to allow\n * @returns AgentLoopStrategy that stops after max iterations\n *\n * @example\n * ```typescript\n * const stream = chat({\n *   adapter: openai(),\n *   model: \"gpt-4o\",\n *   messages: [...],\n *   tools: [weatherTool],\n *   agentLoopStrategy: maxIterations(3), // Max 3 iterations\n * });\n * ```\n */\nexport function maxIterations(max: number): AgentLoopStrategy {\n  return ({ iterationCount }) => iterationCount < max\n}\n\n/**\n * Creates a strategy that continues until a specific finish reason is encountered\n *\n * @param stopReasons - Finish reasons that should stop the loop\n * @returns AgentLoopStrategy that stops on specific finish reasons\n *\n * @example\n * ```typescript\n * const stream = chat({\n *   adapter: openai(),\n *   model: \"gpt-4o\",\n *   messages: [...],\n *   tools: [weatherTool],\n *   agentLoopStrategy: untilFinishReason([\"stop\", \"length\"]),\n * });\n * ```\n */\nexport function untilFinishReason(\n  stopReasons: Array<string>,\n): AgentLoopStrategy {\n  return ({ finishReason, iterationCount }) => {\n    // Always allow at least one iteration\n    if (iterationCount === 0) return true\n\n    // Stop if we hit a stop reason\n    if (finishReason && stopReasons.includes(finishReason)) {\n      return false\n    }\n\n    // Otherwise continue\n    return true\n  }\n}\n\n/**\n * Creates a strategy that combines multiple strategies with AND logic\n * All strategies must return true to continue\n *\n * @param strategies - Array of strategies to combine\n * @returns AgentLoopStrategy that continues only if all strategies return true\n *\n * @example\n * ```typescript\n * const stream = chat({\n *   adapter: openai(),\n *   model: \"gpt-4o\",\n *   messages: [...],\n *   tools: [weatherTool],\n *   agentLoopStrategy: combineStrategies([\n *     maxIterations(10),\n *     ({ messages }) => messages.length < 100,\n *   ]),\n * });\n * ```\n */\nexport function combineStrategies(\n  strategies: Array<AgentLoopStrategy>,\n): AgentLoopStrategy {\n  return (state) => {\n    return strategies.every((strategy) => strategy(state))\n  }\n}\n"],"names":[],"mappings":"AAmBO,SAAS,cAAc,KAAgC;AAC5D,SAAO,CAAC,EAAE,qBAAqB,iBAAiB;AAClD;AAmBO,SAAS,kBACd,aACmB;AACnB,SAAO,CAAC,EAAE,cAAc,qBAAqB;AAE3C,QAAI,mBAAmB,EAAG,QAAO;AAGjC,QAAI,gBAAgB,YAAY,SAAS,YAAY,GAAG;AACtD,aAAO;AAAA,IACT;AAGA,WAAO;AAAA,EACT;AACF;AAuBO,SAAS,kBACd,YACmB;AACnB,SAAO,CAAC,UAAU;AAChB,WAAO,WAAW,MAAM,CAAC,aAAa,SAAS,KAAK,CAAC;AAAA,EACvD;AACF;"}

package/dist/esm/utilities/chat-options.d.ts

@@ -0,0 +1,6 @@
+import { AIAdapter, ChatStreamOptionsUnion } from '../types.js';
+export declare function chatOptions<TAdapter extends AIAdapter<any, any, any, any, any>, const TModel extends TAdapter extends AIAdapter<infer Models, any, any, any, any> ? Models[number] : string>(options: Omit<ChatStreamOptionsUnion<TAdapter>, 'providerOptions' | 'model' | 'messages' | 'abortController'> & {
+    adapter: TAdapter;
+    model: TModel;
+    providerOptions?: TAdapter extends AIAdapter<any, any, any, any, infer ModelProviderOptions> ? TModel extends keyof ModelProviderOptions ? ModelProviderOptions[TModel] : never : never;
+}): typeof options;

package/dist/esm/utilities/chat-options.js

@@ -0,0 +1,7 @@
+function chatOptions(options) {
+  return options;
+}
+export {
+  chatOptions
+};
+//# sourceMappingURL=chat-options.js.map

package/dist/esm/utilities/chat-options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-options.js","sources":["../../../src/utilities/chat-options.ts"],"sourcesContent":["import type { AIAdapter, ChatStreamOptionsUnion } from '../types'\n\nexport function chatOptions<\n  TAdapter extends AIAdapter<any, any, any, any, any>,\n  const TModel extends TAdapter extends AIAdapter<\n    infer Models,\n    any,\n    any,\n    any,\n    any\n  >\n    ? Models[number]\n    : string,\n>(\n  options: Omit<\n    ChatStreamOptionsUnion<TAdapter>,\n    'providerOptions' | 'model' | 'messages' | 'abortController'\n  > & {\n    adapter: TAdapter\n    model: TModel\n    providerOptions?: TAdapter extends AIAdapter<\n      any,\n      any,\n      any,\n      any,\n      infer ModelProviderOptions\n    >\n      ? TModel extends keyof ModelProviderOptions\n        ? ModelProviderOptions[TModel]\n        : never\n      : never\n  },\n): typeof options {\n  return options\n}\n"],"names":[],"mappings":"AAEO,SAAS,YAYd,SAkBgB;AAChB,SAAO;AACT;"}

package/dist/esm/utilities/messages.d.ts

@@ -0,0 +1,30 @@
+import { AIAdapter, ConstrainedModelMessage, Modality, ModelMessage } from '../types.js';
+/**
+ * Type-safe helper to create a messages array constrained by a model's supported modalities.
+ *
+ * This function provides compile-time checking that your messages only contain
+ * content types supported by the specified model. It's particularly useful when
+ * combining typed messages with untyped data (like from request.json()).
+ *
+ * @example
+ * ```typescript
+ * import { messages, chat } from '@tanstack/ai'
+ * import { openai } from '@tanstack/ai-openai'
+ *
+ * const adapter = openai()
+ *
+ * // This will error at compile time because gpt-4o only supports text+image
+ * const msgs = messages({ adapter, model: 'gpt-4o' }, [
+ *   {
+ *     role: 'user',
+ *     content: [
+ *       { type: 'video', source: { type: 'url', value: '...' } } // Error!
+ *     ]
+ *   }
+ * ])
+ * ```
+ */
+export declare function messages<TAdapter extends AIAdapter<any, any, any, any, any, any>, const TModel extends TAdapter extends AIAdapter<infer Models, any, any, any, any, any> ? Models[number] : string>(_options: {
+    adapter: TAdapter;
+    model: TModel;
+}, msgs: TAdapter extends AIAdapter<any, any, any, any, any, infer ModelInputModalities> ? TModel extends keyof ModelInputModalities ? ModelInputModalities[TModel] extends ReadonlyArray<Modality> ? Array<ConstrainedModelMessage<ModelInputModalities[TModel]>> : Array<ModelMessage> : Array<ModelMessage> : Array<ModelMessage>): typeof msgs;

package/dist/esm/utilities/messages.js

@@ -0,0 +1,7 @@
+function messages(_options, msgs) {
+  return msgs;
+}
+export {
+  messages
+};
+//# sourceMappingURL=messages.js.map

package/dist/esm/utilities/messages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.js","sources":["../../../src/utilities/messages.ts"],"sourcesContent":["import type {\n  AIAdapter,\n  ConstrainedModelMessage,\n  Modality,\n  ModelMessage,\n} from '../types'\n\n/**\n * Type-safe helper to create a messages array constrained by a model's supported modalities.\n *\n * This function provides compile-time checking that your messages only contain\n * content types supported by the specified model. It's particularly useful when\n * combining typed messages with untyped data (like from request.json()).\n *\n * @example\n * ```typescript\n * import { messages, chat } from '@tanstack/ai'\n * import { openai } from '@tanstack/ai-openai'\n *\n * const adapter = openai()\n *\n * // This will error at compile time because gpt-4o only supports text+image\n * const msgs = messages({ adapter, model: 'gpt-4o' }, [\n *   {\n *     role: 'user',\n *     content: [\n *       { type: 'video', source: { type: 'url', value: '...' } } // Error!\n *     ]\n *   }\n * ])\n * ```\n */\nexport function messages<\n  TAdapter extends AIAdapter<any, any, any, any, any, any>,\n  const TModel extends TAdapter extends AIAdapter<\n    infer Models,\n    any,\n    any,\n    any,\n    any,\n    any\n  >\n    ? Models[number]\n    : string,\n>(\n  _options: { adapter: TAdapter; model: TModel },\n  msgs: TAdapter extends AIAdapter<\n    any,\n    any,\n    any,\n    any,\n    any,\n    infer ModelInputModalities\n  >\n    ? TModel extends keyof ModelInputModalities\n      ? ModelInputModalities[TModel] extends ReadonlyArray<Modality>\n        ? Array<ConstrainedModelMessage<ModelInputModalities[TModel]>>\n        : Array<ModelMessage>\n      : Array<ModelMessage>\n    : Array<ModelMessage>,\n): typeof msgs {\n  return msgs\n}\n"],"names":[],"mappings":"AAgCO,SAAS,SAad,UACA,MAca;AACb,SAAO;AACT;"}

package/dist/esm/utilities/stream-to-response.d.ts

@@ -0,0 +1,48 @@
+import { StreamChunk } from '../types.js';
+/**
+ * Convert a StreamChunk async iterable to a ReadableStream in Server-Sent Events format
+ *
+ * This creates a ReadableStream that emits chunks in SSE format:
+ * - Each chunk is prefixed with "data: "
+ * - Each chunk is followed by "\n\n"
+ * - Stream ends with "data: [DONE]\n\n"
+ *
+ * @param stream - AsyncIterable of StreamChunks from chat()
+ * @param abortController - Optional AbortController to abort when stream is cancelled
+ * @returns ReadableStream in Server-Sent Events format
+ *
+ * @example
+ * ```typescript
+ * const stream = chat({ adapter: openai(), model: "gpt-4o", messages: [...] });
+ * const readableStream = toServerSentEventsStream(stream);
+ * // Use with Response, or any API that accepts ReadableStream
+ * ```
+ */
+export declare function toServerSentEventsStream(stream: AsyncIterable<StreamChunk>, abortController?: AbortController): ReadableStream<Uint8Array>;
+/**
+ * Create a streaming HTTP response from a StreamChunk async iterable
+ * Includes proper headers for Server-Sent Events
+ *
+ * @param stream - AsyncIterable of StreamChunks from chat()
+ * @param init - Optional Response initialization options
+ * @param abortController - Optional AbortController to abort when client disconnects
+ * @returns Response object with SSE headers and streaming body
+ *
+ * @example
+ * ```typescript
+ * export async function POST(request: Request) {
+ *   const { messages } = await request.json();
+ *   const abortController = new AbortController();
+ *   const stream = chat({
+ *     adapter: openai(),
+ *     model: "gpt-4o",
+ *     messages,
+ *     options: { abortSignal: abortController.signal }
+ *   });
+ *   return toStreamResponse(stream, undefined, abortController);
+ * }
+ * ```
+ */
+export declare function toStreamResponse(stream: AsyncIterable<StreamChunk>, init?: ResponseInit & {
+    abortController?: AbortController;
+}): Response;

package/dist/esm/utilities/stream-to-response.js

@@ -0,0 +1,62 @@
+function toServerSentEventsStream(stream, abortController) {
+  const encoder = new TextEncoder();
+  return new ReadableStream({
+    async start(controller) {
+      try {
+        for await (const chunk of stream) {
+          if (abortController?.signal.aborted) {
+            break;
+          }
+          controller.enqueue(
+            encoder.encode(`data: ${JSON.stringify(chunk)}
+
+`)
+          );
+        }
+        controller.enqueue(encoder.encode("data: [DONE]\n\n"));
+        controller.close();
+      } catch (error) {
+        if (abortController?.signal.aborted) {
+          controller.close();
+          return;
+        }
+        controller.enqueue(
+          encoder.encode(
+            `data: ${JSON.stringify({
+              type: "error",
+              error: {
+                message: error.message || "Unknown error occurred",
+                code: error.code
+              }
+            })}
+
+`
+          )
+        );
+        controller.close();
+      }
+    },
+    cancel() {
+      if (abortController) {
+        abortController.abort();
+      }
+    }
+  });
+}
+function toStreamResponse(stream, init) {
+  const { headers, abortController, ...responseInit } = init ?? {};
+  return new Response(toServerSentEventsStream(stream, abortController), {
+    ...responseInit,
+    headers: {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache",
+      Connection: "keep-alive",
+      ...headers || {}
+    }
+  });
+}
+export {
+  toServerSentEventsStream,
+  toStreamResponse
+};
+//# sourceMappingURL=stream-to-response.js.map

package/dist/esm/utilities/stream-to-response.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-to-response.js","sources":["../../../src/utilities/stream-to-response.ts"],"sourcesContent":["import type { StreamChunk } from '../types'\n\n/**\n * Convert a StreamChunk async iterable to a ReadableStream in Server-Sent Events format\n *\n * This creates a ReadableStream that emits chunks in SSE format:\n * - Each chunk is prefixed with \"data: \"\n * - Each chunk is followed by \"\\n\\n\"\n * - Stream ends with \"data: [DONE]\\n\\n\"\n *\n * @param stream - AsyncIterable of StreamChunks from chat()\n * @param abortController - Optional AbortController to abort when stream is cancelled\n * @returns ReadableStream in Server-Sent Events format\n *\n * @example\n * ```typescript\n * const stream = chat({ adapter: openai(), model: \"gpt-4o\", messages: [...] });\n * const readableStream = toServerSentEventsStream(stream);\n * // Use with Response, or any API that accepts ReadableStream\n * ```\n */\nexport function toServerSentEventsStream(\n  stream: AsyncIterable<StreamChunk>,\n  abortController?: AbortController,\n): ReadableStream<Uint8Array> {\n  const encoder = new TextEncoder()\n\n  return new ReadableStream({\n    async start(controller) {\n      try {\n        for await (const chunk of stream) {\n          // Check if stream was cancelled/aborted\n          if (abortController?.signal.aborted) {\n            break\n          }\n\n          // Send each chunk as Server-Sent Events format\n          controller.enqueue(\n            encoder.encode(`data: ${JSON.stringify(chunk)}\\n\\n`),\n          )\n        }\n\n        // Send completion marker\n        controller.enqueue(encoder.encode('data: [DONE]\\n\\n'))\n        controller.close()\n      } catch (error: any) {\n        // Don't send error if aborted\n        if (abortController?.signal.aborted) {\n          controller.close()\n          return\n        }\n\n        // Send error chunk\n        controller.enqueue(\n          encoder.encode(\n            `data: ${JSON.stringify({\n              type: 'error',\n              error: {\n                message: error.message || 'Unknown error occurred',\n                code: error.code,\n              },\n            })}\\n\\n`,\n          ),\n        )\n        controller.close()\n      }\n    },\n    cancel() {\n      // When the ReadableStream is cancelled (e.g., client disconnects),\n      // abort the underlying stream\n      if (abortController) {\n        abortController.abort()\n      }\n    },\n  })\n}\n\n/**\n * Create a streaming HTTP response from a StreamChunk async iterable\n * Includes proper headers for Server-Sent Events\n *\n * @param stream - AsyncIterable of StreamChunks from chat()\n * @param init - Optional Response initialization options\n * @param abortController - Optional AbortController to abort when client disconnects\n * @returns Response object with SSE headers and streaming body\n *\n * @example\n * ```typescript\n * export async function POST(request: Request) {\n *   const { messages } = await request.json();\n *   const abortController = new AbortController();\n *   const stream = chat({\n *     adapter: openai(),\n *     model: \"gpt-4o\",\n *     messages,\n *     options: { abortSignal: abortController.signal }\n *   });\n *   return toStreamResponse(stream, undefined, abortController);\n * }\n * ```\n */\nexport function toStreamResponse(\n  stream: AsyncIterable<StreamChunk>,\n  init?: ResponseInit & { abortController?: AbortController },\n): Response {\n  const { headers, abortController, ...responseInit } = init ?? {}\n  return new Response(toServerSentEventsStream(stream, abortController), {\n    ...responseInit,\n    headers: {\n      'Content-Type': 'text/event-stream',\n      'Cache-Control': 'no-cache',\n      Connection: 'keep-alive',\n      ...(headers || {}),\n    },\n  })\n}\n"],"names":[],"mappings":"AAqBO,SAAS,yBACd,QACA,iBAC4B;AAC5B,QAAM,UAAU,IAAI,YAAA;AAEpB,SAAO,IAAI,eAAe;AAAA,IACxB,MAAM,MAAM,YAAY;AACtB,UAAI;AACF,yBAAiB,SAAS,QAAQ;AAEhC,cAAI,iBAAiB,OAAO,SAAS;AACnC;AAAA,UACF;AAGA,qBAAW;AAAA,YACT,QAAQ,OAAO,SAAS,KAAK,UAAU,KAAK,CAAC;AAAA;AAAA,CAAM;AAAA,UAAA;AAAA,QAEvD;AAGA,mBAAW,QAAQ,QAAQ,OAAO,kBAAkB,CAAC;AACrD,mBAAW,MAAA;AAAA,MACb,SAAS,OAAY;AAEnB,YAAI,iBAAiB,OAAO,SAAS;AACnC,qBAAW,MAAA;AACX;AAAA,QACF;AAGA,mBAAW;AAAA,UACT,QAAQ;AAAA,YACN,SAAS,KAAK,UAAU;AAAA,cACtB,MAAM;AAAA,cACN,OAAO;AAAA,gBACL,SAAS,MAAM,WAAW;AAAA,gBAC1B,MAAM,MAAM;AAAA,cAAA;AAAA,YACd,CACD,CAAC;AAAA;AAAA;AAAA,UAAA;AAAA,QACJ;AAEF,mBAAW,MAAA;AAAA,MACb;AAAA,IACF;AAAA,IACA,SAAS;AAGP,UAAI,iBAAiB;AACnB,wBAAgB,MAAA;AAAA,MAClB;AAAA,IACF;AAAA,EAAA,CACD;AACH;AA0BO,SAAS,iBACd,QACA,MACU;AACV,QAAM,EAAE,SAAS,iBAAiB,GAAG,aAAA,IAAiB,QAAQ,CAAA;AAC9D,SAAO,IAAI,SAAS,yBAAyB,QAAQ,eAAe,GAAG;AAAA,IACrE,GAAG;AAAA,IACH,SAAS;AAAA,MACP,gBAAgB;AAAA,MAChB,iBAAiB;AAAA,MACjB,YAAY;AAAA,MACZ,GAAI,WAAW,CAAA;AAAA,IAAC;AAAA,EAClB,CACD;AACH;"}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@tanstack/ai",
+  "version": "0.0.1",
+  "description": "Core TanStack AI library - Open source AI SDK",
+  "author": "Tanner Linsley",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TanStack/ai.git",
+    "directory": "packages/typescript/ai"
+  },
+  "type": "module",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js"
+    },
+    "./event-client": {
+      "types": "./dist/esm/event-client.d.ts",
+      "import": "./dist/esm/event-client.js"
+    }
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "keywords": [
+    "ai",
+    "tanstack",
+    "sdk",
+    "llm",
+    "chat",
+    "embeddings"
+  ],
+  "dependencies": {
+    "@tanstack/devtools-event-client": "^0.3.5",
+    "partial-json": "^0.1.7"
+  },
+  "peerDependencies": {
+    "@alcyone-labs/zod-to-json-schema": "^4.0.0",
+    "zod": "^3.0.0 || ^4.0.0"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "4.0.14",
+    "zod": "^4.1.13"
+  },
+  "scripts": {
+    "build": "vite build",
+    "clean": "premove ./build ./dist",
+    "lint:fix": "eslint ./src --fix",
+    "test:build": "publint --strict",
+    "test:coverage": "vitest run --coverage",
+    "test:coverage:watch": "vitest --coverage --watch",
+    "test:eslint": "eslint ./src",
+    "test:lib": "vitest",
+    "test:lib:dev": "pnpm test:lib --watch",
+    "test:types": "tsc"
+  }
+}

package/src/base-adapter.ts

@@ -0,0 +1,85 @@
+import type {
+  AIAdapter,
+  AIAdapterConfig,
+  ChatOptions,
+  DefaultMessageMetadataByModality,
+  EmbeddingOptions,
+  EmbeddingResult,
+  Modality,
+  StreamChunk,
+  SummarizationOptions,
+  SummarizationResult,
+} from './types'
+
+/**
+ * Base adapter class with support for endpoint-specific models and provider options.
+ *
+ * Generic parameters:
+ * - TChatModels: Models that support chat/text completion
+ * - TEmbeddingModels: Models that support embeddings
+ * - TChatProviderOptions: Provider-specific options for chat endpoint
+ * - TEmbeddingProviderOptions: Provider-specific options for embedding endpoint
+ * - TModelProviderOptionsByName: Provider-specific options for model by name
+ * - TModelInputModalitiesByName: Map from model name to its supported input modalities
+ * - TMessageMetadataByModality: Map from modality type to adapter-specific metadata types
+ */
+export abstract class BaseAdapter<
+  TChatModels extends ReadonlyArray<string> = ReadonlyArray<string>,
+  TEmbeddingModels extends ReadonlyArray<string> = ReadonlyArray<string>,
+  TChatProviderOptions extends Record<string, any> = Record<string, any>,
+  TEmbeddingProviderOptions extends Record<string, any> = Record<string, any>,
+  TModelProviderOptionsByName extends Record<string, any> = Record<string, any>,
+  TModelInputModalitiesByName extends Record<
+    string,
+    ReadonlyArray<Modality>
+  > = Record<string, ReadonlyArray<Modality>>,
+  TMessageMetadataByModality extends {
+    image: unknown
+    audio: unknown
+    video: unknown
+    document: unknown
+  } = DefaultMessageMetadataByModality,
+> implements
+    AIAdapter<
+      TChatModels,
+      TEmbeddingModels,
+      TChatProviderOptions,
+      TEmbeddingProviderOptions,
+      TModelProviderOptionsByName,
+      TModelInputModalitiesByName,
+      TMessageMetadataByModality
+    >
+{
+  abstract name: string
+  abstract models: TChatModels
+  embeddingModels?: TEmbeddingModels
+  protected config: AIAdapterConfig
+
+  // These properties are used for type inference only, never assigned at runtime
+  _providerOptions?: TChatProviderOptions
+  _chatProviderOptions?: TChatProviderOptions
+  _embeddingProviderOptions?: TEmbeddingProviderOptions
+  // Type-only map; concrete adapters should override this with a precise type
+  _modelProviderOptionsByName!: TModelProviderOptionsByName
+  // Type-only map for model input modalities; concrete adapters should override this
+  _modelInputModalitiesByName?: TModelInputModalitiesByName
+  // Type-only map for message metadata types; concrete adapters should override this
+  _messageMetadataByModality?: TMessageMetadataByModality
+
+  constructor(config: AIAdapterConfig = {}) {
+    this.config = config
+  }
+
+  abstract chatStream(options: ChatOptions): AsyncIterable<StreamChunk>
+
+  abstract summarize(
+    options: SummarizationOptions,
+  ): Promise<SummarizationResult>
+  abstract createEmbeddings(options: EmbeddingOptions): Promise<EmbeddingResult>
+
+  protected generateId(): string {
+    return `${this.name}-${Date.now()}-${Math.random()
+      .toString(36)
+      .substring(7)}`
+  }
+}

package/src/core/chat-common-options.ts

@@ -0,0 +1,55 @@
+/**
+ * Common options shared across different AI provider implementations.
+ * These options represent the standard parameters that work across OpenAI, Anthropic, and Gemini.
+ */
+export interface CommonOptions {
+  /**
+   * Controls the randomness of the output.
+   * Higher values (e.g., 0.8) make output more random, lower values (e.g., 0.2) make it more focused and deterministic.
+   * Range: [0.0, 2.0]
+   *
+   * Note: Generally recommended to use either temperature or topP, but not both.
+   *
+   * Provider usage:
+   * - OpenAI: `temperature` (number) - in text.top_p field
+   * - Anthropic: `temperature` (number) - ranges from 0.0 to 1.0, default 1.0
+   * - Gemini: `generationConfig.temperature` (number) - ranges from 0.0 to 2.0
+   */
+  temperature?: number
+
+  /**
+   * Nucleus sampling parameter. An alternative to temperature sampling.
+   * The model considers the results of tokens with topP probability mass.
+   * For example, 0.1 means only tokens comprising the top 10% probability mass are considered.
+   *
+   * Note: Generally recommended to use either temperature or topP, but not both.
+   *
+   * Provider usage:
+   * - OpenAI: `text.top_p` (number)
+   * - Anthropic: `top_p` (number | null)
+   * - Gemini: `generationConfig.topP` (number)
+   */
+  topP?: number
+
+  /**
+   * The maximum number of tokens to generate in the response.
+   *
+   * Provider usage:
+   * - OpenAI: `max_output_tokens` (number) - includes visible output and reasoning tokens
+   * - Anthropic: `max_tokens` (number, required) - range x >= 1
+   * - Gemini: `generationConfig.maxOutputTokens` (number)
+   */
+  maxTokens?: number
+
+  /**
+   * Additional metadata to attach to the request.
+   * Can be used for tracking, debugging, or passing custom information.
+   * Structure and constraints vary by provider.
+   *
+   * Provider usage:
+   * - OpenAI: `metadata` (Record<string, string>) - max 16 key-value pairs, keys max 64 chars, values max 512 chars
+   * - Anthropic: `metadata` (Record<string, any>) - includes optional user_id (max 256 chars)
+   * - Gemini: Not directly available in TextProviderOptions
+   */
+  metadata?: Record<string, any>
+}