01
listSources
実行しない
各ソースのフィールド、型、行数、および数値フィールドがサポートする演算を返す。3段階の詳細モードにより、ソースが増えてもトークンコストを一定に保つ。
sum · avg · count · min · max · eq · in · gt · gte · lt · lte · is_null · is_not_null
Vercel AI SDK 向け
ガバナンス準拠のデータツール Vercel AI SDK 向け。
sqai.tools() は読み取り専用のツールをちょうど 3 つ generateText に追加します。モデルはソースを探索し、型付きプランを 1 件送信し、決定論的エンジンが算出した数値を返します――すべての回答を再現できるハッシュ付きで。
開始に API キー不要AI SDK Tools Registry 掲載済みai ^7.0.0 · zod ^4.0.0 · Node ≥ 20
IIインストール
依存関係は 1 行。
サーバーサイド専用、Node 20 以降。Next.js では runtime = \"nodejs\" を指定したルートハンドラで実行してください。ピア依存は ai ^7.0.0 と zod ^4.0.0 — プランの型付けに使用するバージョンです。アカウント・キー・設定ファイルは不要です。
IIIクイックスタート
最初のガバナンス準拠の回答。
import { generateText, isStepCount } from 'ai';
import { createSQAI } from '@thyn-ai/sqai-ai-sdk';
const sqai = createSQAI({
sources: [{ name: 'orders', path: './orders.csv' }],
});
const { text } = await generateText({
model: 'anthropic/claude-sonnet-4.5',
tools: sqai.tools(),
stopWhen: isStepCount(12),
prompt: 'Total revenue in the east region?',
});createSQAI() は遅延接続です――最初のツール呼び出しまで何も読み取りません。sqai.tools() は型付きの SqaiToolSet を返すため、キャストは不要です。isStepCount(12) により、モデルが探索・計画・実行を行う余地が確保されます。
ソースを追加するだけ。グルーコードは不要。
CSV、JSON、インメモリレコード、SQLite はプロセス内で動作し、サーバーの外にデータは出ません。Postgres、Snowflake、BigQuery などはエンジン経由で接続します。すべてのソースは同一の型付き形式に統一されるため、ツールから見れば CSV と Snowflake の区別はありません。 全ソース一覧と仕様 →
const sqai = createSQAI({
sources: [
{ name: 'orders', path: './orders.csv' },
{ name: 'sessions', provider: 'sqlite',
path: './app.db', table: 'sessions' },
{ name: 'quotes', records: quotes },
],
});すべてのオプションは絞り込みのみ。
切り捨ては必ず明示される。部分的な行が表示されることはない。モデルが入力するツール入力には allowed* フィールドが存在しない — ポリシーは createSQAI() 時に固定され、実行前にプロセス内で検証される。モデルは与えられた権限を拡張できない。 ガバナンスモデルの全容 →
const sqai = createSQAI({
sources,
allowedSources: ['orders'],
allowedFields: { orders: ['region', 'revenue'] },
allowedFunctions: 'all-readonly',
defaultLimit: 100,
maxRowsToModel: 25,
});オプションデフォルト効果
sources必須ツールが参照できる唯一のデータ。一度登録したソースは不変です。
allowedSources登録済み全件プランがアクセスできるソースを絞り込みます。
allowedFields全フィールドソースごとのカラム許可リスト。それ以外は不可視です。
allowedFunctions"all-readonly"ケイパビリティ許可リスト――絞り込み専用。より広い範囲を指定すると unsupported_operation がスローされます。
defaultLimit100プランが上限を指定しない場合に返される行数。
maxExecutionRows1,0001 回の実行で読み取る行数のハード上限。
maxRowsToModel25モデルに提示される最大行数。
maxCellsToModel250モデルに表示されるセル数の上限。
maxBytesToModel32,000モデルに表示される結果のバイト数の上限。
IVツールボックス
ツールは、ちょうど3つ。
探索、実行、リハーサル — それぞれ1つのツール。インターフェースが知らぬ間に膨らむことはない。
02
queryData
唯一実行するツール
型付きプラン — 判別共用体、実行前に検証済み — を1つ受け取る。結果は4種類、例外は発生しない。答えが「否」であっても、ループには必ず構造が返る。
kind: "query" | "computation" · version: "1"
ok · needs_clarification · rejected · error
03
explainQuery
ドライラン
データに触れることなく、プランを検証・解決する。返される invocation_hash は実行されるであろう内容のプレビューであり、実行済みのハッシュではない。
invocation_hash = preview ≠ executed
V1回の実行、そのまま
実際の実行から得た実際の数値。
generateText · プロンプト1件 · ツールステップ3回
ユーザー
東部地域の総収益と、割引率10%での収益スケジュールのNPVは？
ツール
listSources()orders · 12行 · region, revenueツール
queryData({ kind: "query", version: "1", … })sum(revenue) · region = "east"ok · 2130.50 · 5件の注文plan_hash f87610d8afeb…ツール
queryData({ kind: "computation", version: "1", … })finance.npv · rate 0.1 · values ← orders.revenueok · 3188.17 · 0.83 msアシスタント
東部地域の収益は5件の注文で合計2,130.50。割引率10%での収益スケジュールのNPVは3,188.17。
モデルは一切の計算を行っていない。両数値は決定論的エンジンから得られたものであり、ハッシュによって再現可能だ。
VI汎用ツールとの比較
型付きプランは、ぶれない。
汎用 SQL ツールsqai.tools()
モデルが生成するもの汎用 SQL ツール生の SQL 文字列sqai.tools()型付きプラン1件 — kind「query」または「computation」、version「1」、zod 検証済み
不正な呼び出し汎用 SQL ツール例外、リトライ、またはサイレントな無操作sqai.tools()選択肢付きの needs_clarification を返す — ツールは例外を発生させない
同じ質問を2回汎用 SQL ツール異なる SQL、異なる答えsqai.tools()同じプラン、同じハッシュ — 再現可能
書き込みパス汎用 SQL ツール接続が許可するすべてsqai.tools()構造上、存在しない — 4,574件の読み取り専用ケイパビリティ、モデルから到達可能な抜け穴なし
証明汎用 SQL ツールなし — もっともらしい数値のみsqai.tools()すべての回答に plan_hash と computation_hash
左側の障害モードは、想像ではなく記録されたものだ： vercel/ai #1905 · #2147 · #12020 · #6913
ツールボックスを出荷する。
API キー不要。アカウント不要。最初のツール呼び出しからすぐに動く。
AI SDK Tools Registry 掲載 · ai ^7.0.0 · zod ^4.0.0 · Node ≥ 20 · サーバーサイド