ディレクトリ構成
このリポジトリが何をどこに置いているか。アプリ本体、データ変換、検証ツール、 エージェント運用の4系統に分けて示します。構成図で示した設計が、実際のどのファイルに対応するかを追えるようにするページです。
全体像
retail-ai-ops-copilot/
├── retail_ai_ops/ アプリ本体。質問の振り分けから回答生成まで
│ ├── agent_orchestrator.py 正式なルーティング所有者
│ ├── planner.py 質問の意図分類
│ ├── clients.py Snowflake 接続と実行
│ └── trace.py 実行の証跡記録
├── streamlit_app/ 対話画面。Streamlit in Snowflake で常設
│ └── app.py 質問欄と証跡タブ
├── dbt/ データ変換。staging → intermediate → mart
│ ├── models/ SQL モデル 9 本
│ ├── seeds/ KPI 定義の種データ
│ └── tests/ データ品質テスト 113 件
├── semantic/ Semantic View 契約。自然言語と列の対応
├── sql/ 環境構築用 SQL。新アカウントでの再現手順
├── config/flow-engine/ レビュー観点とテストパターンの正本(JSON)
├── tools/ 決定論チェッカー群。LLM より前に機械が落とす
├── tests/ Python / Node のテスト
├── docs/ 公開面。構成図・観点一覧・本ページ
├── .agent-feedback/ エージェント運用の記録台帳
├── ops/ 実行前提の宣言(doctor が検査)
└── .github/workflows/ CI。push ごとに契約と品質を検証
4つの系統
アプリ本体 runtime
retail_ai_ops/ · streamlit_app/
自然言語の質問を受け、意図を分類し、SQL を生成して実行し、根拠つきで回答します。ルーティングの所有者は agent_orchestrator.py で、画面はそこを直接呼びます。
データ変換 data
dbt/ · semantic/ · sql/
サンプルデータを段階的に整形し、KPI マートまで組み上げます。列の意味と再集計の制約は Semantic View 契約が持ち、自然言語からの参照先になります。
検証ツール gate
tools/ · tests/ · ops/ · .github/
契約違反・秘密値の混入・図の破綻・日本語の不自然さを、判断の前に機械が落とします。LLM のレビューはこの層を通過したものだけを見ます。
運用と記録 docs
docs/ · .agent-feedback/ · config/flow-engine/
レビュー観点とテストパターンの正本、実行の教訓、公開用の説明面。エージェントが毎回読み、判断の根拠として参照します。
主要ディレクトリの詳細
| 場所 | 区分 | 役割と、そこにある理由 |
|---|---|---|
retail_ai_ops/ |
runtime | アプリの中核。agent_orchestrator.py が唯一のルーティング所有者で、構造化 KPI 質問は Cortex Analyst、方針・文書の質問は Cortex Search へ振り分けます。機微情報の要求は実行前に停止し、外部送信は承認待ちで止めます。copilot.py は旧経路の互換用の別名だけを残しています。 |
streamlit_app/ |
runtime | 質問欄と、回答の根拠を開くタブ(経路・生成 SQL・実行結果・引用・証跡)。Streamlit in Snowflake 上に常設し、ログイン付きの固定 URL から最新 main と同じ内容を確認できます。 |
dbt/ |
data | staging・intermediate・mart の3層。月次 KPI マートは粒度・一意性・率の計算(ゼロ除算時は null)・再集計の禁止をテストで固定しています。実際の warehouse 上で build と test が通ることを確認済みです。 |
semantic/ |
data | 自然言語の語と列・指標の対応、および答えられない質問の境界。ここが曖昧だと回答が静かに間違うため、契約として固定しています。 |
sql/ |
data | 新しいアカウントで環境を一から作り直す手順。warehouse の設定値には、過去に起きた障害の対処理由をコメントで残しています。 |
config/flow-engine/ |
gate | レビュー観点(19 件 + 表示用の別名 4 件)とテストパターン(23 件)の正本。変更されたファイルのパスから発火する観点が機械的に決まり、該当が 0 件なら実行を止めます。表示用の HTML はこの JSON を参照する側で、内容のずれは検査で落ちます。 |
tools/ |
gate | 決定論チェッカーの集合。dbt の静的契約、公開面と実体の一致、図の接続と可読性、秘密値の走査、日本語の不自然さ、証跡パスの妥当性。判断を要しない検査をここに集め、LLM に渡す前に落とします。 |
ops/ |
gate | 実行前提の宣言。必要なコマンド・環境・認証の所在を機械可読で持ち、doctor が着手前に検査します。環境差による失敗を、作業の途中ではなく開始前に出すための仕組みです。 |
docs/ |
docs | 公開する説明面。構成図2種、レビュー観点、テストパターン、標準準拠マップ、実装レポート、そして本ページ。実装との乖離は検査で検出し、乖離のまま公開しない運用です。 |
.agent-feedback/ |
docs | エージェント運用の台帳。実行中に踏んだ障害の根本原因と恒久対策を残し、次のセッションが同じ罠を踏まないようにします。セッションは使い捨てでも、知識は残す設計です。 |
設計の要:
判断が要らない検査は
tools/ と .github/workflows/ の機械側へ、
判断が要る検討は LLM のレビュー側へ、と分けています。
観点とテストパターンを config/flow-engine/ の JSON に置いているのは、
「どの変更にどの観点が発火するか」を人の記憶ではなく宣言で決めるためです。