Mimari

Bir çekirdek, üç istemci

ivralo bir Python kütüphanesidir: src/ivralo/ altındaki çekirdek. Ajanlar, araçlar, depolama, incident'lar, job'lar, egress politikası; yapabildiği her şey oradadır. Çekirdeğin üstünde üç ince istemci bulunur:

Kural şu: istemcilerde hiçbir yetenek bulunmaz. İstemci ekranı çizer, girdiyi okur ve çekirdeği çağırır; iki istemcinin birden ihtiyaç duyduğu mantık çekirdeğe taşınır. Bu sınırı testler korur: çekirdek Typer ya da Textual olmadan import edilebilir, cli/ ve tui/ dışında hiçbir şey bir istemciyi import etmez ve her API route'u, diğer istemcilerin de çağırabildiği bir çekirdek fonksiyonunu çağırır. API'nin hiçbir şeyi ikinci kez yazmadan üçüncü bir istemci olarak eklenebilmesi bu sayede oldu.

   ivralo (cli)      ivralo (tui)      ivralo serve (api)
         \                 |                  /
          +---------- çekirdek ---------------+
          |  agents   tools   storage   incident   jobs   egress  ... |
          +-------------------------------------------------------+
                  |                                 |
           PostgreSQL (durum)              çalışma alanı (bir git repo'su)

Üç katman

Çekirdeğin içinde üç katman birbirinden ayrı tutulur:

Uzmanlık ajanın talimatlarında değil, skill'lerde birikir. Uzun bir talimat metni gerekse de gerekmese de yüklenir ve testler onu göremez; skill ise sürümlenebilir, kurulabilir, lint'ten geçirilebilir ve ölçülebilir. Ajan raftaki skill'lerin tek satırlık bir listesini görür ve bir skill'in tam metnini yalnızca bir görev gerektirdiğinde yükler; bağlamın orta boy bir yerel modele sığacak kadar küçük kalması bu sayede olur.

Ajanlar preset'lerden kurulur

Her ajan tek bir factory tarafından bir preset'ten kurulur: bir anahtar, görünen bir ad, bir yetki kümesi, ne işe yaradığını anlatan tek cümlelik bir ipucu, bir araç çağrısı sınırı ve Python kodunun dosya yazıp yazamayacağı. Preset'in kendine ait bir prompt'u yoktur. Her ajan skill rafının tamamını ve aynı ortak kuralları alır; yani bir ajanı diğerinden ayıran, ona ne söylendiği değil, neleri yapabildiğidir.

Kurulan her ajan üç şeyden oluşur: bir model, ayrı bir worker sürecinde çalışan bir Python runtime'ı ve skill rafı.

Hiçbir preset'e ait olmayan yerel bir skill kendi başına bir preset olur; yetkileri, kendi frontmatter'ında tanımlananlardır.

Ana ajan, konuştuğunuz ajandır. Ekibin bir bütün olarak yapabildiği her şeye sahiptir; yalnızca hesap okumaları (Google, GitHub, veritabanları) ve incident raporu yazmak hariçtir. Onay kuralları ve sınırları herkesinkiyle aynıdır. Bir isteği kendisi yapabiliyorsa kendisi cevaplar; işi ancak temiz bir bağlam ya da daha dar bir yetki gerektiğinde devreder: bir uzmana ya da bir instance'a. Instance, bir görev tanımı ve kendi bağlamıyla açılan, sonunda bir rapor döndüren bir preset kopyasıdır. Bir instance hiçbir zaman onu açandan daha fazla yetkiye sahip olamaz. IVRALO_MAIN_GRANTS ana ajanın yetkilerini daraltır; hiçbir şey genişletemez.

Yetki, code.edit, shell.full ya da git.commit gibi adı olan bir izindir. Her ajanın sekiz yetkilik bir temel kümesi vardır (Python, çalışma alanındaki dosyaları okumak ve yazmak, size soru sormak, bir ekip arkadaşına soru sormak ya da iş devretmek, yapılandırılmış bir veritabanını okumak, stok fotoğraf indirmek). Preset'ler buna ekleme yapar; Investigator ise bir kısmından vazgeçer. Tam liste Yetkiler ve ön ayarlar sayfasında.

Modlar birer yetki kümesidir

Geliştirici modu ve sunucu modu iki ayrı program değildir. Mod, başında kimsenin olmadığı, yani hiçbir şeyi onaylayacak kimsenin bulunmadığı bir run'ın sahip olduğu yetki kümesidir:

Mod yalnızca ortamdan ve ana dizindeki .env'den okunur, hiçbir zaman bir repo'nun .ivralo/.env'inden okunmaz; böylece bir repo kendine push yetkisi veremez.

Durum nerede tutulur

Konuşmalarla ilgili bütün durum PostgreSQL'de, ivralo şemasında tutulur: oturumlar, run geçmişi, uzun süreli hafıza, bilgi dizini (pgvector ile) ve job'lar. İkinci bir makineyi aynı veritabanına bağlarsanız aynı konuşmalar orada da görünür. Veritabanı sizin belirttiğiniz bir veritabanı, Docker'ın compose servisi ya da ivralo'nun ana dizin altında kurduğu bir küme olabilir; ayrıntılar PostgreSQL sayfasında.

Diskte ise yapılandırma ve çalışma alanının kendi çalışma dosyaları bulunur:

.ivralo/ klasörü .git/info/exclude'a eklenir; böylece içindekilerin hiçbiri bir commit'e girmez. Tam liste Durum sayfasında.

Paketler

Repo'daki CLAUDE.md dosyası kodun dizinidir; .claude/rules/ altında her alan için bir dosya bulunur. Yapının neden böyle olduğu karar kayıtlarında anlatılıyor; bkz. Kararlar.