Bracket: Thư viện Python dùng hợp đồng để phán định tính trọn vẹn khi thực thi LLM agent

LLM agent thường báo rằng chúng đã "đọc tệp" hoặc "chạy test", nhưng trên thực tế đôi khi lại bỏ qua các bước đó. Các framework agent như LangGraph hay Google ADK hỗ trợ thực thi tốt, nhưng không xác minh liệu các bước cần thiết có thực sự được thực hiện hay không.

Bracket là một thư viện Python nhỏ nhằm lấp đầy khoảng trống này. Trong quá trình thực thi, nó thu thập bằng chứng như đọc tệp, thay đổi tệp, chạy lệnh, gọi LLM..., rồi đối chiếu với các điều kiện hợp đồng được định nghĩa trước để phán định pass/fail một cách máy móc. Việc phán định không do LLM thực hiện mà do các quy tắc được định nghĩa bằng mã đảm nhiệm.

Giải quyết những vấn đề sau

• Phát hiện trường hợp agent giả vờ đã sửa dù còn chưa đọc tệp (read-before-write)
• Cưỡng chế chèn các bước xác minh như "kiểm tra test đã pass" vào pipeline
• Lưu log thực thi để có thể phán định lại (replay) các lần chạy trong quá khứ khi quy tắc phán định thay đổi
• Thống nhất logic xác minh khi dùng kết hợp nhiều framework

Hồ sơ tích hợp sẵn

• code_change - bắt buộc read-before-write, tệp đã thay đổi, lệnh xác minh
• research - đọc tệp, lấy dữ liệu web, bằng chứng grounding
• file_task - tệp đã thay đổi, artifact được xuất ra
• text_answer - bằng chứng grounding

Mọi hồ sơ đều bao gồm các điều kiện "intent resolved" và "không có hard failure".

Người dùng mục tiêu và hiệu quả

• Nhà phát triển cần đưa pipeline agent lên production: biến các điều kiện như "tests pass" thành hợp đồng tường minh để ngăn hồi quy
• Các nhóm đang so sánh, đánh giá nhiều framework agent: có adapter cho LangChain/LangGraph/Google ADK nên vẫn giữ cùng một tiêu chí phán định dù thay framework
• Người vận hành pipeline eval/regression: có thể phán định lại hàng loạt các lần chạy trước đây bằng log JSON trong .bracket/runs/*

Cài đặt và ví dụ 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+, phần lõi không có phụ thuộc bên ngoài. Adapter cho LangChain/LangGraph/Google ADK được cài tùy chọn qua extras.

Bracket không hướng tới những điều sau

• Không phải sản phẩm thay thế framework agent (dùng cùng LangGraph, v.v.)
• Không phải guardrails (không lọc đầu vào/đầu ra mà xác minh quá trình thực thi)
• Không phải công cụ observability (không phải trình xem log mà là bộ phán định pass/fail)
• Không phải nền tảng eval (không đánh giá chất lượng câu trả lời mà xác minh tính trọn vẹn khi thực thi)