feat(ai-sdk): createTool, implementTool helpers (#1151)

Implement or create AI SDK tool from contract/procedure.

Closes: #1150 

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Added @orpc/ai-sdk package enabling integration of oRPC contracts with
the Vercel AI SDK
  * Provides functions to map contract-first definitions to AI SDK tools
* Includes comprehensive documentation with TypeScript examples for AI
SDK integration

* **Documentation**
* Added detailed guides for integrating AI SDK tools with oRPC contracts
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: unnoq

apps/content/docs/integrations/ai-sdk.md

@@ -121,3 +121,102 @@ Prefer `eventIteratorToUnproxiedDataStream` over `eventIteratorToStream`.
 AI SDK internally uses `structuredClone`, which doesn't support proxied data.
 oRPC may proxy events for [metadata](/docs/event-iterator#last-event-id-event-metadata), so unproxy before passing to AI SDK.
 :::
+
+## `implementTool` helper
+
+Implements [procedure contract](/docs/contract-first/define-contract) as an [AI SDK tools](https://ai-sdk.dev/docs/foundations/tools) by leveraging existing contract definitions.
+
+```ts twoslash
+import { oc } from '@orpc/contract'
+import {
+  AI_SDK_TOOL_META_SYMBOL,
+  AiSdkToolMeta,
+  implementTool
+} from '@orpc/ai-sdk'
+import { z } from 'zod'
+
+interface ORPCMeta extends AiSdkToolMeta {} // optional extend meta
+const base = oc.$meta<ORPCMeta>({})
+
+const getWeatherContract = base
+  .meta({
+    [AI_SDK_TOOL_META_SYMBOL]: {
+      name: 'custom-tool-name', // AI SDK tool name
+    },
+  })
+  .route({
+    summary: 'Get the weather in a location', // AI SDK tool description
+  })
+  .input(z.object({
+    location: z.string().describe('The location to get the weather for'),
+  }))
+  .output(z.object({
+    location: z.string().describe('The location the weather is for'),
+    temperature: z.number().describe('The temperature in Celsius'),
+  }))
+
+const getWeatherTool = implementTool(getWeatherContract, {
+  execute: async ({ location }) => ({
+    location,
+    temperature: 72 + Math.floor(Math.random() * 21) - 10,
+  }),
+})
+```
+
+::: warning
+The `implementTool` helper requires a contract with an `input` schema defined
+:::
+
+::: info
+Standard [procedures](/docs/procedure) are also compatible with [procedure contracts](/docs/contract-first/define-contract).
+:::
+
+## `createTool` helper
+
+Converts a [procedure](/docs/procedure) into an [AI SDK Tool](https://ai-sdk.dev/docs/foundations/tools) by leveraging existing procedure definitions.
+
+```ts twoslash
+import { os } from '@orpc/server'
+import {
+  AI_SDK_TOOL_META_SYMBOL,
+  AiSdkToolMeta,
+  createTool
+} from '@orpc/ai-sdk'
+import { z } from 'zod'
+
+interface ORPCMeta extends AiSdkToolMeta {} // optional extend meta
+const base = os.$meta<ORPCMeta>({})
+
+const getWeatherProcedure = base
+  .meta({
+    [AI_SDK_TOOL_META_SYMBOL]: {
+      name: 'custom-tool-name', // AI SDK tool name
+    },
+  })
+  .route({
+    summary: 'Get the weather in a location',
+  })
+  .input(z.object({
+    location: z.string().describe('The location to get the weather for'),
+  }))
+  .output(z.object({
+    location: z.string().describe('The location the weather is for'),
+    temperature: z.number().describe('The temperature in Celsius'),
+  }))
+  .handler(async ({ input }) => ({
+    location: input.location,
+    temperature: 72 + Math.floor(Math.random() * 21) - 10,
+  }))
+
+const getWeatherTool = createTool(getWeatherProcedure, {
+  context: {}, // provide initial context if needed
+})
+```
+
+::: warning
+The `createTool` helper requires a procedure with an `input` schema defined
+:::
+
+::: warning
+Validation occurs twice (once for the tool, once for the procedure call). So validation may fail if `inputSchema` or `outputSchema` transform the data into different shapes.
+:::

apps/content/package.json

@@ -13,6 +13,7 @@
     "@opentelemetry/instrumentation": "^0.207.0",
     "@opentelemetry/sdk-node": "^0.207.0",
     "@opentelemetry/sdk-trace-web": "^2.2.0",
+    "@orpc/ai-sdk": "workspace:*",
     "@orpc/arktype": "workspace:*",
     "@orpc/client": "workspace:*",
     "@orpc/contract": "workspace:*",

packages/ai-sdk/.gitignore

@@ -0,0 +1,26 @@
+# Hidden folders and files
+.*
+!.gitignore
+!.*.example
+
+# Common generated folders
+logs/
+node_modules/
+out/
+dist/
+dist-ssr/
+build/
+coverage/
+temp/
+
+# Common generated files
+*.log
+*.log.*
+*.tsbuildinfo
+*.vitest-temp.json
+vite.config.ts.timestamp-*
+vitest.config.ts.timestamp-*
+
+# Common manual ignore files
+*.local
+*.pem

packages/ai-sdk/README.md

@@ -0,0 +1,81 @@
+<div align="center">
+  <image align="center" src="https://orpc.unnoq.com/logo.webp" width=280 alt="oRPC logo" />
+</div>
+
+<h1></h1>
+
+<div align="center">
+  <a href="https://codecov.io/gh/unnoq/orpc">
+    <img alt="codecov" src="https://codecov.io/gh/unnoq/orpc/branch/main/graph/badge.svg">
+  </a>
+  <a href="https://www.npmjs.com/package/@orpc/ai-sdk">
+    <img alt="weekly downloads" src="https://img.shields.io/npm/dw/%40orpc%2Fai-sdk?logo=npm" />
+  </a>
+  <a href="https://github.com/unnoq/orpc/blob/main/LICENSE">
+    <img alt="MIT License" src="https://img.shields.io/github/license/unnoq/orpc?logo=open-source-initiative" />
+  </a>
+  <a href="https://discord.gg/TXEbwRBvQn">
+    <img alt="Discord" src="https://img.shields.io/discord/1308966753044398161?color=7389D8&label&logo=discord&logoColor=ffffff" />
+  </a>
+  <a href="https://deepwiki.com/unnoq/orpc">
+    <img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki">
+  </a>
+</div>
+
+<h3 align="center">Typesafe APIs Made Simple 🪄</h3>
+
+**oRPC is a powerful combination of RPC and OpenAPI**, makes it easy to build APIs that are end-to-end type-safe and adhere to OpenAPI standards
+
+---
+
+## Highlights
+
+- **🔗 End-to-End Type Safety**: Ensure type-safe inputs, outputs, and errors from client to server.
+- **📘 First-Class OpenAPI**: Built-in support that fully adheres to the OpenAPI standard.
+- **📝 Contract-First Development**: Optionally define your API contract before implementation.
+- **🔍 First-Class OpenTelemetry**: Seamlessly integrate with OpenTelemetry for observability.
+- **⚙️ Framework Integrations**: Seamlessly integrate with TanStack Query (React, Vue, Solid, Svelte, Angular), SWR, Pinia Colada, and more.
+- **🚀 Server Actions**: Fully compatible with React Server Actions on Next.js, TanStack Start, and other platforms.
+- **🔠 Standard Schema Support**: Works out of the box with Zod, Valibot, ArkType, and other schema validators.
+- **🗃️ Native Types**: Supports native types like Date, File, Blob, BigInt, URL, and more.
+- **⏱️ Lazy Router**: Enhance cold start times with our lazy routing feature.
+- **📡 SSE & Streaming**: Enjoy full type-safe support for SSE and streaming.
+- **🌍 Multi-Runtime Support**: Fast and lightweight on Cloudflare, Deno, Bun, Node.js, and beyond.
+- **🔌 Extendability**: Easily extend functionality with plugins, middleware, and interceptors.
+
+## Documentation
+
+You can find the full documentation [here](https://orpc.unnoq.com).
+
+## Packages
+
+- [@orpc/contract](https://www.npmjs.com/package/@orpc/contract): Build your API contract.
+- [@orpc/server](https://www.npmjs.com/package/@orpc/server): Build your API or implement API contract.
+- [@orpc/client](https://www.npmjs.com/package/@orpc/client): Consume your API on the client with type-safety.
+- [@orpc/openapi](https://www.npmjs.com/package/@orpc/openapi): Generate OpenAPI specs and handle OpenAPI requests.
+- [@orpc/otel](https://www.npmjs.com/package/@orpc/otel): [OpenTelemetry](https://opentelemetry.io/) integration for observability.
+- [@orpc/nest](https://www.npmjs.com/package/@orpc/nest): Deeply integrate oRPC with [NestJS](https://nestjs.com/).
+- [@orpc/react](https://www.npmjs.com/package/@orpc/react): Utilities for integrating oRPC with React and React Server Actions.
+- [@orpc/tanstack-query](https://www.npmjs.com/package/@orpc/tanstack-query): [TanStack Query](https://tanstack.com/query/latest) integration.
+- [@orpc/experimental-react-swr](https://www.npmjs.com/package/@orpc/experimental-react-swr): [SWR](https://swr.vercel.app/) integration.
+- [@orpc/vue-colada](https://www.npmjs.com/package/@orpc/vue-colada): Integration with [Pinia Colada](https://pinia-colada.esm.dev/).
+- [@orpc/hey-api](https://www.npmjs.com/package/@orpc/hey-api): [Hey API](https://heyapi.dev/) integration.
+- [@orpc/zod](https://www.npmjs.com/package/@orpc/zod): More schemas that [Zod](https://zod.dev/) doesn't support yet.
+- [@orpc/valibot](https://www.npmjs.com/package/@orpc/valibot): OpenAPI spec generation from [Valibot](https://valibot.dev/).
+- [@orpc/arktype](https://www.npmjs.com/package/@orpc/arktype): OpenAPI spec generation from [ArkType](https://arktype.io/).
+
+## `@orpc/ai-sdk`
+
+The [AI SDK](https://ai-sdk.dev/) integration for oRPC.
+
+## Sponsors
+
+<p align="center">
+  <a href="https://cdn.jsdelivr.net/gh/unnoq/unnoq/sponsors.svg">
+    <img src='https://cdn.jsdelivr.net/gh/unnoq/unnoq/sponsors.svg'/>
+  </a>
+</p>
+
+## License
+
+Distributed under the MIT License. See [LICENSE](https://github.com/unnoq/orpc/blob/main/LICENSE) for more information.

packages/ai-sdk/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@orpc/ai-sdk",
+  "type": "module",
+  "version": "0.0.1",
+  "license": "MIT",
+  "homepage": "https://orpc.unnoq.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/unnoq/orpc.git",
+    "directory": "packages/ai-sdk"
+  },
+  "keywords": [
+    "ai-sdk",
+    "orpc"
+  ],
+  "publishConfig": {
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.mts",
+        "import": "./dist/index.mjs",
+        "default": "./dist/index.mjs"
+      }
+    }
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "unbuild",
+    "build:watch": "pnpm run build --watch",
+    "type:check": "tsc -b"
+  },
+  "peerDependencies": {
+    "ai": ">=5.0.76"
+  },
+  "dependencies": {
+    "@orpc/client": "workspace:*",
+    "@orpc/contract": "workspace:*",
+    "@orpc/server": "workspace:*",
+    "@orpc/shared": "workspace:*"
+  },
+  "devDependencies": {
+    "ai": "6.0.0-beta.85",
+    "zod": "^4.1.12"
+  }
+}

packages/ai-sdk/src/index.test.ts

@@ -0,0 +1,3 @@
+it('exports createTool', async () => {
+  expect(Object.keys(await import('./index'))).toContain('createTool')
+})

packages/ai-sdk/src/index.ts

@@ -0,0 +1,8 @@
+export * from './tool'
+
+export {
+  AsyncIteratorClass,
+  asyncIteratorToStream as eventIteratorToStream,
+  asyncIteratorToUnproxiedDataStream as eventIteratorToUnproxiedDataStream,
+  streamToAsyncIteratorClass as streamToEventIterator,
+} from '@orpc/shared'