professorpalmer/Puppetmaster

Provider-neutral control plane for durable-state agent swarms: subprocess workers, leases, artifacts, memory, and deterministic stitching.

Puppetmaster – LLM 기반 개발 에이전트를 위한 지속적인 오케스트레이션

개요 – puppetmaster(PyPI에서 puppetmaster‑ai로 설치)는 이미 사용 중인 LLM 기반 도구(Cursor, Claude‑Code, Codex, Gemini Antigravity, Hermes, OpenAI 호환 API 등)를 통해 다단계 엔지니어링 작업을 실행할 수 있는 Python 기반 슈퍼바이저입니다. 독립적인 워커 프로세스를 시작하고, 각 하위 작업을 가장 적합한 모델로 라우팅하며, 모든 유형화된 결과를 로컬 SQLite 데이터베이스에 영구 저장합니다. 저장된 아티팩트는 전체 워크플로를 검사 가능하고, 재개 가능하며, 감사 가능하게 만듭니다.

중요성 – 일반적인 LLM "에이전트"는 단일 증가 트랜스크립트를 유지하므로 오류 복구, 모델 출력 비교 또는 수행된 작업 증명이 어렵습니다. Puppetmaster는 작업을 지속적인 유형화된 아티팩트로 분할하여 개발자에게 코드베이스 감사, 리팩토링 또는 저장소 전체 자동화를 위한 신뢰할 수 있는 상태 레이어를 제공합니다.

핵심 개념

개념	역할
Pilots (MCP)	Puppetmaster를 호출하는 프론트엔드(Cursor Agent, Grok Bot, Claude Desktop, Pi, OMP).
Adapters / Workers	구체적인 모델 백엔드(cursor, claude‑code, codex, hermes, antigravity, 일반 agentic API).
Supervisor	라우팅을 조정하고, 워커를 시작하고, SQLite 아티팩트를 작성하고, 통합 요약을 제공합니다.
SQLite store	각 단계의 지속적인 로그(페이로드, 증거, 콘텐츠 해시)로 나중에 쿼리 가능.
Dashboard	실시간 작업 검사를 위한 소형 웹 UI(`http://127.0.0.1:<port>/?job=<id>&embed=1`). 휴대폰에서도 사용 가능.

빠른 시작(셸)

# 설치(pipx 권장)
pipx install puppetmaster-ai
# 보유한 어댑터 설정(예: Cursor)
puppetmaster setup --platforms cursor

# 현재 저장소에서 간단한 "doctor" 패스 실행
puppetmaster doctor

# 감독된 변경 시작
puppetmaster start "Review this repo for release blockers" \
    --review --dry-run

# 최신 작업 검사
puppetmaster show $(puppetmaster last)

지원되는 UI(Cursor, Grok Bot 등)에서는 다음을 입력하기만 하면 됩니다:

Use Puppetmaster to run doctor in this repo and summarize what is missing.

UI는 요청을 로컬 슈퍼바이저로 전달하고, 적절한 워커를 시작하며, 폴링할 수 있는 작업 ID를 반환합니다.

주요 기능

다중 모델 라우팅 – 하위 작업별로 가장 저렴하거나 가장 강력한 모델 선택. 비용 라우팅은 SWE‑bench Lite에서 지출을 약 30% 절감하는 것으로 나타났습니다.
지속적인 상태 – 각 워커는 유형화된 아티팩트를 SQLite에 작성합니다. 작업은 충돌 후에도 생존하며 재개할 수 있습니다.
팬아웃 및 스티칭 – 병렬 워커를 시작한 다음 최종 모델이 간결한 요약을 생성합니다.
어댑터 비종속 – MCP 계약을 따르는 모든 CLI에서 작동(Cursor, Claude‑Code, Codex, Gemini Antigravity, Hermes 또는 일반 API 키).
Grok Bot용 원격 MCP – 동일한 도구 핸들러를 HTTP/SSE를 통해 노출하여 Cursor의 Grok Bot이 다른 머신에서 작업을 구동할 수 있습니다.
선택적 CodeGraph 컨텍스트 – codegraph 인덱스가 있으면 워커가 구조적 코드 정보를 자동으로 받습니다.
대시보드 및 CLI 검사 – puppetmaster artifacts <job_id> 또는 python -m puppetmaster dashboard로 원시 결과를 봅니다.
안전 후크 – 내장 요청 수준 검증(puppetmaster setup --verify-first-run …) 및 SECURITY.md에 문서화된 보안 모델.

증거 및 벤치마크

SWE‑bench Lite – 단일 모델 기준선 대비 실제 지출 29% 감소, 토큰 일치 약 48% 절감(단일 시드 연구).
NL2Repo‑Bench – 평균 통과율 91.1%, 게시된 약 40% 기준선의 약 2.3배. 자세한 방법론은 링크된 벤치마크 저장소와 공개 블로그 게시물에 있습니다.
재현 가능한 벤치마크 스크립트는 저장소(CLAIMS.md)에 포함되어 있으며, 라우팅, 아티팩트 무결성 및 오류 분류를 다룹니다.

성숙도 및 라이선스

버전 v1.27.8(베타, 일일 드라이버). 최근 릴리스에는 내구성 수정, 지속적 계획, 크롬 없는 임베디드 대시보드가 추가되었습니다.
설치 – pipx 또는 pip. puppetmaster setup은 어댑터 및 MCP 후크의 멱등 설치를 처리합니다.
제거 – puppetmaster uninstall은 모든 MCP 항목을 제거합니다. 상태는 --purge‑state로 제거할 수 있습니다.
라이선스 – MIT.

사용 시기

이미 하나 이상의 LLM 기반 코딩 어시스턴트를 사용 중이고 이를 단일 장소에서 조정하려는 경우.
모델이 수행한 작업에 대한 감사 준비 로그가 필요한 경우(예: 보안 감사, 규정 준수 확인).
워크플로가 병렬 모델 호출 및 최종 통합 요약의 이점을 얻는 경우.
간단한 단계에는 저렴한 모델을 라우팅하고 중요한 편집에는 고가 모델을 예약하여 비용을 절감하려는 경우.

자세한 정보

전체 문서: docs/README.md
어댑터 설정 세부 정보: docs/ADAPTERS.md
기능 매트릭스: docs/FEATURES.md
벤치마크 주장: docs/CLAIMS.md
대시보드 사용법: docs/DASHBOARD.md

결론 – Puppetmaster는 임시 LLM 코딩 어시스턴트를 내장 비용 라우팅, 내구성 및 검사 도구를 갖춘 안정적인 상태 저장 엔지니어링 파이프라인으로 전환하는 실용적인 오픈 소스 레이어입니다.