avlu

Ajan çalışma ortamı için araç kutusu: alt ajan akışına sert kapı (sahiplik, test dokunulmazlığı, "bitti" kanıtı, sır temizleme), not kasası için hafıza araması ve ölçümü, ve bunların hepsini model yargısı olmadan ölçülebilir bir puana bağlayan açık eval çatısı. Yalnız standart kütüphane, Python 3.11+.

Eski çalışma adı sistem-oss'tu; Python paketi sistem_oss ve CLI adları (sistem-puani, sistem-anlam) değişmedi.

English summary. avlu is a small, dependency-free Python toolkit for an AI-agent working environment. It has three parts: (1) a hard gate for multi-agent orchestration (sistem_oss.akis: ownership checks, "existing tests must not change", frozen acceptance tests, verified "done" evidence, secret scrubbing of the environment, a single source of truth for writer/reviewer model profiles); (2) memory retrieval and its measurement for a markdown note vault (sistem-anlam: embedding search with lexical RRF fusion; sistem-puanla: hit@k / MRR / negative-set violations over a fixed question set); (3) an open eval framework that turns deterministic measurements into a 0-100 score and a badge (sistem-puani), with tests instead of model judgement, frozen thresholds, and user-defined metrics as [[olcut]] plugins in an avlu.toml (any-language command that prints JSON). Today the built-in 17 metrics still read one person's local files; the plugin format and the equality test ("no avlu.toml → identical score") are in place, adapters and shared data are on the roadmap. Documentation and identifiers are Turkish.

Bu ne, kime, neden

• Ne: Üç parça, tek paket.
  1. Orkestrasyon kapısı (sistem_oss.akis): bir yazıcı ajanın worktree'sinde sahiplik dışı dosya değişti mi, mevcut bir test dosyasına dokunuldu mu, dondurulmuş kabul testi değişti mi, "bitti" kanıtı güncel ve çıkış kodu 0 mı, rapor sözleşmedeki her maddeyi gerçek komut çıktısıyla karşılıyor mu. İhlal varsa reddeder, uyarmaz. Alt sürece giden ortamdan sırları temizler; yazıcı ve reviewer model profillerini tek tablodan çözer (aynı firma reviewer olamaz).
  2. Hafıza araması ve ölçümü (sistem-anlam, sistem-puanla, sistem-karne, sistem-ayir): not kasasında embedding araması, sözcük aramasıyla RRF füzyonu; sabit soru setinde hit@k, MRR, olumsuz set ihlali; not kalite karnesi.
  3. Açık eval çatısı ve puan (sistem-puani): ölçümleri 0-100 puana ve rozete çevirir. Puan model yargısı içermez; eşikler donmuştur, ölçüt gevşetilerek puan yükseltilemez. Kendi ölçütünü avlu.toml içinde tanımlarsın, komutun JSON basar, puana girer.
• Kime: Alt ajanlarla iş yaptıran ve "yazıcı testleri değiştirdi mi, gerçekten bitti mi" sorusuna betikle cevap isteyenlere; not hafızasının geri getirme kalitesini sayıyla izlemek isteyenlere; "bence 7/10" yerine her seferinde yeniden hesaplanabilen bir ortam puanı isteyenlere. Hazır, her makinede çalışan bir servis değildir; kendi ortamına bağlarsın.
• Neden: Ajan ortamları (hook'lar, orkestrasyon kuralları, hafıza araması) sessizce bozulur ve yazıcı model kırmızı testi "düzeltmenin" en kısa yolunu bulur. Kapı bunu derleyici gibi reddeder; puan bozulmayı görünür kılar; bir model hakemine bırakılan puan ise ölçümü anlamsızlaştırır (TANIM.md).

Durum: erken sürüm (v0.x). Tanım ve donmuş eşikler: TANIM.md.

Hızlı başlangıç

Gereksinim: Python 3.11+. Çalışma zamanı bağımlılığı yok (geliştirme için pytest, coverage, ruff).

python -m pip install -e ".[dev]"
python -m pytest -q
python -m ruff check src tests
sistem-puani --json
sistem-puani --dogrula

• python -m pytest: ağsız testler (731 test; tam koşu yaklaşık 2 dakika). Kaynak kopyaları bulunmayan makinede altı eşitlik testi atlanır (skip).
• sistem-puani: ölçüm kaynakları (hafıza sonuçları, vaka seti, sır kapısı, saldırı korpusu) makinede yoksa ilgili ölçüt "ölçüm yok" yazar ve 0 puan alır; komut yine 0 ile çıkar. Temiz bir makinede toplam puan bu yüzden düşük çıkar: bu hata değil, ölçülemeyenin 0 sayılmasıdır. --json her ölçütün değerini ve açıklamasını verir; çıktı ayrıca olcumler/ altına yazılır (git'e girmez). Kapı için gitleaks PATH'te olmalıdır, yoksa kapı "kapalı" sayılır ve toplam puan 0 olur.
• sistem-puani --dogrula: ölçüm yapmaz; repodaki PUAN.json ile rozet.json dosyalarının birbiriyle ve şemayla tutarlı olduğunu denetler (CI bunu koşar).
• sistem-puani --json --avlu ornek/avlu.toml: örnek ölçüt eklentisini puana katar (aşağıda "Kendi ölçütünü ekle").
• Embedding sağlayıcısına giden tek komut grubu sistem-anlam dizin|ara'dır ve API anahtarı gerekir (aşağıdaki "Anlam araması" bölümü). Yukarıdaki komutların hiçbiri ücretli API çağırmaz.

Orkestrasyon kapısı (sistem_oss.akis)

Bir işi şeritlere bölüp yazıcı, bağımsız reviewer ve doğrulayıcıya dağıtan bir akışın kod tarafı. Akışın kabuk betiği (şerit açma, model çağırma, ledger) bu repoda değildir; burada kabuğun çağırdığı kararlar ve kapı vardır. Yalnız standart kütüphane; git komutlarını çağırır. Dosya yazan yalnız iki yer vardır: kabul (hash dondurma) ve rapor --kaydet (geçerli raporun kopyası ve rapor.log).

Dosya	Ne yapar
akis/kapi.py	Sert kapı. denetle: tabana göre değişen dosyalar sahiplik glob'u dışındaysa, mevcut bir test dosyası değişmiş ya da silinmişse, dondurulmuş kabul testi değişmişse ihlal. kabul: kabul testlerini içerik hash'iyle dondurur. rapor: yazıcı/reviewer raporunu şemaya göre denetler ve sözleşme maddelerini gerçek komut çıkışıyla karşılaştırır. Çıkış 0 temiz, 1 ihlal, 2 denetlenemedi (fail-closed). assume-unchanged / skip-worktree ile gizlenmiş dosyaları da yakalar.
akis/bitti.py	"Bitti" kanıtı. Sözleşmedeki ```bitti bloğunu ya da bitti.cmd'yi okur; kanıt logunun komut hash'i, worktree içerik özeti ve çıkış kodu güncel mi bakar. Komut çalıştırmaz: yazıcının "testler geçti" demesi değil, kabuğun koştuğu komutun kaydı sayılır.
akis/gizli.py	Sır temizleme. Alt sürece verilecek ortamdan, değeri sır gibi görünen (bilinen anahtar kalıbı ya da yüksek entropili uzun dize) ya da adı key/token/secret/passw/credential/auth içeren değişkenleri çıkarır; açıkça izin verilenler korunur. Girdi sözlüğünü değiştirmez, temizlenmiş kopya döndürür.
akis/profil.py	Profil tablosu, tek kaynak. Yazıcı/reviewer profilleri (firma, model, efor, roller, seçilebilirlik); efor tavanı high. profil_coz adı çözer (bilinmeyen ya da seçilemez profil hata verir), reviewer_adaylari aynı firmayı dışlar, profil_tablosu kabuğun bastığı tabloyu üretir.

python -m sistem_oss.akis.kapi denetle <iş dizini> <worktree>
python -m sistem_oss.akis.kapi kabul   <iş dizini> <worktree> <test yolu>...
python -m sistem_oss.akis.kapi rapor   <iş dizini> <rapor.md> <bitti_gecerli 0|1> [madde.log|-] [yazici|reviewer]

Bunların yanında kabuğun kullandığı yardımcı alt komutlar vardır: madde-kos, madde-cmd, kapsam-disi, bicim, sozlesme-dogrula; rapor için --kaydet bayrağı. Argümansız ya da hatalı çağrı kullanım metnini basıp 2 ile çıkar.

<iş dizini> şeridin kayıt klasörüdür (sahiplik glob'ları, taban sha'sı, dondurulmuş kabul hash'leri, sözleşme). Kapının test takımı (tests/test_akis_*.py) yazıcının kapıyı atlatma yollarını (test silme, yeniden adlandırma, gizli index bayrağı, boş bitti bloğu, çift numaralı sözleşme maddesi) birer vaka olarak tutar. Ortam değişkenleri: AKIS_BITTI_SURE, AKIS_KAPI_ESKI (aşağıdaki tablo).

Anlam araması (sistem-anlam)

Beyin vault'undaki notlar (knowledge/, notes/, tasks/; arşiv, emekli ve başka notun supersedes'i ile eskimiş notlar hariç) ~1200 karakterlik parçalara bölünür, embedding vektörleri <vault>/.tmp/beyin-anlam/ altında önbelleğe alınır ve sorgu kosinüs benzerliğiyle aranır. --karma beyin context (sözcük) sırası ile embedding sırasını RRF (k=60) ile birleştirir; iki liste de --k uzunluğuna kesilir. Yalnız standart kütüphane; beyin'in kendi koduna dokunmaz.

sistem-anlam dizin --vault <vault>
sistem-anlam ara "<soru>" --vault <vault> [--project P] [--k 10] [--karma] [--json]
sistem-anlam durum --vault <vault>

Ortam değişkenleri (tam liste aşağıdaki tabloda):

• BEYIN_VAULT: --vault verilmezse vault kökü. İkisi de yoksa komut açık hatayla durur.
• BEYIN_ANLAM_SAGLAYICI: nebius (varsayılan, Qwen/Qwen3-Embedding-8B, anahtar NEBIUS_API_KEY) ya da gemini (gemini-embedding-2, 1536 boyut, anahtar GEMINI_API_KEY). Her sağlayıcının önbelleği ayrıdır (vektorler.json / vektorler-gemini.json). Anahtar yoksa ağ çağrısı yapılmaz, açık hata verilir; anahtar hiçbir hata metnine ya da çıktıya yazılmaz.
• BEYIN_ANLAM_BAGLAM: yalnız gemini sağlayıcısında; 0 değilse her yeni parçanın başına gemini-3.5-flash-lite ile üretilen 1-2 cümlelik bağlam (Bağlam: ...) eklenir (contextual retrieval); cümleler <vault>/.tmp/beyin-anlam/baglam.json içinde saklanır, notlar değişmez.

Gemini önek kalıbı: belge parçaları title: <başlık> | text: <gövde>, sorgu task: search result | query: <soru> biçiminde gönderilir (Nebius'ta sorguya Instruct: ... Query: talimatı eklenir, belge ham gider). visibility: private ya da remote_allowed: false notlar ve sır kalıbı içeren sorgular uzak servise gönderilmez. --json çıktısı: {"records": [{"source", "score"}], "yontem": "anlam"|"karma"[, "degraded": true]}.

Kaynak modül ~/beyin/araclar/beyin-anlam; kopya kaynakla eşitlik testiyle korunur (tests/test_anlam_esitlik.py, kaynak yoksa skip). Testler ağsızdır (sahte embed, geçici vault).

Hafıza ölçümü (sistem-puanla, sistem-karne, sistem-ayir)

Sabit bir JSONL soru setini beyin context (ya da sistem-anlam ara) çıktısının tekilleştirilmiş kaynak sırasıyla karşılaştırır; sistem puanındaki hafiza_* ölçütlerinin kaynağı bu sonuçlardır. Yalnız standart kütüphane; beyin'in kendi koduna dokunmaz, context çağrıları --no-sync --json ile vault'a yazmaz.

sistem-puanla --vault <vault> --sorular sorular.jsonl [--sonuclar DIR] [--k 5] [--set gerileme|yetenek]
              [--yontem beyin|anlam|karma|rerank] [--tekrar N] [--etiket AD] [--karsilastir] [--sync] [--jev]
sistem-karne  --vault <vault> [--cikti DIR] [--puan-sonucu SONUC.json] [--bugun YYYY-MM-DD]
sistem-ayir   --sorular sorular.jsonl --sonuc SONUC.json [--sonuc ...] [--k 5] [--yeniden]

--vault verilmezse BEYIN_VAULT okunur; ikisi de yoksa komut açık hatayla durur. Sonuçlar --sonuclar (karne: --cikti) klasörüne YYYY-MM-DD-HHMM[-etiket].json olarak yazılır; varsayılan <vault>/araclar/beyin-puan/sonuclar. --yontem anlam|karma paket içindeki sistem_oss.anlam betiğini çalıştırır (önce sistem-anlam dizin gerekir); rerank vault'taki araclar/beyin-hibrit/ara.py betiğini bekler. Soru setleri ve sonuç dosyaları kişisel not içeriği taşır; repoya girmez. Biçim örneği sentetiktir: src/sistem_oss/veri/sorular.ornek.jsonl.

Soru satırı (JSONL, UTF-8):

Alan	Zorunlu	Anlam
id	evet	tekil metin kimliği
soru	evet	context'e verilen sorgu
proje	hayır	--project değeri; null ya da yok ise projesiz arama
beklenen	evet	doğru kabul edilen notların vault içi, ileri eğik çizgili yolları; yalnız olumsuz soruda boş
yasak	hayır	ilk k'de görünmemesi gereken yollar (eskimiş, arşiv, private notlar)
tur	evet	kelime (anahtar sözcük eşleşmesi) ya da anlam (başka sözcüklerle sorulmuş)
set	hayır	gerileme (bugün geçen; ≈%100 kalmalı) ya da yetenek (henüz geçilemeyen; gelişme alanı)

Ölçütler (yollar NFC + casefold ile karşılaştırılır, çıktıda özgün yazım korunur):

• hit@k: beklenen notlardan en az biri tekilleştirilmiş ilk k kaynak içindeyse 1, değilse 0; hit@1, hit@3 ve hit@k birlikte verilir. Genel, kelime ve anlam grupları için ortalama alınır.
• MRR: ilk doğru kaynağın sırasının tersi (1/sıra); bulunamazsa 0. Grup ortalaması.
• Olumsuz ihlal: yasak listesindeki bir yol ilk k'de göründüyse o soru ihlaldir; özet olumsuz.ihlal ihlalli soru sayısıdır. Yalnız olumsuz sorular (beklenen boş) isabet ortalamasına girmez.
• Hatalı: alt süreç hatası, zaman aşımı ya da geçersiz JSON; ortalamadan düşer, uyarı basılır. Tüm sorular hatalıysa ya da bir olumsuz soru hatalıysa çıkış kodu 1'dir.
• Neden sınıfı (başarısız soru başına, özet nedenler): hata; yasak_ihlal; siralama (doğru not aday kümesindeydi, ilk k'ye çıkmadı); aday_yok (arama aşaması notu hiç getirmedi); sira_dusuk (aday kümesi bilinmiyor, not listede ama k'nin altında). Aday kümesi veren yöntemlerde asama özeti tavanı (aday kapsaması) ve son sıra hit@k'yi ayrı gösterir.
• --tekrar N: aynı seti N kez koşar; hit@k / MRR ortalama ve aralığı, koşudan koşuya sonucu değişen kararsiz sorular. İsabet ilk koşudan, ihlal ve hata tüm koşulardan birleştirilir.
• --karsilastir: aynı klasördeki önceki sonuçla yalnız ortak ve iki koşuda da hatasız soruları, mevcut k ile yeniden hesaplayarak karşılaştırır.

sistem-ayir soru setini sonuç dosyalarına göre bölümler: verilen tüm sonuçlarda ilk k'de, hatasız ve ihlalsiz bulunan soru gerileme'ye geçer ("mezun olur"); gerileme setindeki soru bir koşuda kaçırılsa da otomatik düşmez (o bir gerileme sinyalidir, --yeniden baştan sınıflar); olumsuz sorular hep gerilemedir.

sistem-karne vault'taki knowledge/ ve notes/ notlarına açıklanabilir kalite puanı verir: doğrulama (facts.dogrulama), kullanım (receipt anılışı), bağlantı (diğer notlardan wiki/yol anılışı), tazelik (son git commit ya da mtime) ve bulunabilirlik (puanla sonucundaki hit@k) sinyallerinin ağırlıklı toplamı; supersedes ile eskimiş ya da emekli status'lu not en çok 20 alır, supersedes döngüleri ve valid_to süresi geçmiş notlar işaretlenir (gecerlilik modülü). Hiçbir not değiştirilmez; karne-YYYY-MM-DD.json ve .md tablo yazılır.

Kaynak modül ~/beyin/araclar/beyin-puan; ortak.py (sistem_oss.ortak) anlam ve puanla paketlerinin ortak yardımcısıdır, tek kopyadır. Kopyalar kaynakla eşitlik testiyle korunur (tests/test_puanla_esitlik.py, kaynak yoksa skip). Testler ağsız ve alt süreçsizdir (sahte beyin çağrısı, geçici vault). Kaynaktaki auto_olc.py (beyin'in iç modüllerine bağlı auto_context deneyi) taşınmadı.

Eval çatısı ve puan (sistem-puani)

Her ölçüt doğrusaldır: taban değerde 0, hedef değerde tam puan, arası orantılı, dışı kırpılır. Ağırlıklar ve eşikler src/sistem_oss/veri/esikler.json içindedir. Puan = ağırlıklı toplam / toplam ağırlık × 100 (yerleşik 17 ölçütün ağırlığı 90 eder; eklenti ölçütleri payda ile birlikte büyür). Sır/kişisel veri kapısı bulgu verirse toplam puan 0 olur (kapı: gitleaks + kişisel veri taraması). Ölçülemeyen ölçüt 0 puan alır ve raporda "ölçüm yok" yazar.

Yerleşik 17 ölçüt (bugün tek bir ortamın dosyalarını okur; hangisinin nasıl taşınabilir olduğu docs/OLCUTLER.md içinde):

Alan	Ağırlık	Ölçütler	Veri nerede
Hafıza	20	gerileme ve yetenek setlerinde hit@5, olumsuz set ihlali	repo dışı: yerel arama ölçüm sonuçları ve soru seti
Güvenlik	18	sır kapısı test takımı, saldırı korpusunda engelleme, zararsız korpusta yanlış red	repo dışı: sır kapısı hook'u, testleri, saldırı korpusu; zararsız korpus (118 komut) repoda
Orkestrasyon	15	akış test takımı, reviewer yakalama (etiketli vaka), şerit koşu hata oranı	repo dışı: akış kapı testi ve vaka sonuç dosyası
Teslim	7	altyapı/ürün commit oranı (son 7 gün)	repo dışı: oran ölçen betik
Bakım	8	lint hatası (ruff), skill doğrulayıcı hatası, izlenen .bak/.log/geçici dosya	kısmen repoda (ruff, geçici dosya); skill doğrulayıcı repo dışı
OSS hazırlığı	22	CI'da temiz klon (Windows + Linux), test kapsamı, README quickstart CI'da, LICENSE + NOTICE + CONTRIBUTING + sürüm etiketi	repoda ve GitHub Actions'ta (gh gerekir)

Ölçüm kurallarının ayrıntısı (tazelik penceresi, canlı yöntem süzgeci, kapı) TANIM.md içindedir.

Kendi ölçütünü ekle (avlu.toml)

Repo kökündeki avlu.toml (ya da --avlu <yol>) içindeki her [[olcut]] girdisi puana girer:

[[olcut]]
id = "ornek_oran"
ad = "Örnek oran"
alan = "Örnek"
agirlik = 10
taban = 0
hedef = 1
komut = ["{python}", "olcut_ornek.py"]   # argv; kabuk yok; {python} = sys.executable
alan_yolu = "ornek.oran"                 # komutun stdout'a bastığı JSON içinde noktalı yol
# zaman_asimi = 60                       # saniye; isteğe bağlı (varsayılan 60, üst sınır 86400)

id, alan, agirlik, taban, hedef, komut ve alan_yolu zorunludur; ad yoksa id kullanılır. Komut herhangi bir dilde olabilir; cwd TOML dosyasının klasörüdür. Zaman aşımı, sıfırdan farklı çıkış, JSON olmayan çıktı, olmayan alan ya da sayı olmayan değer istisna değil "ölçüm yok" sayılır (0 puan, açıklamada nedeni). Alt süreç ağacı zaman aşımında Windows'ta Job object, POSIX'te süreç grubuyla kapatılır. Çalışan örnek: ornek/avlu.toml ve ornek/olcut_ornek.py. Eşitlik kuralı: avlu.toml yokken puan, ham, normalizasyon ve ölçüt satırları eklenti öncesiyle bire bir aynıdır (tests/test_kabul_eklenti.py). Eklenti kimliği yerleşik bir ölçütle çakışırsa ya da yapılandırma bozuksa komut 2 ile çıkar. avlu.toml repoda bulunan bir komutu çalıştırdığı için yalnız güvendiğin repoda koş (TANIM.md, v0.3 notu).

Rozet

Rozet, sistem-puani --rozet ile yerelde alınan ölçümün özetidir (PUAN.json, rozet.json). CI ortamında hafıza sonuçları, vaka seti ve saldırı korpusu bulunmadığı için CI puan ölçmez; sistem-puani --dogrula ile bu iki dosyanın tutarlılığını denetler. PUAN.json içindeki olcum_yok ve olculen_puan bilgi alanıdır (ölçülemeyen ölçütler; yalnız ölçülebilenlerle hesaplanan değer), puanı değiştirmez. Rozet rengi: 85 ve üstü yeşil, 60 ve üstü sarı, altı kırmızı. Rozet adresindeki hesap/repo adı, repo yeniden adlandırılırsa güncellenmelidir.

Yol haritası (v0.3)

Yön kararı 2026-11-07'de verildi, 2026-11-08'de yeniden onaylandı: avlu, bir kişinin ortamına bağlı 17 ölçütten herkesin kendi evalini tanımlayıp koşturduğu açık bir çatıya dönüşür (şirketlerin iç eval'leri gibi). Çekirdek ortak kalır: puanlama matematiği, kapı, rozet, eşitlik testi, "ölçüm yok" kuralı. Sıra:

1. 17 ölçütü üçe ayırma (taşınabilir / adaptörle taşınabilir / avlu verisi gereken): bitti, docs/OLCUTLER.md.
2. avlu.toml + ölçüt eklenti biçimi + eşitlik testi: bitti (v0.3.0, yukarıdaki bölüm).
3. Adaptörler (hafıza ara, orkestrasyon kos, güvenlik kapi, teslim repo listesi; docs/OLCUTLER.md): planlandı. Bugün yerleşik 17 ölçütün yolları puan.py içinde sabit kodludur.
4. Evrensel vaka seti (ekilmiş hatalı reviewer vakaları) ve vault'tan otomatik soru seti üreticisi: planlandı. Bugün zararsız komut korpusu (118 komut) dışında ortak veri repoda yok.
5. İkinci bir kullanıcı ortamında koşu; "ölçüm yok" dağılımının gerçek testi: planlandı. İki katmanlı puan (profil + puan) de bu adımla gelir; bugün rozet tek sayıdır.

Eşikler donmuştur (src/sistem_oss/veri/esikler.json); tanım değişiklikleri TANIM.md'ye tarihli notla ve sürümle girer, eşik gevşetilmez.

Paket içeriği

Modül	Ne yapar	Komut
sistem_oss.akis	orkestrasyon kapısı: sahiplik/test/kabul denetimi, "bitti" kanıtı, rapor şeması, sır temizleme, profil tablosu	`python -m sistem_oss.akis.kapi denetle
sistem_oss.anlam	not kasası için embedding araması ve sözcük araması ile RRF füzyonu	sistem-anlam
sistem_oss.puanla	hafıza soru seti ölçümü, not kalite karnesi, soru seti ayırma	sistem-puanla, sistem-karne, sistem-ayir
sistem_oss.puan, sistem_oss.eklenti	puan hesabı, rozet, sır ve kişisel veri kapısı, avlu.toml ölçüt eklentileri	sistem-puani (ya da python sistem_puani.py)

Ortam değişkenleri

Değişken	Okuyan	Varsayılan / anlam
AKIS_BITTI_SURE	sistem_oss.akis.kapi	sözleşme maddesi komutlarının zaman aşımı (varsayılan 15m; s/m/h/d ekleri)
AKIS_KAPI_ESKI	sistem_oss.akis.kapi	1 ise taban sha'sı ya da sahiplik dosyası olmayan eski şeritte hata yerine uyarı
BEYIN_VAULT	sistem-anlam	--vault verilmezse vault kökü; ikisi de yoksa komut hatayla durur
BEYIN_ANLAM_SAGLAYICI	sistem-anlam	nebius (varsayılan) ya da gemini
BEYIN_ANLAM_BAGLAM	sistem-anlam	yalnız gemini; 0 bağlam cümlesini kapatır (varsayılan açık)
NEBIUS_API_KEY	sistem-anlam (nebius)	embedding anahtarı; yoksa ağ çağrısı yapılmaz
GEMINI_API_KEY	sistem-anlam (gemini)	embedding ve bağlam cümlesi anahtarı; yoksa ağ çağrısı yapılmaz
SISTEM_OSS_OLCUM	sistem-puani	ölçüm çıktı klasörü (varsayılan: repo kökünde olcumler/)
SISTEM_OSS_SALDIRI	sistem-puani	saldırı korpusu dosyası (varsayılan: ~/.ai/korpus/saldiri.jsonl; repoya girmez)
GITLEAKS	sistem-puani	gitleaks çalıştırılabilir adı ya da yolu (varsayılan: gitleaks, PATH'ten)

Durum / sınırlar

Kapı, anlam araması ve hafıza ölçümü her ortamda çalışır; yerleşik puan ölçütleri bugün tek bir ortamın dosyalarını okur. Genel amaçlı bir kütüphane ya da hazır bir "ajan puanlama servisi" değildir. Kod bir kişinin kendi makinesindeki düzenden çıkarıldı ve bunun izleri duruyor:

• Ölçümlerin bir kısmı yerel dosyalara bağlıdır. Hafıza, sır kapısı, saldırı korpusu, reviewer vaka sonuçları, altyapı/ürün oranı ve skill doğrulayıcı ölçütleri varsayılan olarak ev dizinindeki ~/.ai/ ve ~/beyin/ altındaki dosya ve betikleri okur; bunlar bu repoda yok. Bu dosyalar yoksa ilgili ölçüt "ölçüm yok" yazar ve 0 puan alır. Yalnız bu repo klonlanmış, ev dizininde hiçbir yerel veri olmayan bir makinede ölçülebilenler: lint (ruff), izlenen geçici dosya, test kapsamı, OSS dosyaları ve (gh ile repoya bağlıysa) CI; bu durumda toplam puan 100 üzerinden 34.4 çıkar (17 ölçütün 10'u "ölçüm yok"). Kendi ölçütlerini avlu.toml ile ekleyebilirsin; yerleşik 17 ölçütün yollarını değiştiren adaptör ise yoktur (yol haritası 3), bunun için puan.py içindeki toplayıcıları uyarlaman gerekir.
• Akışın kabuğu repoda değil. sistem_oss.akis kapı ve kararlardır; şerit açan, modeli çağıran ve ledger tutan kabuk betiği ayrı bir yerel araçtır. Kapıyı kendi orkestrasyonuna bağlamak için kapi.pynin beklediği iş dizini düzenini (sahiplik glob'ları, taban sha'sı, kabul hash'leri, sözleşme) kendin üretmen gerekir.
• Zararsız korpus ölçümü hook'u doğrulamaz. Yanlış-red ölçütü 118 komutu sır kapısı hook'una (~/.ai/hooks/sir_kapisi.py, repoda yok) verir ve reddedileni sayar. Hook makinede yoksa hiçbir komut reddedilmez ve ölçüt "0/118 yanlış red" ile tam puan alır. Bu ölçüt yalnız hook'un varlığı başka yerden bilindiğinde anlamlıdır.
• Rozet yerel ölçümdür. README'deki puan, proje sahibinin kendi makinesinde ölçülüp PUAN.json olarak commit'lenmiştir; CI yalnız bu dosyanın tutarlılığını doğrular, puanı yeniden üretemez. Aynı puanı üretmek için ilgili yerel veriye erişmek gerekir.
• Saldırı korpusu bilerek yayımlanmaz. Atlatma listesi olduğu için repoya girmez (.gitignore); yerelde SISTEM_OSS_SALDIRI ile gösterilir. Yayımlanan zararsız korpus yalnız yanlış-red oranını ölçer. Bu nedenle güvenlik alanındaki saldırı ölçütü bugün "ölçüm yok"tur (PUAN.json → olcum_yok).
• Puan 100 değildir. Eksik ölçütler PUAN.json içinde açıktır. Hedef eşikler esikler.json içinde donmuştur.
• Anlam araması Nebius ya da Gemini'ye ağ çağrısı yapar (ücretli API anahtarı gerekir); --karma modu vault'ta beyin'in beyin.py betiğini sözcük sırası için çağırır, yoksa tek yöntemle döner (degraded). Vault düzeni beyin'e (knowledge/, notes/, tasks/, ön bilgi alanları) özgüdür.
• Platform: CI'da Windows ve Linux denenir; macOS denenmedi.
• Kararlılık: belgeler ve kod tanımlayıcıları Türkçedir; v0.x arayüzleri haber verilmeden değişebilir.
• Etiketli vaka seti ve hafıza soru seti (sorular-v3) bu repoda yok.

Katkı

Kurallar ve geliştirme komutları: CONTRIBUTING.md. Sürüm notları: CHANGELOG.md.

Lisans

MIT. Atıflar: NOTICE.