Bracket: LLM agent çalışma bütünlüğünü sözleşme tabanlı olarak değerlendiren Python kütüphanesi

LLM agent’lar "dosyayı okudum", "testleri çalıştırdım" diye rapor verir; ancak gerçekte bu adımları atladıkları durumlar olabilir. LangGraph, Google ADK gibi agent çerçeveleri yürütmeyi iyi yapar ama gerekli adımların gerçekten geçilip geçilmediğini doğrulamaz.

Bracket, bu boşluğu dolduran küçük bir Python kütüphanesidir. Çalışma sırasında kanıtları (dosya okuma, dosya değiştirme, komut çalıştırma, LLM çağrıları vb.) toplar ve bunları önceden tanımlanmış sözleşme koşullarıyla karşılaştırarak pass/fail sonucunu mekanik olarak belirler. Kararı LLM vermez; kodla tanımlanmış kurallar verir.

çözdüğü problemler

• Agent’ın dosyayı hiç okumadan değiştirmiş gibi davranmasını yakalar (read-before-write)
• "Testlerin geçtiğini doğrulama" gibi doğrulama adımlarını pipeline içine zorunlu olarak enjekte eder
• Çalışma günlüklerini saklar ve karar kuralları değiştiğinde geçmiş çalışmaları yeniden değerlendirebilir (replay)
• Birden fazla çerçevenin birlikte kullanıldığı durumlarda doğrulama mantığını birleştirir

Yerleşik profiller

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

Tüm profillerde "intent resolved" ve "hard failure yok" koşulları bulunur.

Hedef kullanıcılar ve etkisi

• Agent pipeline’larını production’a almak zorunda olan geliştiriciler: "tests pass" gibi koşulları açık sözleşmelere dönüştürerek regresyonları önleme
• Birden fazla agent framework’ünü karşılaştıran/değerlendiren ekipler: LangChain/LangGraph/Google ADK adaptörleri sayesinde framework değişse bile aynı değerlendirme ölçütlerini koruma
• Eval/regression pipeline işletmecileri: .bracket/runs/* JSON günlükleriyle geçmiş çalışmaları toplu olarak yeniden değerlendirebilme

Kurulum ve örnek 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+, çekirdek kısmında harici bağımlılık yok. LangChain/LangGraph/Google ADK adaptörleri extras olarak isteğe bağlı kurulabilir.

Bracket’in amaçlamadığı şeyler

• Agent framework’lerinin yerine geçen bir ürün değil (LangGraph vb. ile birlikte kullanılır)
• Guardrails değil (girdi/çıktı filtreleme değil, yürütme sürecini doğrulama)
• Bir observability aracı değil (log görüntüleyici değil, pass/fail karar vericisi)
• Bir eval platformu değil (yanıt kalitesini değil, çalışma bütünlüğünü doğrular)