pdml-agent

속성 기반 머신러닝(property-driven-ml) 실험 파이프라인을 위한 MCP 서버 및 도구 호출 에이전트로, 컴퓨팅 자원을 소비하는 모든 작업에 사람의 개입 게이트를 두고 모든 호출에 대한 구조적 추적을 제공합니다.

속성 기반 머신러닝은 형식 논리 제약 조건에 대해 분류기를 훈련하므로, 실행은 제약 조건, 데이터셋, 미분 가능 논리 및 시드(seed)로 정의되며, 예측 성능과 제약 조건 보안 모두에 대한 에포크별 지표를 생성합니다. 이는 데모용이 아닌 진정한 도구 기반 도메인을 만듭니다. 실험을 나열하고, 구성을 복구하고, 결과를 읽고, 실행을 비교하고, 새로운 실행을 계획, 승인 및 실행할 수 있습니다.

상태: 범위 내에서 완료. 서버, 에이전트, 게이트, 추적. 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 클라이언트처럼 표준 입출력(stdin/stdout)을 통해 서버에 연결되며 서버가 노출하는 도구만으로 작업합니다. 도메인 모듈은 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. 정확도 예산 내 최적 논리. 세 턴. 실행을 나열하고, 네 가지 결과를 모두 한 병렬 턴에 가져오고, 0.76 정확도 포인트에 대해 0.9981 보안의 YG를 답변했으며, 아무것도 실행되지 않았습니다.

B. 기존 실행의 변형 계획. 네 턴. 한 병렬 턴에 구성, 비교 및 논리 정의를 가져오고, dry_run=true로 run_experiment를 호출하고, 계획과 정확한 명령을 보고했으며, 일치하는 실행이 존재하므로 비교했습니다.

C. 존재하지 않는 실행과 비교. 세 턴. 추측 대신 먼저 나열하고, STL이 단순히 실행이 없는 실제 논리임을 확인하고, 그렇게 말했습니다.

D. 훈련, 운영자 거절. 여섯 턴. 도구 설명이 요청하는 대로 먼저 dry run으로 계획한 다음 실행을 요청했습니다. 승인자가 거절했습니다. 모델은 실행되지 않았음을 보고하고 재시도하지 않았으며, 계획을 제공하고, 존재하는 것으로 답변했습니다.

E. 훈련, 운영자 승인. 여섯 턴, 그리고 실제 훈련 실행. 동일한 계획-후-실행 순서; 승인자가 수락했고, 실행이 활성화된 상태로 시작된 서버는 CPU에서 28.6초 동안 한 에포크 동안 main.py를 실행하고 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 비교(한 에포크 대 열, 지연, 의도적으로 약화된 공격 예산)에 대한 혼동 요인을 나열하고, 에포크 0 행에서 제약 조건 보안이 훈련되지 않은 모델에서는 당연히 1.0이며 수렴된 정확도와 함께서만 의미가 있음을 관찰했습니다. 이는 지표의 올바른 해석입니다.

해당 시드 1 CSV는 실제 실행이며 의도적으로 합성 픽스처 옆에 보관됩니다. 다른 모든 실행과 마찬가지로 첫 번째 줄은 훈련에 사용된 argv입니다.

데이터에 대해 알아야 할 두 가지 사항

에포크 0은 사전 훈련 평가입니다. --epochs 10으로 구성된 실행은 0에서 10까지 번호가 매겨진 11개의 행을 씁니다. 행 수와 최종 에포크는 별도로 보고됩니다. 행 수를 "에포크"라고 부르면 훈련이 하나 과대평가되기 때문입니다.

훈련 스크립트는 평가하지 않은 지표에 대해 -1을 씁니다. get_results는 이를 null로 정규화하므로, 센티널이 측정값으로 읽히지 않습니다. 기준 실행에는 제약 조건 지표가 전혀 없으며, 마이너스 1을 보고하는 대신 그렇게 말해야 합니다.

한계, 과장되지 않도록 명시

모델은 다섯 작업에서 실시간으로 is_error 도구 결과를 한 번도 만나지 않았습니다. 이는 식별자를 신뢰하기 전에 나열하라는 지시를 따랐기 때문입니다. 오류 경로는 smoke_test.py에서 프로토콜 수준으로, 그리고 래퍼 수준에서 테스트되었지만, 작업 중간 도구 오류로부터의 실시간 복구는 시연되지 않았습니다.

메모이제이션은 실시간으로 실행되지 않았습니다. 모델은 어떤 실행에서도 동일한 호출을 반복하지 않았습니다. 단위 테스트되었으며 모든 추적에서 유휴 상태입니다.

프롬프트 캐싱은 구성되지 않았습니다. 모든 추적에서 cache_read_input_tokens는 0이며, 입력 토큰 수(작업당 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

스모크 테스트는 표준 입출력(stdin/stdout)을 통해 서버를 시작하고, 도구를 열거하고, 각각을 호출하고, 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).