kermt-monitor

kermt-monitor

切り離して実行されるあらゆる KERMT ワークフロー向けのコンパニオンスキルです。対象は 3 つの事前学習スキル（kermt-continue-pretrain、kermt-pretrain-scratch、kermt-add-cmim-pretrain）と kermt-finetune です。kermt-infer と kermt-embed はデフォルトではブロッキング実行されるため、このスキルは不要ですが、ユーザーが意図的に切り離して起動した場合でも、このモニターは動作します（ステップ 4 のワークフロー振り分けでは、不明なワークフローの場合、実行ディレクトリ内の最新のログファイルを追跡します）。実行ディレクトリの run.json を読み取り、コンテナの状態を Docker に問い合わせ、最新の進捗を表示して、ログを末尾から表示するか、追跡します。

ハードウェア要件

ありません。このスキルはディスクの読み取りと Docker への問い合わせのみを行い、GPU 計算は行いません。

入力

次のいずれかです。

• <run-dir> — run.json を含むディレクトリを指す位置引数です（例：runs/continue-pretrain_2026-05-17T10-23Z）。推奨です。
• --container <name-or-id> — コンテナを直接指定します。このスキルは、利用可能であればコンテナの inspect 出力内で参照される実行ディレクトリから run.json も読み取りますが、それがなくても縮退モードで動作します。

オプション：

• --lines N — 表示するログ末尾の行数（デフォルトは 50）。
• --follow — ^C まで docker logs -f をストリーミングします。「損失を監視する」場合に便利です。指定しない場合、このスキルは一度だけ実行して終了します。
• --json — 人間が読めるテキストではなく、構造化されたステータスレポートを出力します。親エージェントが後続のアクションを実行する場合に便利です。

ワークフロー

RUN_DIR=$1（またはユーザーが指定したパス）とします。

1. マニフェストを特定します。

   MANIFEST=$RUN_DIR/run.json
   

   マニフェストが存在しない場合は処理を中止し、実行ディレクトリの規約（runs/<workflow>_<ts>/）を示すわかりやすいメッセージを表示します。

2. マニフェストを解析します（Python ヘルパー）。

   workflow=$(jq -r .workflow $MANIFEST)
   container_name=...   # not directly in run.json today; the skill that
                        # launched stored it in run.json under
                        # container.name during launch (see below note).
   logs_dir=$(jq -r .logs_dir $MANIFEST)
   image_tag=$(jq -r .container.image_tag $MANIFEST)
   started_at=$(jq -r .started_at $MANIFEST)
   

3. コンテナの状態を Docker に問い合わせます。

   docker ps --filter "name=$container_name" --format \
       '{{.ID}}\t{{.Status}}\t{{.CreatedAt}}'
   

   見つからない場合は、docker inspect $container_name --format '{{.State.Status}} (exit {{.State.ExitCode}})' にフォールバックし、コンテナが正常終了または失敗して終了したのか、終了後に削除された（--rm）のかを確認します。

4. 実行中のログファイルを見つけます。

   case "$workflow" in
     continue-pretrain|pretrain-scratch)  LOG=$logs_dir/pretrain_ddp.log ;;
     finetune)                            LOG=$logs_dir/finetune.log ;;
     *)                                   LOG=$(ls -1t $logs_dir/*.log 2>/dev/null | head -n 1) ;;
   esac
   

   マニフェストの workflow フィールドで、事前学習（pretrain_ddp.log）とファインチューニング（finetune.log）を判別します。それ以外のワークフローでは、$logs_dir 内で最終更新日時が最も新しい .log ファイルを使用します。

5. 最新の進捗を表示します。

   • 生の直近の出力には tail -n $LINES $LOG を使用します。
   • 直近の進捗行を解析し、人間が読みやすい要約を表示します。形式はワークフローによって異なります。
     • 事前学習：エポック／ステップ／val_loss

       Current epoch: 12/100  step: 4523/9000  val_loss: 0.832 (best 0.821 @ step 4100)
       

     • ファインチューニング：fold／エポック／val_（回帰の場合は val_mae、分類の場合は val_auc など。run.json から args_applied.metric を読み取ります）

       Fold 0  epoch 12/30  val_mae 0.187 (best 0.182 @ epoch 9)
       

     Wall-clock: 1h 23m since started_at; ETA ~6h remaining.
     

6. 最終テスト指標ブロック（ファインチューニング完了時）。 workflow が finetune であり、コンテナが正常終了し（State.Status=exited、 ExitCode=0）、さらに $RUN_DIR/ckpt/fold_*/test_result.csv が存在する場合は、これを解析してタスクごとの指標テーブルを出力します。

   Final test metrics (per task):
     Target              MAE
     HLM_clearance       0.187
     RLM_clearance       0.213
     MDR1-MDCK_efflux    0.241
     solubility_pH6.8    0.156
   

   指標の列は args_applied.metric に一致します（回帰の場合は mae、分類の場合は auc など）。複数フォールドまたはアンサンブルの実行では、フォールド／モデル全体の平均を計算し、std > 0 の場合は ± std を付記します。test_result.csv が存在しない場合（実行が未完了、またはテスト分割が出力されていない場合）は、何も表示せずにスキップします。

7. --follow が指定されている場合は、ライブログをストリーミングします。

   docker logs -f $container_name
   

   ^C まで繰り返します。

8. 停止／クリーンアップのヒント（一度だけ実行するモードの最後に表示します）。

   To stop:        docker stop $container_name
   To remove:     docker rm $container_name
   To re-run:    `$(jq -r .cmd_replay $MANIFEST)`
   

厳守事項

• ユーザーデータに対して読み取り専用です。 run.json は変更せず、コンテナのチェックポイントディレクトリにも触れないでください。モニターは確認のみを行います。
• ユーザーから明示的な指示がない限り、コンテナを停止しないでください。 ユーザーが停止を求めた場合は docker stop を実行します。放棄を求めた場合は、コンテナを実行したままにして、終了してください。
• kermt イメージをプルしたり変更したりしないでください。 モニターは読み取りのみを行います。
• JSON 出力モードは非対話型です。 「終了するには ^C を押してください」というプロンプトは省略し、親エージェントがパイプで渡せるよう、単一の JSON ドキュメントを出力してください。

container_name の受け渡しに関する注意

現行の run.json スキーマには、起動したコンテナ名がまだ含まれていません。kermt_run_detached は標準出力にコンテナ名を出力しますが、ランナースクリプトはそれを run.json に記録していません。モニターはファイルシステムを使った検索にフォールバックします。runs/<workflow>_*/ ディレクトリを一覧表示し、更新日時で照合するか、--container <name> を明示的に指定してください。今後の対応として、起動スキルで終了前にコンテナ名を run.json に記録するようにします。

出力（テキストモード、デフォルト）

KERMT continue-pretrain · runs/continue-pretrain_2026-05-17T10-23Z
  Container : kermt-continue-pretrain-…  (Up 1 hour, status: running)
  Image     : kermt:latest@sha256:…
  Repo      : 2fe00f9 (clean)
  Started   : 2026-05-17T10:23:14Z (1h 23m ago)
  Workflow  : continue-pretrain, pretrain_mode=hybrid, world_size=2

  Latest log (last 50 lines from $LOG):
    [Epoch 12/100] step 4523/9000 loss 0.832 lr 1.2e-4
    [val] step 4100 val_loss 0.821 (new best)
    ...

  Progress: epoch 12/100, ~12% done. ETA ~6h.
  TensorBoard: tensorboard --logdir $RUN_DIR/logs/tb
  Replay command: $(jq -r .cmd_replay $RUN_DIR/run.json)