アーキテクチャ設計 (Architecture)

基本方針 (Principles)

実データに触るコードはサーバでしか動かさない．手元では合成データで同じコードパスを流す
手元への回収はホワイトリスト方式．回収対象を明示的に列挙し，列挙外（画像・manifest・患者 ID）は持ち帰れないようにする
設定は YAML に集約し，pydantic で検証する．コードに絶対パス・閾値を書かない
実験は runs/<実験ID>/ に閉じる．同じ設定と seed で同じ結果に辿れるようにする

ディレクトリ構成 (Directory Layout)

TIASJudgeModel/
├── configs/                      # 実験設定 YAML
├── src/tias_judge_model/
│   ├── schema.py                 # pydantic 設定スキーマ
│   ├── data/                     # manifest 読み込み・Dataset・分割・前処理
│   ├── models/                   # timm ラッパ（アーキテクチャ差し替え点）
│   ├── training/                 # 学習ループ・損失・スケジューラ
│   ├── evaluation/               # 指標・混同行列・レポート生成
│   ├── baseline/                 # ルールベース比較（扱いは未定）
│   ├── remote/                   # リモート実行（tar over ssh・tmux・回収）
│   └── cli/                      # エントリポイント
├── scripts/                      # 合成データ生成・manifest 生成
├── tests/
├── data/                         # .gitignore（合成データ．実データは置かない）
└── runs/                         # .gitignore（実験結果）

依存方向は cli → training / evaluation → data / models の一方向とする．data と models は CLI・学習ループを import しない．

データ契約 (Data Contract)

サーバ上のデータ配置（~/data/TIASJudgeModel/）:

~/data/TIASJudgeModel/
├── images/          # 舌領域セグメンテーション済み画像
└── manifest.csv     # 学習が読む唯一の入口

manifest.csv の列:

列名	内容	備考
`image_path`	`images/` からの相対パス	—
`patient_id`	患者を一意に識別する ID	必須．分割の単位になる
`label`	舌色 5 分類のいずれか	医師の診断記録に由来
`note`	任意の備考	除外理由等

manifest はサーバ上の生成スクリプトで作る（実データの構造を確認してから実装する）
patient_id が取得できない場合，画像 ID を患者 ID と見なす代替はしない．生成を止めて人間が判断する（同一患者が分割を跨ぐと評価が壊れるため）

クラス定義 (Class Definition)

内部表現は英字 slug，表示は日本語とし，整数 ID を固定して混同行列の軸をぶらさない．

ID	slug	表示
0	`pale`	淡白
1	`light_red`	淡紅
2	`red`	紅
3	`dark_red`	暗赤
4	`purple`	紫

※ 並び順は TIASjudge の定義に合わせて確定する（順序尺度として扱えるかは未確定．SPEC_02 参照）．

実験の出力 (Run Artifacts)

runs/<実験ID>/
├── config.yaml            # 解決済み設定 ＋ git コミットハッシュ ＋ seed
├── history.csv            # エポックごとの損失・指標
├── metrics.json           # 最終指標（macro F1・accuracy・クラス別）
├── confusion_matrix.png   # 図
├── confusion_matrix.csv   # 数値
├── log.txt
└── checkpoints/best.pt

実験 ID の書式: YYYYmmdd-HHMMSS_<設定ファイル名>_<git短縮ハッシュ>

回収ホワイトリスト (Pull Whitelist)

手元へ回収できるのは以下のみ．リモート実行ツールにこの制約を実装する．

回収する	回収しない
`config.yaml`・`history.csv`・`metrics.json`・`.png`・集計のみの `.csv`・`log.txt`	画像・`manifest.csv`・患者 ID を含むファイル・個票の予測結果

checkpoints/ は既定では回収せず，明示的に指定したときのみ回収する
個票（画像ごとの予測）が必要な分析はサーバ上で行い，集計結果だけを持ち帰る

CLI (Entry Points)

コマンド	役割	実行場所
データセット集計	枚数・患者数・クラス分布・画像サイズ・破損チェック	サーバ（結果の要約のみ手元へ）
学習	設定 YAML を受け取って学習する	サーバ
評価	学習済み run の評価・レポート生成	サーバ
リモート実行	コード送信・ジョブ実行・結果回収・GPU 空き確認	手元

コマンド名は実装時に確定し，ENV_04 開発コマンドに記載する．