---

İçindekiler

• KACHOW nedir?
• Demo ve Arayüz
  • Platform görünümü
• Temel Yetenekler
  • Evrak analizi
  • Mevzuat arama
  • Taslak üretimi
  • Kaynak doğrulama
  • Birim yönlendirme
  • İnsan onayı
• Sistem Mimarisi
  • Mimari yaklaşım
• AI İş Akışları
  • Router niyetleri
• Baştan Sona İşlem Akışı
• Human-in-the-Loop
• Güvenlik ve Yetkilendirme
  • Multi-tenant yapı
  • Roller
  • PostgreSQL Row-Level Security
  • Guardrail katmanları
• Taslak Doğrulama
• Mevzuat Bilgi Grafiği
• Kuruma Özel Öğrenme
  • 1. Preference-pair oluşturma
  • 2. Stil profili çıkarımı
  • 3. Opsiyonel LoRA / DPO
• İkili Çalışma Modu: Yerel ve Sunucu
  • Üç reasoning profili
• Neden Bu Tasarım?
• Değerlendirme
• Öne Çıkan Sonuçlar
• Model Karşılaştırması
  • Hız ve doğruluk grafikleri
• OCR Benchmark
  • Alan kurtarma karşılaştırması
  • Gecikme / doğruluk konumlandırması
• LLM Judge ve İnsan Değerlendirmesi
• Red Team Sonuçları
• Performans
• Testler
• Backend
• Frontend
• CI
• Veri Setleri
• Teknoloji Yığını
• Monitoring
  • Prometheus
  • Grafana
  • Langfuse
  • Jaeger + OpenTelemetry
• Hızlı Başlangıç
• Gereksinimler
  • 1. Repoyu klonlayın
  • 2. Ortam değişkenlerini oluşturun
  • 3. Veritabanını ve backend'i hazırlayın
  • 4. Diğer servisleri başlatın
  • Yararlı komutlar
• Ortam Değişkenleri
• Dağıtım
  • Docker Compose
  • Kubernetes
• Proje Yapısı
• Daha Fazla Dokümantasyon
• Lisans

---

KACHOW nedir?

Kamu kurumlarında bir evrakın işlenmesi yalnızca metni okumaktan ibaret değildir. Evrakın türünün belirlenmesi, gerekli bilgilerin kontrol edilmesi, ilgili mevzuatın bulunması, resmî cevap hazırlanması, uygun birime yönlendirilmesi ve imza öncesinde doğrulanması gerekir.

KACHOW bu sürecin tekrar eden bölümlerini otomatikleştirir ancak karar sürecinden insanı çıkarmayı amaçlamaz.

Bir evrak yüklendiğinde sistem:

1. belgeyi okur,
2. evrak türünü ve temel alanları çıkarır,
3. eksik bilgileri belirler,
4. ilgili mevzuatı arar,
5. resmî yazışma taslağı oluşturur,
6. taslaktaki iddiaları kaynak belgeyle karşılaştırır,
7. uygun kurumsal birimi önerir,
8. kritik veya belirsiz durumlarda kullanıcı onayı ister.

flowchart TB

    classDef step fill:#F5F3FF,stroke:#8B5CF6,stroke-width:1.5px,color:#172033;
    classDef input fill:#EFF6FF,stroke:#3B82F6,stroke-width:1.5px,color:#172033;
    classDef guard fill:#FEF2F2,stroke:#EF4444,stroke-width:1.5px,color:#172033;
    classDef human fill:#FFF7ED,stroke:#F59E0B,stroke-width:1.5px,color:#172033;
    classDef decision fill:#FFFBEB,stroke:#D97706,stroke-width:1.5px,color:#172033;
    classDef done fill:#ECFDF5,stroke:#10B981,stroke-width:1.5px,color:#172033;

    subgraph TASK1["Görev 1 · Evrak Analizi"]
        direction LR

        A[Evrak Yükleme]:::input
        B[Okuma ve OCR]:::input
        C[Input Guardrail]:::guard
        D[Sınıflandırma]:::step
        E[Alanları Çıkar]:::step

        A --> B --> C --> D --> E
    end

    subgraph TASK2["Görev 2 · Zenginleştirme ve Taslak"]
        direction LR

        F[Eksikleri Bul]:::step
        G[Mevzuat Arama]:::step
        H[Özetleme]:::step
        I[Yazışma Türünü Belirle]:::step
        J[Taslak Üretimi]:::step

        F --> G --> H --> I --> J
    end

    subgraph TASK3["Görev 3 · Doğrulama ve Karar"]
        direction LR

        K[Kaynak Doğrulama]:::guard
        L[Output Guardrail]:::guard
        M{İnsan Onayı<br/>Gerekli mi?}:::decision
        N[Birim Yönlendirme]:::step
        O[Kaydet ve Gönder]:::done
        P[İnsan Müdahalesine Aktar]:::human

        K --> L --> M
        M -->|Hayır| N --> O
        M -->|Evet| P
    end

    TASK1 --> TASK2
    TASK2 --> TASK3

    style TASK1 fill:#EFF6FF,stroke:#93C5FD,stroke-width:1.5px
    style TASK2 fill:#F5F3FF,stroke:#C4B5FD,stroke-width:1.5px
    style TASK3 fill:#FEF2F2,stroke:#FCA5A5,stroke-width:1.5px

Her işlem adımı LangGraph üzerinde ayrı bir düğüm olarak çalışır. Akışın durumu sunucuda tutulduğu için kullanıcı onayı gereken bir noktada işlem durabilir ve daha sonra aynı noktadan devam edebilir.

---

Demo ve Arayüz

Demo videosu:

Platform görünümü

Ana Sayfa — koyu tema

Karar Destek Sohbeti — kurum/kişi tespiti

Mesajlar — yeni konuşma

Evrak Kütüphanesi — özet sekmesi

Taslaklar — önizleme ve gönderim

Mevzuat Haritası — ilişki grafiği

Tüm 42 ekran görüntüsü ve başlıkları için: Ekran Görüntüsü Galerisi

Arayüzde özellikle üç nokta görünür tutulur:

• evrak yükleme ve analiz süreci,
• ajanların ilerleyişinin SSE üzerinden canlı gösterimi,
• sistemin kullanıcıdan bilgi veya onay beklediği Human-in-the-Loop adımları.

---

Temel Yetenekler

Evrak analizi

KACHOW hem metin katmanı bulunan PDF'leri hem de taranmış belgeleri işleyebilir.

Dijital belgelerde metin doğrudan çıkarılır. Gerekli olduğunda Tesseract ve vision tabanlı OCR katmanları devreye girer.

Analiz sonucunda sistem:

• evrak türünü belirler,
• tarih, sayı, konu, muhatap ve gönderen kurum gibi alanları çıkarır,
• eksik alanları işaretler,
• kısa veya ayrıntılı özet oluşturur,
• evrakla ilişkili mevzuatı arar.

Çıkarılan alanlar Pydantic şemalarıyla yapılandırılır; yalnızca serbest metin olarak tutulmaz.

Mevzuat arama

Mevzuat araması BM25 + dense retrieval kullanan hibrit bir arama katmanı üzerinden yapılır.

Sistem iki kaynaktan yararlanabilir:

• canlı mevzuat-mcp sorguları,
• bağlantı kurulamadığında datasets/mevzuat/ altındaki yerel fallback korpüsü.

Bir kaynak bulunamadığında mevzuat referansı üretilmez.

Taslak üretimi

Analiz tamamlandıktan sonra sistem resmî yazışma taslağı oluşturabilir.

Taslak oluşturulurken:

• kaynak evrak,
• bulunan mevzuat,
• yazışma türü,
• kurumun tercihleri ve stil profili

birlikte kullanılır.

Üretilen taslak daha sonra ayrı bir doğrulama aşamasından geçer.

Kaynak doğrulama

Taslakta geçen tarih, sayı, tutar, kişi, kurum ve mevzuat atıfları kaynak evrakla karşılaştırılır.

Kritik bir tutarsızlık bulunursa yüksek genel güven skoru bu hatayı gizleyemez. Bu tür bulgular forces_approval üzerinden ayrı olarak işlenir ve taslak kullanıcı onayına gönderilir.

Birim yönlendirme

Routing Graph evrakın içeriğine göre uygun kurumsal birimi önerir.

Sonuç yalnızca bir birim adı değildir. Sistem mümkün olduğunda:

• önerilen birimi,
• güven skorunu,
• yönlendirme gerekçesini,
• alternatif birimleri

birlikte döndürür.

İnsan onayı

KACHOW'un temel tasarım kararlarından biri kritik kararların otomatik olarak geçilmemesidir.

Eksik bilgi, doldurulmamış alan, olası halüsinasyon veya başka kritik bir doğrulama problemi bulunduğunda LangGraph akışı interrupt ile durdurulur.

Kullanıcı gerekli bilgiyi sağladığında aynı thread tekrar başlatılmaz; mevcut checkpoint üzerinden devam eder.

---

Sistem Mimarisi

KACHOW backend'i bir modüler monolit olarak tasarlanmıştır.

Tek bir deploy edilebilir backend bulunur ancak authentication, documents, drafts, routing, messaging, training ve diğer alanlar ayrı domain sınırları içinde tutulur.

flowchart LR
    classDef ui fill:#EFF6FF,stroke:#3B82F6,stroke-width:1.5px,color:#172033;
    classDef api fill:#EEF2FF,stroke:#6366F1,stroke-width:1.5px,color:#172033;
    classDef ai fill:#F5F3FF,stroke:#8B5CF6,stroke-width:1.5px,color:#172033;
    classDef data fill:#F8FAFC,stroke:#64748B,stroke-width:1.5px,color:#172033;
    classDef ext fill:#ECFDF5,stroke:#10B981,stroke-width:1.5px,color:#172033;
    classDef safe fill:#FEF2F2,stroke:#EF4444,stroke-width:1.5px,color:#172033;

    FE[React 18 + TypeScript<br/>TanStack Query · SSE]:::ui
    API[FastAPI<br/>Auth · Tenant · Rate Limit]:::api
    AUTH[JWT + RBAC/ABAC<br/>Ownership · Clearance]:::safe
    LG[LangGraph<br/>AI Workflows]:::ai

    PG[(PostgreSQL<br/>RLS + Checkpoints)]:::data
    QD[(Qdrant<br/>Hybrid Retrieval)]:::data
    RD[(Redis<br/>Session / Cache)]:::data

    LLM[Ollama / Evren]:::ext
    MCP[Mevzuat MCP]:::ext

    FE -->|REST + SSE| API
    API --> AUTH --> LG

    LG --> PG
    LG --> QD
    LG --> RD
    LG --> LLM
    LG --> MCP

Mimari yaklaşım

Ağır ML bağımlılıkları gerektiren LoRA/DPO eğitim işleri ayrı bir worker sürecinde çalışır.

---

AI İş Akışları

Sistemde farklı görevler tek bir dev prompt üzerinden yürütülmez. Her iş için ayrı LangGraph akışları bulunur.

flowchart LR
    classDef api fill:#EFF6FF,stroke:#3B82F6,stroke-width:1.5px,color:#172033;
    classDef ai fill:#F5F3FF,stroke:#8B5CF6,stroke-width:1.5px,color:#172033;
    classDef safe fill:#FEF2F2,stroke:#EF4444,stroke-width:1.5px,color:#172033;
    classDef out fill:#ECFDF5,stroke:#10B981,stroke-width:1.5px,color:#172033;

    IN[İstek / Evrak]:::api
    GUARD[Input Guardrail]:::safe
    ROUTER{Intent Router}:::ai

    PLAN[Planning Graph]:::ai
    ANALYZE[Document Analysis Graph]:::ai
    DRAFT[Draft Graph]:::ai
    REVISE[Revise Graph]:::ai
    ROUTING[Routing Graph]:::ai

    OUT[Output Guardrail]:::safe
    RESULT[API Yanıtı]:::out

    IN --> GUARD --> ROUTER
    ROUTER --> PLAN
    ROUTER --> ANALYZE
    ROUTER --> DRAFT
    ROUTER --> REVISE
    ROUTER --> ROUTING

    PLAN --> OUT
    ANALYZE --> OUT
    DRAFT --> OUT
    REVISE --> OUT
    ROUTING --> OUT

    OUT --> RESULT

Router niyetleri

Gelen istekler altı temel niyetten birine yönlendirilir:

Router yalnızca statik anahtar kelime kontrolü yapmaz. Lexical skor, semantik sinyal ve scope kontrolleri birlikte değerlendirilir.

---

Baştan Sona İşlem Akışı

sequenceDiagram
    autonumber

    participant U as Kullanıcı
    participant F as Frontend
    participant A as FastAPI
    participant D as Analysis Graph
    participant G as Guardrails
    participant T as Draft Graph
    participant H as Human Gate

    U->>F: Evrak yükler
    F->>A: POST /documents/analyze
    A->>A: Auth + sahiplik + clearance kontrolü
    A->>D: Analizi başlat

    D->>D: Metin çıkar / OCR fallback
    D->>G: Injection + PII kontrolü
    D->>D: Sınıflandır ve alanları çıkar
    D->>D: Eksikleri bul
    D->>D: Mevzuatı ara
    D->>D: Özet oluştur
    D-->>F: Analiz sonucu

    U->>F: Taslak ister
    F->>T: Draft Graph

    T->>T: Taslak üret
    T->>G: Claim-check + LLM Judge

    alt Kritik bulgu
        G->>H: Onay gerekli
        H-->>F: Kullanıcı girdisi bekleniyor
        U->>F: Yanıt / onay / revizyon
        F->>T: Resume
    else Düzeltilebilir bulgu
        T->>T: Sınırlı otomatik onarım
    end

    T-->>F: Doğrulanmış taslak

    F->>A: Routing isteği
    A-->>F: Birim + gerekçe + alternatifler

    U->>F: Onay / revizyon / ret

---

Human-in-the-Loop

Kullanıcı onayı gereken durumlar sunucu tarafında korunur.

stateDiagram-v2
    [*] --> Calisiyor

    Calisiyor --> Calisiyor: node_start / node_end
    Calisiyor --> OnayBekliyor: human_gate interrupt

    OnayBekliyor --> DevamEdiyor: kullanıcı yanıtı
    DevamEdiyor --> Calisiyor: Command(resume)

    OnayBekliyor --> Yenilendi: sayfa yenilendi
    Yenilendi --> OnayBekliyor: session state geri yüklenir

    Calisiyor --> Tamamlandi
    Tamamlandi --> [*]

Sayfanın yenilenmesi bekleyen onayı kaybettirmez. Frontend ilgili session state'ini tekrar çekerek interrupt bilgisini ve mesaj geçmişini geri yükler.

Eski veya artık geçerli olmayan bir interrupt üzerinden işlem yapılmaya çalışılırsa sunucu bunu reddeder ve istemci güncel state'i yeniden alır.

---

Güvenlik ve Yetkilendirme

Multi-tenant yapı

KACHOW birden fazla kurumun aynı platform üzerinde çalışabileceği şekilde tasarlanmıştır.

Her kurumun:

• kullanıcıları,
• evrakları,
• taslakları,
• geri bildirimleri,
• mevzuat ilişkileri,
• adaptif stil profili

diğer kurumlardan izole edilir.

Roller

Yetkilendirme yalnızca role bağlı değildir.

Her istekte gerektiğinde:

• kullanıcının rolü,
• kurum üyeliği,
• belge sahipliği,
• gizlilik seviyesi,
• özel izin grant'leri

birlikte değerlendirilir.

PostgreSQL Row-Level Security

Kurum izolasyonu yalnızca uygulama koduna bırakılmaz.

PostgreSQL RLS politikaları farklı kurumların satırlarını veritabanı seviyesinde ayırır. Böylece uygulama katmanındaki olası bir sorgu hatası tenant izolasyonunu tek başına aşamaz.

Guardrail katmanları

Girdi tarafında:

• prompt-injection temizliği,
• PII tespiti,
• hassasiyet kontrolü

uygulanır.

Çıktı tarafında:

• prompt sızıntısı,
• kişisel veri,
• kaynak dışı iddialar,
• kritik doğrulama bulguları

kontrol edilir.

TCKN ve IBAN kontrolleri yalnızca regex'e dayanmaz; uygun durumlarda checksum doğrulaması da uygulanır.

---

Taslak Doğrulama

Taslak oluşturulduktan sonra otomatik olarak gönderilmez.

flowchart LR
    classDef step fill:#EFF6FF,stroke:#3B82F6,stroke-width:1.5px,color:#172033;
    classDef safe fill:#FEF2F2,stroke:#EF4444,stroke-width:1.5px,color:#172033;
    classDef human fill:#FFF7ED,stroke:#F59E0B,stroke-width:1.5px,color:#172033;
    classDef done fill:#ECFDF5,stroke:#10B981,stroke-width:1.5px,color:#172033;

    A[Taslak]:::step
    B[Claim Check]:::safe
    C[Yapı ve Stil Kontrolü]:::safe
    D[LLM Judge]:::safe
    E{Kritik bulgu?}:::safe

    F[Otomatik Onay]:::done
    G[Otomatik Onarım]:::step
    H[İnsan Onayı]:::human

    A --> B --> C --> D --> E
    E -->|Hayır, skor yüksek| F
    E -->|Düzeltilebilir| G --> B
    E -->|Evet| H

Kritik bulgular ortalama güven skorundan bağımsız işlenir.

Örneğin:

• kaynakta bulunmayan bir tarih veya tutar,
• farklı kişiye ait bilginin taslağa taşınması,
• örnek belgeden veri sızıntısı,
• doldurulmamış placeholder

taslağı doğrudan insan onayına yönlendirebilir.

---

Mevzuat Bilgi Grafiği

GET /documents/graph endpoint'i, belgeler ile atıfta bulundukları mevzuat arasındaki ilişkileri görselleştirir.

Ayrı bir graph database kullanılmaz.

Grafik PostgreSQL'deki belge ve analiz verilerinden ihtiyaç anında türetilir.

Bu yaklaşım:

• ayrı graph veritabanı senkronizasyonunu ortadan kaldırır,
• mevcut tenant ve clearance kurallarını tekrar kullanır,
• kullanıcıların erişemediği belgelerin grafikte görünmesini engeller.

Frontend'de KnowledgeGraphView.tsx üzerinden force-directed bir ağ olarak gösterilir.

---

Kuruma Özel Öğrenme

Her kurum geçmiş geri bildirimlerinden kendi resmî yazışma stilini geliştirebilir.

Bu süreç üç aşamalıdır:

1. Preference-pair oluşturma

Kullanıcı geri bildirimlerinden tercih edilen ve edilmeyen çıktı çiftleri çıkarılır.

En az 50 örnek oluşmadan otomatik stil çıkarımı başlatılmaz.

2. Stil profili çıkarımı

style_miner.py, istatistiksel farkları ve tek bir LLM çağrısını kullanarak kurum için:

• style_rules,
• avoided_patterns

üretir.

Bu bilgiler CompanyAdapter yapısında tutulur.

3. Opsiyonel LoRA / DPO

Yeterli veri bulunan kurumlarda ayrı eğitim worker'ı üzerinden SFT veya DPO uygulanabilir.

Ağır torch, peft ve trl bağımlılıkları ana backend imajına eklenmez.

Her kurumun adaptasyonu diğer kurumlardan izoledir.

---

İkili Çalışma Modu: Yerel ve Sunucu

KACHOW aynı iş akışını iki farklı model altyapısıyla çalıştırabilir. Hangi sağlayıcının kullanılacağı LOCAL_MODE ile belirlenir; domain ve workflow kodu değişmez.

• Local Mod: Kurum verisinin dışarı çıkmaması gereken senaryolarda Ollama ve yerel Qdrant ile kapalı ağda çalışabilir.
• Evren Modu: LOCAL_MODE=false olduğunda model çağrıları TEKNOFEST Evren altyapısına yönlendirilir. Daha büyük modeller gerektiğinde aynı uygulama akışı korunur.

Üç reasoning profili

Görevler aynı model ayarıyla çalıştırılmaz. İhtiyaç duyulan hız ve muhakeme seviyesine göre üç profil kullanılır:

• Hızlı (Fast): Sınıflandırma, routing ve kısa karar görevleri. Düşük gecikme önceliklidir.
• Dengeli (Balanced): Taslak üretimi, özetleme ve standart belge analizleri için varsayılan profil.
• Derin (Deep): Karmaşık mevzuat yorumlama ve çok adımlı değerlendirme gereken durumlarda reasoning etkin profil.

Bu ayrım sayesinde basit bir sınıflandırma isteği ile kapsamlı bir taslak doğrulaması aynı hesaplama maliyetiyle çalıştırılmaz.

---

Neden Bu Tasarım?

Bazı kararlar özellikle hata durumları düşünülerek alındı.

---

Değerlendirme

Deney makinesi: Aşağıdaki tüm ölçümler, 64 GB RAM ve tek bir NVIDIA RTX 3060 (12 GB VRAM) bulunan iş istasyonunda alınmıştır.

KACHOW'un değerlendirmesi tek bir "başarı skoru" üzerinden yapılmıyor. Sistem farklı görevlerde ayrı ayrı ölçülüyor:

Aşağıdaki sonuçlar bu başlıkların her biri için ayrı benchmarklardan gelir. Böylece örneğin hızlı çalışan fakat kaynak doğruluğu düşük bir model, tek bir ortalama puan içinde "iyi" görünmez.

---

Öne Çıkan Sonuçlar

Local Mode'da, dengeli (Balanced) profille alınan sonuçlar:

---

Model Karşılaştırması

Aşağıdaki testler reasoning/thinking özellikleri kapalıyken gerçekleştirilmiştir.

Hız ve doğruluk grafikleri

Yukarıdaki tablonun dört sayısal sütunu ayrı sütun grafikleri olarak. Nokta adlarında kısa kod kullanılır (GitHub Mermaid görünümünde model isimleri üst üste binmesin diye); router yalnızca yönlendirme yaptığı için Türkçe ve Formatlama grafiklerine girmez.

xychart-beta
    title "Hız — Token / saniye"
    x-axis ["Q9", "Q4", "G12", "MN12", "L8", "E-L", "E-F", "E-R"]
    y-axis "Token/sn" 0 --> 170
    bar [34, 56, 22, 26, 32, 75, 105, 160]

xychart-beta
    title "Doğruluk (%)"
    x-axis ["Q9", "Q4", "G12", "MN12", "L8", "E-L", "E-F", "E-R"]
    y-axis "Doğruluk" 80 --> 100
    bar [93, 87, 90, 89, 91, 99, 94, 92]

xychart-beta
    title "Türkçe (%)"
    x-axis ["Q9", "Q4", "G12", "MN12", "L8", "E-L", "E-F"]
    y-axis "Türkçe" 80 --> 100
    bar [92, 88, 88, 89, 92, 99, 95]

xychart-beta
    title "Formatlama (%)"
    x-axis ["Q9", "Q4", "G12", "MN12", "L8", "E-L", "E-F"]
    y-axis "Formatlama" 80 --> 100
    bar [94, 89, 91, 90, 91, 99, 95]

---

OCR Benchmark

OCR karşılaştırması sentetik belgelerde değil, datasets/resmi_yazisma içindeki gerçek resmî yazışmalarda gerçekleştirildi.

Test seti:

• 23 belge,
• 52 sayfa,
• 134 elle doğrulanmış alan.

Değerlendirilen alanlar:

• Sayı,
• Tarih,
• Konu,
• Muhatap,
• Gönderen Kurum,
• İmza Sahibi,
• İmza Unvanı.

Ağırlıklı doğruluk:

%60 başlık + %40 imza

Üretimde kullanılan vision modeli:

OLLAMA_VISION_MODEL="glm-ocr:latest"

glm-ocr, özellikle ıslak imzanın basılı metne temas ettiği belgelerde diğer motorlardan daha iyi sonuç verdi.

Alan kurtarma karşılaştırması

Aşağıdaki grafik, başlık alanları ile imza alanlarının OCR zinciri sonunda ne oranda kurtarıldığını gösterir.

xychart-beta
    title "OCR Alan Kurtarma"
    x-axis ["OD", "TS", "PO", "GLM", "UO", "DS"]
    y-axis "Kurtarma Oranı (%)" 0 --> 100
    bar [83, 83, 83, 90, 18, 90]
    bar [74, 74, 74, 100, 52, 74]

1. seri: Başlık alanları — Sayı, Tarih, Konu, Muhatap, Gönderen
2. seri: İmza alanları — İmza Sahibi, İmza Unvanı

Gecikme / doğruluk konumlandırması

Bu görünüm, motorların sayfa başına gecikme (yatay eksen) ile ağırlıklı belge anlama doğruluğu (dikey eksen) arasındaki dengede nerede durduğunu gösterir. Eksen değerleri, motorları birbirine göre yerleştirmek için 0–1 aralığına ölçeklenmiştir; mutlak sayı değildir. Sağa gidildikçe motor yavaşlar, yukarı çıkıldıkça doğruluk artar — yani tercih edilen bölge sol üst köşedir (hızlı + isabetli). Her noktanın etiketinde motorun adı, ham gecikmesi ve ağırlıklı doğruluğu birlikte yazılıdır; kesin ölçümler yukarıdaki benchmark tablosundadır.

quadrantChart
    title OCR motorlari: gecikme / dogruluk
    x-axis "Hizli (dusuk gecikme)" --> "Yavas (yuksek gecikme)"
    y-axis "Dusuk dogruluk" --> "Yuksek dogruluk"
    quadrant-1 "Yavas - isabetli"
    quadrant-2 "Hizli - isabetli (tercih)"
    quadrant-3 "Hizli - isabetsiz"
    quadrant-4 "Yavas - isabetsiz"
    "OpenDataLoader-PDF  0.17 sn  %79": [0.05, 0.79]
    "Tesseract  1.74 sn  %79": [0.28, 0.76]
    "DeepSeek-OCR  3.55 sn  %83": [0.58, 0.83]
    "GLM-OCR  4.20 sn  %94": [0.68, 0.94]
    "Unlimited-OCR  5.96 sn  %32": [0.95, 0.32]

Bu benchmark sırasında extraction zincirinde iki regresyon da tespit edildi ve düzeltildi:

• vision onarımının bazı belgelerde önceki sonucu kötüleştirebilmesi,
• header-band dışında kalan başlık alanlarının full-page fallback'e yükseltilmemesi.

---

LLM Judge ve İnsan Değerlendirmesi

---

Red Team Sonuçları

Red Team değerlendirmesi hem elle hazırlanmış senaryoları hem de otomatik üretilen saldırı varyasyonlarını içerir.

---

Performans

Ölçümler, bölümün başında belirtilen deney makinesinde (64 GB RAM · RTX 3060 12 GB VRAM) alınmıştır.

---

Testler

README hazırlanırken testler Docker ortamında çalıştırılmıştır.

Backend

2995 test · %86 coverage · tümü geçiyor

2958 passed, 37 deselected
TOTAL coverage: %86
Coverage gate: %86

Varsayılan koşu; marker'la ayrılan e2e / performance / real_corpus testlerini deselect eder. Bunlar kendi lane'lerinde (make test-e2e, pytest -m performance, make test-corpus) çalışır ve hepsi geçer. Integration testleri gerçek PostgreSQL ve RLS migration zinciri üzerinde çalışır.

Frontend

447 test · %80.72 statement coverage · tümü geçiyor

Coverage eşikleri ratchet mantığıyla tutulur; coverage yükseldiğinde eşik artırılır.

CI

.github/workflows/ci.yml iki bağımsız job çalıştırır.

Backend

PostgreSQL + Redis + Qdrant
        ↓
Alembic migration
        ↓
pytest + coverage gate

Frontend

npm ci
  ↓
Typecheck
  ↓
ESLint
  ↓
Vitest
  ↓
Coverage

CI şu anda workflow_dispatch ile GitHub Actions üzerinden manuel tetiklenir.

---

Veri Setleri

datasets/resmi_yazisma/ — Türkçe resmî yazışma korpusu, 1.763 belge. HuggingFace'te yayında.

%%{init: {"theme": "base", "themeVariables": {"pie1": "#3B82F6", "pie2": "#8B5CF6", "pie3": "#10B981", "pie4": "#D97706", "pie5": "#EF4444", "pieOuterStrokeWidth": "2px", "pieStrokeColor": "#6B7280", "pieOpacity": 1, "pieSectionTextColor": "#FFFFFF", "pieSectionTextSize": "15px", "pieTitleTextColor": "#8B98A5", "pieLegendTextColor": "#8B98A5"}}}%%
pie showData
    title Kategori Dağılımı
    "Diğer resmî yazışma" : 531
    "Bilgilendirme metni" : 418
    "Cevap yazısı" : 370
    "Üst yazı" : 330
    "Dilekçe" : 114

---

Teknoloji Yığını

Frontend tarafında Redux veya Zustand kullanılmaz; server state TanStack Query ile, auth ve tema gibi istemci state'leri React Context ile yönetilir.

---

Monitoring

KACHOW'un monitoring katmanı yalnızca log toplamaktan ibaret değildir.

Prometheus

3 scrape job bulunur:

• prometheus,
• kachow-backend,
• qdrant.

monitoring/prometheus/rules/kachow.rules.yml altında 12 alert kuralı bulunur.

Grafana

Provision edilen dashboard'lar:

• company_dashboard.json,
• fastapi_dashboard.json,
• transfers_dashboard.json.

Langfuse

LLM çağrılarında:

• token,
• maliyet,
• latency,
• trace

bilgilerini toplar.

Jaeger + OpenTelemetry

HTTP, SQLAlchemy, Redis ve httpx operasyonları dağıtık trace olarak izlenir.

Her isteğe CorrelationIdMiddleware tarafından X-Request-ID atanır ve aynı ID audit kayıtlarına taşınır.

---

Hızlı Başlangıç

Gereksinimler

• Docker
• Docker Compose v2
• Local Mode kullanılacaksa Ollama ve uygun donanım
• Evren Mode kullanılacaksa Evren API anahtarı

1. Repoyu klonlayın

git clone https://github.com/chyp3r/KACHOW-Teknofest-2026.git
cd KACHOW-Teknofest-2026

2. Ortam değişkenlerini oluşturun

cp .env.example .env

Local Mode:

LOCAL_MODE=true

Evren Mode:

LOCAL_MODE=false
EVREN_API_KEY=...

3. Veritabanını ve backend'i hazırlayın

make bootstrap

Bu komut:

• PostgreSQL'in hazır olmasını bekler,
• Alembic migration'larını uygular,
• varsayılan seed hesaplarını oluşturur,
• backend'i ayağa kaldırır.

API:

http://localhost:8000

4. Diğer servisleri başlatın

make up

Yararlı komutlar

make logs
make test
make test-e2e
make reset

Kubernetes kurulumu için:

docs/deployment/README.md

---

Ortam Değişkenleri

Ana yapılandırma dosyası:

.env.example

Docker dışında doğrudan host üzerinde backend çalıştırmak için:

backend/.env.example

Önemli değişken grupları:

Tüm seçenekler için .env.example dosyasına bakın.

---

Dağıtım

Docker Compose

Geliştirme ortamında compose.yml 15 servis içerir.

Temel topoloji:

flowchart LR
    classDef app fill:#EFF6FF,stroke:#3B82F6,stroke-width:1.5px,color:#172033;
    classDef data fill:#F8FAFC,stroke:#64748B,stroke-width:1.5px,color:#172033;
    classDef obs fill:#F5F3FF,stroke:#8B5CF6,stroke-width:1.5px,color:#172033;

    FE[Frontend]:::app --> BE[Backend]:::app
    BE --> WK[Worker]:::app

    BE --> PG[(PostgreSQL)]:::data
    BE --> RD[(Redis)]:::data
    BE --> QD[(Qdrant)]:::data

    BE -.-> LF[Langfuse]:::obs
    BE -.-> JG[Jaeger]:::obs
    PM[Prometheus]:::obs --> BE
    GF[Grafana]:::obs --> PM

Kubernetes

deploy/kubernetes/ altında 11 manifest bulunur.

Backend şu anda STORAGE_TYPE=local nedeniyle tek replica ile çalışır. Pod-lokal storage yerine S3 gibi ortak bir storage backend kullanılmadan replica sayısının artırılması amaçlanmamıştır.

Ingress'te SSE için buffering kapalıdır.

proxy-buffering: off
proxy-read/send-timeout: 600s
proxy-body-size: 50m

Migration işlemi backend init container'ı yerine ayrı bir Kubernetes Job olarak yürütülür.

Prod imajları:

ghcr.io/chyp3r/kachow-backend
ghcr.io/chyp3r/kachow-frontend

Migration Job ve backend Deployment aynı IMAGE_TAG değerini kullanmalıdır.

Detaylı deployment dokümantasyonu:

docs/deployment/

---

Proje Yapısı

backend/app/
├── domains/
│   ├── documents
│   ├── drafts
│   ├── routing
│   ├── units
│   ├── auth
│   ├── audit
│   ├── feedback
│   ├── messaging
│   ├── notifications
│   ├── training
│   └── ...
│
├── ai/
│   ├── workflows/
│   ├── agents/
│   ├── verification/
│   ├── guardrails/
│   ├── retrieval/
│   ├── training/
│   └── compliance/
│
├── api/
└── infrastructure/

frontend/src/
├── features/
├── pages/
├── hooks/
├── api/
├── contexts/
└── providers/

docs/
evaluation/
monitoring/
datasets/
.github/workflows/

---

Daha Fazla Dokümantasyon

README sistemin genel görünümünü verir. Daha ayrıntılı bilgiler docs/ altında tutulur.

• Deployment
• Architecture
• Security
• Development Rules
• Agent Rules
• Contributing
• Changelog

---

Lisans

KACHOW Apache License 2.0 altında lisanslanmıştır.

Ayrıntılar için LICENSE dosyasına bakın.

Üçüncü taraf bağımlılıkları kendi lisans koşullarına tabidir.