First commit to add modelbridge module and its test.

[tkokada]

feature/modelbridge Update Guide

このドキュメントは feature/modelbridge ブランチで導入したモデルブリッジ設計の概要とレビュー時に押さえるべきポイントをまとめたものです。

1. 全体像と目的

• モデルブリッジが担う "マクロ HPO → ミクロ HPO" の橋渡しを、NumPy ベースのシンプルな回帰と標準ライブラリ中心のパイプラインで再現しています。
• 既存の aiaccel ユーティリティ（設定読み込み・ロギングなど）と統一感のある API / CLI を提供することで、この機能を他の HPO パスと同様に扱えるようにしています。

2. 主要モジュールと役割

aiaccel/hpo/modelbridge

• app.py: aiaccel-hpo modelbridge の CLI エントリ。設定を Omegaconf 経由で読み込み、run_pipeline を呼び出します。
• config.py: 再設計仕様で定義した dataclass 群と load_bridge_config による型付きバリデーション。マクロ/ミクロ両方のパラメータ空間を区別して管理します。
• runner.py: 実行フローの中心。マクロ・ミクロ各フェーズのトライアル実行、サンプル構築、回帰の学習・評価・成果物出力をまとめています。
• optimizers.py: Optuna を用いた最適化フェーズ実行（マクロ、ミクロ共通）。TrialContext に統一情報を詰めて evaluators.py の Strategy へ渡します。
• evaluators.py: 設定から評価関数を動的ロードするための薄いラッパ。Python callable / 外部コマンドの両方をサポートします。
• regression.py: マクロ→ミクロを多出力線形モデルとして表現。RegressionSample から NumPy の最小二乗で係数を推定し、predictions.csv に出力できる dict 形式の予測を返します。
• io.py, summary.py, logging.py, types.py: 結果ファイルの書き出し、サマリ集計、ロギング補助といった共通処理をコンパクトに提供します。
• exceptions.py: 設計上の不正状態（設定不備、評価失敗など）を表す独自例外。

examples/hpo/modelbridge

• simple_benchmark.py: 単一シナリオ（平滑な二変数関数）を使った極小例。マクロとミクロが同じ関数空間を探索し、回帰モデルを通じた推論・比較まで一周させます。
• multi_function_benchmark.py: modelbridge-cc の Simple Benchmark を着想源に、Sphere / Rastrigin / Griewank 間の橋渡しを複数シナリオで行います。SCENARIOS 定義により各ケースのマクロ・ミクロ関数や回帰設定、トライアル数を切り替えています。

3. 既存 aiaccel との関係

• CLI: aiaccel/launcher.py が aiaccel.hpo.modelbridge.app を呼び出すため、既存の aiaccel-hpo <subcommand> 流儀と整合します。
• 設定: aiaccel.config の load_config, resolve_inherit, print_config をそのまま利用し、既存プロジェクトと同じ Config パターンでモデルブリッジを設定できます。
• Optuna: HPO の裏側は aiaccel が既に依存している Optuna に統一。追加の重い依存は導入していません。

4. 新機能・挙動の要点

• ペアリングと回帰学習: マクロ／ミクロそれぞれのトライアルを trial index で同期し、RegressionSample(features=macro_params, target=micro_params) を生成。NumPy の最小二乗で複数パラメータを一度に回帰します。
• 評価 / 編集結果の記録: regression.json に学習済みパラメータを保存し、predictions.csv に実測値と推論値を併記。summary.json にはシナリオごとの試行回数・ベストパラメータ・評価値を集約します。
• 再現性: BridgeSettings.seed でマクロ・ミクロ両フェーズの乱数を固定。run_pipeline が設定されたシードをフェーズ毎に使い分けている点も確認済みです。

5. テストと検証

• tests/hpo/test_modelbridge/ に新たに軽量テストを整備。
  • test_config.py: 設定のバリデーション挙動を検証。
  • test_evaluators.py: Python callable とコマンド評価の双方が利用できることを確認。
  • test_optimizers.py: Optuna フェーズの実行結果と最良パラメータ取得をチェック。
  • test_regression.py: 多出力回帰の学習／不正入力時の例外を確認。
  • test_runner.py: パイプラインの成果物（summary, trials, predictions）生成を一通り確認。

6. サンプル実行方法

simple_benchmark

python examples/hpo/modelbridge/simple_benchmark.py

• 出力: work/modelbridge/simple/ 配下に summary.json, scenarios/simple/... が生成されます。
• 動作: 12 回のマクロ/ミクロ HPO を行い、線形回帰でマクロ→ミクロを推定。実測値と推測値を predictions.csv で対比。

multi_function_benchmark

python examples/hpo/modelbridge/multi_function_benchmark.py

• 出力: work/modelbridge/multi_function/ 配下に、各シナリオ（sphere_to_rastrigin など）の成果物ディレクトリが作成されます。
• 動作: Sphere ↔ Rastrigin ↔ Griewank の3ケースをそれぞれ独立したシナリオとして実行し、回帰モデルを構築・評価。predictions.csv で比較が可能です。

[tkokada]

feature/modelbridge 変更サマリ (2025-11-16)

1. 背景

• CLI 構成とパイプライン管理を刷新。
• ユーザーが Makefile から段階的に modelbridge を実行できるようにするため、CLI、ランナー、テンプレート設定を整備。

2. 主要変更点

1. CLI 再配置 (aiaccel/hpo/apps/modelbridge.py)

   • 旧 aiaccel/hpo/modelbridge/app.py を廃止し、apps 配下に完全な CLI を実装。
   • --phase (macro/micro/regress/summary/full) と --scenario フィルタを追加し、Makefile からフェーズ単位で呼び出せるようにした。
   • 設定は OmegaConf から読み込み、BridgeConfig にマッピングして run_pipeline を起動。

2. パイプライン再設計 (aiaccel/hpo/modelbridge/runner.py, io.py)

   • run_pipeline が phases / scenarios オプションを受け付けるよう拡張。未実行フェーズは CSV/JSON から復元。
   • マクロ/ミクロの CSV に trial_index を保存し、回帰フェーズで同じ順序を再構築。
   • 回帰結果 (regression.json, predictions.csv, scenario_summary.json) を保存し、summary フェーズのみでトップレベル summary.json を再生成可能。
   • IO ヘルパに read_csv, read_json を追加し、レジューム時に活用。

3. Makefile 化 (プロジェクトルート)

   • 新規 Makefile を追加。MODELBRIDGE_STAGES := mb-config mb-macro mb-micro mb-regress mb-summary を定義し、modelbridge-run で順次実行。
   • aiaccel-job を全フェーズで使用しつつ、ログ/センチネル (work/modelbridge/.mb_*.done) を管理。
   • MODELBRIDGE_CONFIG 変数で任意の YAML を指定可能 (デフォルトは任意)。

4. テンプレートとドキュメント

   • examples/hpo/modelbridge/modelbridge.yaml を追加し、make modelbridge-run MODELBRIDGE_CONFIG=... で即実行できる設定を提供。
   • examples/hpo/modelbridge/README.md にクイックスタートと出力先メモを記載。

5. テスト整備

   • tests/conftest.py を追加し、sys.path にプロジェクトルートを挿入 (pytest 実行環境で tests.* モジュールを import 可能にするため)。
   • tests/hpo/modelbridge/test_runner.py にフェーズ単位の再実行テストを追加。
   • 新規 tests/hpo/test_modelbridge_cli.py で CLI の --dry-run / --phase を検証。

3. 残確認事項

• Makefile の MODELBRIDGE_CONFIG は必須。CI やローカルで実行する際は make modelbridge-run MODELBRIDGE_CONFIG=examples/hpo/modelbridge/modelbridge.yaml などを指定する。
• aiaccel-hpo optimize 連携や aiaccel-job の Python API 化は今後の課題。現状は CLI + Makefile で実現。

[tkokada]

72809d9 以降の変更サマリ（feature/modelbridge）

• modelbridge 設定を pydantic v2 へ刷新し、エイリアス正規化・レイヤード --set オーバーライド対応、JSON Schema 出力を追加。
• Runner を PlanBuilder/DAG/RunContext で再設計し、各フェーズをクラス化（Hpo/Regression/Evaluation/Summary）。manifest.json・シナリオ checkpoint.json に成果物と sha256 を記録するよう拡張。
• Evaluator の環境変数付与をヘルパーに集約し、HTTP POST アダプタを追加（callable/command と共存）。
• ログ設定を整理し、console/file 両方オフなら no-op、--json-log で構造化出力を選択可能に。
• CLI を plan/run/validate/schema に絞り、--set で設定上書き・JSON ログ指定をサポート。scaffold サブコマンドとモジュールを削除。
• IO/型: hash_file 追加、RunContext/RunnerFn 型エイリアス導入、dag.py で簡易トポロジカル順序付けを提供。
• 例とドキュメント: Makefile.template が --set bridge.output_dir/working_directory を自動付与し JSON ログ切替に対応。

File/Feature Quick Reference

• CLI interfaces and overrides: aiaccel/hpo/apps/modelbridge.py
• Plan/execute/DAG/RunContext: aiaccel/hpo/modelbridge/runner.py, aiaccel/hpo/modelbridge/dag.py
• Optuna HPO: aiaccel/hpo/modelbridge/optimizers.py
• Regression fit/eval: aiaccel/hpo/modelbridge/regression.py
• Evaluators (callable/command/http) + env injection: aiaccel/hpo/modelbridge/evaluators.py
• Logging (JSON/console/file control): aiaccel/hpo/modelbridge/logging.py
• IO + hashing: aiaccel/hpo/modelbridge/io.py
• Specs/schema/testing hooks: work/specification/modelbridge/modelbridge_09.md, tests/hpo/modelbridge/*