仕組み

モデルが提案する。
SQAI が処理する。

エージェントは SQL を書かず、実行コードも出力しない。型付きリクエストを書く——そしてすべてのリクエストは同じ経路を辿る。固定されたコントラクトに対して検証され、ポリシーに照合され、決定論的エンジンで実行され、再現可能なハッシュとともに返される。

ask()、compute()、AI SDK ツール呼び出しのいずれも、同じ経路を通る。すべてのチェックが通過するまで、エンジンには何も触れない。

01型付き意図

エンジンが解析できるリクエスト。信頼に頼る文字列ではない。

モデルが出力するのは型付きオブジェクトであり、SQL でもコードでもない。クエリ意図は QuerySpec——名前付きソースに対して集計するメトリクスを指定する。計算意図は ComputationSpec——コントラクトに定義された名前付き関数と、その引数およびバインディングを指定する。判別ユニオン一つ、形状は二つ——そのどちらにも、実行可能な文字列が潜む余地はない。

これが記述面のすべてだ。形状が表現できないものは、モデルも要求できない。

QuerySpec構造
{
"kind": "query",ユニオンタグ — query または computation
"version": "1",スペックバージョン（固定）
"source_name": "sales",接続済みソース（正確な名前で指定）
"metric": "revenue",集計対象のカラム
"aggregation": "sum",sum · avg · count · min · max のいずれか
"group_by": "region"省略可 — フィールドで結果を分割する
}

こちらも省略可filter · limit · order

計算の形状module · function · args · kwargs · bindings · seed?

02コントラクト検証

ハッシュ固定の単一コントラクト。未知の操作は案内とともに拒否される。

スペックはケイパビリティコントラクトに対して検証される——すべての操作、その正確なシグネチャ、決定論フラグを列挙した、生成済みのハッシュ固定ファイルだ。ケイパビリティに到達できるのは、読み取り専用かつ決定論的である場合、またはシード付きで決定論的である場合に限られる。書き込み可能な操作と非決定論的な操作は実行時にブロックされるのではなく、そもそも記述面に生成されない。

未知の関数は unsupported_operation として失敗し、同じインデックスから nearest_matches を返す——モデルはループせず、自己修正する。

ケイパビリティコントラクト

contract_hashsha256:79f1c5a6c7164e7e9e1750e70a5c03292fa87eb52d8148a740c06695924be9a1

4,778
コントラクトに列挙された操作
4,574
SDK に公開済み（読み取り専用）
4,564
完全決定論的
10
シード必須のシミュレーション
204
記述面から除外

適格条件read_only && (deterministic || deterministic_when_seeded)

未知の名前に対してunsupported_operation + nearest_matches

03ポリシー検証

実行の可否と方法は、あなたの許可リストが決める。

ポリシーは createSQAI() がインスタンスを構築する時点で固定され、何かが実行される前にプロセス内で適用される——ソース、すべてのメトリクス・グループ・フィルタ・バインドカラム、そして関数名に対して。ポリシーはコントラクトを狭めることしかできない。適格な記述面の外にあるケイパビリティを指定しても、unsupported_operation がスローされる。

モデルのツール入力には allowed* フィールドが存在しない。リクエスト内のいかなる要素もアクセスを拡張できない——プロンプトインジェクションが拡張できるものも、したがって存在しない。

allowedSourcesモデルが指定できるソース

  • "sales"

allowedFieldsソースごとに読み取れるカラム

  • sales.region
  • sales.revenue
  • sales.order_date

allowedFunctionsデフォルト — 読み取り専用のケイパビリティのみ、それ以上はない

  • "all-readonly"

拒否は明確・帰属明示・最終決定

  • policy_denied_source
  • policy_denied_field
  • policy_denied_function

source: "sqai" · 再試行不可

04決定論的エンジン

実行前に固定済み：float64、シングルスレッド、単一ランタイム。

まずバインディングが解決される。モデルがソースとフィールドを指定すると、SQAI はエンジンの行整列プリミティブ extractColumns を通じて実際の値を取得し、null はペアワイズで処理する。SQAI が自ら配列を zip することはない——ハッシュ化される入力は、実行された入力と完全に一致する。

ここで初めてリクエストがエンジンに触れる。ランタイムは署名・バージョン管理・固定済みだ：float64 精度、シングルスレッド。初回の compute() でのみ約 110 秒かけてプロビジョニングされ、以降は常駐する——finance.npv のウォーム計測は 0.83〜0.93 ms。

決定論エンベロープ
runtime_bundle_version0.1.0
runtime_bundle_sha2564d64142e4c1ff63d299cfc8b172fdf97cb59169b545e1e02978e678a632ce6e1
platformdarwin
architecturearm64
precision_modefloat64
thread_count1
seed—
input_hash2ea5ede72acd2912fe9e1230cef34afad4c9436bfa8a709bac2da02b478e3212

すべての結果とともに記録される——エンベロープは保証の範囲を過大申告せず、正確に示す。

05回答と出所情報

2つのハッシュ。実行前に1つ、実行後に1つ。

invocation_hash は実行前に刻印される——モジュール、関数、引数、解決済みバインディング、シード、コントラクト、スコープを対象とする。computation_hash は実行後に刻印される：invocation_hash と正規化された結果を合成したものだ。再現とは、再実行してバイトを比較することを意味する。

両 SDK は単一の正規シリアライザを共有するため、同じ計算は TypeScript と Python でバイト同一のハッシュを生成する。クエリの回答も同じ規律に従う：正規化された解決済みプランに対する plan_hash、決定経路、そして実行されたスコープが付与される。

3188.1687606249325finance.npv · ライブカラムにバインド済み · ウォーム 0.83 ms

実行前に刻印

invocation_hash

8223a694250fc751fcf8a7777b8e1f524c44ff1f0e7e83451467f554a6123950

モジュール · 関数 · 引数 · 解決済みバインディング · シード · コントラクト · スコープ

実行後にスタンプ

computation_hash

ff5280ea128113f528dd1e9a28b9bc4a81469075ed7c981c7176fb172d98085d

呼び出しハッシュと正規化された結果を合成したもの

TypeScript と Python で完全に同一 — 一方の言語で算出した結果は、もう一方でそのまま再生・検証できる。

両者を照合する対象contract_hash sha256:79f1c5a6…

クエリプレーン上でplan_hash f87610d8afeb…decision_path "exact_spec"deterministic_scope "local_registered_source"

06ディスカバリーループ

推測しない。発見し、ドライランし、それから実行する。

フィールド名と関数シグネチャは発見されるものであり、幻覚ではない。AI SDK が公開するツールはちょうど三つ — そのうち実行するのは一つだけだ。

  1. 01listSources()

    何に触れられるか？

    接続済みのソース一覧。正確なフィールド名・型・フィールドごとに許可された操作を含む。実行はしない。

  2. 02listSources({ capabilitySearch: "npv" })

    何を計算できるか？

    同じツールで決定論的カタログを検索 — 一致するモジュール、正確なシグネチャ、シードの要否を返す。

  3. 03explainQuery({ … })

    実行できるか？

    ドライラン。解決済みプラン・信頼度・プレビュー用 invocation_hash を返す — あくまでプレビューであり、実行済みハッシュではない。

  4. 04queryData({ … })

    実行する。

    実行する唯一のツール。結果と完全な来歴を返す。サイズ超過の結果は result_id で取得可能。

ツールは例外を投げない — すべての結果は型付きで返るok · needs_clarification · rejected · error

仕組みをフィールド単位で。

ドキュメントを読む →