Merge branch 'TanStack:main' into ts-react-search

Author: denis-shvets

.github/workflows/autofix.yml

@@ -22,9 +22,7 @@ jobs:
       - name: Setup Tools
         uses: tanstack/config/.github/setup@main
       - name: Fix formatting
-        run: pnpm prettier:write
-      - name: Generate Docs
-        run: pnpm generate-docs
+        run: pnpm format
       - name: Apply fixes
         uses: autofix-ci/action@635ffb0c9798bd160680f18fd73371e355b85f27
         with:

.github/workflows/release.yml

@@ -40,7 +40,9 @@ jobs:
           title: "ci: Version Packages"
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+      - name: Generate Docs
+        if: steps.changesets.outputs.published == 'true'
+        run: pnpm generate-docs
       - name: Commit Generated Docs
         if: steps.changesets.outputs.published == 'true'
         run: |
@@ -56,3 +58,8 @@ jobs:
           fi
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - name: Comment on PRs about release
+        if: steps.changesets.outputs.published == 'true'
+        uses: tanstack/config/.github/comment-on-release@main
+        with:
+          published-packages: ${{ steps.changesets.outputs.publishedPackages }}

docs/guides/server-tools.md

@@ -256,10 +256,54 @@ const getUserData = getUserDataDef.server(async ({ userId }) => {
 });
 ```
 
+## Using JSON Schema
+
+If you have existing JSON Schema definitions or prefer not to use Zod, you can define tool schemas using raw JSON Schema objects:
+
+```typescript
+import { toolDefinition } from "@tanstack/ai";
+import type { JSONSchema } from "@tanstack/ai";
+
+const inputSchema: JSONSchema = {
+  type: "object",
+  properties: {
+    userId: {
+      type: "string",
+      description: "The user ID to look up",
+    },
+  },
+  required: ["userId"],
+};
+
+const outputSchema: JSONSchema = {
+  type: "object",
+  properties: {
+    name: { type: "string" },
+    email: { type: "string" },
+  },
+  required: ["name", "email"],
+};
+
+const getUserDataDef = toolDefinition({
+  name: "get_user_data",
+  description: "Get user information from the database",
+  inputSchema,
+  outputSchema,
+});
+
+// When using JSON Schema, args is typed as `any`
+const getUserData = getUserDataDef.server(async (args) => {
+  const user = await db.users.findUnique({ where: { id: args.userId } });
+  return { name: user.name, email: user.email };
+});
+```
+
+> **Note:** JSON Schema tools skip runtime validation. Zod schemas are recommended for full type safety and validation.
+
 ## Best Practices
 
 1. **Keep tools focused** - Each tool should do one thing well
-2. **Validate inputs** - Use Zod schemas to ensure type safety
+2. **Validate inputs** - Use Zod schemas to ensure type safety (JSON Schema skips validation)
 3. **Handle errors** - Return meaningful error messages
 4. **Use descriptions** - Clear descriptions help the model use tools correctly
 5. **Secure sensitive operations** - Never expose API keys or secrets to the client

docs/guides/tools.md

@@ -33,7 +33,49 @@ This approach provides:
 - **Type Safety**: Full TypeScript inference from Zod schemas
 - **Code Reuse**: Define schemas once, use everywhere
 - **Flexibility**: Tools can execute on server, client, or both
+- **Schema Options**: Use Zod schemas or raw JSON Schema objects
 
+## Schema Options
+
+TanStack AI supports two ways to define tool schemas:
+
+### Option 1: Zod Schemas (Recommended)
+
+Zod schemas provide full TypeScript type inference and runtime validation:
+
+```typescript
+import { z } from "zod";
+
+const inputSchema = z.object({
+  location: z.string().describe("City name"),
+  unit: z.enum(["celsius", "fahrenheit"]).optional(),
+});
+```
+
+### Option 2: JSON Schema Objects
+
+For cases where you already have JSON Schema definitions or prefer not to use Zod, you can pass raw JSON Schema objects directly:
+
+```typescript
+import type { JSONSchema } from "@tanstack/ai";
+
+const inputSchema: JSONSchema = {
+  type: "object",
+  properties: {
+    location: {
+      type: "string",
+      description: "City name",
+    },
+    unit: {
+      type: "string",
+      enum: ["celsius", "fahrenheit"],
+    },
+  },
+  required: ["location"],
+};
+```
+
+> **Note:** When using JSON Schema, TypeScript will infer `any` for input/output types since JSON Schema cannot provide compile-time type information. Zod schemas are recommended for full type safety.
 
 ## Tool Definition
 
@@ -74,6 +116,58 @@ const getWeatherServer = getWeatherDef.server(async ({ location, unit }) => {
 });
 ```
 
+### Using JSON Schema
+
+If you prefer JSON Schema or have existing schema definitions:
+
+```typescript
+import { toolDefinition } from "@tanstack/ai";
+import type { JSONSchema } from "@tanstack/ai";
+
+// Define schemas using JSON Schema
+const inputSchema: JSONSchema = {
+  type: "object",
+  properties: {
+    location: {
+      type: "string",
+      description: "The city and state, e.g. San Francisco, CA",
+    },
+    unit: {
+      type: "string",
+      enum: ["celsius", "fahrenheit"],
+    },
+  },
+  required: ["location"],
+};
+
+const outputSchema: JSONSchema = {
+  type: "object",
+  properties: {
+    temperature: { type: "number" },
+    conditions: { type: "string" },
+    location: { type: "string" },
+  },
+  required: ["temperature", "conditions", "location"],
+};
+
+// Create the tool definition
+const getWeatherDef = toolDefinition({
+  name: "get_weather",
+  description: "Get the current weather for a location",
+  inputSchema,
+  outputSchema,
+});
+
+// Create server implementation (args is typed as `any` with JSON Schema)
+const getWeatherServer = getWeatherDef.server(async (args) => {
+  const { location, unit } = args;
+  const response = await fetch(
+    `https://api.weather.com/v1/current?location=${location}&unit=${unit || "fahrenheit"}`
+  );
+  return await response.json();
+});
+```
+
 ## Using Tools in Chat
 
 ### Server-Side

docs/reference/classes/ToolCallManager.md

@@ -5,7 +5,7 @@ title: ToolCallManager
 
 # Class: ToolCallManager
 
-Defined in: [tools/tool-calls.ts:41](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/tools/tool-calls.ts#L41)
+Defined in: [tools/tool-calls.ts:51](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/tools/tool-calls.ts#L51)
 
 Manages tool call accumulation and execution for the chat() method's automatic tool execution loop.
 
@@ -47,7 +47,7 @@ if (manager.hasToolCalls()) {
 new ToolCallManager(tools): ToolCallManager;
 ```
 
-Defined in: [tools/tool-calls.ts:45](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/tools/tool-calls.ts#L45)
+Defined in: [tools/tool-calls.ts:55](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/tools/tool-calls.ts#L55)
 
 #### Parameters
 
@@ -67,7 +67,7 @@ readonly [`Tool`](../interfaces/Tool.md)\<`ZodType`\<`unknown`, `unknown`, `$Zod
 addToolCallChunk(chunk): void;
 ```
 
-Defined in: [tools/tool-calls.ts:53](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/tools/tool-calls.ts#L53)
+Defined in: [tools/tool-calls.ts:63](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/tools/tool-calls.ts#L63)
 
 Add a tool call chunk to the accumulator
 Handles streaming tool calls by accumulating arguments
@@ -126,7 +126,7 @@ Handles streaming tool calls by accumulating arguments
 clear(): void;
 ```
 
-Defined in: [tools/tool-calls.ts:193](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/tools/tool-calls.ts#L193)
+Defined in: [tools/tool-calls.ts:208](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/tools/tool-calls.ts#L208)
 
 Clear the tool calls map for the next iteration
 
@@ -145,7 +145,7 @@ executeTools(doneChunk): AsyncGenerator<ToolResultStreamChunk, ModelMessage<
 | null>[], void>;
 ```
 
-Defined in: [tools/tool-calls.ts:111](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/tools/tool-calls.ts#L111)
+Defined in: [tools/tool-calls.ts:121](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/tools/tool-calls.ts#L121)
 
 Execute all tool calls and return tool result messages
 Also yields tool_result chunks for streaming
@@ -171,7 +171,7 @@ Also yields tool_result chunks for streaming
 getToolCalls(): ToolCall[];
 ```
 
-Defined in: [tools/tool-calls.ts:101](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/tools/tool-calls.ts#L101)
+Defined in: [tools/tool-calls.ts:111](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/tools/tool-calls.ts#L111)
 
 Get all complete tool calls (filtered for valid ID and name)
 
@@ -187,7 +187,7 @@ Get all complete tool calls (filtered for valid ID and name)
 hasToolCalls(): boolean;
 ```
 
-Defined in: [tools/tool-calls.ts:94](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/tools/tool-calls.ts#L94)
+Defined in: [tools/tool-calls.ts:104](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/tools/tool-calls.ts#L104)
 
 Check if there are any complete tool calls to execute
 

docs/reference/functions/convertZodToJsonSchema.md

@@ -9,17 +9,19 @@ title: convertZodToJsonSchema
 function convertZodToJsonSchema(schema): Record<string, any> | undefined;
 ```
 
-Defined in: [tools/zod-converter.ts:31](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/tools/zod-converter.ts#L31)
+Defined in: [tools/zod-converter.ts:57](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/tools/zod-converter.ts#L57)
 
-Converts a Zod schema to JSON Schema format compatible with LLM providers.
+Converts a schema (Zod or JSONSchema) to JSON Schema format compatible with LLM providers.
+If the input is already a JSONSchema object, it is returned as-is.
+If the input is a Zod schema, it is converted to JSON Schema.
 
 ## Parameters
 
 ### schema
 
-Zod schema to convert
+Zod schema or JSONSchema object to convert
 
-`ZodType`\<`unknown`, `unknown`, `$ZodTypeInternals`\<`unknown`, `unknown`\>\> | `undefined`
+[`SchemaInput`](../type-aliases/SchemaInput.md) | `undefined`
 
 ## Returns
 
@@ -32,12 +34,13 @@ JSON Schema object that can be sent to LLM providers
 ```typescript
 import { z } from 'zod';
 
-const schema = z.object({
+// Using Zod schema
+const zodSchema = z.object({
   location: z.string().describe('City name'),
   unit: z.enum(['celsius', 'fahrenheit']).optional()
 });
 
-const jsonSchema = convertZodToJsonSchema(schema);
+const jsonSchema = convertZodToJsonSchema(zodSchema);
 // Returns:
 // {
 //   type: 'object',
@@ -47,4 +50,13 @@ const jsonSchema = convertZodToJsonSchema(schema);
 //   },
 //   required: ['location']
 // }
+
+// Using JSONSchema directly (passes through unchanged)
+const rawSchema = {
+  type: 'object',
+  properties: { location: { type: 'string' } },
+  required: ['location']
+};
+const result = convertZodToJsonSchema(rawSchema);
+// Returns the same object
 ```

docs/reference/functions/toolDefinition.md

@@ -9,7 +9,7 @@ title: toolDefinition
 function toolDefinition<TInput, TOutput, TName>(config): ToolDefinition<TInput, TOutput, TName>;
 ```
 
-Defined in: [tools/tool-definition.ts:170](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/tools/tool-definition.ts#L170)
+Defined in: [tools/tool-definition.ts:174](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/tools/tool-definition.ts#L174)
 
 Create an isomorphic tool definition that can be used directly or instantiated for server/client
 
@@ -22,11 +22,11 @@ The definition contains all tool metadata (name, description, schemas) and can b
 
 ### TInput
 
-`TInput` *extends* `ZodType`\<`unknown`, `unknown`, `$ZodTypeInternals`\<`unknown`, `unknown`\>\> = `ZodAny`
+`TInput` *extends* [`SchemaInput`](../type-aliases/SchemaInput.md) = `ZodAny`
 
 ### TOutput
 
-`TOutput` *extends* `ZodType`\<`unknown`, `unknown`, `$ZodTypeInternals`\<`unknown`, `unknown`\>\> = `ZodAny`
+`TOutput` *extends* [`SchemaInput`](../type-aliases/SchemaInput.md) = `ZodAny`
 
 ### TName
 

docs/reference/index.md

@@ -41,6 +41,7 @@ title: "@tanstack/ai"
 - [ImagePart](interfaces/ImagePart.md)
 - [InternalToolCallState](interfaces/InternalToolCallState.md)
 - [JSONParser](interfaces/JSONParser.md)
+- [JSONSchema](interfaces/JSONSchema.md)
 - [ModelMessage](interfaces/ModelMessage.md)
 - [ProcessorResult](interfaces/ProcessorResult.md)
 - [ProcessorState](interfaces/ProcessorState.md)
@@ -80,12 +81,14 @@ title: "@tanstack/ai"
 - [ContentPartForModalities](type-aliases/ContentPartForModalities.md)
 - [ExtractModalitiesForModel](type-aliases/ExtractModalitiesForModel.md)
 - [ExtractModelsFromAdapter](type-aliases/ExtractModelsFromAdapter.md)
+- [InferSchemaType](type-aliases/InferSchemaType.md)
 - [InferToolInput](type-aliases/InferToolInput.md)
 - [InferToolName](type-aliases/InferToolName.md)
 - [InferToolOutput](type-aliases/InferToolOutput.md)
 - [MessagePart](type-aliases/MessagePart.md)
 - [ModalitiesArrayToUnion](type-aliases/ModalitiesArrayToUnion.md)
 - [Modality](type-aliases/Modality.md)
+- [SchemaInput](type-aliases/SchemaInput.md)
 - [StreamChunk](type-aliases/StreamChunk.md)
 - [StreamChunkType](type-aliases/StreamChunkType.md)
 - [ToolCallState](type-aliases/ToolCallState.md)