Add Vercel AI SDK and Mastra tool adapters (chdb/ai-sdk, chdb/mastra)#61
Open
ShawnChen-Sirius wants to merge 1 commit into
Open
Add Vercel AI SDK and Mastra tool adapters (chdb/ai-sdk, chdb/mastra)#61ShawnChen-Sirius wants to merge 1 commit into
ShawnChen-Sirius wants to merge 1 commit into
Conversation
Lets an agent run ClickHouse SQL with chDB as a first-class tool in the two main TS agent frameworks, with one shared executor so behavior is identical across them. - integrations/chdb-tool-core.mjs: framework-agnostic core — a shared description (chDB engine + the table functions it can reach: file/s3/url/postgresql/mysql/ mongodb/remoteSecure), and runChdbQuery() which runs SQL via a bound Session (or the default connection), returns rows as JSON capped at maxRows (with a truncated flag), and returns the engine error to the model instead of throwing. - chdb/ai-sdk (integrations/ai-sdk.mjs): wraps the core in the Vercel AI SDK tool() shape (description + zod inputSchema + execute). - chdb/mastra (integrations/mastra.mjs): wraps it in Mastra createTool() (id, description, input/output zod schemas, execute; tolerant of the .context input shape). Authored as ESM (.mjs + .d.mts) because both frameworks are ESM-only, which also avoids a CJS-requiring-ESM break; exposed as the chdb/ai-sdk and chdb/mastra subpaths. ai, @mastra/core, and zod are optional peer dependencies. Tests: AI SDK adapter verified end to end (builds a valid tool; execute runs SQL and returns rows; a bad query returns a typed error string). Full v3 suite green. ChDBStore (a Mastra storage adapter) is intentionally deferred — MastraStorage is a large, version-sensitive surface that deserves its own pass. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Contributor
Author
|
@chibugai, review it |
There was a problem hiding this comment.
Pull request overview
Adds first-class “agent tool” integrations for running ClickHouse SQL via chDB in two ESM-only TypeScript agent ecosystems (Vercel AI SDK and Mastra), sharing a single framework-agnostic executor to keep behavior consistent.
Changes:
- Introduces a shared
runChdbQuery()core (description + execution semantics) and two thin adapters (chdb/ai-sdk,chdb/mastra). - Exposes the adapters via new subpath exports and adds optional peer deps (
ai,@mastra/core,zod). - Adds a Vitest integration test covering the AI SDK adapter end-to-end.
Reviewed changes
Copilot reviewed 7 out of 8 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| test/v3/integrations/ai-sdk.test.ts | Adds an end-to-end test for the Vercel AI SDK tool wrapper. |
| integrations/chdb-tool-core.mjs | Introduces shared tool description and runChdbQuery() executor used by both adapters. |
| integrations/ai-sdk.mjs | Adds the Vercel AI SDK tool() adapter wrapper. |
| integrations/ai-sdk.d.mts | Adds type declarations for the AI SDK adapter subpath. |
| integrations/mastra.mjs | Adds the Mastra createTool() adapter wrapper. |
| integrations/mastra.d.mts | Adds type declarations for the Mastra adapter subpath. |
| package.json | Adds ./ai-sdk and ./mastra exports, files whitelist entry, and optional peer/dev deps. |
| package-lock.json | Updates lockfile for new deps and version metadata. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+33
to
+36
| const { session, maxRows = 1000 } = opts | ||
| if (typeof sql !== 'string' || sql.trim() === '') { | ||
| return { rows: [], rowCount: 0, truncated: false, error: 'sql must be a non-empty string' } | ||
| } |
Comment on lines
+38
to
+47
| const res = await (session | ||
| ? session.queryAsync(sql, { format: 'JSON' }) | ||
| : queryAsync(sql, { format: 'JSON' })) | ||
| // ClickHouse 'JSON' format: { meta, data, rows, statistics }. | ||
| const parsed = res.json() | ||
| const data = Array.isArray(parsed?.data) ? parsed.data : [] | ||
| const truncated = data.length > maxRows | ||
| return { | ||
| rows: truncated ? data.slice(0, maxRows) : data, | ||
| rowCount: typeof parsed?.rows === 'number' ? parsed.rows : data.length, |
Comment on lines
+3
to
+4
| // @ts-expect-error - .mjs adapter has a sibling .d.mts; vitest resolves the runtime file | ||
| import { chdbQueryTool } from '../../../integrations/ai-sdk.mjs' |
Comment on lines
+18
to
+20
| /** Build a Vercel AI SDK tool that runs ClickHouse SQL with chDB. */ | ||
| export function chdbQueryTool(opts?: ChdbToolOptions): unknown | ||
| export default chdbQueryTool |
Comment on lines
+18
to
+20
| /** Build a Mastra tool that runs ClickHouse SQL with chDB. */ | ||
| export function chdbQueryTool(opts?: ChdbToolOptions): unknown | ||
| export default chdbQueryTool |
Comment on lines
65
to
75
| "devDependencies": { | ||
| "@types/node": "^20.14.0", | ||
| "ai": "^7.0.2", | ||
| "apache-arrow": "^21.1.0", | ||
| "chai": "^4.5.0", | ||
| "mocha": "^10.7.3", | ||
| "node-gyp": "^9.3.1", | ||
| "typescript": "^5.5.0", | ||
| "vitest": "^2.0.0" | ||
| "vitest": "^2.0.0", | ||
| "zod": "^4.4.3" | ||
| }, |
|
Reviewed — OCR deep pass (opus-4-8, 5 source files) plus a manual read of the core and both adapters. No correctness or safety issues found; looks good to me. What I specifically checked and was happy with:
One non-blocking design note, just for awareness: the tool deliberately hands the model the full SQL surface, including table functions that reach external hosts and embed credentials ( |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Lets an agent run ClickHouse SQL with chDB as a first-class tool in the two main
TypeScript agent frameworks, over one shared executor so behavior is identical.
integrations/chdb-tool-core.mjs— framework-agnostic core: a shared description(the chDB engine plus the table functions it can reach: file/s3/url/postgresql/
mysql/mongodb/remoteSecure) and
runChdbQuery(), which runs SQL via a boundSession(or the default connection), returns rows as JSON capped atmaxRows(with a
truncatedflag), and returns the engine error to the model instead ofthrowing.
chdb/ai-sdk(integrations/ai-sdk.mjs) — the core in the Vercel AI SDKtool()shape (description + zodinputSchema+execute).chdb/mastra(integrations/mastra.mjs) — the core in MastracreateTool()(id, description, input/output zod schemas, execute; tolerant of the
.contextinput shape).
Authored as ESM (
.mjs+.d.mts) because both frameworks are ESM-only, whichalso avoids a CJS-requiring-ESM break; exposed via the
chdb/ai-sdkandchdb/mastrasubpath exports.ai,@mastra/core, andzodare optional peerdependencies.
Tests
AI SDK adapter verified end to end (builds a valid tool;
executeruns SQL andreturns rows; a bad query returns a typed error string). Full v3 suite green.
Not included
ChDBStore(a Mastra storage adapter) is intentionally deferred —MastraStorageis a large, version-sensitive surface that deserves its own pass.
🤖 Generated with Claude Code