Bracket: ไลบรารี Python สำหรับตัดสินความครบถ้วนของการทำงานของ LLM agent แบบอิงสัญญา

LLM agent มักรายงานว่า "อ่านไฟล์แล้ว" หรือ "รันเทสต์แล้ว" แต่ในความเป็นจริงบางครั้งกลับข้ามขั้นตอนเหล่านั้นไป เฟรมเวิร์ก agent อย่าง LangGraph และ Google ADK ช่วยให้รันงานได้ดี แต่ไม่ได้ตรวจสอบว่ามีการผ่านขั้นตอนที่จำเป็นจริงหรือไม่.

Bracket คือไลบรารี Python ขนาดเล็กที่เข้ามาอุดช่องว่างนี้ โดยจะรวบรวมหลักฐานระหว่างการทำงาน (เช่น การอ่านไฟล์ การแก้ไขไฟล์ การรันคำสั่ง การเรียก LLM ฯลฯ) แล้วนำไปเทียบกับเงื่อนไขสัญญาที่กำหนดไว้ล่วงหน้า เพื่อให้ตัดสิน pass/fail ได้แบบเชิงกลไก ไม่ได้ให้ LLM เป็นผู้ตัดสิน แต่ใช้กฎที่นิยามไว้ในโค้ดเป็นผู้ตัดสิน

ปัญหาที่แก้ได้

• จับกรณีที่ Agent แก้ไขไฟล์ทั้งที่ยังไม่ได้อ่านมาก่อน (read-before-write)
• บังคับใส่ขั้นตอนตรวจสอบอย่าง "ยืนยันว่าเทสต์ผ่าน" เข้าไปใน pipeline
• เก็บ execution log ไว้ และเมื่อกฎการตัดสินเปลี่ยนก็สามารถนำการรันในอดีตกลับมาตัดสินใหม่ได้ (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 pipeline ขึ้น production: ทำเงื่อนไขอย่าง "tests pass" ให้เป็นสัญญาแบบชัดเจนเพื่อป้องกัน regression
• ทีมที่กำลังเปรียบเทียบและประเมินหลาย agent framework: มีอะแดปเตอร์สำหรับ LangChain/LangGraph/Google ADK จึงคงเกณฑ์การตัดสินแบบเดียวกันได้แม้เปลี่ยนเฟรมเวิร์ก
• ผู้ดูแล Eval/regression pipeline: สามารถนำ log JSON ใน .bracket/runs/* มาตัดสินการรันเก่าแบบเป็นชุดได้

การติดตั้งและตัวอย่าง 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+ และแกนหลักไม่มี dependency ภายนอก ส่วนอะแดปเตอร์ LangChain/LangGraph/Google ADK ติดตั้งแบบ extras ได้ตามต้องการ

สิ่งที่ Bracket ไม่ได้ตั้งใจจะเป็น

• ไม่ใช่ตัวแทน Agent framework (ใช้ร่วมกับ LangGraph เป็นต้น)
• ไม่ใช่ Guardrails (ไม่ได้กรองอินพุต/เอาต์พุต แต่ตรวจสอบกระบวนการทำงาน)
• ไม่ใช่เครื่องมือ Observability (ไม่ใช่ log viewer แต่เป็นตัวตัดสิน pass/fail)
• ไม่ใช่แพลตฟอร์ม Eval (ไม่ได้ตรวจคุณภาพคำตอบ แต่ตรวจความครบถ้วนของการทำงาน)