BenchFlow는 샌드박스 환경(sandboxed environments)에서 벤치마크 작업에 대해 AI 에이전트(AI agents)를 실행합니다. 단일 에이전트(Single-agent), 멀티 에이전트(multi-agent), 그리고 멀티 라운드(multi-round) 패턴은 하나의 Scene 기반 라이프사이클(lifecycle)을 공유합니다.

모든 ACP 에이전트— Gemini CLI, Claude Code, Codex, OpenCode, OpenHands, OpenClaw, Pi 또는 사용자 정의 에이전트
단일 + 멀티 + 점진적 콜백(Single + multi + progressive callback)— 단일 에이전트 / 멀티 에이전트 (코더 + 리뷰어, 시뮬레이션된 사용자) / Python BaseUser를 사용한 멀티 라운드
샌드박스(Sandboxes)— 로컬 Docker, 병렬 클라우드 실행을 위한 Daytona, 서버리스/GPU 기반 작업 환경을 위한 Modal
강화된 검증기(Hardened verifier)— 기본적으로 BenchJack/Meerkat 스타일의 보상 해킹(reward-hacking)을 차단하며, 작업별로 기능에 따라 옵트아웃(opt out) 가능

uv tool install benchflow

Python 3.12+ 및 uv가 필요합니다. Daytona 실행을 위해 DAYTONA_API_KEY를 설정하거나, Modal 실행을 위해 Modal 인증을 구성하십시오. 관련 에이전트 API 키(GEMINI_API_KEY, ANTHROPIC_API_KEY 등)를 내보내거나(export), 구독 인증을 위해 claude login / codex --login을 실행하십시오.

'시작하기(Getting started)'로 시작한 다음, 사고 모델(mental model)을 위해 '개념(Concepts)'을 읽으십시오. 그 다음 목표에 따라 다음을 참조하십시오:

노트북(Notebooks)과 실행 가능한 예제 스크립트는 docs/examples/ 아래에 위치하여, 예제가 이를 설명하는 문서와 함께 버전 관리되도록 합니다.

벤치마크 데이터셋(Benchmark datasets)은 외부 Git 리포지토리(repos)에 저장되며 두 개의 필드로 참조됩니다:

# benchmarks/skillsbench-claude-glm51.yaml
source:
repo: benchflow-ai/skillsbench # GitHub org/repo
...

CLI를 통해 모든 벤치마크를 실행할 수 있습니다:

# YAML 설정 파일로부터
bench eval create --config benchmarks/skillsbench-claude-glm51.yaml
# 인라인(Inline) — YAML 소스 필드를 반영
...

리포지토리는 처음 사용 시 .cache/datasets/ 아래에 로컬로 클론(cloned) 및 캐싱(cached)됩니다.

SkillsBench 자체는 pyproject.toml 내에서 GitHub main 브랜치의 BenchFlow를 소스로 사용합니다.

BenchFlow의 변경 사항이 반영된 후, lockfile이 최신 BenchFlow 커밋을 가리키도록 해야 하는 경우 SkillsBench에서 uv lock --upgrade-package benchflow를 실행하십시오.

SWE-bench Pro에 대한 점진적 공개(Progressive disclosure)— BaseUser

추상화 (abstraction)는 다회차 롤아웃 (multi-round rollout)을 유도합니다: 간결한 0단계 프롬프트 (round-0 prompt) → 실패한 테스트 힌트 (failing-test hints) → 전체 사양 (full spec). Daytona에서 5/5 오라클 (oracle)을 달성했으며, 실행 가능한 데모는 docs/examples/swebench_pro_progressive_disclosure.ipynb에서 확인할 수 있습니다. 점진적 공개 (Progressive disclosure)를 참조하십시오.

두 가지 실행 가능한 랩 (labs)이 보안 스토리를 검증합니다:

labs/benchjack-sandbox-hardening/
— 0.2.1+ 버전에서 0.2.0의 보상 (reward)을 0.0에서 1.0으로 뒤바꾸는 세 가지 BenchJack 익스플로잇 (exploits)을 차단함을 보여주는 엔드 투 엔드 (end-to-end) 데모.

labs/reward-hack-matrix/
— 0.2.0 대 0.2.2를 비교하며 실제 벤치마크 전반에 걸쳐 수행한 전체 보상 해킹 (reward-hack) 스윕 (sweep).

평가 연구자 / 논문 작성자 (Eval researchers / paper writers)
→ 시작하기 (Getting started) → 개념 (Concepts) → 사용 사례 (Use cases)

태스크 작성자 (Task authors)
→ 태스크 작성 (Task authoring) → 샌드박스 강화 (Sandbox hardening)

benchflow와 통합하는 에이전트 빌더 (Agent builders integrating with benchflow)
→ 개념 (Concepts) → Python API 레퍼런스 (Python API reference) → benchflow.agents.registry

외부 벤치마크 어댑터 (External benchmark adapters)
→ 태스크 작성 (Task authoring) → 점진적 공개 (Progressive disclosure)

PR (Pull Requests)을 환영합니다. main 브랜치를 대상으로 제출해 주세요. CI는 모든 PR에 대해 ruff와 테스트를 실행합니다. 로컬에서 먼저 ruff check .와 pytest tests/를 실행해 주세요.

릴리스를 위해서는: pyproject.toml을 다음 안정 버전 (stable version)으로 올리고, main에 v<version> 태그를 생성한 뒤, 해당 태그를 푸시(push)하십시오. 그러면 CI가 PyPI에 게시합니다. 그 후 main을 다음 .dev0 버전으로 올리십시오.

Apache-2.0.