pdml-agent

一个基于 property-driven-ml 实验管线的 MCP 服务器和工具调用代理，具有人工介入门控机制，用于控制任何消耗计算资源的操作，并为每次调用提供结构化追踪。

Property-driven ML 根据形式逻辑约束训练分类器，因此一次运行由约束、数据集、可微逻辑和种子定义，并生成每个 epoch 的预测性能和约束安全性指标。这使得它成为一个真正适合工具化的领域，而非演示性领域：可以列出实验、恢复配置、读取结果、比较运行，以及规划、批准和执行新的运行。

状态：按范围完成。 服务器、代理、门控、追踪。已在 CPU 上演示真实执行。

架构

┌──────────────────────────────────────────────────────────────┐
│  agent.py                       (Anthropic SDK tool runner)  │
│                                                              │
│   claude-opus-5 ──► pending tool_use ──► ToolLedger.wrap     │
│        ▲                                   │  memoise (RO)  │
│        │                                   │  gate (compute)│
│        │ tool_result                       │  trace (JSONL) │
│        └───────────────────────────────────┘        │        │
└─────────────────────────────┬───────────────────────┼────────┘
                   MCP over stdio                     ▼
┌─────────────────────────────┴────────────────┐   traces/*.jsonl
│  server.py           (mcp MCPServer, thin)   │
│   list_experiments  get_experiment_config    │
│   get_results       compare_runs             │
│   search_logic_definitions                   │
│   run_experiment ──► PDML_ALLOW_EXECUTE=1 ?  │
└────┬───────────┬──────────────┬──────────────┘
     ▼           ▼              ▼
experiments.py  logic_defs.py  runner.py ──► subprocess: main.py
(read CSVs)     (parse source)  (plan/execute)   in property-driven-ml

agent.py 对领域一无所知。它像任何其他 MCP 客户端一样通过 stdio 连接到服务器，仅使用服务器暴露的工具。领域模块不依赖 MCP，可通过导入进行测试。server.py 仅注册工具并委派任务。

布局

pdml_agent/
  experiments.py   reading and comparing runs
  logic_defs.py    searching the logic implementations
  runner.py        validating, planning and executing runs
  server.py        the MCP layer, deliberately thin
  agent.py         the agent: runner, gate, memoisation, tracing
scripts/
  make_fixtures.py generate sample runs
  smoke_test.py    start the server, exercise every tool, check refusals
  demo.py          run the agent on five tasks
fixtures/results/  sample runs, so nothing needs a GPU to demo
demo_output/       what the agent said and did, one JSON per task
traces/            one JSONL per run, every turn and every call

工具

门控

run_experiment 是唯一消耗计算资源的工具，并且有两个独立机制在其前面。

除非服务器以 PDML_ALLOW_EXECUTE=1 启动，否则不会执行。 这是由运行服务器的人做出的决定，任何请求都无法更改。没有此设置时，dry_run=false 返回 status: refused 并附带计划，且这不是错误。

未经操作员批准确切的调用，代理不会发送执行请求。 批准提示显示工具名称和完整的参数（JSON 格式），而非摘要。拒绝返回正常结果 declined_by_operator，模型被指示报告此情况并停止，而非重试。

任何一层单独都能阻止不必要的运行。两者结合意味着任何一层都不必完美。决定哪些需要批准的策略是一个函数 needs_approval，小到一目了然。

追踪

每次运行都会追加到 traces/<timestamp>-<question>.jsonl。每行一个事件，从不重写。

turn 记录包含步骤编号、模型的停止原因、其文本和思考摘要、即将进行的调用以及该轮的令牌使用量。tool_call 记录包含工具、其参数、调用是否成功、是否来自缓存或被门控、延迟、结果摘要，以及模型自身陈述的原因，取自其伴随调用写下的句子。gate 记录包含决策。run_start 和 run_end 用总计括起整个过程。

系统提示要求模型用一句话说明每次调用的原因，它确实这样做了。从拒绝路径的追踪中：

turn 1  "I'll start by finding the existing YG runs to confirm identifiers."
turn 2  "No results with those filters; let me broaden."
turn 3  "The constraint is named `standard-robustness`. Let me get the seed-0 run's config and results."
turn 4  "Now the dry-run plan for the requested run (matching epsilon 0.3 from the seed-0 baseline)."
turn 5  "Plan validated. Now executing it."          ← gate: declined
turn 6  "The training run was not executed: the operator declined ..."

该追踪还发现了此仓库自身工具中的一个缺陷。第 1 轮返回空结果，因为 list_experiments 按结果文件夹名称过滤，而 run_experiment 按类名过滤，同一概念使用了两种词汇。模型自行恢复，代价是一轮，其第 3 轮的原因准确说明了它推断出的内容。list_experiments 现在接受两种拼写。

演示内容

五个任务，没有一个能通过一次调用回答。完整记录在 demo_output/，完整追踪在 traces/。

A. 在精度预算内找到最佳逻辑。 三轮。列出运行，在一个并行轮中获取所有四个结果，回答 YG 在 0.76 精度点下安全性为 0.9981，并说明未执行任何操作。

B. 规划现有运行的变体。 四轮。在一个并行轮中获取配置、比较和逻辑定义，以 dry_run=true 调用 run_experiment，报告计划和确切命令，并在存在匹配运行时进行比较。

C. 与不存在的运行进行比较。 三轮。先列出而非猜测，确认 STL 是真实逻辑但尚无运行，并如实说明。

D. 训练，操作员拒绝。 六轮。首先按工具描述要求进行干运行规划，然后请求执行。审批者拒绝。模型报告未执行且未重试，给出计划，并用现有内容回答。

E. 训练，操作员批准。 六轮，以及一次真实训练运行。相同的先规划后执行序列；审批者接受；以启用执行模式启动的服务器在 CPU 上运行 main.py 一个 epoch，耗时 28.6 秒，并写入 fixtures/results/standard-robustness/mnist/1/YG.csv。然后代理调用 get_results 和 compare_runs 处理新运行，并报告最终 Test-P-Metric 为 0.9160，Test-C-Sec-self 为 0.5482。两者均与 CSV 匹配。 未经提示，它列出了与种子 0 比较的混杂因素（一个 epoch 对十个、延迟、故意削弱的攻击预算），并从 epoch 0 行观察到约束安全性在未训练模型上微不足道地为 1.0，仅当与收敛精度结合时才有意义。这是对指标的正确解读。

该种子 1 的 CSV 是真实运行，并特意与合成夹具放在一起。其第一行是训练时使用的 argv，与其他所有运行一样。

关于数据的两件值得了解的事

Epoch 0 是训练前评估。 配置为 --epochs 10 的运行会写入编号 0 到 10 的十一行。行数和最终 epoch 分别报告，因为将行数称为“epochs”会高估训练一轮。

训练脚本将未评估的指标写入 -1。 get_results 将其规范化为 null，因此哨兵值不会被误读为测量值。基线运行根本没有约束指标，它应该如实说明，而非报告负一。

限制，明确说明以免夸大

模型在五个任务中从未遇到 is_error 工具结果，因为它遵循先列出再信任标识符的指令。错误路径在 smoke_test.py 的协议级别和包装器级别进行了测试，但未演示任务中途工具错误后的实时恢复。

记忆化从未实时触发。模型在任何运行中均未重复相同的调用。它经过了单元测试，并在所有追踪中处于空闲状态。

未配置提示缓存。cache_read_input_tokens 在所有追踪中均为零，输入令牌计数（每个任务 11k 到 46k）大多是重新发送的上下文。在工具定义和系统提示上设置缓存断点将大幅减少此数量，这是明显的下一步改进。

执行运行需要 main.py 可解析的检出。在上游 main 上，情况并非如此：--epsilon 和 --delta 各定义两次，argparse 在读取任何参数之前拒绝重复，因此 python main.py --help 失败。这在分支的 fix/duplicate-argparse-flags 分支上已修复，并带有回归测试，演示将 PDML_REPO_DIR 指向该检出。

尝试运行

uv sync
uv run python scripts/make_fixtures.py
uv run python scripts/smoke_test.py

烟雾测试通过 stdio 启动服务器，枚举工具，调用每个工具，检查未设置 PDML_ALLOW_EXECUTE 时执行是否被拒绝，并检查未知实验 ID 是否返回错误而非静默成功。它不消耗任何资源。

要向代理提问，设置 ANTHROPIC_API_KEY：

uv run python -m pdml_agent.agent "Which mnist run has the best constraint security?"
uv run python scripts/demo.py A B C D

要让它实际训练，将其指向 main.py 可解析的 property-driven-ml 检出以及带有 torch 的解释器，然后传递启用执行的标志：

export PDML_REPO_DIR=~/property-driven-ml
export PDML_PYTHON=~/property-driven-ml/.venv/bin/python
uv run python -m pdml_agent.agent --allow-execute "Train a one-epoch YG run on mnist at seed 2 ..."
uv run python scripts/demo.py E

您将看到确切的调用并被要求批准。

服务器读取的环境变量：PDML_RESULTS_DIR（运行所在目录，默认 fixtures/results）、PDML_REPO_DIR（property-driven-ml 检出）、PDML_PYTHON（main.py 的解释器，否则为仓库的 .venv）、PDML_ALLOW_EXECUTE（设为 1 以允许执行）、PDML_EXECUTE_TIMEOUT（秒，默认 3600）。