academic-repo-analyzer

Academic Repo Analyzer

簡潔なリポジトリ理解ドキュメントと、機械可読な Semantic Architecture Handoff v1 を作成します。ハンドオフでは、リポジトリのフォルダー構成やエンジニアリング上の定型処理ではなく、科学的な役割と実行可能な関係を記述します。

タスクやフレームワークの分類が不確かな場合に限り、keywords.md を読みます。根拠が乏しい場合は、references/missing-info-policy.md を読みます。

基本原則：ナラティブを優先し、抽出は非侵襲的に行う

1. 論文とユーザーのナラティブ > コードの実装：
   • 論文の図は、ソフトウェアエンジニアリング成果物の全体ではなく、科学的な貢献と概念的なデータフローを示します。
   • 論文で学習アルゴリズムやインフラストラクチャシステムが特に提案されていない限り、エンジニアリング上の配線処理（DataLoader、Trainer、Logger、ConfigParser、DeviceManager、Optimizer のセットアップなど）は省略します。
2. 事実確認とパラメーターの根拠付け：
   • 論文の草稿やユーザーのアーキテクチャがすでにある場合、リポジトリアナライザーはアーキテクチャを一から考案するのではなく、根拠を補うファクトチェッカーとして機能します（テンソルの次元、損失関数、正確なモジュール名、実行方向を検証します）。

入力の契約

• 優先するもの：リポジトリのパス、README、依存関係、エントリーポイント、主要なモデル／アルゴリズムファイル、設定、動作を確認できるテスト。
• 受け入れるもの：一部のみのリポジトリ、単独のモデルファイル、主要なアルゴリズムスクリプト。
• 最低要件：README、エントリーポイント、主要な実装ファイルのいずれか1つ。
• Git のメタデータが利用可能な場合は、ソースのリビジョンを記録します。
• 名前や README の記述は手がかりとして扱い、図に関わる重要な主張はコードまたはテストで検証します。

出力の契約

人間向けの要約はおよそ30～70行に収めた後、以下のハンドオフブロックを出力します。

1. リポジトリの概要と科学的なタスク。
2. 調査した内容を列挙した、根拠／完全性に関する記述。
3. 意味的なコンポーネントとその責務。
4. 実行／助言／フィードバック／永続化の接続関係。
5. エージェント、ツール、評価器、外部システムが関わる場合の権限または信頼境界。
6. 図の提案（全体フレームワーク、ネットワークアーキテクチャ、モジュール詳細、概念／動機、プロトコル／シーケンス）。
7. Semantic Architecture Handoff v1。

ワークフロー

1. 根拠を探す

README、依存関係ファイル、エントリースクリプト（train、main、eval、inference、predict、run、simulate、benchmark）、設定、主要なアルゴリズムファイルを探します。トップレベルのディレクトリは調査の手がかりにすぎず、アーキテクチャのモジュールとして数えてはいけません。

大規模なリポジトリでは、トップレベルと、根拠を示せる範囲の主要ファイルのサンプルを調査します。サンプリングの範囲を明記してください。キーワードのヒットだけを根拠に、全体を調査したと主張してはいけません。

2. タスクと実装スタックを分類する

科学的な目的、主要なフレームワーク、データ／実験インターフェース、主な実行経路を、ファイルまたはシンボルの根拠とともに特定します。根拠のない推測は明示します。

3. 意味グラフを構築する

論文の図に含めるべき、科学的または実行上の明確な責務を持つ場合に限り、コンポーネントを1つ作成します。コンポーネントが複数のファイルにまたがっていてもよく、1つのファイルが複数のコンポーネントを実装していてもかまいません。

各コンポーネントについて、以下を記録します。

• 安定した id と短い表示用 label。
• role：
  • General ML / Deep Learning：input_data、encoder_backbone、fusion_interaction、loss_objective、task_head、model、output。
  • Agentic / Interactive：reasoning、decision、deterministic_execution、observation、memory、persistence、advisory、exception。
  • Systems / Modular：source、scheduler、processor、storage、sink、other。
• figure_importance：primary または secondary。
• path:line、クラス、関数、テスト、設定キーなどの根拠へのポインター。
• 1文での責務の説明。科学的に重要な場合は、明示的な非権限範囲も記載します。

接続関係は個別に記録します。接続の種類には executed、advisory、feedback、persistence、exception を使用します。2つのファイルが互いをインポートしているという理由だけで、エッジを推測してはいけません。

4. 視覚的なグループを導き出す

関連するコンポーネントを、責任範囲または説明の段階ごとにグループ化します。以下を報告します。

• semantic_component_count：根拠のあるコンポーネントの数。
• visual_group_count：提案する図に含まれる意味のある領域の数。
• peer_module_count：真に同等な兄弟コンポーネントの最大数。

これらの数値はレイアウトの計画に役立ちます。いずれも、それだけで配色を決定するものではありません。

5. 引き継ぎ内容を出力する

{
  "schema": "academic-figure/SemanticArchitecture@1",
  "source_revision": "<commit-or-unknown>",
  "domain": "<controlled-domain>",
  "evidence_level": "high|partial|sparse",
  "components": [
    {
      "id": "backbone",
      "label": "Encoder Backbone",
      "role": "encoder_backbone",
      "figure_importance": "primary",
      "responsibility": "Extracts multi-scale feature representations.",
      "evidence": ["models/backbone.py:ResNet"]
    }
  ],
  "connections": [
    {
      "from": "input_data",
      "to": "backbone",
      "kind": "executed",
      "label": "raw inputs",
      "evidence": ["models/pipeline.py:forward"]
    }
  ],
  "authority_boundaries": [],
  "semantic_component_count": 1,
  "visual_group_count": 1,
  "peer_module_count": 0,
  "figure_types": ["Overall Framework"],
  "forbidden_claims": ["<claims the figure must not imply>"]
}

対象ドメイン：CV、NLP、Speech/Audio、RL、Robotics、Multimodal、TimeSeries、Generative、Protein/AI4Science、GNN/ScientificComputing、Systems/Infrastructure、ScientificComputing(non-ML)、またはOther。

根拠が乏しい場合

• README がない場合：コードから慎重に推測し、推測であることを明示します。
• エントリーポイントがない場合：結果をコンポーネントレベルの構造に限定します。
• コア実装がない場合：タスクと技術スタックのみを報告し、裏付けのないエッジは省きます。
• リポジトリがほぼ空の場合：アーキテクチャを創作せず、不足している資料を最低限提示します。

終了

人間向けの概要と有効な引き継ぎ内容を提示したら終了します。ユーザーが次の段階を希望する場合にのみ、図の計画を提案してください。