ai-ml-data-science

データサイエンスエンジニアリングスイート

モデルを選ぶ前に、意思決定と予測のタイムスタンプを明確にします。特徴量はスコアリング時点で利用可能でなければなりません。

クイックリファレンス

ニーズ	デフォルトの方針
再現可能な Python ワークフロー	uv とスクリプト、または Git で管理しやすいノートブック（リアクティブで差分を確認しやすいノートブックには marimo）
高速なローカル分析	DuckDB と Polars を併用します。古い例を応用する前に、インストール済みの API をPolars のドキュメントで確認してください
データコントラクト	データセットの境界で Pandera または GX Core を使用します
表形式データのベースライン	線形モデルまたはロジスティックモデルと、ツリーベースの候補を組み合わせます。表形式データ向け基盤モデルを追加するのは、references/modelling-patterns.md §3.1 でライセンスとサイズを確認してからにしてください
特徴量エンジニアリング	学習時とサービング時の安全性が明確な変換を使用します
ラベルのないテキストコーパス	埋め込み -> UMAP -> HDBSCAN -> c-TF-IDF の順に適用します。文書レベルのラベルが不要な場合は、トピックレベルの LLM ラベルを使用します
チューニング	ベースラインが安定してから Optuna を使用します
評価	スライス、閾値、キャリブレーション、不確実性
引き継ぎ	モデルカード、評価レポート、失敗モード、モニタリングの想定事項

このスキルを使う場面

• データセットを探索し、モデリングの実現可能性を確認するとき
• 特徴量パイプラインとリーク対策を設計するとき
• モデルファミリーを選択し、比較するとき
• タクソノミーやラベリングの取り組みがまだない段階で、ラベルのないテキストをクラスタリングし、トピックを見つけるとき
• 再現可能な実験ワークフローを構築するとき
• 評価レポート、モデルカード、引き継ぎ成果物を作成するとき
• 実験が本当に本番環境への引き継ぎ準備ができているか確認するとき
• 責任ある AI モデリングの仕組みについて説明するとき：公平性と交差性、プライバシー、解釈可能性、ポイズニング、記憶、人的監督、環境面でのトレードオフ
• 汎用マルチモーダルモデルを設計するとき：画像とテキストの対照学習、融合、VQA／ドキュメント／動画システム、拡散モデルの制御、適応、品質とレイテンシのトレードオフ

別のスキルを使う場面

• サービング、自動再学習、モニタリング、インシデント対応 -> ai-mlops
• 予測と時系列検証 -> ai-ml-timeseries
• レイクハウスまたはバッチ取り込みインフラストラクチャ -> data-lake-platform
• ストリーミングインフラストラクチャ（Kafka、Flink、CDC） -> data-streaming
• プロンプト設計、ファインチューニング、LLM システム設計 -> ai-llm または ai-rag

---

ワークフロー

1. モデルに取り掛かる前に、意思決定、ターゲット、ベースライン、予測のタイムスタンプを明確にします。
2. データセットの形状、所有者、リークのリスクを検証します。
3. 実現可能な範囲で最もシンプルなベースラインを最初に構築します。
4. 時点整合性のある特徴量を設計し、ベースラインの信頼性を確認してから、より強力な候補と比較します。
5. 同じ分割戦略、同じ指標定義、同じ計算予算で評価します。 グラフモデルでは、学習済み／時間的なトポロジー、自己教師あり事前学習、またはグラフの説明可能性を評価する場合に、graph-model-evaluation を読み込みます。その分割、ベースライン、健全性チェックの結果を記録してください。
6. 閾値、キャリブレーションの状態、失敗モード、再現性に関する注記を含む引き継ぎ成果物を作成します。

---

基本ルール

• 予測のタイムスタンプを明記します
• 時間またはエンティティのリークが起こり得る場合、ランダム分割を安易に信用しません
• 少なくとも1つのシンプルなベースラインを、より強力な候補1つと比較します
• 閾値設定、キャリブレーション、不確実性を意思決定の一部として扱います
• データのバージョン、特徴量のバージョン、シード、分割ロジックを再現可能な状態に保ちます
• サービング、再学習、モニタリングは ai-mlops に振り分けます

予測時点の適格性ゲート

すべての特徴量について、ソースイベント、イベント時刻、利用可能時刻、変換バージョン、エンティティ結合キーを記録します。宣言した予測タイムスタンプの時点で存在しない値は除外します。オフラインのバックフィルとオンラインサービングで異なる実装を使用できるのは、一致するエンティティとタイムスタンプを対象としたポイントインタイムテストで意味的な同等性が実証され、変換バージョンの系譜が保持され、本番環境の乖離が監視されている場合に限ります。残ったパイプラインを、意図した分割単位と判定しきい値で評価し、最もシンプルで実行可能なベースラインと比較します。予測アクション、棄却経路、偽陽性と偽陰性のコストが明確な場合に限り、モデルは意思決定に利用できる状態です。

既知の落とし穴

• 時間、エンティティ、世帯、アカウント、セッションのリークが起こり得るのに、ランダムな訓練／テスト分割を使う。
• 予測時点より後でしか利用できない情報を使って特徴量を構築し、その結果を「本番環境に対応済み」と呼ぶ。
• ベースラインと指標の定義が安定する前にモデルをチューニングする。
• しきい値の選択、キャリブレーション、スライスごとの挙動、運用上のトレードオフを無視し、AUCや単一の集計スコアだけを報告する。
• ノートブックの状態を実際のパイプラインロジックにしてしまう。隠れた実行順序やキャッシュされた状態により、再現性はすぐに損なわれます。
• 単独でほぼ完璧な分離を示す特徴量や、ドメインの専門家が不自然に高いと感じる指標は、まずリークのバグ報告として扱い、発見として扱うのはその後にします（references/eda-best-practices.md の「専門家の直感」を参照）。
• 繰り返し登場するエンティティには、デプロイに合った分割が必要です。未知のエンティティへの汎化にはグループホールドアウトを使います。時間分割では、同じエンティティを再度スコアリングする場合に過去のエンティティが保持されることがあります。いずれの場合も、特徴量の利用可能性を保証し、訓練フォールド内で前処理を適合させます。
• ライブラリのバージョン、ベンチマーク値、APIパターンを記憶や古いチュートリアルに頼って引用し、現在インストールされているバージョンで確認しない。表形式MLツール（Optuna、SHAP、scikit-learn、勾配ブースティング木ライブラリ）は、1年のうちに破壊的変更を伴うメジャーバージョンをまたぐことがあります。

パターンの選択

問題の形状	方針
表形式またはリレーショナル	ベースラインとツリーベースの比較
時系列予測	ai-ml-timeseries に移行
従来型のテキスト、または埋め込みと分類器	ここで対応
ラベルなしテキスト、未知のテーマ、トピックの発見	ここで対応。references/text-clustering-topic-modeling.md を参照
LLM ワークフロー、プロンプト、または RAG	ai-llm または ai-rag に移行
デプロイ、監視、再訓練	ai-mlops に移行
取り込みまたはレイクハウスアーキテクチャ	data-lake-platform に移行
責任あるAIの概念とモデリングのトレードオフ	ここで対応。運用上の制御は ai-mlops に、測定とレッドチーミングは ai-evals に移行
マルチモーダル表現、融合、VQA／文書／動画、拡散モデルの仕組み	ここで対応。本番運用と評価は ai-mlops と ai-evals に移行

---

コアパターン

再現可能なワークスペース

• uv と明示的な依存関係
• uv.lock をコミットし、CIで uv sync --locked を実行します。pandas 3.0 のコードでは、コピーオンライトと str dtype の変更によって挙動が変わります（references/eda-best-practices.md を参照）。
• スクリプト優先、またはGitに適したノートブックのエントリポイント。リアクティブでGit差分を確認できるノートブックを使う場合は、Jupyterの代替として marimo を検討してください。marimoはリアクティブ（依存するセルが自動再実行）で、ノートブックを通常のPythonスクリプトとして保存し、隠れた状態による実行順序の問題を解消します。
• 固定シードと明示的な分割ロジック
• データセットと特徴量に関する前提を記録

特徴量エンジニアリングと契約

• 数値、カテゴリ、テキスト、時間ベースの変換
• 時点整合性のある可用性チェック
• 再利用可能なエンコーダーと、文書化された鮮度に関する前提

評価と意思決定への準備

• 主指標とガードレール
• 閾値戦略
• キャリブレーションと不確実性への対応
• スライス分析と定性的なエラーのレビュー

自律的な実験

指標が明確で、探索空間が限定されており、各実行のコストが十分に低く、自動で採用または取り消せる場合に限り、エージェント主導の実験ループを使用してください。

---

テンプレート

• assets/project/template-standard.md
• assets/project/template-quick.md
• assets/features/template-feature-engineering.md
• assets/eda/template-eda.md
• assets/evaluation/template-evaluation-report.md
• assets/evaluation/template-model-card.md
• assets/review/experiment-review-template.md

スクリプト

スクリプト	目的
scripts/ml_toolkit.py	model-spec JSON からモデルカード、リークチェック、モデル品質レポートを生成します
scripts/leakage_scan.py	ML の特徴量／ターゲット列の仕様（JSON/JSONL）を対象とする静的リークスキャナーです。列メタデータから、時間リーク、ターゲットリーク、ID リークのアンチパターンを検出します。終了コード 0 はメタデータ上の指摘なし、1 は検出結果あり、2 は入力形式の不備または I/O エラーを示します。スコアリング時の適格性を検証するには prediction_time を設定してください。label_time のみを使う方法は、従来のより弱いカットオフです。

一般的な使い方：

python scripts/ml_toolkit.py card --input data/sample-model-spec.json
python scripts/ml_toolkit.py leakage --input data/sample-model-spec.json
python scripts/ml_toolkit.py report --input data/sample-model-spec.json --output report.md

ml_toolkit.py leakage と report は、時間カットオフがない場合も含め、WARN/FAIL で終了コード 1、無効な入力または I/O エラーで終了コード 2 を返します。静的チェックで PASS となった場合でも、引き継ぎ前に行単位の可用性と分割の検証が必要です。スキャナーは空でない target と columns を受け付けます。JSONL では各行に完全な仕様を 1 つ記述し、不正なレコードは拒否します。一致する ISO 時刻（タイムゾーンの扱いを統一）または記号形式の T±<integer><s|m|h|d> オフセットを使用してください。モデル仕様のフィールドについては、scripts/README.md を参照してください。

ナビゲーション

コアリファレンス

• references/eda-best-practices.md
• references/feature-engineering-patterns.md
• references/data-contracts-lineage.md
• references/modelling-patterns.md
• references/evaluation-patterns.md
• references/graph-model-evaluation.md — 範囲を限定したグラフ事前学習、説明、時間的評価、推定トポロジーの評価契約
• references/class-imbalance-patterns.md
• references/hyperparameter-optimization.md
• references/text-clustering-topic-modeling.md — モジュール式の embed/UMAP/HDBSCAN/c-TF-IDF パイプライン、表現モデルによる再ランキング、トピック単位（文書単位ではない）の LLM ラベリング、単純な k-means を優先すべき場合
• references/interpretability-explainability.md
• references/responsible-ai-mechanics.md — 公平性／交差性、差分プライバシー、説明可能性、ポイズニング／連合学習、再識別、ウォーターマーク、人間による監督／異議申し立て、著作権／記憶、環境面でのトレードオフ
• references/multimodal-modeling.md — CLIP/SigLIP の目的関数、融合、VQA／文書／動画システム、拡散モデルの制御／多様性／高速化、適応、レイテンシー、コスト
• references/reproducibility-checklist.md
• references/llm-data-pipeline.md — LLM の評価時に行う汚染チェック（Min-K% スクリーニング、汚染耐性のあるベンチマーク）。事前学習コーパスのキュレーション（重複排除、フィルタリング、汚染除去、混合）については、まず ai-data-curation-pretraining を参照してください
• references/feature-freshness-streaming.md
• references/production-feedback-loops.md
• references/ml-diagrams.md — 古典的な ML（k-means、ロジスティック回帰、決定木、協調フィルタリング）やニューラルネットワークのアーキテクチャ（MLP、RNN、CNN、Transformer）の Mermaid 図カタログ。ドキュメント、README、PR の説明への埋め込みに使用します

データと外部リファレンス

• data/sources.json
• data/sample-model-spec.json

関連スキル

• ai-architecture-advisor — 木モデル、ディープラーニング、LLM のどれを使うか（構築前に決定します）
• ai-mlops
• ai-ml-timeseries
• data-lake-platform
• ai-llm
• ai-rag
• huggingface-datasets — 現在は外部の huggingface-skills: プラグインにあります

学びのループ

過去の決定や落とし穴が関連する場合は、存在すれば learnings.consolidated.md を参照してください。必要な履歴がある場合、または利用可能な代替手段としてのみ learnings.md を使用してください。それ以外の場合は、どちらも参照しないでください。

適用後、記録しておく価値のあるパターン、再発を防ぐべきミス、または意外だった分野の事実に遭遇した場合は、agents-skills-feedback-loop/scripts/append_learning.py を使って learnings.md に日付付きの箇条書きを 1 つ追記してください。SKILL.md 自体は変更しないでください。