Dokümantasyon / Katkı
Kararlar
ivralo'da, nedenini bilmeyen birini şaşırtacak her karar kısa bir kayıt olarak yazılır. Bu sayfada bu kayıtların ne olduğu, nasıl okunduğu ve ivralo'yu çalıştırıyorsanız hangilerinin en önemli olduğu anlatılıyor.
Karar kaydı nedir
Mimari karar kaydı (ADR), tek bir kararı ve bu kararın neden alındığını anlatan kısa bir dosyadır. ivralo'da bir karar şu üç koşulu sağlıyorsa ADR'ı yazılır:
- geri dönmek zordur;
- bağlamı bilmeyen birini şaşırtır;
- diğer seçeneğin de artıları olduğu gerçek bir ödünleşimden çıkmıştır.
Bir kayıt bir ile üç cümle arasındadır; bazen kısa bir sonuçlar listesi de içerir. Kararı uygulayan kodla aynı pull request'te gelir; böylece neden ile değişiklik birlikte merge edilir. Kod yorumları ve kılavuz, kayıtlara "ADR 0113" gibi numarasıyla atıf yapar.
Nerede bulunurlar
Kayıtlar repo'da docs/adr/ altındadır. Her biri ayrı bir Markdown dosyasıdır, NNNN-slug.md biçiminde adlandırılır ve alındıkları sırayla numaralanır. main üzerinde 169 kayıt var. Repo özeldir; erişim için kemalcalak@gmail.com adresine yazabilirsiniz.
Bir kayıt nasıl okunur
---
status: accepted
supersedes: 0051 (the table half; the reference syntax and the announcement stand)
---
# 0056 - The provider list is agno's, discovered, not written - and the embedder is chosen the same way
A model is named ``<package>[.<Class>]:<model>`` where the package is a
directory under `agno.models` ...
- Başlık kararın kendisidir, tek cümle halinde. Yalnızca başlıkları okumak bile tasarımın büyük kısmını anlatır.
- Gövde nedenini anlatır: ne seçildiğini, neye tercih edildiğini ve bedelinin ne olduğunu.
- status, karar alındığında
acceptedolur. Yerine yenisi gelen bir kaydın durumu değişmez; bunu size yerine geçen kayıt söyler. - Bir kaydın kararı değiştirilmek için hiçbir zaman düzenlenmez. Bir kararı geri almak için onun yerine geçen yeni bir kayıt yazılır; eski kaydın numarası yeni kaydın frontmatter'ında ya da ilk cümlesinde geçer. Çoğu zaman eski kaydın yalnızca bir kısmı değiştirilir ve yeni kayıt, yukarıdaki örnekte olduğu gibi, hangi kısmın geçerli kaldığını belirtir.
Yani bir kararın hâlâ geçerli olup olmadığını öğrenmek için onun numarasını anan daha sonraki bir kayıt var mı diye bakın. Örneğin ADR 0051, embedding'lerin Ollama'da kalacağını söylüyordu; ADR 0056 bu kısmın yerine geçti ve embedder'ın herhangi bir sağlayıcı olabilmesini sağladı. 0051'deki, barındırılan bir modelin her zaman duyurulacağı kuralı ise hâlâ geçerli.
Kayıt ile kod çeliştiğinde çalışan şey koddur. Kayıt, kodun ne yapmak için yazıldığını ve nedenini anlatır.
ivralo'yu çalıştırırken en önemli kararlar
| ADR | Karar | Kısaca |
|---|---|---|
| 0004 | Konuşmalarla ilgili bütün durum PostgreSQL'de tutulur | Oturumlar, run'lar ve hafıza yerel dosyalarda değil, sizin veritabanınızdadır |
| 0026 | Web varsayılan olarak açıktır, anahtar gerektirmez ve belgeler dışarı çıkmaz | Dışarı yalnızca arama sorgusu çıkar; arama için anahtar gerekmez |
| 0036 | Span'ler makineden yalnızca sizin ayarladığınız bir endpoint üzerinden çıkar | IVRALO_OTEL_ENDPOINT bir collector göstermedikçe tracing kapalıdır |
| 0052 | Bir uzmanın Python kodu ayrı bir worker sürecinde çalışır | Zaman aşımı, bellek sınırı ve erişebileceği hiçbir kimlik bilgisi yok |
| 0056 | Sağlayıcı listesi agno'nundur; elle yazılmaz, keşfedilir | Model ve embedder için agno'nun bütün sağlayıcıları kullanılabilir |
| 0075 | Çekirdek arayüzden bağımsızdır; hiçbir yetenek bir istemcide bulunmaz | Komut satırı, oturum ve API aynı çekirdeği çağırır |
| 0113 | Tek bir egress politikası vardır ve her çıkışta uygulanır | Web, tarayıcı, worker ve shell için tek kural; kesin bir sınır değil, bir korkuluk |
| 0115 | Bir incident'ın olguları hesaplanır, sonucuna ise bir kapı karar verir | Kod sayar, bir ekip üyesi yorumlar, sonuca kod karar verir |
| 0116 | İstemciler çekirdekle tek bir yerel API üzerinden konuşur; API varsayılan olarak kapalıdır | Loopback'te, token arkasında çalışan ivralo serve |
| 0128 | Bir turun düzenlemeleri tek bir changeset olabilir | Hazırlanır, hazırlanan ağaçta doğrulanır, tek parça halinde uygulanır ya da atılır |
| 0130 | Bir çalışma alanının tanımları ancak bir kişi klasörü güvenilir saydıktan sonra çalışır | Bir repo'nun komutları ve ayarları sizin "evet" demenizi bekler |
| 0149 | ivralo'nun kendi sırları hiçbir zaman bir modele ya da bir cevaba ulaşmaz | ivralo'nun tuttuğu anahtarlar ve parolalar, model herhangi bir şeyi okumadan önce maskelenir |
| 0155 | ivralo yalnızca tek tür branch push eder | Açtığı taslak pull request için kendi açtığı branch'i; hiçbir zaman merge etmez |
| 0157 | Araçlar ana ajandadır; ana ajan yalnızca temiz bir bağlam ya da daha dar bir yetki için iş devreder | İşin çoğunu, aynı onay kurallarıyla tek bir ajan yapar |
| 0167 | Barındırılan bir modelle yapılan incident incelemesi, tanımlayıcıların maskelenmesini gerektirir | Kanıt barındırılan bir modele yalnızca yer tutucular olarak ulaşır |
Bunların nasıl bir araya geldiği Mimari sayfasında, gizlilikle ilgili kararların ayrıntıları ise Makineden neler çıkar sayfasında anlatılıyor.