Show GN: Bracket : LLM agent 실행 완결성을 계약 기반으로 판정하는 Python 라이브러리

LLM agent는 "파일을 읽었다", "테스트를 돌렸다"라고 보고하지만 실제로는 그 단계를 건너뛰는 경우가 있습니다. LangGraph, Google ADK 같은 agent 프레임워크는 실행은 잘 해주지만 필요한 단계를 거쳤는지는 검증하지 않습니다.

Bracket은 이 간극을 메꾸는 작은 Python 라이브러리입니다. 실행 중 증거(파일 읽기, 파일 변경, 커맨드 실행, LLM 호출 등)를 수집하고, 사전에 정의한 계약 조건과 대조해서 pass/fail을 기계적으로 판정합니다. LLM이 판정하지 않고 코드로 정의된 규칙이 판정합니다.

해결하는 문제

• Agent가 파일을 읽지도 않고 수정한 척 하는 경우를 잡아냄 (read-before-write)
• "테스트 통과 확인" 같은 검증 단계를 파이프라인에 강제 주입
• 실행 로그를 저장해 두고 판정 규칙이 바뀌었을 때 과거 실행을 재판정(replay)
• 여러 프레임워크를 섞어 쓸 때 검증 로직을 단일화

내장 프로파일

• code_change - read-before-write, file changed, verification command 필수
• research - file read, web fetch, grounding evidence
• file_task - file changed, artifact emitted
• text_answer - grounding evidence

모든 프로파일에 "intent resolved"와 "hard failure 없음" 조건이 포함됩니다.

타겟 사용자와 효과

• Agent 파이프라인을 프로덕션에 올려야 하는 개발자: "tests pass" 같은 조건을 명시적 계약으로 만들어 회귀 방지
• 여러 agent 프레임워크를 비교,평가 중인 팀: LangChain/LangGraph/Google ADK 어댑터가 있어 프레임워크 교체와 무관하게 동일 판정 기준 유지
• Eval/regression 파이프라인 운영자: .bracket/runs/* JSON 로그로 과거 실행을 일괄 재판정 가능

설치 및 예제
pip install bracket

from bracket import Harness, ExecutionContract

contract = ExecutionContract.code_change(goal="Fix failing test")
harness = Harness(app_name="my-agent", artifact_dir=".bracket")
run = harness.start_run(contract)

run.record_file_read("app.py", byte_count=1842)
run.record_file_changed("app.py")
run.record_command("pytest tests/", exit_code=0, kind="verification")

result = harness.finish_run_sync(run, final_output="Fixed the bug.")
print(result.verdict.outcome) # VERIFIED / BLOCKED / PARTIAL

Python 3.12+, 코어는 외부 의존성 없음. LangChain/LangGraph/Google ADK 어댑터는 extras로 선택 설치.

Bracket이 지양하는 것

• Agent 프레임워크 대체품 아님 (LangGraph 등과 함께 사용)
• Guardrails 아님 (입출력 필터링이 아니라 실행 과정 검증)
• Observability 도구 아님 (로그 뷰어가 아니라 pass/fail 판정기)
• Eval 플랫폼 아님 (응답 품질이 아니라 실행 완결성 검증)