data serve tool (dst)

dstはあなたのデータウェアハウスをAIに提供し、そのライフサイクル全体にエンジニアリングのベストプラクティスをもたらします。 AIは自然言語で問いかけます。dstは、チームが書き留めた定義に基づき、回答を生成したSQL、信頼度グレード、そしてレシートを添付して回答します。

問題

• AIをウェアハウスに向けると、AIは何にでも答えます。AIは答えないという失敗をしません。そしてそれが失敗モードです。間違った回答は、回答がないことよりも悪いのです。

• それは「売上」が何を意味するかを推測し、返す数値は完全に正しい数値のように見えます。

• コンテキストだけではこれは解決しません。AIは非決定的であり、別のチーム、別のモデル、別の四半期でうまくいくものが、あなたにとってうまくいくとは限りません。

• 確かめる唯一の方法は、自分のデータで継続的にテストすることです。

解決策

• 宣言: データの提供方法を、バージョン管理下のファイルとして宣言します。

• テスト: 実際に自分たちに機能するものをテストします。承認された回答はどれも回帰テストとなり、パイプライ内のどのスイッチも入れ替えて再計測できます。

• デプロイ: 明示的に失敗するゲートを通過したものだけをデプロイします。

• 監査: 提供されたすべてを監査します。誰が問い、何が走り、何がコストだったか。すべてのミスが新しいテスとしてフィードバックされます。

実践者たちが実践者のために作られました。新しワークフロではなく、ファイル、プルリックエスト、CI、終了コードです。

テスト: エンジン

生成処理は本質的に非決定的ぶだため、dstはテスト後付しではなく、製品そのものとして扱います。

• 承認された回答はすべて回帰テストです。 証明された回答は、誰かが保証した質問→SQL ペアです。dst test は、実際の生成パイプライを通して同じ質問を再捉し、保存されたSQLと生成されたSQLの両方をあなたのウェアハウスで無理行し、結果を比較します。

• 動作も固定されます。 tests スイートは、evals/cases.yaml のケースで応答の シェイプ を検証します: expect: clarify | refuse | answer。回答可能な質問を拒否し始めたり、明確化をする代わりに推測し始めるレンズは、そのスイートを失敗します。

• すべての結果が記録されます。 テスト実行はデータベースに書き込まれるため、精度は動きを監視できる数値です。そしてデプロイはそこにゲートされます。前回の公開よりも良くない変更は既定されます。

パイプラインは該当するレンズごとに、いわっ提チューン可能です（回答のストリい厳しさ、自己修復、回答 unit のジャジャ、ゲートのき）硬。ど変数でも計測可能です。一つ変更して、dst test を実行すればわかります。また、あなたの質問 であれだけが成果をしているかを知りたい場合、同梱のプruービンググランrが機能をひとつずつを除いてパイプラインを実行します: python -m services.benchmark --data ./data --strip <feature>。調整可能な全体のサーフェスについては、configuration に配置 を参照してください。

Related MCP server: RunContext

デプロイ: ゲートを通して

レンズはファイルです。回答の意味を変えることは、編集ではなくデプロイです:

edit files → dst plan (dry run) → dst apply (gated, atomic)

dst plan は、変更が何をすかを表示し、apply がそれを拒否する場合には終了コード1で終了します。プランはアプを予測ます。dst apply は 1 つのトランザクションです。接続がプローブされ、常袋の証明済み回答がすべてライブ生成に再実行されます。いずれかの失敗が起こると なにも デプロイされず、実際に行われたバージョンが変わりません。

• バージョン: 公開 (publish) のたびにレンズのバージョンを「ムナップ" ショットし、dst lens log は、何がいつ誰によって（human:ana@corp / token:ci)管理されたか。ロールバックは git revert + dst apply です。

• environments は、試す場所です。 それぞれが別の dst です。あなたのノート PC、共有 サンドボックス、本番。サンドボックスを別のモデル、別の温度、別のテーブル、または別の B 代入えの定義に向けて、dst test を実行し、スコていを比較できます。サンドボックスの コスト はすでにあなたが実行しているサーバーで 1 回 dst bootstrap かぜん。デプロイは同じ git コミットを本番に適用することです。地方のあいだでコプロパティされることはなく、ファイルには環境ごとの同期する情報は含まれません。

• CI もあなたがやっているのと同じコマンドを実行します。 終了コードがインターフェースです。PR ジョブは dst plan を実行し、マージは dst apply --require-gates を実行し、スケジュールされたものは dst test --all と dst drift を実行します。実際に設定されている GitHub Actions の例は 環境とCI ガイド にあります。

監査: すべての回答に、価格付けされ、署名される

• レシート。 すべてのデータ回答には、ポータブルで HMAC 署名されたレシートがあります: リクエスト ID、レンズ、認定、そして、厳密な SQL のハッシュ。これは後で、API または verify_receipt MCP ツールを介して検証できます。拒否にはレシーがありません。データの主張をしていないからです。

• 記帳済。 dst observe は「誰がこれをどういう目的で使っているのか」に応えてくれます: すべての呼び出しについて、質問、SQL、結果、AI と ウェアハウス両方のメーター上のコストが記録されます。回答、拒否、エラーの別々に数えられます。制御された拒否は結果であり、エラーではありません。

• 許可・拒否の双方を記録できる。 すべての許可 と すべての拒否常時、呼び出し元、レンズ、理由とともに、追加専用の監査ログに記録されます。

• ウェアハウスは監視対象です。 dst drift は、ライブスキーマと、根拠となる baseの設定を比較し、変更ディーブルを参照する定義・エンティティとすべての変更を相互参照します。終了コード: 0 クリーン、2 変更あり、1 変更内容が「何か宣言されたものを壊す」、4 ベースラインがまだない。

• 疑念は第一級市民の入力です。 どの呼び出しも回答をレビューに送信できます。低信頼の回答は自分でフラグを立てできます (auto_review)。AIジャッジがフルのトレーを選択し、人間の裁定がrails、修正はファイルプラス新しいテスとして着地点し、そこでループがしまいます:

---
config:
  theme: base
  themeVariables:
    fontFamily: "ui-monospace, Menlo, monospace"
    fontSize: "14px"
    primaryColor: "#faf6ee"
    primaryBorderColor: "#b45309"
    primaryTextColor: "#292524"
    lineColor: "#b45309"
    edgeLabelBackground: "#faf6ee"
---
flowchart TD
    serve(["an answer is served,<br/>with its receipt"])
    doubt["someone doubts it"]
    test["it becomes a test:<br/>an approved answer + its check"]
    gate["it gates every deploy"]
    serve -- "flagged by the asker,<br/>or by dst itself" --> doubt
    doubt -- "AI drafts the fix,<br/>a person approves it" --> test
    test -- "commit + dst apply" --> gate
    gate -- "the corrected answer serves<br/>from then on, and the AI learns from it" --> serve

一度修正されたミスは、一度修正されグレードに戻り、それを証明できます: 修正された質問はその後、許可されたSQLでがサービスされ、そのテストは dst apply のたびに再実行されます。詳細: 修正ループへ

仕組み

レンズ: レンズは提供の単位のことです。ユースケース（例: 解約、営業歩合、ボード メトリクス）を共有のセマンティック アセットの選択として宣言し、アクセス権とじプライベートな時計を持ちます。エージェントはレンズに自然言語の質問をし、基盤のある、引用の付いた回答を受けるします。

セマンティック ファイル: エンティティとビジネス定義を、一度ファイルとして書提し、レンズがそれらを選択して共有します。一つの定義、一つのメトリクスであり、エージェントが仲買にした単語は変わりますが、意味は変わりません。

キュレーション済みコンテキスト: レンズが回答に活用できる、レビュー済みの定義文セット。各エントリは意図的であり、説明可能で、レンズとともにバージョン管理されます。

認定された回答: レビュー済みの質問→SQL ペアであり、一致した場合はそのまま直接提供され、dst test との dst apply の各回帰テストとして再び実行されます。修正されたミスはその 1つになり、それゆえ修理されたまま残ります。

ガバナンス: アクセス管理は、選択した方法で履行されます: 人やグループのためのレンズごとの許可リスト、呼び出し元ごとの API キー (dst_…)、レート制限、データベース（Postgres RLS）で実施するテナント分離。保存されたウェアハウスの資格情報は保存時にします。

観察: コすべての呼び出しがトレースされます。どのレンズ、どの呼び出し元、どの質問、SQL、AI と ウェアハウスのコスト、そして結果 (回答済み、拒否、エラー) を実現で分けて記録します。回答は レビュー に回すことができます: AIジャッジは推論トレースを監査し、必要なときに人間による審査にエスカレーションします。

エージェントこそがインターフェース

クエ UI はありません。消費者はエージェントです。あなたの使う MCP クライアント（Claude Desktop、Claude Code、Cursor、またはあなたの商品の中のエージェント）でも、統制された /mcp の MCP サーバーに、ただ URL をスコープ付きの dst_… キー瞪着れば接続できます (services/mcp/README.md)。すべての質問が同じ管理されたパイプラインを構造ので、どのエージェントが聞いた場合でも回答は同じです:

agent (Claude Desktop · Claude Code · Cursor · your product's agent)
        │  MCP — one scoped dst_… key per person
        ▼
   dst  ── lens: semantic model + context + access
        │   ground → SQL guard → execute → compose (cited)
        ▼
   your warehouse (BigQuery · Snowflake · Postgres · MySQL · DuckDB)
        │
   trace + cost + review  →  Observe

人間は、ループの中にいて、クエリパスの中たちいません。ダッシュボードは、ファイルが何を宣言指示しているかを把握し、状態を観察するためのコックピットです。レビューキと、ドリフトに行えるし、アクセス状況、コストが見られます。レンズは UI ではなく、ファイルとして作られいます (dst init → 編集 →plan/apply)。（REST で： (あなたのエージェントにデータを組み込むための REST 入口) API リファレンス もあります。

プロジェクトの様子

プロジェクトはファイルです: バージョン管理され、PR でレビュー、こうしたように適用されます。以下の内容は dst init が生成するものから軽く情報を除してあります (examples/ 以下にあるデモのだからこのフォルダごと削除可能ですが、で dst init は、それをど it also の下に生成します。デモ レンズは lenses/customer_value/にあります):

name: orders
description: One row per order.
source:
  connection: jaffle
  table: orders
default_time_field: order_date
primary_key: [order_id]
fields:
  - {name: order_id,    type: integer}
  - {name: customer_id, type: integer}
  - {name: order_date,  type: date}
  - {name: status,      type: string}
  - {name: amount,      type: number, description: Order total (USD).}
metrics:
  - {name: revenue,     agg: sum,   expr: orders.amount, format: currency}
  - {name: order_count, agg: count, expr: orders.order_id}
  - name: average_order_value
    type: ratio
    numerator: revenue
    denominator: order_count
    format: currency
joins:
  - {right: customers, on: customers.customer_id = orders.customer_id,
     type: left, relationship: many_to_one}

定義は、ビジネス用語を SQL にバインドします:

---
metric: repeat_customer
sql: customers.number_of_orders > 1
---

A repeat customer has number_of_orders > 1.

そして あいまい な定義の場合は、推測せずに dst は明確化(cra)を委ねせます。

---
metric: value
status: ambiguous
possible_mappings:
  - lifetime value — customers.customer_lifetime_value
  - order amount — orders.amount
---

必要なのはマッピングだけです。生成される前に、マッピングから、ist がコードで明確 it を構築します。

name: customer_value
description: Customer lifetime value and order activity.
connections: [jaffle]
select:
  entities:
    - name: customers
    - name: orders
  definitions: [lifetime_value, repeat_customer, value]
model:
  temperature: 0.0
  answer_mode: balanced
instructions: Select explicit columns.
access:
  allow:
    - caller: alex        # deny-by-default; or `- group: everyone`
eval_gate: block          # a failing eval suite blocks the apply
auto_review: unverified   # low-confidence answers open review tickets

# Served VERBATIM on a match — and each one is a regression test:
# `dst test` re-asks the question and compares against this SQL's result.
- question: How many customers are repeat customers?
  sql: SELECT count(*) AS n FROM customers WHERE number_of_orders > 1
- question: What was total revenue?
  sql: SELECT sum(amount) AS revenue FROM orders

name: analytics

providers:
  anthropic:
    type: anthropic
    api_key_env: DST_API_KEY_ANTHROPIC
  # any openai-compatible endpoint works: deepseek, ollama, vllm, groq …

connections:
  jaffle:
    type: duckdb
    config: {path: fixtures/jaffle_shop.duckdb}
  wh:
    type: bigquery                  # or snowflake, postgres, mysql
    config: {project: my-gcp-project}
    secret_env: DST_API_KEY_WH      # an inline key is a parse error

$ dst query customer_value "How many customers are repeat customers?"
19 of the 100 customers are repeat customers.

sql: SELECT count(*) AS n FROM customers WHERE number_of_orders > 1
basis: A repeat customer has number_of_orders > 1.
confidence: verified · definition: repeat_customer

$ dst query customer_value "What is the average value of a customer?"
clarify: 'value' is ambiguous in this dataset — lifetime value (total
historical revenue per customer) or order amount (a single order's total)?
  - lifetime value — customers.customer_lifetime_value
  - order amount — orders.amount

拒否または明確化はエラーではありません: dst は推測するのではなく、聞くようにしています。

クイックスタート

パッケージをインストールします。前提条件: Python 3.12+、Docker (dst が独自の Postgres を動かすためです)、および最低 1 つのジェネレーター AI の API キー: Anthropic、または OpenAI 互換のエンドポイント (DeepSeek、Ollama、vLLM、Groq、そのたゆルせゲトウエ)

pip install dst-core            # the CLI is `dst`
dst init analytics --warehouse demo --yes
cd analytics                    # put your provider key in the generated .env
dst dev                         # Postgres up + migrate + serve, one command

# in a second terminal, same directory
dst bootstrap --org me --email you@example.com
dst apply
dst query customer_value "How many customers are repeat customers?"

dst init は、同梱の jaffle DuckDB ウェアハウスにプロジェクトを生成するので、実際のウェアハウスに続する前にも apply と query が動作します。公開された wheel にはマイグレーションクラウス (マイグレーコン) も台帳のダッシュッドも同梱されている dst dev を http://localhost:8000 で提供します。クイックスタート がメインのルートで、これをめて実際のウェアハウスに至れます。

ソースから実行する

コントリビューター向けの手順: リポジトリのチェックアウト、リポジトリ自身のMakefile、そしてバンドル版ではなくViteで構築するダッシュボードです。前提条件: 上記に加え、uv・Node 22+・pnpmです。

# 1. Backend deps
make install                 # uv sync

# 2. Configure — create .env in the repo root (see "Configuration" below)
echo 'DST_PROVIDERS={"anthropic": {"type": "anthropic", "api_key": "sk-ant-..."}}' > .env
# openai-compatible works the same:
#   {"ollama": {"type": "openai-compatible", "base_url": "http://localhost:11434/v1", "api_key": "unused"}}

# 3. Start Postgres (pgvector), run migrations, seed an org + admin token
make up
make migrate
make seed                    # prints a dstadm_… admin token — copy it

# 4. Run the API (http://localhost:8000)
make dev

次に、ダッシュボード:

cd apps/web
pnpm install
pnpm dev                     # http://localhost:5173

ダッシュボードを開いて、右上のdstadm_…管理トークンを貼り付けると、このorgを管理できます: レビューキューン、ドリフト監査、呼び出し元、コスト。レンズそれ自体はファイルとして作ります。uv run dst initは、同封のjaffle DuckDBウェアハウス上に雛形を作れるため、実のウェアハウスに接続する前でもuv run dst applyとuv run dst queryを試せます。ソースをチェックアウトしてもdstはPATHに入りませんし、uv run dst … はMakefileの対象と同じ、すべてのコマンドがuv run dst …として動きます。

エージェントにレンズをクエリさせるには: Settingsで呼び出し元キー（caller key）を発行し、それを lens.yaml のallow-listに追加し、uv run dst applyして、MCPでエージェントに接続します。

設定

設定は .env から読み込まれます（services/config.pyを参照）。主なキー:

ウエアハウスとコンチキストソースの認証情報は環境変数ではありません: dst.yaml の中で secret_env 参照として接続を宣言します（クイックスタート参照）。 .env.example は services/config.py から生成されるため、完全かつ常に最新の設定面を提供します。

プロジェクト構成

services/          FastAPI app (services.app:app)
  api/             control plane (/mgmt/*) + data plane (/v1/*)
  contracts/       lens config, semantic model, protocols
  connectors/      warehouse connectors
  context/         embedding providers + the serving error surface
  runtime/         the query pipeline (ground → guard → execute → compose)
  reviews/         AI-judge + human review queue
  governance/      access policy, credentials, rate limits, audit
  mcp/             remote + stdio MCP server (see its README)
apps/web/          React + Vite dashboard
migrations/        Alembic migrations
fixtures/          built-in jaffle DuckDB warehouse

開発

アーキテクチャー: Postgres + pgvector上のFastAPI（レンズ設定、コンチキストのベクタストア、リクエストトレース、レビュー）はウエアハウスから読み取り、結果セット自体は永続化されません。トレースが保持するのは、質問・SQL・合成された回答・その引用のみ。最初の数件の結果行は、レンズが logging.log_samples をオプシするとのみ保持されます。ウエアハウスのプロファイリングは、さらに列ごとの統計と低カーディナリティの値のリストを保存します。exclude_columns に指定した列は形状だけ読み取り、値を収集しません。dst は個人データを分類も述べも行いません。自分のネットワークの外に出したくない値の列は公開しないでください。ダッシュボードは、同一オリジンまたは分割型のReact SPA（シングルページアプリケーション）です。

ユーザー向けドキュメントはdocs/（クイックスタート、コンセプト、ガイド、リファレンス）で確認でき、https://www.dataservetool.comに公開されています。コントリビューター向けサブシステムマップはARCHITECTURE.mdです。

ライセンス

Apache-2.0。コントリビューション: CONTRIBUTING.md · 脆弱性情報: SECURITY.md · 問題や質問: github.com/get-dst/ddst/issues。