@tanstack/ai 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Tanner Linsley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,131 @@
+<div align="center">
+  <img src="./media/header_ai.png" >
+</div>
+
+<br />
+
+<div align="center">
+<a href="https://npmjs.com/package/@tanstack/ai" target="\_parent">
+  <img alt="" src="https://img.shields.io/npm/dm/@tanstack/ai.svg" />
+</a>
+<a href="https://github.com/TanStack/ai" target="\_parent">
+	  <img alt="" src="https://img.shields.io/github/stars/TanStack/ai.svg?style=social&label=Star" alt="GitHub stars" />
+</a>
+<a href="https://bundlephobia.com/result?p=@tanstack/ai@latest" target="\_parent">
+  <img alt="" src="https://badgen.net/bundlephobia/minzip/@tanstack/ai@latest" />
+</a>
+</div>
+
+<div align="center">
+<a href="#badge">
+  <img alt="semantic-release" src="https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg">
+</a>
+	<a href="#badge">
+		<img src="https://img.shields.io/github/v/release/tanstack/ai" alt="Release"/>
+	</a>
+<a href="https://twitter.com/tan_stack">
+  <img src="https://img.shields.io/twitter/follow/tan_stack.svg?style=social" alt="Follow @TanStack"/>
+</a>
+</div>
+
+<div align="center">
+  
+### [Become a Sponsor!](https://github.com/sponsors/tannerlinsley/)
+</div>
+
+# TanStack AI
+
+A powerful, type-safe AI SDK for building AI-powered applications.
+
+- Provider-agnostic adapters (OpenAI, Anthropic, Gemini, Ollama, etc.)
+- **Multimodal content support** - Send images, audio, video, and documents
+- Chat completion, streaming, and agent loop strategies
+- Headless chat state management with adapters (SSE, HTTP stream, custom)
+- Isomorphic type-safe tools with server/client execution
+- **Enhanced integration with TanStack Start** - Share implementations between AI tools and server functions
+
+### <a href="https://tanstack.com/ai">Read the docs →</b></a>
+
+## Bonus: TanStack Start Integration
+
+TanStack AI works with **any** framework (Next.js, Express, Remix, etc.).
+
+**With TanStack Start**, you get a bonus: share implementations between AI tools and server functions with `createServerFnTool`:
+
+```typescript
+import { createServerFnTool } from '@tanstack/ai-react'
+
+// Define once, get AI tool AND server function (TanStack Start only)
+const getProducts = createServerFnTool({
+  name: 'getProducts',
+  inputSchema: z.object({ query: z.string() }),
+  execute: async ({ query }) => db.products.search(query),
+})
+
+// Use in AI chat
+chat({ tools: [getProducts.server] })
+
+// Call directly from components (no API endpoint needed!)
+const products = await getProducts.serverFn({ query: 'laptop' })
+```
+
+No duplicate logic, full type safety, automatic validation. The `serverFn` feature requires TanStack Start. See [docs](https://tanstack.com/ai) for details.
+
+## Get Involved
+
+- We welcome issues and pull requests!
+- Participate in [GitHub discussions](https://github.com/TanStack/ai/discussions)
+- Chat with the community on [Discord](https://discord.com/invite/WrRKjPJ)
+- See [CONTRIBUTING.md](./CONTRIBUTING.md) for setup instructions
+
+## Partners
+
+<table align="center">
+  <tr>
+    <td>
+      <a href="https://www.coderabbit.ai/?via=tanstack&dub_id=aCcEEdAOqqutX6OS" >
+        <picture>
+          <source media="(prefers-color-scheme: dark)" srcset="https://tanstack.com/assets/coderabbit-dark-CMcuvjEy.svg" height="40" />
+          <source media="(prefers-color-scheme: light)" srcset="https://tanstack.com/assets/coderabbit-light-DVMJ2jHi.svg" height="40" />
+          <img src="https://tanstack.com/assets/coderabbit-light-DVMJ2jHi.svg" height="40" alt="CodeRabbit" />
+        </picture>
+      </a>
+    </td>
+    <td>
+      <a href="https://www.cloudflare.com?utm_source=tanstack">
+        <picture>
+          <source media="(prefers-color-scheme: dark)" srcset="https://tanstack.com/assets/cloudflare-white-DQDB7UaL.svg" height="60" />
+          <source media="(prefers-color-scheme: light)" srcset="https://tanstack.com/assets/cloudflare-black-CPufaW0B.svg" height="60" />
+          <img src="https://tanstack.com/assets/cloudflare-black-CPufaW0B.svg" height="60" alt="Cloudflare" />
+        </picture>
+      </a>
+    </td>
+  </tr>
+</table>
+
+<div align="center">
+<img src="./media/partner_logo.svg" alt="AI & you?" height="65">
+<p>
+We're looking for TanStack AI Partners to join our mission! Partner with us to push the boundaries of TanStack AI and build amazing things together.
+</p>
+<a href="mailto:partners@tanstack.com?subject=TanStack AI Partnership"><b>LET'S CHAT</b></a>
+</div>
+
+## Explore the TanStack Ecosystem
+
+- <a href="https://github.com/tanstack/config"><b>TanStack Config</b></a> – Tooling for JS/TS packages
+- <a href="https://github.com/tanstack/db"><b>TanStack DB</b></a> – Reactive sync client store
+- <a href="https://github.com/tanstack/devtools">TanStack Devtools</a> – Unified devtools panel
+- <a href="https://github.com/tanstack/form"><b>TanStack Form</b></a> – Type‑safe form state
+- <a href="https://github.com/tanstack/pacer"><b>TanStack Pacer</b></a> – Debouncing, throttling, batching
+- <a href="https://github.com/tanstack/query"><b>TanStack Query</b></a> – Async state & caching
+- <a href="https://github.com/tanstack/ranger"><b>TanStack Ranger</b></a> – Range & slider primitives
+- <a href="https://github.com/tanstack/router"><b>TanStack Router</b></a> – Type‑safe routing, caching & URL state
+- <a href="https://github.com/tanstack/router"><b>TanStack Start</b></a> – Full‑stack SSR & streaming
+- <a href="https://github.com/tanstack/store"><b>TanStack Store</b></a> – Reactive data store
+- <a href="https://github.com/tanstack/table"><b>TanStack Table</b></a> – Headless datagrids
+- <a href="https://github.com/tanstack/virtual"><b>TanStack Virtual</b></a> – Virtualized rendering
+
+… and more at <a href="https://tanstack.com"><b>TanStack.com »</b></a>
+
+<!-- USE THE FORCE LUKE -->

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

@@ -0,0 +1,35 @@
+import { AIAdapter, AIAdapterConfig, ChatOptions, DefaultMessageMetadataByModality, EmbeddingOptions, EmbeddingResult, Modality, StreamChunk, SummarizationOptions, SummarizationResult } from './types.js';
+/**
+ * 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 declare 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;
+    _providerOptions?: TChatProviderOptions;
+    _chatProviderOptions?: TChatProviderOptions;
+    _embeddingProviderOptions?: TEmbeddingProviderOptions;
+    _modelProviderOptionsByName: TModelProviderOptionsByName;
+    _modelInputModalitiesByName?: TModelInputModalitiesByName;
+    _messageMetadataByModality?: TMessageMetadataByModality;
+    constructor(config?: AIAdapterConfig);
+    abstract chatStream(options: ChatOptions): AsyncIterable<StreamChunk>;
+    abstract summarize(options: SummarizationOptions): Promise<SummarizationResult>;
+    abstract createEmbeddings(options: EmbeddingOptions): Promise<EmbeddingResult>;
+    protected generateId(): string;
+}

package/dist/esm/base-adapter.js

@@ -0,0 +1,12 @@
+class BaseAdapter {
+  constructor(config = {}) {
+    this.config = config;
+  }
+  generateId() {
+    return `${this.name}-${Date.now()}-${Math.random().toString(36).substring(7)}`;
+  }
+}
+export {
+  BaseAdapter
+};
+//# sourceMappingURL=base-adapter.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"base-adapter.js","sources":["../../src/base-adapter.ts"],"sourcesContent":["import type {\n  AIAdapter,\n  AIAdapterConfig,\n  ChatOptions,\n  DefaultMessageMetadataByModality,\n  EmbeddingOptions,\n  EmbeddingResult,\n  Modality,\n  StreamChunk,\n  SummarizationOptions,\n  SummarizationResult,\n} from './types'\n\n/**\n * Base adapter class with support for endpoint-specific models and provider options.\n *\n * Generic parameters:\n * - TChatModels: Models that support chat/text completion\n * - TEmbeddingModels: Models that support embeddings\n * - TChatProviderOptions: Provider-specific options for chat endpoint\n * - TEmbeddingProviderOptions: Provider-specific options for embedding endpoint\n * - TModelProviderOptionsByName: Provider-specific options for model by name\n * - TModelInputModalitiesByName: Map from model name to its supported input modalities\n * - TMessageMetadataByModality: Map from modality type to adapter-specific metadata types\n */\nexport abstract class BaseAdapter<\n  TChatModels extends ReadonlyArray<string> = ReadonlyArray<string>,\n  TEmbeddingModels extends ReadonlyArray<string> = ReadonlyArray<string>,\n  TChatProviderOptions extends Record<string, any> = Record<string, any>,\n  TEmbeddingProviderOptions extends Record<string, any> = Record<string, any>,\n  TModelProviderOptionsByName extends Record<string, any> = Record<string, any>,\n  TModelInputModalitiesByName extends Record<\n    string,\n    ReadonlyArray<Modality>\n  > = Record<string, ReadonlyArray<Modality>>,\n  TMessageMetadataByModality extends {\n    image: unknown\n    audio: unknown\n    video: unknown\n    document: unknown\n  } = DefaultMessageMetadataByModality,\n> implements\n    AIAdapter<\n      TChatModels,\n      TEmbeddingModels,\n      TChatProviderOptions,\n      TEmbeddingProviderOptions,\n      TModelProviderOptionsByName,\n      TModelInputModalitiesByName,\n      TMessageMetadataByModality\n    >\n{\n  abstract name: string\n  abstract models: TChatModels\n  embeddingModels?: TEmbeddingModels\n  protected config: AIAdapterConfig\n\n  // These properties are used for type inference only, never assigned at runtime\n  _providerOptions?: TChatProviderOptions\n  _chatProviderOptions?: TChatProviderOptions\n  _embeddingProviderOptions?: TEmbeddingProviderOptions\n  // Type-only map; concrete adapters should override this with a precise type\n  _modelProviderOptionsByName!: TModelProviderOptionsByName\n  // Type-only map for model input modalities; concrete adapters should override this\n  _modelInputModalitiesByName?: TModelInputModalitiesByName\n  // Type-only map for message metadata types; concrete adapters should override this\n  _messageMetadataByModality?: TMessageMetadataByModality\n\n  constructor(config: AIAdapterConfig = {}) {\n    this.config = config\n  }\n\n  abstract chatStream(options: ChatOptions): AsyncIterable<StreamChunk>\n\n  abstract summarize(\n    options: SummarizationOptions,\n  ): Promise<SummarizationResult>\n  abstract createEmbeddings(options: EmbeddingOptions): Promise<EmbeddingResult>\n\n  protected generateId(): string {\n    return `${this.name}-${Date.now()}-${Math.random()\n      .toString(36)\n      .substring(7)}`\n  }\n}\n"],"names":[],"mappings":"AAyBO,MAAe,YA0BtB;AAAA,EAiBE,YAAY,SAA0B,IAAI;AACxC,SAAK,SAAS;AAAA,EAChB;AAAA,EASU,aAAqB;AAC7B,WAAO,GAAG,KAAK,IAAI,IAAI,KAAK,KAAK,IAAI,KAAK,OAAA,EACvC,SAAS,EAAE,EACX,UAAU,CAAC,CAAC;AAAA,EACjB;AACF;"}

package/dist/esm/core/chat-common-options.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 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>;
+}

package/dist/esm/core/chat.d.ts

@@ -0,0 +1,30 @@
+import { AIAdapter, ChatStreamOptionsForModel, StreamChunk } from '../types.js';
+/**
+ * Standalone chat streaming function with type inference from adapter
+ * Returns an async iterable of StreamChunks for streaming responses
+ * Includes automatic tool execution loop
+ *
+ * @param options Chat options
+ * @param options.adapter - AI adapter instance to use
+ * @param options.model - Model name (autocompletes based on adapter)
+ * @param options.messages - Conversation messages
+ * @param options.tools - Optional tools for function calling (auto-executed)
+ * @param options.agentLoopStrategy - Optional strategy for controlling tool execution loop
+ *
+ * @example
+ * ```typescript
+ * const stream = chat({
+ *   adapter: openai(),
+ *   model: 'gpt-4o',
+ *   messages: [{ role: 'user', content: 'Hello!' }],
+ *   tools: [weatherTool], // Optional: auto-executed when called
+ * });
+ *
+ * for await (const chunk of stream) {
+ *   if (chunk.type === 'content') {
+ *     console.log(chunk.delta);
+ *   }
+ * }
+ * ```
+ */
+export declare function chat<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: ChatStreamOptionsForModel<TAdapter, TModel>): AsyncIterable<StreamChunk>;