Humindx Docs

Appearance

LLM Orkestrasyonu ve Ajan Yönetimi (LLM Orchestration) ​

Bu doküman, Humindx ekosistemindeki yapay zeka ajanlarının (Gölge, Ayna, Mentor vb.) nasıl yönetildiğini, model yönlendirme (routing) stratejilerini ve sohbet metinlerinin psikometrik verilere dönüşümünü sağlayan prompt mimarisini tanımlar.

Kapsam Uyarısı: Bu doküman, LLM'lerin prompt mühendisliğini, bağlam yönetimini (RAG) ve yapılandırılmış veri çıkarımını kapsar. Çıkarılan bu verilerin istatistiksel olarak nasıl ağırlıklandırılıp Big Five / RIASEC skorlarına dönüştüğü scoring-algorithms.md dosyasında anlatılmıştır.

1. Çift Yollu Model Yönlendirme (Dual-Path Model Routing) ​

Humindx'te her LLM çağrısı aynı model üzerinden yapılmaz. Hız, maliyet (Birim Ekonomisi) ve çıkarım derinliği arasındaki dengeyi sağlamak için Çift Yollu (Dual-Path) bir yönlendirme stratejisi kullanılır.

1.1. Konuşma Modeli (Hot Path) ​

  • Amaç: Kullanıcıya anında ve doğal bir sohbet deneyimi sunmak.
  • Model Seçimi: Gecikme süresi (latency) düşük ve maliyeti uygun modeller (örn. GPT-4o-mini, Llama 3 8B).
  • İşlem: Kullanıcının mesajına, ajanın personasına (Gölge, Mentor vb.) uygun tepkiyi saniyeler içinde verir. Psikometrik analiz yapmaz.

1.2. Çıkarım Modeli (Cold Path - Zero-Shot Inference) ​

  • Amaç: Biten bir senaryonun veya belirli bir mesaj sayısının ardından tüm transkripti analiz ederek psikometrik çıkarım yapmak.
  • Model Seçimi: Akıl yürütme (reasoning) kapasitesi en yüksek modeller (örn. Claude 3.5 Sonnet, GPT-4o).
  • İşlem: Arka planda asenkron çalışır. Transkripti okur ve önceden belirlenmiş bir JSON şemasında (Structured Output) trait kaymalarını döndürür.

Model Listesi Notu: Doküman boyunca kullanılan model isimleri (GPT-4o-mini, Claude 3.5 Sonnet vb.) 2026 itibarıyla geçerli örneklerdir. Kalıcı olan model isimleri değil, yetenek sınıflarıdır: Hız odaklı (Hot Path), Akıl Yürütme odaklı (Cold Path), Uzun Bağlam odaklı (RAG). Spesifik model seçimleri guides/architecture-decisions/ altında bir ADR ile sabitlenecektir.

2. Sistem Prompt Mimarisi ve Ajan Tipleri ​

Ajanların tutarlı davranmasını sağlamak için Sistem Prompt'ları katmanlı (layered) bir yapıda oluşturulur: [Temel Kurallar] + [Kullanıcı Bağlamı / RAG] + [Ajan Personası] + [Senaryo Hedefi]

2.1. Persona Şablonları (Persona Templates) ​

Ajan TipiPrompt Odak Noktası (Özet)Kullanım Amacı
Gölge (Shadow)"Kullanıcının [X] özelliğinin tam zıttısın. Eğer o uzlaşmacıysa (Agreeable), sen inatçı ve rekabetçisin. Amacın onu nazikçe provoke ederek stres toleransını ölçmek."Sınırları test etme, maskeleri düşürme.
Ayna (Mirror)"Kullanıcıyla aynı Big Five profiline sahipsin. Onun kullandığı kelime kalıplarını kopyala. Kör noktalarını ona kendi cümleleriyle göster."Öz-farkındalık (Self-reflection).
Mentor (Sage)"Tarihteki filozofların metinleriyle eğitilmiş bir bilgesin. Provoke etme, sadece Sokratik sorular sorarak kullanıcının çözüm bulmasını sağla."Kriz anı desteği, stres yönetimi.

Dinamik Persona Kalibrasyonu: Gölge ve Ayna ajanlarının prompt'ları statik şablonlar değildir. Sohbet başlamadan önce RAG pipeline, kullanıcının güncel Materialized State'inden (bkz. ../architecture/context-rooms-design.md Bölüm 6) Big Five skorlarını okur. Gölge Ajan için en yüksek skorlu trait belirlenir (örn. Agreeableness: 82) ve prompt bu trait'in düşük ucuna kalibre edilir (örn. "Sen son derece rekabetçi ve uzlaşmaya dirençli birisin"). Ayna Ajan için ise aynı skorlar kopyalanarak prompt'a enjekte edilir. Bu mekanizma, ajanların kullanıcıyla birlikte "evrimleşmesini" sağlar.

2.2. Sisli Sohbet (Misty Chat) Mekanizması ​

Sisli sohbetlerde, LLM'e şu kesin komut (System Directive) verilir:

"Sen şu an [GÖLGE] ajanısın. Ancak senaryo bitene kadar karşındaki kullanıcıya hangi ajan olduğunu veya hangi özelliğini test ettiğini ASLA söyleme. Doğal bir insan gibi davran. Senaryo sonlandığında, sisin kalktığını belirt ve 'Aslında ben senin tam zıttın olan bir profili canlandırıyordum...' diyerek analizi sun."

3. Bellek Yönetimi ve RAG (Retrieval-Augmented Generation) ​

Yapay zeka asistanının kullanıcıyı "hatırlaması" (Nomi etkisi), B2C uygulamasının en büyük kanca (retention) stratejisidir.

3.1. Ücretsiz Kullanıcı (Bellek Duvarı) ​

  • TTL (Time-to-Live): Redis üzerindeki oturum (session) geçmişi 24 saat sonra silinir.
  • Sonuç: Kullanıcı 2. gün girdiğinde LLM onu hatırlamaz. Bu, Premium geçişin ana tetikleyicisidir. Psikometrik çıkarımlar saklanır (Genom), ancak sohbet bağlamı unutulur.

3.2. Premium Kullanıcı (Uzun Vadeli Bellek / Vector Search) ​

  • Vektörel Geri Çağırma (Vector Retrieval): Premium kullanıcı yeni bir sohbete başladığında, RAG pipeline devreye girer.
  • Kullanıcının [NEUTRAL] ve [PRO] odalarındaki geçmiş sohbet vektörleri (Noise-Injected Embeddings) pgvector üzerinden taranır.
  • En ilgili 3-4 geçmiş anı, Sistem Prompt'una "Geçmiş Bilgi" (Context) olarak enjekte edilir.

    Örnek RAG Enjeksiyonu: "Kullanıcı 2 ay önce yöneticisiyle iletişim kurmakta zorlandığını ve gergin hissettiğini belirtmişti. Bu konuşmada bu konunun ne durumda olduğunu üstü kapalı sor."

Oda Filtresi: RAG sorgusu yalnızca DISCOVERY([PRO], [NEUTRAL]) ve PROFESSIONAL odalarındaki vektörleri tarar. SOCIAL ve CLINICAL oda vektörleri RAG pipeline'ından açıkça hariç tutulmuştur — bu filtre, ../architecture/context-rooms-design.md'deki Privacy Firewall ilkesinin vektör veritabanı katmanındaki yansımasıdır. Bu hariç tutma, uygulama kodunda değil vektör sorgu şablonunda (query template) sabitlenmiş olup, geliştiricinin sorgusunda filtre unutması durumunda dahi Sosyal/Klinik verinin prompt'a sızmasını engeller.

4. LLM'den Yapılandırılmış Veri Çıkarımı (Structured Output) ​

Cold Path'te çalışan Çıkarım Modeli (Inference Model), metin değil makine okunabilir veri üretmek zorundadır. Bu işlem, LLM'lerin Function Calling veya JSON Schema zorlaması özellikleri kullanılarak yapılır.

4.1. Çıkarım Şeması (JSON Schema Örneği) ​

Bir iş görüşmesi simülasyonu bittiğinde LLM'in üretmesi beklenen JSON çıktısı:

json
{
  "scenario_id": "sim_8472",
  "detected_traits": [
    {
      "trait_id": "bigfive_agreeableness",
      "shift_value": -2.5,
      "reasoning": "Kullanıcı, müşteri baskısı karşısında uzlaşmak yerine agresif bir dille savunmaya geçti.",
      "llm_confidence": 0.88
    },
    {
      "trait_id": "bigfive_conscientiousness",
      "shift_value": 1.2,
      "reasoning": "Teslimat tarihine sadık kalmak için inisiyatif alıp planlamayı revize etti.",
      "llm_confidence": 0.95
    }
  ],
  "suggested_label": "[PRO]"
}
  • shift_value: LLM, mutlak bir skor (Örn: Skoru 75) vermez. Bu yanıltıcıdır. LLM sadece bir "hareket/değişim" (Örn: -2.5 puan) önerir. Nihai skor hesaplaması Scoring Engine tarafından yapılır.
  • llm_confidence: LLM'in kendi çıkarımından ne kadar emin olduğu. Bu değer, Confidence & Audit Engine tarafından verinin Güven Skoru'na katılıp katılmayacağını belirlemek için kullanılır (Örn: < 0.70 ise reddedilir). Eşik değerleri ve reddetme mantığı için bkz. confidence-engine.md

5. Halüsinasyon Kontrolü ve EU AI Act Önlemleri ​

LLM'lerin "aşırı teşhis" (overdiagnosis) veya "klinik tanı koyma" riskini (halüsinasyon) engellemek kritik bir regülasyon şartıdır.

5.1. Sınırlandırıcı Kurallar (Guardrails) ​

  1. Klinik Teşhis Yasağı: Sistem prompt'larında kesin bir direktif bulunur: "Hiçbir koşulda depresyon, anksiyete, DEHB gibi klinik tanılar koyma. Yalnızca davranışsal eğilimleri (Big Five modeline göre) analiz et."
  2. Anchor (Çapa) Modellemesi: LLM, açık uçlu kavramlar uyduramaz. Çıkarımlar yalnızca sistemde tanımlı (Hardcoded) Big Five facet'leri (alt kırılımları) veya RIASEC kodları ile eşleşmek zorundadır. JSON şemasındaki trait_id enum kontrolünden geçirilir. Geçersiz trait üreten LLM çıktısı, Scoring Engine tarafından "Parse Error" olarak düşürülür ve işlenmez.

Son Güncelleme: 2026-04-15 — Dual-path routing, RAG bellek yönetimi, Oda Filtresi, Dinamik Persona Kalibrasyonu ve Structured Output şeması tanımlandı.

Simetri tarafından inşa ediliyor.