@databricks/ai-sdk-provider 0.0.1 → 0.1.0

package/LICENSE

@@ -0,0 +1,69 @@
+Databricks License
+Copyright (2024) Databricks, Inc.
+
+Definitions.
+
+Agreement: The agreement between Databricks, Inc., and you governing
+the use of the Databricks Services, as that term is defined in
+the Master Cloud Services Agreement (MCSA) located at
+www.databricks.com/legal/mcsa.
+
+Licensed Materials: The source code, object code, data, and/or other
+works to which this license applies.
+
+Scope of Use. You may not use the Licensed Materials except in
+connection with your use of the Databricks Services pursuant to
+the Agreement. Your use of the Licensed Materials must comply at all
+times with any restrictions applicable to the Databricks Services,
+generally, and must be used in accordance with any applicable
+documentation. You may view, use, copy, modify, publish, and/or
+distribute the Licensed Materials solely for the purposes of using
+the Licensed Materials within or connecting to the Databricks Services.
+If you do not agree to these terms, you may not view, use, copy,
+modify, publish, and/or distribute the Licensed Materials.
+
+Redistribution. You may redistribute and sublicense the Licensed
+Materials so long as all use is in compliance with these terms.
+In addition:
+
+- You must give any other recipients a copy of this License;
+- You must cause any modified files to carry prominent notices
+stating that you changed the files;
+- You must retain, in any derivative works that you distribute,
+all copyright, patent, trademark, and attribution notices,
+excluding those notices that do not pertain to any part of
+the derivative works; and
+- If a "NOTICE" text file is provided as part of its
+distribution, then any derivative works that you distribute
+must include a readable copy of the attribution notices
+contained within such NOTICE file, excluding those notices
+that do not pertain to any part of the derivative works.
+
+You may add your own copyright statement to your modifications and may
+provide additional license terms and conditions for use, reproduction,
+or distribution of your modifications, or for any such derivative works
+as a whole, provided your use, reproduction, and distribution of
+the Licensed Materials otherwise complies with the conditions stated
+in this License.
+
+Termination. This license terminates automatically upon your breach of
+these terms or upon the termination of your Agreement. Additionally,
+Databricks may terminate this license at any time on notice. Upon
+termination, you must permanently delete the Licensed Materials and
+all copies thereof.
+
+DISCLAIMER; LIMITATION OF LIABILITY.
+
+THE LICENSED MATERIALS ARE PROVIDED "AS-IS" AND WITH ALL FAULTS.
+DATABRICKS, ON BEHALF OF ITSELF AND ITS LICENSORS, SPECIFICALLY
+DISCLAIMS ALL WARRANTIES RELATING TO THE LICENSED MATERIALS, EXPRESS
+AND IMPLIED, INCLUDING, WITHOUT LIMITATION, IMPLIED WARRANTIES,
+CONDITIONS AND OTHER TERMS OF MERCHANTABILITY, SATISFACTORY QUALITY OR
+FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. DATABRICKS AND
+ITS LICENSORS TOTAL AGGREGATE LIABILITY RELATING TO OR ARISING OUT OF
+YOUR USE OF OR DATABRICKS' PROVISIONING OF THE LICENSED MATERIALS SHALL
+BE LIMITED TO ONE THOUSAND ($1,000) DOLLARS. 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 LICENSED MATERIALS OR
+THE USE OR OTHER DEALINGS IN THE LICENSED MATERIALS.

package/NOTICE

@@ -0,0 +1,16 @@
+Copyright (2025) Databricks, Inc.
+
+This Software includes software developed at Databricks and its use is subject to the included LICENSE file.
+
+________________
+This Software contains code from the following open source projects, licensed under the Apache 2.0 license (Apache License, Version 2.0):
+
+vercel/ai - https://github.com/vercel/ai
+Copyright 2023 Vercel, Inc.
+
+________________
+This Software contains code from the following open source projects, licensed under the MIT license (The MIT License):
+
+colinhacks/zod - https://github.com/colinhacks/zod
+Copyright (c) 2025 Colin McDonnell
+

package/README.md

@@ -1,3 +1,169 @@
 # @databricks/ai-sdk-provider
 
-Placeholder package - reserved for Databricks AI SDK Provider.
+Databricks provider for the [Vercel AI SDK](https://sdk.vercel.ai/docs).
+
+## Features
+
+- 🚀 Support for three Databricks endpoint types:
+  - **Chat Agent** (`agent/v2/chat`) - Databricks chat agent API
+  - **Responses Agent** (`agent/v2/responses`) - Databricks responses agent API
+  - **FM API** (`llm/v1/chat`) - Foundation model chat completions API
+- 🔄 Stream and non-stream (generate) support for all endpoint types
+- 🛠️ Custom tool calling mechanism for Databricks agents
+- 🔐 Flexible authentication (bring your own tokens/headers)
+- 🎯 Full TypeScript support
+
+## Installation
+
+```bash
+npm install @databricks/ai-sdk-provider
+```
+
+## Peer Dependencies
+
+This package requires the following peer dependencies:
+
+```bash
+npm install @ai-sdk/provider @ai-sdk/provider-utils
+```
+
+To use the provider with AI SDK functions like `generateText` or `streamText`, also install:
+
+```bash
+npm install ai
+```
+
+## Quick Start
+
+```typescript
+import { createDatabricksProvider } from '@databricks/ai-sdk-provider'
+import { generateText } from 'ai'
+
+// Create provider with your workspace URL and authentication
+const provider = createDatabricksProvider({
+  baseURL: 'https://your-workspace.databricks.com/serving-endpoints',
+  headers: {
+    Authorization: `Bearer ${token}`,
+  },
+})
+
+// Use the Chat Agent endpoint
+const responsesAgent = provider.responsesAgent('your-agent-endpoint')
+
+const result = await generateText({
+  model: responsesAgent,
+  prompt: 'Hello, how are you?',
+})
+
+console.log(result.text)
+```
+
+## Authentication
+
+The provider requires you to pass authentication headers:
+
+```typescript
+const provider = createDatabricksProvider({
+  baseURL: 'https://your-workspace.databricks.com/serving-endpoints',
+  headers: {
+    Authorization: `Bearer ${token}`,
+  },
+})
+```
+
+## API Reference
+
+### Main Export
+
+#### `createDatabricksProvider(settings)`
+
+Creates a Databricks provider instance.
+
+**Parameters:**
+
+- `settings.baseURL` (string, required): Base URL for the Databricks API calls
+- `settings.headers` (object, optional): Custom headers to include in requests
+- `settings.provider` (string, optional): Provider name (defaults to "databricks")
+- `settings.fetch` (function, optional): Custom fetch implementation
+- `settings.formatUrl` (function, optional): Optional function to format the URL
+
+**Returns:** `DatabricksProvider` with three model creation methods:
+
+- `chatAgent(modelId: string)`: Create a Chat Agent model
+- `responsesAgent(modelId: string)`: Create a Responses Agent model
+- `fmapi(modelId: string)`: Create an FM API model
+
+### Tool Constants
+
+```typescript
+import { DATABRICKS_TOOL_DEFINITION, DATABRICKS_TOOL_CALL_ID } from '@databricks/ai-sdk-provider'
+```
+
+#### Why are these needed?
+
+The AI SDK requires tools to be defined ahead of time with known schemas. However, Databricks agents can orchestrate tools dynamically at runtime - we don't know which tools will be called until the model executes.
+
+To bridge this gap, this provider uses a special "catch-all" tool definition:
+
+- **`DATABRICKS_TOOL_DEFINITION`**: A universal tool definition that accepts any input/output schema. This allows the provider to handle any tool that Databricks agents orchestrate, regardless of its schema.
+
+- **`DATABRICKS_TOOL_CALL_ID`**: The constant ID (`'databricks-tool-call'`) used to identify this special tool. The actual tool name from Databricks is preserved in the metadata so it can be displayed correctly in the UI and passed back to the model.
+
+This pattern enables dynamic tool orchestration by Databricks while maintaining compatibility with the AI SDK's tool interface.
+
+### MCP Utilities
+
+```typescript
+import {
+  MCP_APPROVAL_STATUS_KEY,
+  MCP_APPROVAL_REQUEST_TYPE,
+  MCP_APPROVAL_RESPONSE_TYPE,
+  isMcpApprovalRequest,
+  isMcpApprovalResponse,
+  createApprovalStatusOutput,
+  getMcpApprovalState,
+} from '@databricks/ai-sdk-provider'
+```
+
+MCP (Model Context Protocol) approval utilities for handling approval workflows.
+
+## Examples
+
+### Responses Agent Endpoint
+
+```typescript
+const responsesAgent = provider.responsesAgent('my-responses-agent')
+
+const result = await generateText({
+  model: responsesAgent,
+  prompt: 'Analyze this data...',
+})
+
+console.log(result.text)
+```
+
+### With Tool Calling
+
+```typescript
+import { DATABRICKS_TOOL_CALL_ID, DATABRICKS_TOOL_DEFINITION } from '@databricks/ai-sdk-provider'
+
+const responsesAgent = provider.responsesAgent('my-agent-with-tools')
+
+const result = await generateText({
+  model: responsesAgent,
+  prompt: 'Search for information about AI',
+  tools: {
+    [DATABRICKS_TOOL_CALL_ID]: DATABRICKS_TOOL_DEFINITION,
+  },
+})
+```
+
+## Links
+
+- [Vercel AI SDK Documentation](https://sdk.vercel.ai/docs)
+- [Databricks Documentation](https://docs.databricks.com/)
+- [GitHub Repository](https://github.com/databricks/databricks-ai-bridge)
+
+## Contributing
+
+This package is part of the [databricks-ai-bridge](https://github.com/databricks/databricks-ai-bridge) monorepo.