Training Guardian Agent · 训练守护智能体

一行命令，训练脚本零行改动，获得完整守护能力。

One command. Zero changes to your training script. Full guardian capabilities.

guarftrain init && guarftrain watch -- python train.py --epochs 20

What's New in v0.2.0

What does it do? · 它做什么？

Quick Start · 快速开始

Install · 安装

# 方式 1: pip 安装（推荐，轻量核心 ~2MB，torch 已有不重装）
pip install guarftrain

# 方式 2: 从源码安装
git clone https://github.com/Washington5533/guarftrain.git
cd guarftrain
pip install .

# 按需安装可选组件
pip install guarftrain[agent]       # AI 决策层 (anthropic)
pip install guarftrain[mcp]         # MCP 外部 Agent 接入
pip install guarftrain[dashboard]   # Web 控制面板
pip install guarftrain[full]        # 全部安装

Three steps to guard · 三步守护

# 1. 初始化项目（自动扫描训练脚本，生成配置）
cd /path/to/your-project
guarftrain init

# 2. 守护训练（纯规则，零外部依赖）
guarftrain watch -- python train.py --epochs 20

# 3. 或启用 AI + Dashboard + MCP
guarftrain watch --agent --with-dashboard --with-mcp -- python train.py --epochs 20

What does the training script need? · 训练脚本要满足什么？

Four contracts (just good training hygiene):

1. --resume / --ckpt flags for checkpoint resumption
2. cp_{epoch}/model.pth with epoch/model_state_dict/optimizer_state_dict
3. Structured logging: epoch {n} loss {v} val_acc {v} lr {v}
4. Importable: train:build_model / train:get_dataloaders

Missing any one? Only the corresponding capability is disabled — training still runs.

四项契约（写好训练脚本的基本功），缺任一项只关对应能力，不阻断训练。

Architecture · 架构

┌─ Guardian Process (sidecar) ────────────────────────────────────┐
│                                                                  │
│  CLI (run.py) ──→ 14 subcommands                                 │
│  ├─ watch ──→ Watchdog: Popen + crash recovery + CLI rewrite    │
│  │             └─ Monitor: log tail + GPU poll + anomaly detect  │
│  │                  └─ AgentAdvisor: LLM decide → intervene       │
│  ├─ serve ──→ MCP Server: 32 tools (22 read + 10 write)          │
│  ├─ start ──→ Dashboard + MCP one-click                        │
│  └─ experiments / query / compare ──→ Cross-experiment analysis  │
│                                                                  │
│  Decision Layers · 决策分层:                                      │
│  ┌─ Contract (hard boundary, human-defined)                     │
│  ├─ Agent (LLM, optional, within action space)                  │
│  ├─ Rules (deterministic, always-on fallback)                   │
│  ├─ MCP (external agent access, dual-mode delegation)           │
│  └─ Dashboard (remote config, dirty-flag user protection)       │
│                                                                  │
│  Training Process: python train.py (0 changes required)          │
└──────────────────────────────────────────────────────────────────┘

CLI Commands · 命令速查

MCP Tools · MCP 工具

24 read-only (always available, no auth):

get_training_status · get_metrics_history · list_checkpoints · compare_checkpoints · get_anomaly_history · get_recovery_history · get_summary · get_agent_decision_log · get_contract_status · list_contract_proposals · list_experiments · query_experiment · compare_experiments · get_model_structure · get_guardian_mode · get_gallery_config · get_import_format · inspect_source · get_training_log · get_post_training_checklist · get_pending_decisions · get_dashboard_config · recommend_charts · list_dashboard_templates

11 write (token auth + training-phase gating):

trigger_recovery · restart_with_params · stop_training · approve_contract_proposal · reject_contract_proposal · run_visualization · set_gallery_config · run_inference · submit_import · resolve_decision · set_dashboard_config

→ Full API reference: MCP_API_REFERENCE.md

Configuration · 配置

Three layers, zero secrets in YAML:

DEFAULTS  <  guardian.yaml  <  GUARDIAN_* env vars  <  CLI flags

# configs/guardian.yaml — only override what you need
watchdog:
  max_retries: 3
monitor:
  poll_interval: 5
mcp:
  enable_write_tools: true

# Env override: GUARDIAN_ + section + __ + key
export GUARDIAN_WATCHDOG__MAX_RETRIES=5
export GUARDIAN_MCP_TOKEN=your-secret   # write tool auth

Project Status · 项目状态

Docs · 文档索引

License

MIT