nimble-databricks-data-products

Databricks 上の Nimble — データプロダクトビルダー

pricing analysis on dog products from walmart and amazon のような自然言語の概要を、動作する Databricks データプロダクトに変換します： エージェントを発見 → ライブのウェブ検索データを Delta に取り込む → ダッシュボードやアプリを構築 → リンクを提供。 手軽なデモにも、実用的で再利用可能なデータプロダクトにも対応します。

オーケストレーションはあなたが担当します。Databricks の操作は公式の databricks-* スキルに委任します（references/databricks-skills.md を参照）。このスキルが担当するのは、Nimble との連携部分と不足部分 （エージェントの発見、エージェントからの取り込み、AI/BI ダッシュボード JSON、ブランディング）です。

基本ルール

• 決めつけずに発見する。 エージェント名は nimble_agent_list()、入力パラメーターは nimble_agent_describe('<agent>') で確認し、出力フィールドは 1 回呼び出して調べます（to_json(parsing[0])）。 記憶を頼りにハードコードしないでください（Amazon 検索では query ではなく keyword を使用します）。
• 複数に展開する前に調べる。 まず各ソースで 1 回ずつ呼び出し、ローカライズフラグ、フィールド名、 値の形式を確認します。ソースによって異なります（数値の価格を返すものもあれば、通貨文字列を返すものもあります）。
• Statements API の呼び出し 1 回につき、ステートメントは 1 つ。 1 回の呼び出しに複数の ; 区切りのステートメントを含めると、解析エラーになります。
• Bash の呼び出しごとに新しいシェルが起動します。 環境変数や cd の内容は引き継がれないため、インラインで設定してください。references/preflight.md を参照してください。
• まず迅速に失敗を検知し、その後に確認する。 最初に Phase 0 の事前確認を実行し、ウェアハウスと書き込み可能なスキーマを推奨してから、書き込み前に確認を取ります。
• 必ず成果物を確認する。 テーブル、テーブル + ダッシュボード、テーブル + ダッシュボード + アプリのどれにするかは、実行ごとに選択します。
• ブランディングは常に適用し、中立的にする。 「Powered by Nimble」+ ライトテーマ + 黄色のアクセント。references/branding.md を参照してください。
• 成果物はそのまま残す。 後片付けはしません。
• 作業内容と要点を示す。 最後に URL と、一文でまとめたインサイト（例：価格差）を提示します。

ワークフロー

作業を漏らさないよう、これらを todo として管理してください。

Phase 0 — 事前確認（読み取り専用、迅速に失敗を検知）

一般的なチェックには databricks-core スキルを活用してください。

1. databricks current-user me → 認証を確認し、ユーザー名を取得します（デフォルトスキーマに使用）。
2. RUNNING 状態の SQL ウェアハウスを探します：databricks warehouses list。すでに RUNNING のものを優先し、なければ起動を提案します。
3. インテグレーションの確認 — 以下が存在することを確認します： nimble_integration.tools.{nimble_search, nimble_extract, nimble_agent_run, nimble_agent_list, nimble_agent_describe}。 簡易チェック：databricks functions list nimble_integration tools。 見つからない場合 → STOP し、references/install-nimble-integration.md （Nimble クックブック）を使ってユーザーを案内します。自動インストールは試みないでください。
4. ターゲットを推奨して確認する： ウェアハウスと、書き込み可能な catalog.schema （デフォルトは users.<username>）。書き込み可能であることを確認します。一部の共有カタログでは CREATE TABLE が許可されていません。 推奨内容を提示し、書き込み前にユーザーが確認または変更できるようにします。

詳細と正確なコマンド：references/preflight.md。

Phase 1 — 概要を解釈して確認（AskUserQuestion）

概要を次の要素に分解します：ドメイン／対象 · 検索語 · ソース · 分析目標。 次に、1 回の AskUserQuestion 呼び出しにまとめて質問します：

• 成果物 — 必ず質問します：テーブル／テーブル + ダッシュボード／テーブル + ダッシュボード + アプリ。
• ソース — 該当すると判断したエージェントを確認します（例：Amazon + Walmart SERP）。
• 件数 — デフォルトは検索語 8～10 件、ソースごとに約 100 行以上。

概要の意図（「分析目標」）を維持してください。Phase 4 のテンプレートと要点は、これに基づいて決まります。

フェーズ 2 — エージェントを確認し、統一スキーマを設計する

references/nimble-agents.mdを参照してください。

1. SQL経由でnimble_agent_list()を実行し、ソース／ドメインのキーワードで絞り込みます。
2. 選んだ各エージェントについて、nimble_agent_describe('<name>')を実行し、入力パラメーターを確認します（必須項目、正確な名前、ローカライズ／ページネーションのフラグ）。出力フィールドはここではなく、§2.5のプローブで確認します。
3. source列と正規化されたコア（product_name, price, currency, rating, review_count, brand, url, …）を含む統一テーブルを1つ設計し、選んだエージェントが実際に出力するフィールドだけを残します。複数ソースの比較は、共通カラムを基盤とします。

フェーズ 3 — 取り込み（制御テーブル＋セットベースの呼び出しを1回）

SQLの全文はreferences/nimble-agents.mdを参照してください。キーワードごとのファイルではなく、制御テーブルを基準に取り込みを実行します。再現性があり、行を追加して再実行するだけで拡張できます。 0. まず各ソースにつき1回だけ呼び出してプローブします（早期に失敗を検出）。 一括実行する前に、各ソースにつきnimble_agent_runを1回実行し、ステータス、実際のフィールド名、ローカライズフラグ、価格を問題なく数値に変換できるかを確認します。これにより、Walmartクラスの想定外の挙動（ローカライズ、通貨記号付きの価格文字列、product_priceとpriceの違い）を、無駄な一括実行後ではなく約40秒で検出できます。効果が最も高い手順です。nimble-agents.md §2.5を参照してください。

1. 制御（クエリ）テーブル<schema>.<table>_queries（source、agent、keyword、params_json、localization、enabled）を作成し、（source × term）ごとに1行を登録します。params_jsonには、各エージェントの実際のパラメーター名（input_propertiesから取得）を使用します。ローカライズはエージェントごとに設定します（例：amazon_serpはtrue、walmart_serpはfalse）。
2. 統一結果テーブル（source列＋正規化されたコア＋raw VARIANT）を作成します。
3. 制御テーブルに対する相関LATERAL結合を使い、nimble_agent_run(q.agent, q.params_json, q.localization)を呼び出すINSERTを1つ実行します。/*+ REPARTITION(N) */ヒント（N ≈ enabledの行数。控えめな値にします。並列度が高いとAPIのレート制限に抵触する場合があります）を指定して、エージェントの呼び出しを並列実行します。長い単一のステートメントなので、bash scripts/ingest.sh <WH> ingest.sqlで非同期に実行します。
4. 制御テーブルと照合します（LEFT JOIN）。項目が見つからない検索語は空の結果を返し、相関LATERAL結合では空の行が除外されるため、すべてのソースが対象になっていることを照合して確認します。あるソースが0件の場合は、構築を進める前に、そのエージェントのローカライズフラグと型変換を再確認してください。診断の順序については、nimble-agents.md §6を参照してください。

フェーズ 4 — 成果物を作成する

一致したエージェントの vertical／entity_type に応じてテンプレートを選択します。

分野	ダッシュボード／アプリの形式
Eコマース（SERP/PDP/CLP）	KPI、ソース／キーワード別の掲載商品と平均価格、スポンサー付き掲載の割合、価格と評価の散布図、「開く」リンク付きの商品テーブル、複数ソースの場合は比較バー＋可能な範囲で商品単位の価格差
ソーシャル	アカウント／投稿別のボリュームとエンゲージメント、人気コンテンツのテーブル、「いいね」とフォロワーの分布
不動産	価格と平方フィートあたりの価格、所在地別の掲載物件数、寝室／浴室数の内訳
マップ／ローカル	平均評価、レビュー数、場所のテーブル
LLM／AEO	ソース／回答の有無、シェア・オブ・ボイス、引用のテーブル
フォールバック	KPI＋2 つのカテゴリ別棒グラフ＋生データのテーブル（任意の output_schema で動作）

比較の深さ（ハイブリッド）： 集計／カテゴリの比較は必ず作成し、さらに、ソース間の商品単位のマッチングも可能な範囲で試みます（ブランドと主要なトークンを正規化）。確度の高い一致がある場合は「同一商品の価格差」ビューを追加します。確度の高い一致がない場合は、集計比較を維持し、商品単位のマッチングの確度が十分でなかったことを記載します。

• ダッシュボード → scripts/build_dashboard.py を使用します（簡潔な仕様 → 有効な serialized_dashboard の作成と公開）。Lakeview 固有の注意点がすべて組み込まれています。仕様の形式とレシピについては references/dashboard-cookbook.md をお読みください。
• アプリ → references/app-cookbook.md に従います（スキャフォールドとデプロイは databricks-apps に委任し、Nimble 固有の SQL、ブランディング、数値文字列／ライトモードに関する注意点を追加します）。
• ブランディング → references/branding.md（常に適用します）。

フェーズ 5 — 検証、納品、共有

• ダッシュボードを公開するか、アプリが RUNNING であることを確認し、URL を取得します。
• 作成したものと主なインサイト（比較から得られた結論）を要約します。
• ダッシュボード／アプリのリンクの共有を提案します。Slack または Notion コネクターが利用できる場合は、そこへの投稿も提案します（Slack にはリンク＋主なインサイト、Notion には日付入りの短いページを投稿します）。提案は一度だけにし、しつこく勧めないでください。
• competitor-intel／company-deep-dive で明らかになったブランドのビジネス動向を調べる、または nimble-web-expert で一度だけさらに深くデータを取得するなど、関連スキルを使った次のステップを提案します。
• 追加のグラフ、商品単位のマッチング、テーマ設定、定期更新ジョブなどの変更を提案します。

参考資料一覧

• references/databricks-skills.md — 各フェーズで使用する公式の databricks-* スキル。
• references/install-nimble-integration.md — インテグレーションのゲートに失敗した場合のセットアップ。
• references/preflight.md — 認証、ウェアハウス、書き込み可能なスキーマの検出（正確なコマンド）。
• references/nimble-agents.md — 検出、スキーマのマッピング、取り込み SQL と注意点。
• references/dashboard-cookbook.md — Lakeview JSON のレシピとすべての注意点（正式な情報源）。
• references/app-cookbook.md — AppKit デモアプリの連携と注意点。
• references/branding.md — 「Powered by Nimble」、ロゴ、色。
• scripts/ingest.sh — 非同期のステートメント並列実行とポーリング。
• scripts/build_dashboard.py — 簡潔な仕様からダッシュボードを作成して公開します。
• assets/nimble-logo.png — アプリのブランディングに使用する Nimble のロゴ。