Bracket: pustaka Python untuk menilai kelengkapan eksekusi agent LLM berbasis kontrak

Agent LLM sering melaporkan "sudah membaca file" atau "sudah menjalankan tes", tetapi dalam kenyataannya kadang melewati langkah tersebut. Framework agent seperti LangGraph dan Google ADK dapat mengeksekusi dengan baik, tetapi tidak memverifikasi apakah langkah yang diperlukan benar-benar telah dilalui.

Bracket adalah pustaka Python kecil yang menutup celah ini. Selama eksekusi, ia mengumpulkan bukti seperti pembacaan file, perubahan file, eksekusi perintah, panggilan LLM, dan lainnya, lalu membandingkannya dengan syarat kontrak yang telah didefinisikan sebelumnya untuk secara mekanis menentukan pass/fail. Yang menilai bukan LLM, melainkan aturan yang didefinisikan dalam kode.

Menyelesaikan masalah berikut

• Menangkap kasus saat agent berpura-pura memodifikasi file tanpa pernah membacanya terlebih dahulu (read-before-write)
• Menyisipkan secara paksa langkah verifikasi seperti "konfirmasi tes lulus" ke dalam pipeline
• Menyimpan log eksekusi dan menilai ulang (replay) eksekusi lama saat aturan penilaian berubah
• Menyatukan logika verifikasi saat menggunakan campuran beberapa framework

Profil bawaan

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

Semua profil mencakup kondisi "intent resolved" dan "tidak ada hard failure".

Pengguna sasaran dan manfaat

• Pengembang yang harus membawa pipeline agent ke produksi: menjadikan syarat seperti "tests pass" sebagai kontrak eksplisit untuk mencegah regresi
• Tim yang sedang membandingkan dan mengevaluasi beberapa framework agent: tersedia adaptor LangChain/LangGraph/Google ADK sehingga kriteria penilaian yang sama tetap terjaga meski framework diganti
• Operator pipeline eval/regression: log JSON di .bracket/runs/* memungkinkan penilaian ulang massal atas eksekusi sebelumnya

Instalasi dan contoh 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+, inti tanpa dependensi eksternal. Adaptor LangChain/LangGraph/Google ADK dapat dipasang secara opsional lewat extras.

Hal yang tidak dituju Bracket

• Bukan pengganti framework agent (digunakan bersama LangGraph dan lainnya)
• Bukan guardrails (bukan pemfilteran input/output, melainkan verifikasi proses eksekusi)
• Bukan alat observability (bukan penampil log, melainkan penilai pass/fail)
• Bukan platform eval (bukan kualitas respons, melainkan verifikasi kelengkapan eksekusi)