Initial commit: LangGraph multi-agent car finance chatbot

.gitignore

@@ -0,0 +1,30 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+.venv/
+venv/
+*.egg-info/
+
+# Ortam değişkenleri
+.env
+.env.*
+
+# Veritabanı
+*.db
+*.sqlite3
+
+# ChromaDB persist
+chatbot/data/chroma/
+
+# Log dosyaları
+*.log
+chatbot/app_out.log
+
+# IDE
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db

README.md

@@ -0,0 +1,365 @@
+# Araç Finansmanı Chatbot — Agentic Demo
+
+Bankacılık mobil uygulaması için geliştirilmiş **LangGraph tabanlı çok-ajanlı (multi-agent)** araç finansmanı ön başvuru chatbotu. Müşteri, konuşma arayüzü üzerinden yeni veya ikinci el araç finansmanı ön başvurusunu tamamen otomatik olarak tamamlayabilir; süreç boyunca SSS sorabilir, verilerini düzeltebilir ve çapraz satış teklifini kabul edebilir.
+
+---
+
+## İçindekiler
+
+1. [Proje Kapsamı](#1-proje-kapsamı)
+2. [İş Kuralları](#2-iş-kuralları)
+3. [Agentic Workflow](#3-agentic-workflow)
+4. [Agent'lar](#4-agentlar)
+5. [Tool'lar (Araçlar)](#5-toollar-araçlar)
+6. [Güvenlik Katmanları](#6-güvenlik-katmanları)
+7. [Teknolojiler](#7-teknolojiler)
+8. [Proje Yapısı](#8-proje-yapısı)
+9. [İzleme Paneli](#9-i̇zleme-paneli)
+10. [Kurulum ve Çalıştırma](#10-kurulum-ve-çalıştırma)
+11. [Konfigürasyon](#11-konfigürasyon)
+12. [Diyagramlar](#12-diyagramlar)
+
+---
+
+## 1. Proje Kapsamı
+
+| Kapsam İçi | Kapsam Dışı |
+|---|---|
+| Yeni araç finansman ön başvurusu | Nihai kredi onayı |
+| 2. el araç finansman ön başvurusu | Faiz oranı garantisi |
+| SSS / genel bilgi sorguları (RAG) | Ticari araç finansmanı |
+| HGS çapraz satış teklifi | Bireysel kredi, konut kredisi vb. |
+| Hedefli alan güncellemesi | Şube işlemleri |
+| Başvuru numarası oluşturma | Gerçek kredi skorlama |
+
+Sistem, müşteriye **adım adım rehberlik** eder. LLM her cevabı üretmez; deterministik iş kuralları önceliklidir ve LLM yalnızca niyet sınıflandırma, slot çıkarımı ile FAQ cevaplama için kullanılır.
+
+---
+
+## 2. İş Kuralları
+
+### 2.1 Yeni Araç Finansmanı
+
+| Kural | Değer |
+|---|---|
+| Proforma fatura üst limiti | **7.000.000 TL** |
+| Maksimum finansman oranı | Fatura tutarının **%60'ı** |
+| Kefil zorunluluğu eşiği | Fatura **≥ 5.000.000 TL** ise kefil TCKN zorunlu |
+| Araç tipi kısıtı | Yalnızca **binek** araç — ticari araçlar reddedilir |
+| Limit aşımı davranışı | Sistem maksimum tutarı önerir, müşteriden yeni değer ister |
+
+### 2.2 İkinci El Araç Finansmanı
+
+| Kural | Değer |
+|---|---|
+| Maksimum araç yaşı | **5 yıl** |
+| Maksimum finansman oranı | Kasko değerinin **%40'ı** |
+| Mutlak finansman üst limiti | **3.000.000 TL** |
+| Uygulanan limit | `min(%40 × kasko, 3.000.000 TL)` |
+| Satıcı TCKN | Opsiyonel (müşteri vermek istemeyebilir) |
+
+### 2.3 Genel Kurallar
+
+- **TCKN format kontrolü** intake aşamasında regex ile yapılır: 11 hane, yalnızca rakam, sıfırla başlamaz. Mod-11 doğrulama fonksiyonu (`validate_tckn`) araç olarak kodda hazır fakat validation agent tarafından şu an çağrılmıyor.
+- Tüm TCKN'ler veritabanına yazılmadan önce **maskelenir** (`123****8901` formatı).
+- Müşteri onay ekranında her alanı **hedefli olarak değiştirebilir**; yalnızca değiştirilen alan ve ona bağımlı alanlar yeniden sorulur.
+- Başvuru tamamlandıktan sonra UUID formatında **başvuru numarası** üretilir.
+- HGS çapraz satış yalnızca **aktif HGS'i olmayan** müşterilere sunulur.
+
+---
+
+## 3. Agentic Workflow
+
+Sistem **Supervisor + Specialist Agents** mimarisi üzerine inşa edilmiştir.
+
+```
+Müşteri Mesajı
+       │
+       ▼
+  [Input Guard]  ← PII maskeleme, injection tespiti
+       │
+       ▼
+  [Supervisor]   ← Niyet sınıflandırma, yönlendirme
+       │
+  ┌────┴─────────────────────────────────────────┐
+  │           │             │           │         │
+  ▼           ▼             ▼           ▼         ▼
+[Intake    [Intake      [FAQ/RAG   [Submission [Cross-sell
+ Yeni]      2.El]        Agent]     Agent]     Agent HGS]
+  │           │
+  └────┬──────┘
+       ▼
+[Validation Agent]  ← TCKN, katalog, iş kuralı kontrolleri
+       │
+       ▼
+  [Output Guard]  ← PII redaction, finansal taahhüt filtresi
+       │
+       ▼
+  Müşteri Cevabı
+```
+
+### Paralel FAQ Akışı
+
+Müşteri herhangi bir adımda SSS sorarsa:
+1. Supervisor `intent=faq` tespit eder
+2. Mevcut adım bilgisi state içindeki `faq_snapshot` alanına kaydedilir (`{"step": current_step}`)
+3. FAQ Agent soruyu yanıtlar
+4. Oturum önceki adımdan **devam eder** — müşteri yerini kaybetmez
+
+### Hedefli Güncelleme Akışı
+
+Onay ekranında müşteri alan değiştirmek istediğinde:
+1. LLM hangi alanın değiştirileceğini çıkarır
+2. Yalnızca o alan yeniden sorulur
+3. Bağımlı alanlar bozulduysa otomatik uyarı verilir
+
+---
+
+## 4. Agent'lar
+
+| Agent | Sorumluluk | Agentic Desen |
+|---|---|---|
+| **Supervisor Agent** | Niyet sınıflandırma, yönlendirme, planlama | Planner + Router |
+| **Intake Agent (Yeni Araç)** | Fatura, model, finansman, kefil TCKN toplanması; araç kataloğu sorgusu (binek/ticari doğrulama) | Slot Filling + Tool Use |
+| **Intake Agent (2. El)** | Kasko, yaş, finansman, satıcı TCKN toplanması | Slot Filling + Tool Use |
+| **Validation Agent** | Finansman limit kontrolü, iş kuralı kontrolleri | Tool Use (deterministik) |
+| **FAQ/RAG Agent** | SSS sorularını vektör DB'den yanıtlama | RAG + Tool Use |
+| **Submission Agent** | Onaylanan başvuruyu SQLite'a kaydetme | Tool Use + Write |
+| **Cross-sell Agent** | HGS durumu sorgulama ve kayıt | Tool Use (Scoped Access) |
+
+Her agent **least-privilege** prensibine göre çalışır: yalnızca ihtiyaç duyduğu tool'lara erişimi vardır.
+
+---
+
+## 5. Tool'lar (Araçlar)
+
+| Tool | Dosya | Açıklama |
+|---|---|---|
+| `validate_tckn` / `_mask` | `tools/tckn_tool.py` | Mod-11 doğrulama fonksiyonu (hazır, şu an çağrılmıyor) + TCKN maskeleme (`_mask` her yerde aktif) |
+| `lookup_vehicle` | `tools/catalog_tool.py` | Marka/model → binek/ticari sınıflandırması (JSON katalog) |
+| `retrieve_faq` | `tools/rag_tool.py` | ChromaDB'den semantic arama, chunk döndürme |
+| `write_application` | `tools/db_tool.py` | Ön başvuruyu SQLite'a kayıt |
+| `check_hgs_status` | `tools/hgs_tool.py` | Müşterinin aktif HGS'i var mı? (mock) |
+| `register_hgs` | `tools/hgs_tool.py` | HGS başvurusu kayıt (mock) |
+
+Tüm tool'lar `@tool` decorator ile LangChain'e kayıtlıdır. LLM hangi tool'u çağıracağına karar verir; iş mantığı tool içinde deterministik çalışır.
+
+---
+
+## 6. Güvenlik Katmanları
+
+Bu projede uygulanan güvenlik katmanları:
+
+| Katman | Bileşen | İşlev |
+|---|---|---|
+| **L4** | Input Guard (`guardrails/input_guard.py`) | PII maskeleme (TCKN, IBAN, kart), prompt injection tespiti, uzunluk limiti |
+| **L5** | Orchestrator | Least-privilege tool erişimi, deterministik kural motoru |
+| **L7** | Output Guard (`guardrails/output_guard.py`) | PII redaction, finansal taahhüt filtresi, FAQ kaynak zorunluluğu |
+
+> L1 (TLS), L2 (IDP), L3 (API Gateway/WAF) bu projenin kapsam dışındaki altyapı gereksinimleridir.
+
+Tüm guard ve tool olayları **SQLite Audit Log**'a yazılır (`audit_events` tablosu, append-only); TCKN gibi hassas veriler maskelenmiş haliyle kaydedilir.
+
+---
+
+## 7. Teknolojiler
+
+### Çerçeveler ve Kütüphaneler
+
+| Teknoloji | Kullanım Amacı |
+|---|---|
+| **LangGraph** | Multi-agent state machine, checkpointing, graph orchestration |
+| **LangChain** | Tool dekoratörü, LLM soyutlama katmanı, mesaj formatları |
+| **Gradio** | Chatbot web arayüzü |
+| **OpenTelemetry** | Tracing altyapısı kurulu (`observability/tracer.py`), şu an ConsoleSpanExporter ile terminale yazıyor; Jaeger/Grafana bağlantısı yok |
+
+### Yapay Zeka / LLM
+
+| Teknoloji | Kullanım Amacı |
+|---|---|
+| **GPT-4o** (`ACTIVE_MODEL`) | Ana model — FAQ cevaplama, çok adımlı muhakeme |
+| **GPT-4o-mini** (`ROUTER_MODEL`) | Hızlı model — niyet sınıflandırma, slot çıkarımı |
+| **Claude (Anthropic)** | Opsiyonel alternatif model |
+| **Gemini (Google)** | Opsiyonel alternatif model |
+| **Jina Embeddings v3** | FAQ chunk embedding (API tabanlı) |
+
+### Depolama
+
+| Teknoloji | Kullanım Amacı |
+|---|---|
+| **ChromaDB** | Vektör veritabanı — FAQ RAG için semantic arama |
+| **SQLite** | Ön başvuru ve HGS kayıtları |
+| **LangGraph MemorySaver** | Oturum başına konuşma durumu (short-term memory) |
+
+### Üretim Hedefi (Planlanan, Şu An Kodda Yok)
+
+| Teknoloji | Kullanım Amacı |
+|---|---|
+| **vLLM** | LLM inference sunucusu (Llama 3.1 8B / 70B) |
+| **BAAI/bge-m3** | On-prem embedding modeli |
+| **Qdrant** | On-prem vektör veritabanı |
+| **Redis** | Oturum store ve checkpointer |
+
+---
+
+## 8. Proje Yapısı
+
+```
+CarFinanceAgent/
+└── chatbot/
+    ├── app.py                      # Gradio arayüzü — giriş noktası
+    ├── config.py                   # Merkezi konfigürasyon, iş kuralları, API key'ler
+    ├── setup.py                    # Kurulum scripti (DB init, FAQ indeksleme)
+    │
+    ├── graph/
+    │   ├── state.py                # ConversationState TypedDict
+    │   └── builder.py              # LangGraph graph tanımı, edge'ler
+    │
+    ├── agents/
+    │   ├── supervisor.py           # Niyet sınıflandırma, yönlendirme
+    │   ├── intake_new.py           # Yeni araç slot filling
+    │   ├── intake_used.py          # 2. el slot filling
+    │   ├── faq_agent.py            # RAG tabanlı SSS yanıtlama
+    │   ├── validation_agent.py     # TCKN, katalog, iş kuralı doğrulaması
+    │   ├── submission_agent.py     # Başvuru kayıt
+    │   └── crosssell_agent.py      # HGS çapraz satış
+    │
+    ├── tools/
+    │   ├── tckn_tool.py            # TCKN mod-11 doğrulama
+    │   ├── catalog_tool.py         # Araç kataloğu lookup
+    │   ├── rag_tool.py             # ChromaDB retrieval
+    │   ├── db_tool.py              # SQLite yazma/okuma
+    │   └── hgs_tool.py             # HGS mock servisi
+    │
+    ├── guardrails/
+    │   ├── input_guard.py          # L4: PII maskeleme, injection filtresi
+    │   └── output_guard.py         # L7: PII redaction, finansal taahhüt filtresi
+    │
+    ├── memory/
+    │   ├── checkpointer.py         # LangGraph MemorySaver konfigürasyonu
+    │   └── vector_store.py         # ChromaDB bağlantısı, indexleme, arama
+    │
+    ├── llm/
+    │   ├── router.py               # LLM seçimi (ACTIVE_MODEL / ROUTER_MODEL)
+    │   └── prompts.py              # Tüm sistem prompt şablonları
+    │
+    ├── observability/
+    │   ├── tracer.py               # OpenTelemetry tracing altyapısı (ConsoleSpanExporter)
+    │   ├── audit_logger.py         # KVKK uyumlu SQLite audit log
+    │   ├── metrics.py              # SQLite'tan metrik hesaplama (latency, dönüşüm oranı vb.)
+    │   └── dashboard.py            # Gradio İzleme Paneli sekmesi
+    │
+    └── data/
+        ├── faq.md                  # SSS kaynak dokümanı (Markdown)
+        ├── vehicle_catalog.json    # Araç marka/model → binek/ticari kataloğu
+        ├── chroma/                 # ChromaDB persist dizini
+        └── applications.db         # SQLite veritabanı
+```
+
+---
+
+## 9. İzleme Paneli
+
+Uygulama, sohbet sekmesinin yanında **📊 İzleme Paneli** sekmesi içerir. Yenile butonuna basıldığında SQLite `audit_events` tablosundan anlık veri çeker; ek bir servis gerekmez.
+
+### Gösterilen Metrikler
+
+| Metrik | Kaynak |
+|---|---|
+| Toplam başvuru sayısı | `applications` tablosu |
+| HGS dönüşüm oranı (%) | `hgs_registrations / applications` |
+| Guard tetiklenme sayısı | `audit_events` — `event_type=guard_event` |
+| LLM latency p50 / p95 (ms) | Son 100 `llm_call` olayından hesaplanır |
+
+### Denetim Olay Tablosu
+
+Son 30 audit olayı listelenir: oturum ID, saat, olay türü (`llm_call`, `tool_call`, `guard_event`, `slot_change`), agent adı ve özet.
+
+### LLM Çağrı Tablosu
+
+Son 50 LLM çağrısı; model, latency, token sayısı, prompt ve response önizlemesiyle gösterilir. Kısmî oturum UUID'siyle filtrelenebilir.
+
+> İlgili dosyalar: `observability/dashboard.py` (Gradio sekme), `observability/metrics.py` (SQLite sorgular), `observability/audit_logger.py` (kayıt).
+
+---
+
+## 10. Kurulum ve Çalıştırma
+
+### Gereksinimler
+
+- Python 3.11+
+- OpenAI API key (GPT-4o için)
+- Jina AI API key (FAQ embedding için)
+
+### Adımlar
+
+```bash
+# 1. Sanal ortam oluştur ve aktifleştir
+cd chatbot
+python -m venv .venv
+.venv\Scripts\activate          # Windows
+# source .venv/bin/activate     # Linux/Mac
+
+# 2. Bağımlılıkları yükle
+pip install -r requirements.txt
+
+# 3. Ortam değişkenlerini ayarla
+cp .env.example .env
+# .env dosyasını düzenleyip API key'leri gir
+
+# 4. İlk kurulumu çalıştır (DB init + FAQ indeksleme)
+python setup.py
+
+# 5. Uygulamayı başlat
+python app.py
+```
+
+Uygulama başladıktan sonra `http://localhost:7860` adresinde Gradio arayüzü açılır.
+
+---
+
+## 11. Konfigürasyon
+
+`config.py` dosyası merkezi konfigürasyon noktasıdır. Model değiştirmek için yalnızca `.env` dosyasını güncellemek yeterlidir:
+
+```env
+# .env
+OPENAI_API_KEY=sk-...
+ANTHROPIC_API_KEY=sk-ant-...
+GOOGLE_API_KEY=AI...
+JINA_API_KEY=jina_...
+
+# Model seçimi
+ACTIVE_MODEL=gpt-4o           # veya: claude-opus-4-7, gemini-2.0-flash
+ROUTER_MODEL=gpt-4o-mini      # hızlı sınıflandırma modeli
+```
+
+### İş Kurallarını Değiştirme
+
+Tüm eşikler `config.py`'de sabitler olarak tanımlıdır:
+
+```python
+NEW_CAR_MAX_INVOICE = 7_000_000.0       # TL
+NEW_CAR_FINANCE_RATIO = 0.60            # %60
+NEW_CAR_GUARANTOR_THRESHOLD = 5_000_000.0
+USED_CAR_MAX_AGE = 5                    # yıl
+USED_CAR_FINANCE_RATIO = 0.40           # %40
+USED_CAR_MAX_FINANCE = 3_000_000.0      # TL
+```
+
+---
+
+## 12. Diyagramlar
+
+Detaylı sistem mimarisi, use case akışları ve güvenlik katmanı diyagramları için [chatbot/DIAGRAMS.md](chatbot/DIAGRAMS.md) dosyasına bakın.
+
+> **Not:** Diyagramlar Mermaid formatındadır. VS Code'da görüntülemek için **"Markdown Preview Mermaid Support"** uzantısını yükleyin, ardından `Ctrl+Shift+V` ile önizleyin. Alternatif olarak [mermaid.live](https://mermaid.live) sitesini kullanabilirsiniz.
+
+### Diyagram Listesi
+
+| # | Diyagram | Açıklama |
+|---|---|---|
+| 1 | Agentic Tasarım | Agent'lar, tool'lar ve shared memory |
+| 2 | Ana Akış (Use Case) | Yeni araç ve 2. el dalları, SSS entegrasyonu |
+| 3 | Hedefli Güncelleme Akışı | Onay ekranında alan değiştirme mantığı |
+| 4 | Paralel FAQ Akışı | Sequence diagram — snapshot / restore döngüsü |

chatbot/DIAGRAMS.md

@@ -0,0 +1,149 @@
+# Araç Finansmanı Chatbot — Diyagramlar
+
+---
+
+## 1. Agentic Tasarım
+
+```mermaid
+graph TD
+    USR[Müşteri Mesajı] --> SUP{Supervisor Agent<br/>Planner + Router}
+
+    SUP -->|niyet: yeni araç| INTAKE_NEW[Intake Agent<br/>Yeni Araç]
+    SUP -->|niyet: 2.el| INTAKE_USED[Intake Agent<br/>2. El]
+    SUP -->|niyet: SSS| FAQ[FAQ/RAG Agent]
+    SUP -->|kayıt zamanı| APP[Application Submission Agent]
+    SUP -->|çapraz satış| XS[Cross-sell Agent<br/>HGS]
+
+    INTAKE_NEW --> VAL[Validation Agent]
+    INTAKE_USED --> VAL
+    VAL -.tool.-> TOOLS[(Tool Registry<br/>TCKN, Katalog, Hesap)]
+
+    FAQ -.tool.-> VDB[(Vektör DB<br/>ChromaDB)]
+    APP -.tool.-> APPDB[(Ön Başvuru DB)]
+    XS -.tool.-> HGSAPI[HGS Servisi]
+
+    SUP <--> MEM[(Shared State / Memory<br/>slotlar, conversation history)]
+    INTAKE_NEW <--> MEM
+    INTAKE_USED <--> MEM
+    FAQ <--> MEM
+    APP <--> MEM
+    XS <--> MEM
+
+    SUP --> REF[Reflection / Self-check]
+    REF --> SUP
+```
+
+
+---
+
+## 2. Use Case Workflow — Ana Akış
+
+```mermaid
+flowchart TD
+    Start([Müşteri chatbot'u açar]) --> S1[1- Karşılama ve amaç teyidi]
+    S1 --> S2{2- Niyet Sınıflandırma<br/>LLM}
+    S2 -->|Yeni Araç| A1
+    S2 -->|2. El| B1
+    S2 -->|SSS Sorusu| F1[FAQ/RAG Akışı]
+    S2 -->|Alakasız| OOS[Kapsam dışı - kibarca yönlendir]
+    F1 --> Resume[Önceki adıma dön]
+
+    subgraph NewCar["Dal A — Yeni Araç"]
+        A1[A1- Proforma fatura tutarı sor] --> A1V{≤ 7M?}
+        A1V -->|Hayır| AStop1[Üst limit aşıldı - başvuru kapatılır]
+        A1V -->|Evet| A2[A2- Araç modeli sor]
+        A2 --> A2V{Ticari mi?<br/>Katalog lookup}
+        A2V -->|Evet| AStop2[Ticari modele uygun değil]
+        A2V -->|Hayır| A3[A3- İstenen finansman sor]
+        A3 --> A3V{≤ %60 × fiyat?}
+        A3V -->|Hayır| A3F[Maks tutarı öner, tekrar sor]
+        A3F --> A3
+        A3V -->|Evet| A4{Fiyat ≥ 5M?}
+        A4 -->|Evet| A5[A5- Kefil TCKN sor]
+        A5 --> A5V{TCKN 11 hane format geçerli?}
+        A5V -->|Hayır| A5
+        A5V -->|Evet| Recap
+        A4 -->|Hayır| Recap
+    end
+
+    subgraph Used["Dal B — 2. El"]
+        B1[B1- Kasko değeri sor] --> B2[B2- Araç yaşı sor]
+        B2 --> B2V{Yaş ≤ 5?}
+        B2V -->|Hayır| BStop1[5 yaş üstü kabul edilmiyor]
+        B2V -->|Evet| B3[B3- İstenen finansman sor]
+        B3 --> B3V{"≤ min %40×kasko ve 3M?"}
+        B3V -->|Hayır| B3F[Maks tutarı öner, tekrar sor]
+        B3F --> B3
+        B3V -->|Evet| B4[B4- Satıcı TCKN sor - opsiyonel]
+        B4 --> Recap
+    end
+
+    Recap[7- Onay Ekranı: tüm alanları göster]
+    Recap --> Edit{Müşteri değiştirmek istiyor mu?}
+    Edit -->|Evet, alan adı belirt| GoTo[İlgili alanın sorusu tekrar sorulur ve doğrulanır]
+    GoTo -.yeni araç alanı güncelleme.-> A1
+    GoTo -.yeni araç alanı güncelleme.-> A2
+    GoTo -.yeni araç alanı güncelleme.-> A3
+    GoTo -.yeni araç alanı güncelleme.-> A5
+    GoTo -.ikinci el alanı güncelleme.-> B1
+    GoTo -.ikinci el alanı güncelleme.-> B2
+    GoTo -.ikinci el alanı güncelleme.-> B3
+    GoTo -.ikinci el alanı güncelleme.-> B4
+    Edit -->|Hayır, onayla| Submit[8- Ön başvuru DB'ye yaz]
+    Submit --> RefNo[Başvuru numarası dön]
+    RefNo --> Cross[9- HGS Çapraz Satış]
+    Cross --> CrossQ{HGS istiyor mu?}
+    CrossQ -->|Evet| HGS[HGS servisine kayıt]
+    CrossQ -->|Hayır| End
+    HGS --> End([Bitiş - özet ve teşekkür])
+```
+
+
+---
+
+## 3. Hedefli Güncelleme Akışı
+
+```mermaid
+flowchart TD
+    Recap[Onay Ekranı] -->|"'X alanını değiştir'"| Detect[LLM: hedef alanı çıkar]
+    Detect --> AskOne[Yalnız hedef alanı sor]
+    AskOne --> V1{Alanın kendi kuralı OK?}
+    V1 -->|Hayır| AskOne
+    V1 -->|Evet| Cross{Çapraz kurallar<br/>hâlâ geçerli mi?}
+    Cross -->|Evet| Recap
+    Cross -->|Hayır - bağımlı alan bozuldu| Notify[Müşteriye bildir:<br/>'yeni X ile mevcut Y uymuyor']
+    Notify --> AskDep[Yalnız bağımlı alanı sor]
+    AskDep --> V2{Doğrula}
+    V2 -->|Hayır| AskDep
+    V2 -->|Evet| Recap
+```
+
+
+---
+
+## 4. Paralel SSS (FAQ) Akışı — Sequence
+
+```mermaid
+sequenceDiagram
+    participant U as Müşteri
+    participant O as Orchestrator
+    participant R as Router LLM
+    participant F as FAQ Agent (RAG)
+    participant S as State (faq_snapshot)
+
+    Note over U,S: Müşteri Dal A - adım A2 (model sorusu) cevabını bekliyor
+    O->>U: "Hangi marka ve model?"
+    U->>O: "Vade seçenekleri nedir?"
+    O->>R: niyet sınıflandır
+    R-->>O: intent=faq
+    O->>S: faq_snapshot = {step: A2, awaited_slot: vehicle_model}
+    O->>F: query("vade seçenekleri")
+    F->>F: embed + top-k retrieve
+    F-->>O: cevap + kaynak chunk
+    O->>U: cevap + "Kaldığımız yerden - markayı sormuştum, devam edelim mi?"
+    U->>O: "BMW 320i"
+    O->>R: niyet sınıflandır
+    R-->>O: intent=slot_answer (vehicle_model)
+    O->>S: faq_snapshot temizle + slot kaydet
+    O->>U: (A3 - finansman tutarı sorusu)
+```

chatbot/agents/crosssell_agent.py

@@ -0,0 +1,86 @@
+"""
+agents/crosssell_agent.py — HGS Çapraz Satış Agent'ı
+
+AGENTIC PATTERN: Scoped Tool Access (Least-Privilege)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Bu agent YALNIZCA HGS servisine erişebilir.
+Ön Başvuru DB'ye dokunamaz — bu least-privilege prensibin uygulaması.
+
+İki adım:
+1. check_hgs_status → aktif HGS varsa adımı atla
+2. Teklif sun → onaylanırsa register_hgs çağır
+"""
+from langchain_core.messages import AIMessage
+from tools.hgs_tool import check_hgs_status, register_hgs
+from graph.state import ConversationState
+from observability.audit_logger import log_tool_call, log_slot_change
+
+HGS_ACCEPT_WORDS = ["evet", "istiyorum", "tamam", "olur", "onaylıyorum"]
+HGS_REJECT_WORDS = ["hayır", "istemiyorum", "geç", "atla", "vazgeçtim", "lazım değil", "hayir"]
+
+
+def run_crosssell(state: ConversationState) -> dict:
+    """HGS çapraz satış node fonksiyonu."""
+
+    # Adım 1: Aktif HGS var mı?
+    hgs_status = check_hgs_status.invoke({"session_id": state["session_id"]})
+    log_tool_call(state["session_id"], "crosssell_agent", "check_hgs_status",
+                  {}, hgs_status, True)
+
+    if hgs_status["has_active_hgs"]:
+        # HGS zaten var → adımı atla
+        return {
+            "current_step": "crosssell_skipped",
+            "hgs_consent": False,
+            "messages": state["messages"] + [
+                AIMessage(content="HGS'iniz zaten aktif. İyi sürüşler! 🚗\n\nBaşvurunuz için teşekkürler.")
+            ],
+            "flow_ended": True,
+        }
+
+    # Adım 2: Müşterinin son mesajı HGS teklifine cevap mı?
+    last_message = state["messages"][-1]
+    user_text = last_message.content if hasattr(last_message, "content") else ""
+
+    if hasattr(last_message, "type") and last_message.type == "ai":
+        # Teklifi zaten gönderdik, cevap bekliyoruz
+        return {"current_step": "crosssell_waiting"}
+
+    lower = user_text.lower()
+
+    if any(w in lower for w in HGS_REJECT_WORDS):
+        log_slot_change(state["session_id"], "hgs_consent", None, False)
+        return {
+            "current_step": "crosssell_declined",
+            "hgs_consent": False,
+            "flow_ended": True,
+            "messages": state["messages"] + [
+                AIMessage(content="Anlaşıldı. Başvurunuz için teşekkürler, iyi günler! 🙂")
+            ],
+        }
+
+    if any(w in lower for w in HGS_ACCEPT_WORDS):
+        # HGS kaydı yap
+        hgs_result = register_hgs.invoke({
+            "session_id": state["session_id"],
+            "application_id": state.get("application_id", ""),
+        })
+        log_tool_call(state["session_id"], "crosssell_agent", "register_hgs",
+                      {"application_id": state.get("application_id")},
+                      hgs_result, hgs_result["success"])
+        log_slot_change(state["session_id"], "hgs_consent", None, True)
+
+        if hgs_result["success"]:
+            msg = f"HGS'iniz başarıyla tanımlandı! (HGS No: {hgs_result['hgs_id']})\n\nTeşekkürler, iyi sürüşler! 🚗"
+        else:
+            msg = "HGS tanımlamasında bir sorun oluştu. Şubemizden destek alabilirsiniz."
+
+        return {
+            "current_step": "crosssell_complete",
+            "hgs_consent": True,
+            "flow_ended": True,
+            "messages": state["messages"] + [AIMessage(content=msg)],
+        }
+
+    # İlk kez geliyorsa teklif gösterildi mi? (submission_agent zaten HGS_PITCH'i gönderdi)
+    return {"current_step": "crosssell_waiting"}

chatbot/agents/faq_agent.py

@@ -0,0 +1,134 @@
+"""
+agents/faq_agent.py — FAQ / RAG Agent
+
+AGENTIC PATTERN: RAG (Retrieval-Augmented Generation)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+RAG pattern'de model yeni bilgi üretmez; mevcut dokümanı
+kullanarak soruyu cevaplar. Bu sayede:
+- Halüsinasyon riski minimum (sadece getirilen chunk'tan cevap)
+- Cevap kaynağı şeffaf (kaynak chunk gösterilir)
+- Doküman güncellenince otomatik güncel cevap
+
+Akış:
+  1. retrieve_faq tool'u → ChromaDB'den top-k chunk
+  2. Chunk'lar prompt'a context olarak eklenir
+  3. Büyük model cevap üretir (sadece context'ten)
+  4. Output Guard: kaynak chunk zorunlu
+  5. State snapshot'tan kaldığı yere dönülür
+
+SCOPED ACCESS: FAQ agent sadece VectorDB read yetkisine sahip.
+Slot okuyamaz/yazamaz — başka müşterinin verisi sızmaz.
+"""
+import time
+from langchain_core.messages import AIMessage
+from tools.rag_tool import retrieve_faq
+from llm.factory import get_main_llm, get_llm
+from llm.prompts import FAQ_SYSTEM
+from graph.state import ConversationState
+from guardrails.output_guard import check_output
+from observability.audit_logger import log_llm_call, log_tool_call
+
+
+def run_faq_agent(state: ConversationState) -> dict:
+    """
+    FAQ node fonksiyonu.
+
+    Müşterinin sorusunu RAG ile yanıtlar, ardından
+    kaldığı adıma devam etmesini önerir.
+    """
+    last_message = state["messages"][-1]
+    user_query = last_message.content if hasattr(last_message, "content") else str(last_message)
+
+    # ── Adım 1: Retrieval ─────────────────────────────────────────────────────
+    retrieval_result = retrieve_faq.invoke({"query": user_query})
+    chunks = retrieval_result["chunks"]
+    context = retrieval_result["context"]
+
+    log_tool_call(
+        session_id=state["session_id"],
+        agent="faq_agent",
+        tool_name="retrieve_faq",
+        args={"query": user_query[:100]},
+        result={"chunk_count": len(chunks)},
+        success=True,
+    )
+
+    # ── Adım 2: LLM ile cevap üret ────────────────────────────────────────────
+    llm = get_main_llm()
+    system_with_context = FAQ_SYSTEM.format(context=context)
+
+    faq_messages = [
+        {"role": "system", "content": system_with_context},
+        {"role": "user", "content": user_query},
+    ]
+
+    start = time.time()
+    response = llm.invoke(faq_messages)
+    # Gemini RECITATION/SAFETY filtresinde boş içerik dönebilir; farklı sampling
+    # ile bir kez daha dene (sıcaklık > 0 genelde filtreyi aşar).
+    if not (response.content or "").strip():
+        response = get_llm(size="large", temperature=0.5).invoke(faq_messages)
+    latency = int((time.time() - start) * 1000)
+
+    log_llm_call(
+        session_id=state["session_id"],
+        agent="faq_agent",
+        model=llm.model,
+        latency_ms=latency,
+        tokens_in=len(system_with_context.split()) + len(user_query.split()),
+        tokens_out=len(response.content.split()),
+        prompt=[
+            {"role": "system", "content": system_with_context},
+            {"role": "user", "content": user_query},
+        ],
+        response=response.content,
+    )
+
+    # ── Adım 3: Output Guard ──────────────────────────────────────────────────
+    guard_result = check_output(
+        text=response.content,
+        session_id=state["session_id"],
+        is_faq_response=True,
+        source_chunks=chunks,
+    )
+
+    if not guard_result["allowed"]:
+        answer = "Bu konuda şu anda yardımcı olamıyorum. Lütfen şubemizi arayın."
+    else:
+        answer = guard_result["cleaned_text"]
+
+    # ── Adım 4: Resume mesajı ekle ────────────────────────────────────────────
+    pending_question = _get_pending_question(state)
+    resume_hint = f"\n\n---\n*Kaldığımız yere dönelim: {pending_question}*" if pending_question else ""
+
+    full_answer = answer + resume_hint
+
+    return {
+        "current_step": "faq_answered",
+        "messages": state["messages"] + [AIMessage(content=full_answer)],
+        # Snapshot korunur; bir sonraki turda supervisor yeniden çalışır
+    }
+
+
+# Bekleyen soru metinleri — slot bazlı
+_PENDING_SLOT_QUESTIONS = {
+    "kasko_value": "Aracın güncel kasko değeri nedir? (TL olarak)",
+    "vehicle_age": "Aracın model yılı veya yaşı nedir? (örn: 2021 model veya 3 yaşında)",
+    "requested_amount_used": "Ne kadar finansman almak istiyorsunuz? (TL olarak)",
+    "seller_tckn": "Satıcının TC kimlik numarası nedir? (Bilmiyorsanız 'geç' yazabilirsiniz)",
+    "invoice_amount": "Aracın proforma fatura tutarı nedir? (TL olarak)",
+    "vehicle_model": "Hangi marka ve model aracı düşünüyorsunuz?",
+    "requested_amount_new": "Ne kadar finansman almak istiyorsunuz? (TL olarak)",
+    "guarantor_tckn": "Kefilinizin TC kimlik numarası nedir?",
+}
+
+
+def _get_pending_question(state: ConversationState) -> str | None:
+    """FAQ'ten sonra kullanıcının döneceği bekleyen soruyu üretir."""
+    awaited = state.get("awaited_slot")
+    if awaited and awaited in _PENDING_SLOT_QUESTIONS:
+        return _PENDING_SLOT_QUESTIONS[awaited]
+    # Henüz araç türü seçilmemişse baştaki soruya dön
+    if not state.get("vehicle_type"):
+        return "Yeni araç mı, 2. el araç mı düşünüyorsunuz?"
+    return None

chatbot/agents/intake_new.py

@@ -0,0 +1,260 @@
+"""
+agents/intake_new.py — Yeni Araç Slot Toplama Agent'ı
+
+AGENTIC PATTERN: Slot Filling + LLM Entity Extraction
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Hangi slot'un eksik olduğunu state'e bakarak bulur,
+o slot için soru sorar veya müşterinin cevabından değeri çıkarır.
+
+LLM'in görevi SADECE:
+  - Sayı normalize (iki buçuk milyon → 2500000)
+  - Entity extract (araç modeli: "bmw üç serisi" → BMW 3 Serisi)
+  - TCKN ham metin çıkarımı
+
+İş kuralı kararları (ticari mi, limit aşıldı mı) → validation_agent.
+"""
+import time
+from langchain_core.messages import AIMessage
+from llm.factory import get_router_llm
+from llm.json_utils import parse_llm_json
+from llm.prompts import SLOT_EXTRACTION_SYSTEM, VEHICLE_MODEL_EXTRACTION_SYSTEM
+from graph.state import ConversationState
+from observability.audit_logger import log_llm_call, log_slot_change
+from tools.tckn_tool import _mask
+
+
+# Sıralı slot listesi (hangi alan önce sorulacak)
+NEW_CAR_SLOTS_ORDER = [
+    "invoice_amount",
+    "vehicle_model",
+    "requested_amount_new",
+    "guarantor_tckn",  # sadece kefil_required=True ise
+]
+
+SLOT_QUESTIONS = {
+    "invoice_amount": "Aracın proforma fatura tutarı nedir? (TL olarak)",
+    "vehicle_model": "Hangi marka ve model aracı düşünüyorsunuz?",
+    "requested_amount_new": "Ne kadar finansman almak istiyorsunuz? (TL olarak)",
+    "guarantor_tckn": "Proforma tutarı 5.000.000 TL üzerinde olduğu için kefil göstermeniz gerekmektedir. Kefilinizin TC kimlik numarası nedir?",
+}
+
+
+def get_next_missing_slot(state: ConversationState) -> str | None:
+    """Sıradaki eksik slot'u döndürür; tümü doluysa None."""
+    for slot in NEW_CAR_SLOTS_ORDER:
+        if slot == "guarantor_tckn" and not state.get("kefil_required"):
+            continue
+        if not state.get(slot):
+            return slot
+    return None
+
+
+def run_intake_new(state: ConversationState) -> dict:
+    """
+    Yeni araç intake node fonksiyonu.
+
+    İki mod:
+    A) Eksik slot var → soru sor
+    B) Son mesaj bir cevap → parse et, slot'a yaz, doğrula
+    """
+    last_message = state["messages"][-1]
+    user_text = last_message.content if hasattr(last_message, "content") else str(last_message)
+
+    # Eğer son mesaj AI ise (soru sorduk) → henüz cevap yok, bekle
+    if hasattr(last_message, "type") and last_message.type == "ai":
+        # Tüm slotlar zaten dolmuşsa intake_new_complete'i koru, recap akışı bozulmasın
+        if get_next_missing_slot(state) is None:
+            return {"current_step": "intake_new_complete", "awaited_slot": None}
+        return {"current_step": "intake_new_waiting"}
+
+    # Mevcut state'den ne beklediğimizi bul (awaited_slot alanından)
+    awaited_slot = state.get("awaited_slot")
+    import sys
+    print(f"[DEBUG intake_new] awaited_slot={awaited_slot} user_text={user_text!r} current_step={state.get('current_step')} invoice={state.get('invoice_amount')} vtype={state.get('vehicle_type')}", flush=True)
+    sys.stdout.flush()
+
+    # Parse fazından gelen güncellemeleri biriktir, ama erken return etme;
+    # parse başarılıysa aynı tur içinde sıradaki slotu da sormak istiyoruz.
+    parse_updates: dict = {}
+    if awaited_slot and awaited_slot in NEW_CAR_SLOTS_ORDER:
+        updated = _parse_slot(state, awaited_slot, user_text)
+        print(f"[DEBUG intake_new] parse result for slot '{awaited_slot}': {updated}", flush=True)
+        if updated:
+            parse_succeeded = awaited_slot in updated and updated[awaited_slot] is not None
+            if parse_succeeded:
+                updated["awaited_slot"] = None
+                updated["edit_target_slot"] = None  # slot toplandı, edit hedefini temizle
+                # flow_ended set edildiyse (ör. fatura üst limit aşımı) hemen dur
+                if updated.get("flow_ended"):
+                    return updated
+                parse_updates = updated
+                # Merge'i sıradaki-slot lookup'ı doğru görebilsin diye state üstüne uygula
+                state = {**state, **parse_updates}
+            else:
+                # Parse başarısız → tekrar sor (zaten updated içinde messages var)
+                return updated
+
+    # Bir sonraki eksik slot'u bul ve sor
+    next_slot = get_next_missing_slot(state)
+    print(f"[DEBUG intake_new] next missing slot: {next_slot}", flush=True)
+    if next_slot:
+        question = SLOT_QUESTIONS[next_slot]
+        return {
+            **parse_updates,
+            "current_step": f"asking_{next_slot}",
+            "awaited_slot": next_slot,
+            "messages": state["messages"] + [AIMessage(content=question)],
+        }
+
+    # Tüm slot'lar dolu → recap'e geç
+    print(f"[DEBUG intake_new] all slots filled, proceeding to recap", flush=True)
+    return {**parse_updates, "current_step": "intake_new_complete", "awaited_slot": None}
+
+
+def _parse_slot(state: ConversationState, slot: str, user_text: str) -> dict | None:
+    """LLM ile slot değerini parse et."""
+    llm = get_router_llm()
+
+    if slot in ("invoice_amount", "requested_amount_new"):
+        return _parse_number_slot(state, slot, user_text, llm)
+    elif slot == "vehicle_model":
+        return _parse_vehicle_model(state, user_text, llm)
+    elif slot == "guarantor_tckn":
+        return _parse_tckn_slot(state, slot, user_text, llm)
+    return None
+
+
+def _parse_number_slot(state, slot, user_text, llm) -> dict:
+    start = time.time()
+    response = llm.invoke([
+        {"role": "system", "content": SLOT_EXTRACTION_SYSTEM},
+        {"role": "user", "content": user_text},
+    ])
+    import sys
+    print(f"[DEBUG _parse_number_slot] slot={slot} user_text={user_text!r} llm_response={response.content!r}", flush=True)
+    sys.stdout.flush()
+    latency = int((time.time() - start) * 1000)
+    log_llm_call(
+        state["session_id"], "intake_new", llm.model, latency,
+        len(user_text.split()), len(response.content.split()),
+        prompt=[
+            {"role": "system", "content": SLOT_EXTRACTION_SYSTEM},
+            {"role": "user", "content": user_text},
+        ],
+        response=response.content,
+    )
+
+    parsed = parse_llm_json(response.content)
+    value = parsed.get("value") if parsed else None
+
+    if value is None:
+        question = SLOT_QUESTIONS.get(slot, "Lütfen rakamla yazın.")
+        return {
+            "current_step": f"asking_{slot}",
+            "awaited_slot": slot,
+            "messages": state["messages"] + [
+                AIMessage(content=f"Devam edelim — {question} (lütfen rakamla yazın, örn: 3000000 veya 3M TL)")
+            ],
+        }
+
+    old_val = state.get(slot)
+    log_slot_change(state["session_id"], slot, old_val, value)
+
+    # Fatura üst limit hızlı kontrol — kapatma, yeniden sor
+    if slot == "invoice_amount" and value > 7_000_000:
+        msg = (f"Proforma fatura tutarı maksimum 7.000.000 TL olabilir "
+               f"(girilen: {int(value):,} TL).\n"
+               "Aracın proforma fatura tutarı nedir? (TL olarak)")
+        return {
+            "current_step": "asking_invoice_amount",
+            "awaited_slot": "invoice_amount",
+            "messages": state["messages"] + [AIMessage(content=msg)],
+        }
+
+    return {slot: value, "current_step": f"{slot}_collected"}
+
+
+def _parse_vehicle_model(state, user_text, llm) -> dict:
+    start = time.time()
+    response = llm.invoke([
+        {"role": "system", "content": VEHICLE_MODEL_EXTRACTION_SYSTEM},
+        {"role": "user", "content": user_text},
+    ])
+    latency = int((time.time() - start) * 1000)
+    log_llm_call(
+        state["session_id"], "intake_new", llm.model, latency,
+        len(user_text.split()), len(response.content.split()),
+        prompt=[
+            {"role": "system", "content": VEHICLE_MODEL_EXTRACTION_SYSTEM},
+            {"role": "user", "content": user_text},
+        ],
+        response=response.content,
+    )
+
+    parsed = parse_llm_json(response.content)
+    if parsed:
+        brand = parsed.get("brand", "")
+        model = parsed.get("model", "")
+        needs_clarification = parsed.get("needs_clarification", False)
+    else:
+        needs_clarification = True
+        brand = model = ""
+
+    if needs_clarification or not model:
+        return {
+            "current_step": "asking_vehicle_model",
+            "awaited_slot": "vehicle_model",
+            "messages": state["messages"] + [
+                AIMessage(content="Marka ve modeli tam olarak belirtebilir misiniz? (örn: Toyota Corolla, BMW 3 Serisi)")
+            ],
+        }
+
+    vehicle_model_str = f"{brand} {model}".strip()
+
+    # Ticari araç kontrolü — kataloğa bakarak hemen filtrele
+    from tools.catalog_tool import lookup_vehicle
+    catalog_result = lookup_vehicle.invoke({"brand": brand, "model": model})
+    if catalog_result["found"] and catalog_result["type"] == "ticari":
+        msg = (f"Maalesef {vehicle_model_str} ticari bir araçtır. "
+               "Bankamız yalnızca binek araçlara finansman sağlamaktadır. "
+               "Farklı bir araç modeli girebilirsiniz.")
+        return {
+            "current_step": "asking_vehicle_model",
+            "awaited_slot": "vehicle_model",
+            "messages": state["messages"] + [AIMessage(content=msg)],
+        }
+
+    log_slot_change(state["session_id"], "vehicle_model", state.get("vehicle_model"), vehicle_model_str)
+    return {"vehicle_model": vehicle_model_str, "current_step": "vehicle_model_collected"}
+
+
+def _parse_tckn_slot(state, slot, user_text, llm) -> dict:
+    # Skip intent
+    skip_words = ["geç", "yok", "bilmiyorum", "pas", "atla", "istemiyorum"]
+    if any(w in user_text.lower() for w in skip_words):
+        if slot == "seller_tckn":
+            log_slot_change(state["session_id"], slot, None, "skipped")
+            return {slot: None, "current_step": f"{slot}_skipped"}
+
+    import re
+    # Ham TCKN veya input guard tarafından maskelenmiş (123****8910) her iki pattern'ı tanı
+    match = re.search(r"\b[1-9]\d{10}\b", user_text)
+    masked_match = re.search(r"\b([1-9]\d{2})\*{4}(\d{4})\b", user_text) if not match else None
+
+    if match:
+        tckn = match.group()
+    elif masked_match:
+        # Maskelenmiş geldi — ham hali yok, maskelenmiş hali sakla
+        tckn = masked_match.group()
+    else:
+        return {
+            "current_step": f"asking_{slot}",
+            "awaited_slot": slot,
+            "messages": state["messages"] + [
+                AIMessage(content="TCKN'yi 11 haneli olarak tam yazabilir misiniz?")
+            ],
+        }
+
+    masked = _mask(tckn) if match else tckn
+    log_slot_change(state["session_id"], slot, None, masked)
+    return {slot: tckn, "current_step": f"{slot}_collected"}

chatbot/agents/intake_used.py

@@ -0,0 +1,229 @@
+"""
+agents/intake_used.py — 2. El Araç Slot Toplama Agent'ı
+
+AGENTIC PATTERN: Slot Filling (State Machine'e bağlı)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+intake_new.py ile aynı pattern; 2. el dalının slot'ları farklı.
+Satıcı TCKN opsiyoneldir — müşteri "bilmiyorum" diyebilir.
+"""
+import re
+import time
+from langchain_core.messages import AIMessage
+from llm.factory import get_router_llm
+from llm.json_utils import parse_llm_json
+from llm.prompts import SLOT_EXTRACTION_SYSTEM
+from graph.state import ConversationState
+from observability.audit_logger import log_llm_call, log_slot_change
+from tools.tckn_tool import _mask
+
+USED_CAR_SLOTS_ORDER = ["kasko_value", "vehicle_age", "requested_amount_used", "seller_tckn"]
+
+SLOT_QUESTIONS = {
+    "kasko_value": "Aracın güncel kasko değeri nedir? (TL olarak)",
+    "vehicle_age": "Aracın model yılı veya yaşı nedir? (örn: 2021 model veya 3 yaşında)",
+    "requested_amount_used": "Ne kadar finansman almak istiyorsunuz? (TL olarak)",
+    "seller_tckn": "Satıcının TC kimlik numarası nedir? (Bilmiyorsanız geçebilirsiniz)",
+}
+
+
+def get_next_missing_slot_used(state: ConversationState) -> str | None:
+    for slot in USED_CAR_SLOTS_ORDER:
+        val = state.get(slot)
+        # "" → skipped (geçildi), None → henüz sorulmadı
+        if val is None:
+            return slot
+    return None
+
+
+def run_intake_used(state: ConversationState) -> dict:
+    last_message = state["messages"][-1]
+    user_text = last_message.content if hasattr(last_message, "content") else str(last_message)
+
+    if hasattr(last_message, "type") and last_message.type == "ai":
+        if get_next_missing_slot_used(state) is None:
+            return {"current_step": "intake_used_complete", "awaited_slot": None}
+        return {"current_step": "intake_used_waiting"}
+
+    awaited_slot = state.get("awaited_slot")
+
+    parse_updates: dict = {}
+    if awaited_slot and awaited_slot in USED_CAR_SLOTS_ORDER:
+        updated = _parse_slot_used(state, awaited_slot, user_text)
+        if updated:
+            parse_succeeded = (
+                (awaited_slot in updated and updated[awaited_slot] is not None)
+                or updated.get("current_step", "").endswith("_skipped")
+            )
+            if parse_succeeded:
+                updated["awaited_slot"] = None
+                updated["edit_target_slot"] = None  # slot toplandı, edit hedefini temizle
+                if updated.get("flow_ended"):
+                    return updated
+                parse_updates = updated
+                state = {**state, **parse_updates}
+            else:
+                # Parse başarısız → tekrar sor
+                return updated
+
+    next_slot = get_next_missing_slot_used(state)
+    if next_slot:
+        question = SLOT_QUESTIONS[next_slot]
+        return {
+            **parse_updates,
+            "current_step": f"asking_{next_slot}",
+            "awaited_slot": next_slot,
+            "messages": state["messages"] + [AIMessage(content=question)],
+        }
+
+    return {**parse_updates, "current_step": "intake_used_complete", "awaited_slot": None}
+
+
+def _parse_slot_used(state, slot, user_text) -> dict | None:
+    llm = get_router_llm()
+
+    if slot == "kasko_value":
+        return _parse_number(state, slot, user_text, llm)
+
+    elif slot == "vehicle_age":
+        return _parse_age(state, user_text, llm)
+
+    elif slot == "requested_amount_used":
+        return _parse_number(state, slot, user_text, llm)
+
+    elif slot == "seller_tckn":
+        return _parse_optional_tckn(state, user_text)
+
+    return None
+
+
+def _parse_number(state, slot, user_text, llm) -> dict:
+    start = time.time()
+    response = llm.invoke([
+        {"role": "system", "content": SLOT_EXTRACTION_SYSTEM},
+        {"role": "user", "content": user_text},
+    ])
+    latency = int((time.time() - start) * 1000)
+    log_llm_call(
+        state["session_id"], "intake_used", llm.model, latency,
+        len(user_text.split()), len(response.content.split()),
+        prompt=[
+            {"role": "system", "content": SLOT_EXTRACTION_SYSTEM},
+            {"role": "user", "content": user_text},
+        ],
+        response=response.content,
+    )
+    parsed = parse_llm_json(response.content)
+    value = parsed.get("value") if parsed else None
+
+    if value is None:
+        question = SLOT_QUESTIONS.get(slot, "Lütfen rakamla yazın.")
+        return {
+            "current_step": f"asking_{slot}",
+            "awaited_slot": slot,
+            "messages": state["messages"] + [
+                AIMessage(content=f"Devam edelim — {question} (lütfen rakamla yazın, örn: 500000 veya 500bin TL)")
+            ],
+        }
+    log_slot_change(state["session_id"], slot, state.get(slot), value)
+    return {slot: value, "current_step": f"{slot}_collected"}
+
+
+def _parse_age(state, user_text, llm) -> dict:
+    """Model yılı veya yaş ifadesini parse eder."""
+    import datetime
+    current_year = datetime.date.today().year
+
+    # Önce direkt yıl ara: 2020, 2021 vb.
+    year_match = re.search(r"\b(20\d{2})\b", user_text)
+    if year_match:
+        age = current_year - int(year_match.group(1))
+        log_slot_change(state["session_id"], "vehicle_age", state.get("vehicle_age"), age)
+
+        if age < 0:
+            msg = (f"{year_match.group(1)} henüz geçmiş bir model yılı değil. "
+                   "Lütfen geçerli bir model yılı giriniz (örn: 2021, 2022).")
+            return {
+                "current_step": "asking_vehicle_age",
+                "awaited_slot": "vehicle_age",
+                "messages": state["messages"] + [AIMessage(content=msg)],
+            }
+        if age > 5:
+            msg = (f"Araç yaşı {age} yıl olarak hesaplandı; maksimum kabul edilen 5 yıldır. "
+                   "Lütfen 5 yıl veya daha küçük bir model yılı/yaş giriniz.")
+            return {
+                "current_step": "asking_vehicle_age",
+                "awaited_slot": "vehicle_age",
+                "messages": state["messages"] + [AIMessage(content=msg)],
+            }
+        return {"vehicle_age": age, "current_step": "vehicle_age_collected"}
+
+    # LLM ile parse et
+    start = time.time()
+    response = llm.invoke([
+        {"role": "system", "content": SLOT_EXTRACTION_SYSTEM},
+        {"role": "user", "content": f"Araç yaşı: {user_text}"},
+    ])
+    latency = int((time.time() - start) * 1000)
+    log_llm_call(
+        state["session_id"], "intake_used", llm.model, latency, 10, 10,
+        prompt=[
+            {"role": "system", "content": SLOT_EXTRACTION_SYSTEM},
+            {"role": "user", "content": f"Araç yaşı: {user_text}"},
+        ],
+        response=response.content,
+    )
+
+    parsed = parse_llm_json(response.content)
+    try:
+        age = int(parsed.get("value", 0)) if parsed else None
+    except Exception:
+        age = None
+
+    if age is None:
+        return {
+            "current_step": "asking_vehicle_age",
+            "awaited_slot": "vehicle_age",
+            "messages": state["messages"] + [
+                AIMessage(content="Yaşı anlayamadım. Model yılını (örn: 2021) veya kaç yaşında olduğunu yazar mısınız?")
+            ],
+        }
+
+    if age > 5:
+        msg = (f"Araç yaşı {age} yıl olarak alındı; maksimum kabul edilen 5 yıldır. "
+               "Lütfen 5 yıl veya daha küçük bir model yılı/yaş giriniz.")
+        return {
+            "current_step": "asking_vehicle_age",
+            "awaited_slot": "vehicle_age",
+            "messages": state["messages"] + [AIMessage(content=msg)],
+        }
+
+    log_slot_change(state["session_id"], "vehicle_age", state.get("vehicle_age"), age)
+    return {"vehicle_age": age, "current_step": "vehicle_age_collected"}
+
+
+def _parse_optional_tckn(state, user_text) -> dict:
+    skip_words = ["geç", "yok", "bilmiyorum", "pas", "atla", "istemiyorum", "hayır"]
+    if any(w in user_text.lower() for w in skip_words):
+        return {"seller_tckn": "", "current_step": "seller_tckn_skipped"}
+
+    # Ham TCKN veya input guard tarafından maskelenmiş (789****2355) pattern
+    match = re.search(r"\b[1-9]\d{10}\b", user_text)
+    masked_match = re.search(r"\b[1-9]\d{2}\*{4}\d{4}\b", user_text) if not match else None
+
+    if match:
+        tckn = match.group()
+        masked = _mask(tckn)
+    elif masked_match:
+        tckn = masked_match.group()
+        masked = tckn  # zaten maskeli
+    else:
+        return {
+            "current_step": "asking_seller_tckn",
+            "awaited_slot": "seller_tckn",
+            "messages": state["messages"] + [
+                AIMessage(content="TCKN 11 haneli olmalıdır. Bilmiyorsanız 'geç' yazabilirsiniz.")
+            ],
+        }
+
+    log_slot_change(state["session_id"], "seller_tckn", None, masked)
+    return {"seller_tckn": tckn, "current_step": "seller_tckn_collected"}

chatbot/agents/reflection_agent.py

@@ -0,0 +1,139 @@
+"""
+agents/reflection_agent.py — Self-Check / Reflection Agent
+
+AGENTIC PATTERN: Reflection Pattern
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Reflection pattern: Agent kendi çıktısını veya mevcut state'i
+"dışarıdan bakarak" değerlendirir; eksiklik veya tutarsızlık
+varsa bunu işaretler ve ilgili adıma geri döner.
+
+Bu agent, onay ekranı gösterilmeden önce çalışır:
+  - Tüm zorunlu slot'lar dolu mu?
+  - Kefil zorunluysa TCKN var mı?
+  - Çapraz kurallar hâlâ tutarlı mı? (örn: fatura değişince oran)
+
+Neden Reflection önemli?
+  - Slot filling sırasında oluşabilecek edge case'leri yakalar
+  - LLM'e "güvenme, kontrol et" felsefesini uygular
+  - Başvuru DB'ye hatalı kayıt yazılmasını önler
+"""
+import json
+import time
+from langchain_core.messages import AIMessage
+from llm.factory import get_router_llm
+from llm.prompts import REFLECTION_SYSTEM
+from graph.state import ConversationState
+from observability.audit_logger import log_llm_call
+from config import NEW_CAR_GUARANTOR_THRESHOLD
+
+# Ham slot adlarını müşteriye gösterilecek dostça etiketlere çevir
+SLOT_LABELS = {
+    "invoice_amount": "Proforma fatura tutarı",
+    "vehicle_model": "Araç modeli",
+    "requested_amount_new": "İstenen finansman tutarı",
+    "guarantor_tckn": "Kefil TC kimlik numarası",
+    "kasko_value": "Kasko değeri",
+    "vehicle_age": "Araç yaşı",
+    "requested_amount_used": "İstenen finansman tutarı",
+    "seller_tckn": "Satıcı TC kimlik numarası",
+}
+
+# Geçersiz veya eksik slot için yeniden sorulacak sorular
+SLOT_QUESTIONS = {
+    "invoice_amount": "Proforma fatura tutarı nedir? (TL olarak)",
+    "vehicle_model": "Aracın marka ve modelini belirtir misiniz? (örn: Toyota Corolla)",
+    "requested_amount_new": "Ne kadar finansman almak istiyorsunuz? (TL olarak)",
+    "guarantor_tckn": "Kefil TC kimlik numarası nedir?",
+    "kasko_value": "Aracın güncel kasko değeri nedir? (TL olarak)",
+    "vehicle_age": "Aracın model yılı veya yaşı nedir? (örn: 2021 model veya 3 yaşında)",
+    "requested_amount_used": "Ne kadar finansman almak istiyorsunuz? (TL olarak)",
+    "seller_tckn": "Satıcının TC kimlik numarası nedir? (Bilmiyorsanız 'geç' yazabilirsiniz)",
+}
+
+
+def run_reflection(state: ConversationState) -> dict:
+    """
+    Reflection node fonksiyonu.
+
+    Returns:
+        complete=True → recap'e geç
+        complete=False → eksik/geçersiz alana geri dön
+    """
+    vehicle_type = state.get("vehicle_type")
+
+    # Deterministik kontroller (LLM çağrısı yapmadan)
+    issues = []        # kural ihlali mesajları (dostça metin)
+    missing = []       # hiç doldurulmamış (None) slot'lar
+    reset_slots = []   # dolu ama geçersiz → temizlenip yeniden sorulacak slot'lar
+
+    if vehicle_type == "new":
+        if not state.get("invoice_amount"):
+            missing.append("invoice_amount")
+        if not state.get("vehicle_model"):
+            missing.append("vehicle_model")
+        if not state.get("requested_amount_new"):
+            missing.append("requested_amount_new")
+        # Kefil kontrolü
+        if state.get("kefil_required") and not state.get("guarantor_tckn"):
+            missing.append("guarantor_tckn")
+        # Çapraz kural: fatura değiştiyse oran hâlâ geçerli mi?
+        if state.get("invoice_amount") and state.get("requested_amount_new"):
+            max_allowed = state["invoice_amount"] * 0.60
+            if state["requested_amount_new"] > max_allowed:
+                issues.append(
+                    f"Finansman tutarı ({_fmt(state['requested_amount_new'])} TL), "
+                    f"proforma tutarının %60'ını ({_fmt(max_allowed)} TL) aşıyor."
+                )
+                reset_slots.append("requested_amount_new")
+
+    elif vehicle_type == "used":
+        if not state.get("kasko_value"):
+            missing.append("kasko_value")
+        if state.get("vehicle_age") is None:
+            missing.append("vehicle_age")
+        if not state.get("requested_amount_used"):
+            missing.append("requested_amount_used")
+        # Çapraz kural
+        if state.get("kasko_value") and state.get("requested_amount_used"):
+            max_allowed = min(state["kasko_value"] * 0.40, 3_000_000)
+            if state["requested_amount_used"] > max_allowed:
+                issues.append(
+                    f"Finansman tutarı ({_fmt(state['requested_amount_used'])} TL) limiti aşıyor. "
+                    f"Maksimum: {_fmt(max_allowed)} TL."
+                )
+                reset_slots.append("requested_amount_used")
+
+    if missing or issues:
+        parts = list(issues)
+        if missing:
+            labels = [SLOT_LABELS.get(m, m) for m in missing]
+            parts.append("Eksik bilgiler: " + ", ".join(labels))
+
+        # Önce geçersiz değeri düzelt, yoksa ilk eksik alanı tamamlat
+        target = reset_slots[0] if reset_slots else (missing[0] if missing else None)
+        if target:
+            question = SLOT_QUESTIONS.get(target, f"Lütfen {SLOT_LABELS.get(target, target).lower()} bilgisini girin.")
+            parts.append(question)
+
+        msg = "Başvuruyu kontrol ettim, düzeltmemiz gereken noktalar var:\n" + "\n".join(f"• {p}" for p in parts)
+
+        updates = {
+            "current_step": "reflection_issues_found",
+            "messages": state["messages"] + [AIMessage(content=msg)],
+            "errors": state["errors"] + issues,
+            "edit_target_slot": target,
+        }
+        # Geçersiz slot'ları temizle ki intake yeniden sorabilsin
+        for s in reset_slots:
+            updates[s] = None
+        # Yeniden sorulacak slot'u awaited olarak işaretle → kullanıcı cevabı parse edilir
+        if target:
+            updates["awaited_slot"] = target
+        return updates
+
+    # Her şey tamam
+    return {"current_step": "reflection_passed"}
+
+
+def _fmt(amount: float) -> str:
+    return f"{int(amount):,}".replace(",", ".")

chatbot/agents/submission_agent.py

@@ -0,0 +1,70 @@
+"""
+agents/submission_agent.py — Başvuru Kayıt Agent'ı
+
+AGENTIC PATTERN: Tool Use (write_application)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Müşteri tüm bilgileri onayladıktan sonra bu agent çalışır.
+db_tool aracılığıyla SQLite'a yazar; LLM doğrudan DB'ye erişemez.
+
+Adımlar:
+1. State'deki tüm slot'ları topla
+2. TCKN maskelenmiş haliyle gönder
+3. write_application tool'unu çağır
+4. UUID başvuru numarasını state'e yaz
+5. Müşteriye tebrik mesajı + HGS geçişine hazırlan
+"""
+from langchain_core.messages import AIMessage
+from tools.db_tool import write_application
+from tools.tckn_tool import _mask
+from graph.state import ConversationState
+from observability.audit_logger import log_tool_call
+from llm.prompts import HGS_PITCH
+
+
+def run_submission(state: ConversationState) -> dict:
+    """Onaylanmış başvuruyu veritabanına yazar."""
+
+    vehicle_type = state.get("vehicle_type")
+
+    # TCKN'leri maskele — ham değer DB'ye girmez
+    guarantor_masked = _mask(state["guarantor_tckn"]) if state.get("guarantor_tckn") else None
+    seller_masked = _mask(state["seller_tckn"]) if state.get("seller_tckn") else None
+
+    result = write_application.invoke({
+        "session_id": state["session_id"],
+        "vehicle_type": vehicle_type,
+        "invoice_amount": state.get("invoice_amount"),
+        "vehicle_model": state.get("vehicle_model"),
+        "requested_amount_new": state.get("requested_amount_new"),
+        "guarantor_tckn_masked": guarantor_masked,
+        "kasko_value": state.get("kasko_value"),
+        "vehicle_age": state.get("vehicle_age"),
+        "requested_amount_used": state.get("requested_amount_used"),
+        "seller_tckn_masked": seller_masked,
+    })
+
+    log_tool_call(
+        session_id=state["session_id"],
+        agent="submission_agent",
+        tool_name="write_application",
+        args={"vehicle_type": vehicle_type},
+        result={"success": result["success"], "application_id": result.get("application_id")},
+        success=result["success"],
+    )
+
+    if not result["success"]:
+        error_msg = f"Başvuru kaydedilirken bir hata oluştu: {result['error']}. Lütfen tekrar deneyin."
+        return {
+            "current_step": "submission_failed",
+            "errors": state["errors"] + [error_msg],
+            "messages": state["messages"] + [AIMessage(content=error_msg)],
+        }
+
+    app_id = result["application_id"]
+    hgs_pitch = HGS_PITCH.format(application_id=app_id)
+
+    return {
+        "current_step": "submission_complete",
+        "application_id": app_id,
+        "messages": state["messages"] + [AIMessage(content=hgs_pitch)],
+    }

chatbot/agents/supervisor.py

@@ -0,0 +1,196 @@
+"""
+agents/supervisor.py — Supervisor / Router Agent
+
+AGENTIC PATTERN: Supervisor Pattern
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Supervisor pattern'de bir üst agent, gelen isteği analiz eder
+ve hangi alt-agent'ın görevi üstleneceğine karar verir.
+
+Bu agent:
+1. Müşterinin mesajını alır
+2. Küçük (router) modeli kullanarak intent sınıflandırır
+3. Confidence < 0.7 ise netleştirme sorusu üretir
+4. Sonucu ConversationState'e yazar → LangGraph graph edge'i
+   bu sonuca göre bir sonraki node'u seçer
+
+NEDEN Supervisor Pattern?
+- Her alt-agent kendi sorumluluğuna odaklanır (single responsibility)
+- Yeni bir dal (örn. "sigorta bilgisi") eklemek için sadece Supervisor
+  ve yeni agent yazılır; diğer agent'lara dokunulmaz
+- Supervisor'ın kararı loglarda görülür → debug kolaylığı
+"""
+import time
+from langchain_core.messages import HumanMessage, AIMessage
+from llm.factory import get_router_llm
+from llm.json_utils import parse_llm_json
+from llm.prompts import SUPERVISOR_SYSTEM, MSG_OUT_OF_SCOPE
+from graph.state import ConversationState
+from observability.audit_logger import log_llm_call
+
+
+def run_supervisor(state: ConversationState) -> dict:
+    """
+    Supervisor node fonksiyonu.
+    LangGraph bu fonksiyonu çağırır; dönen dict state'i günceller.
+
+    Returns: state güncellemesi (sadece değişen alanlar)
+    """
+    last_message = state["messages"][-1]
+    user_text = last_message.content if hasattr(last_message, "content") else str(last_message)
+
+    # ── Mid-flow bypass ──────────────────────────────────────────────────────
+    # Zaten bir intake/recap/crosssell akışındaysak LLM sınıflandırması yapmadan
+    # mevcut adımı koru. Aksi halde "onaylıyorum", "2.500.000" gibi cevaplar
+    # yanlış intent (unclear / out_of_scope) olarak yorumlanır ve akış kopar.
+    # NOT: input_guard node'u current_step'i "input_guard_passed" olarak ezdiği
+    # için step kontrolüne güvenmiyoruz; vehicle_type + doldurulmuş slot'lara
+    # veya awaited_slot'a bakıyoruz.
+    vtype = state.get("vehicle_type")
+    has_new_progress = vtype == "new" and (
+        state.get("invoice_amount")
+        or state.get("vehicle_model")
+        or state.get("requested_amount_new")
+    )
+    has_used_progress = vtype == "used" and (
+        state.get("kasko_value")
+        or state.get("vehicle_age")
+        or state.get("requested_amount_used")
+    )
+    in_mid_flow = state.get("awaited_slot") or has_new_progress or has_used_progress
+
+    if in_mid_flow and vtype in ("new", "used"):
+        # Soru soruyorsa mid-flow'da bile FAQ'e yönlendir
+        if _looks_like_finance_question(user_text):
+            return {
+                "current_step": "supervisor_routed_faq",
+                "vehicle_type": vtype,
+                "_supervisor_intent": "faq",
+            }
+        intent = "new_car" if vtype == "new" else "used_car"
+        return {
+            "current_step": f"supervisor_routed_{intent}",
+            "vehicle_type": vtype,
+            "_supervisor_intent": intent,
+        }
+
+    # Deterministik kestirme: akış başında net araç türü ifadeleri LLM'e gitmeden yakalanır.
+    # (LLM router "yeni araç" gibi kısa ifadeleri bazen belirsiz sayıp clarifying'e düşürüyor.)
+    lower_text = user_text.lower().strip()
+    if not state.get("vehicle_type") and not _looks_like_finance_question(user_text):
+        is_new = any(w in lower_text for w in ["yeni", "sıfır", "sifir", "0 km", "0km", "sfr"])
+        is_used = any(w in lower_text for w in ["2.el", "2. el", "2el", "ikinci el", "kullanılmış", "kullanilmis"])
+        if is_new and not is_used:
+            return {"current_step": "supervisor_routed_new_car", "vehicle_type": "new", "_supervisor_intent": "new_car"}
+        if is_used and not is_new:
+            return {"current_step": "supervisor_routed_used_car", "vehicle_type": "used", "_supervisor_intent": "used_car"}
+
+    llm = get_router_llm()
+    start = time.time()
+
+    response = llm.invoke([
+        {"role": "system", "content": SUPERVISOR_SYSTEM},
+        {"role": "user", "content": user_text},
+    ])
+
+    latency = int((time.time() - start) * 1000)
+    log_llm_call(
+        session_id=state["session_id"],
+        agent="supervisor",
+        model=llm.model,
+        latency_ms=latency,
+        tokens_in=len(user_text.split()),  # yaklaşık
+        tokens_out=len(response.content.split()),
+        prompt=[
+            {"role": "system", "content": SUPERVISOR_SYSTEM},
+            {"role": "user", "content": user_text},
+        ],
+        response=response.content,
+    )
+
+    # JSON parse (markdown code fence ve ek metni tolere eder)
+    parsed = parse_llm_json(response.content)
+    if parsed:
+        intent = parsed.get("intent", "out_of_scope")
+        confidence = parsed.get("confidence", 1.0)
+        clarification = parsed.get("clarification")
+    else:
+        intent = "out_of_scope"
+        confidence = 0.0
+        clarification = None
+
+    # Defansif heuristic — küçük router modeli finansman sorularını bazen yanlış
+    # ("out_of_scope", "unclear") ya da düşük confidence ile işaretliyor.
+    # Mesaj net bir araç finansmanı sorusuysa faq'e yönlendir ve clarifying'e
+    # düşmesini engelle (confidence'ı eşiğin üstüne çek).
+    if _looks_like_finance_question(user_text) and intent in ("out_of_scope", "unclear", "faq"):
+        intent = "faq"
+        confidence = max(confidence, 0.75)
+
+    # Netleştirme gerekiyorsa → mesaj ekle, intent belirsiz bırak
+    if intent == "unclear" or confidence < 0.7:
+        clarification_text = clarification or "İsteğinizi tam olarak anlamadım. Araç finansmanı mı yoksa başka bir konuda mı yardımcı olayım?"
+        return {
+            "current_step": "clarifying",
+            "messages": state["messages"] + [AIMessage(content=clarification_text)],
+        }
+
+    # Intent → vehicle_type mapping
+    vehicle_type = None
+    if intent == "new_car":
+        vehicle_type = "new"
+    elif intent == "used_car":
+        vehicle_type = "used"
+
+    # Araç türü belirsizse (new_car/used_car ama hangi tür belli değil) → sor
+    if intent in ("new_car", "used_car") and vehicle_type and not state.get("vehicle_type"):
+        # Mesajda açıkça "yeni"/"sıfır" veya "2.el"/"ikinci el" geçmiyorsa sor
+        lower_text = user_text.lower()
+        has_new = any(w in lower_text for w in ["yeni", "sıfır", "sfr", "0km", "sifir"])
+        has_used = any(w in lower_text for w in ["2.el", "ikinci el", "2el", "kullanılmış", "kullanilmis", "2. el"])
+        if not has_new and not has_used:
+            return {
+                "current_step": "clarifying",
+                "messages": state["messages"] + [AIMessage(content="Yeni araç mı, 2. el araç mı düşünüyorsunuz?")],
+            }
+
+    # Zaten devam eden bir intake adımındaysak current_step'e dokunma
+    # (intake_new/used hangi slot'u beklediğini current_step ile takip eder)
+    existing_step = state.get("current_step", "")
+    mid_intake = existing_step.startswith("asking_") or existing_step.endswith("_collected")
+    new_step = existing_step if mid_intake else f"supervisor_routed_{intent}"
+
+    return {
+        "current_step": new_step,
+        "vehicle_type": vehicle_type if vehicle_type else state.get("vehicle_type"),
+        # Kapsam dışı mesaj varsa hemen yanıtla
+        "messages": (
+            state["messages"] + [AIMessage(content=MSG_OUT_OF_SCOPE)]
+            if intent == "out_of_scope"
+            else state["messages"]
+        ),
+        "flow_ended": intent == "out_of_scope",
+        "_supervisor_intent": intent,
+    }
+
+
+_FINANCE_KEYWORDS = (
+    "finansman", "kredi", "fatura", "kasko", "kefil", "vade", "faiz", "taksit",
+    "hgs", "araç", "arac", "model", "yaş", "yas", "tckn", "sigorta", "ödeme",
+    "odeme", "evrak", "belge", "başvuru", "basvuru", "limit", "proforma", "satıcı", "satici",
+)
+# "milyon", "tl", "tutar", "bin tl" kaldırıldı — saf sayı ifadelerinde false positive yaratıyor
+_QUESTION_MARKERS = (
+    "?", " mi ", " mı ", " mu ", " mü ", "miyim", "mıyım", "muyum", "müyüm",
+    " mi?", " mı?", " mu?", " mü?",
+    "nedir", "ne kadar", "kaç", "nasıl", "ne olur", "var mı", "var mi",
+)
+
+
+def _looks_like_finance_question(text: str) -> bool:
+    """Mesaj araç finansmanı bağlamında bir soru gibi mi görünüyor?"""
+    if not text:
+        return False
+    lower = text.lower() + " "  # sondaki boşluk: "...mu" gibi cümle sonu eklerini yakala
+    has_question = any(m in lower for m in _QUESTION_MARKERS)
+    has_finance = any(k in lower for k in _FINANCE_KEYWORDS)
+    return has_question and has_finance

chatbot/agents/validation_agent.py

@@ -0,0 +1,126 @@
+"""
+agents/validation_agent.py — Doğrulama Agent'ı (ReAct Pattern)
+
+AGENTIC PATTERN: ReAct (Reason + Act)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ReAct pattern: Düşün → Araç Çağır → Gözlemle → Tekrar Düşün...
+
+Bu agent:
+1. Mevcut state'deki slot değerlerini alır
+2. İş kuralı tool'larını çağırarak doğrular
+3. Hata bulursa müşteriye açıklayıcı mesaj gönderir
+4. Tüm kurallar geçerse bir sonraki adıma onay verir
+
+NEDEN ReAct?
+- Validation birden fazla araç çağrısı gerektirebilir
+  (önce fatura kontrolü, sonra oran kontrolü, sonra kefil)
+- Her araç sonucuna göre bir sonraki adımı dinamik seçer
+- İş kuralları LLM'de değil, tool'larda → halüsinasyon riski 0
+
+Araç erişimi: validate_new_car_amount, validate_used_car_amount,
+              validate_tckn, lookup_vehicle, calculate_max_finance_*
+"""
+import time
+from langchain_core.messages import AIMessage
+from llm.factory import get_router_llm
+from tools.tckn_tool import validate_tckn
+from tools.catalog_tool import lookup_vehicle
+from tools.amount_tool import validate_new_car_amount, validate_used_car_amount, calculate_max_finance_new, calculate_max_finance_used
+from graph.state import ConversationState
+from observability.audit_logger import log_tool_call
+
+
+def validate_new_car_state(state: ConversationState) -> dict:
+    """
+    Yeni araç dalındaki tüm slot'ları sırayla doğrular.
+    İlk hata bulunduğunda müşteriye mesaj döner ve akış durur.
+    """
+    errors = []
+    messages_to_add = []
+
+    # Ticari araç kontrolü intake_new'da yapılıyor — validation'da tekrar kontrol gerekmez
+
+    # ── Finansman Tutarı Kontrolü ─────────────────────────────────────────────
+    if state.get("invoice_amount") and state.get("requested_amount_new"):
+        result = validate_new_car_amount.invoke({
+            "invoice_amount": state["invoice_amount"],
+            "requested_amount": state["requested_amount_new"],
+        })
+        log_tool_call(state["session_id"], "validation_agent", "validate_new_car_amount",
+                      {"invoice": state["invoice_amount"], "requested": state["requested_amount_new"]},
+                      result, result["valid"])
+
+        if not result["valid"]:
+            msg = (f"{result['error']}\n"
+                   "Ne kadar finansman almak istiyorsunuz? (TL olarak)")
+            return {
+                "current_step": "validation_needs_retry",
+                "requested_amount_new": None,
+                "awaited_slot": "requested_amount_new",
+                "kefil_required": result.get("kefil_required", False),
+                "errors": state["errors"] + [result["error"]],
+                "messages": state["messages"] + [AIMessage(content=msg)],
+                "flow_ended": False,
+            }
+
+        # Kefil zorunluluğunu state'e yaz
+        if result.get("kefil_required"):
+            return {
+                "current_step": "validation_passed",
+                "kefil_required": True,
+                "errors": state["errors"],
+                "messages": state["messages"],
+                "flow_ended": False,
+            }
+
+    # ── Kefil TCKN Kontrolü ───────────────────────────────────────────────────
+    # TCKN mod-11 doğrulaması demo'da devre dışı — sadece 11 hane kontrolü intake'te yapılıyor
+
+    return {
+        "current_step": "validation_passed",
+        "errors": state["errors"],
+        "messages": state["messages"],
+        "flow_ended": False,
+    }
+
+
+def validate_used_car_state(state: ConversationState) -> dict:
+    """2. El araç slot'larını doğrular."""
+    errors = []
+    messages_to_add = []
+
+    if state.get("kasko_value") and state.get("vehicle_age") is not None and state.get("requested_amount_used"):
+        result = validate_used_car_amount.invoke({
+            "kasko_value": state["kasko_value"],
+            "vehicle_age": state["vehicle_age"],
+            "requested_amount": state["requested_amount_used"],
+        })
+        log_tool_call(state["session_id"], "validation_agent", "validate_used_car_amount",
+                      {"kasko": state["kasko_value"], "age": state["vehicle_age"],
+                       "requested": state["requested_amount_used"]},
+                      result, result["valid"])
+
+        if not result["valid"]:
+            msg = (f"{result['error']} Maksimum: {_fmt(result['max_allowed'])} TL.\n"
+                   "Ne kadar finansman almak istiyorsunuz? (TL olarak)")
+            return {
+                "current_step": "validation_needs_retry",
+                "errors": state["errors"] + [result['error']],
+                "messages": state["messages"] + [AIMessage(content=msg)],
+                "requested_amount_used": None,
+                "awaited_slot": "requested_amount_used",
+                "flow_ended": False,
+            }
+
+    # Satıcı TCKN mod-11 doğrulaması demo'da devre dışı
+
+    return {
+        "current_step": "validation_passed",
+        "errors": state["errors"],
+        "messages": state["messages"],
+        "flow_ended": False,
+    }
+
+
+def _fmt(amount: float) -> str:
+    return f"{int(amount):,}".replace(",", ".")

chatbot/app.py

@@ -0,0 +1,272 @@
+"""
+app.py — Ana Uygulama Girişi (Gradio + FastAPI)
+
+Gradio ChatInterface ile sohbet arayüzü sunar.
+Üst kısımda model seçici dropdown ile GPT/Claude/Gemini arası geçiş.
+Alt sekmede audit/metrik dashboard.
+
+HuggingFace Spaces için: bu dosyayı root'ta tut, demo.launch() çağır.
+"""
+import uuid
+import os
+import sys
+import io
+
+# Proje kök dizinini Python path'e ekle
+sys.path.insert(0, os.path.dirname(__file__))
+
+# Windows konsolunda emoji/unicode karakterlerin print hatası vermemesi için
+if hasattr(sys.stdout, 'buffer'):
+    sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8', errors='replace', line_buffering=True)
+
+import gradio as gr
+from langchain_core.messages import HumanMessage
+
+from config import GRADIO_TITLE, GRADIO_SHARE
+from graph.state import create_initial_state
+from graph.workflow import get_compiled_graph, get_workflow_mermaid
+from memory.checkpointer import get_thread_config
+from memory.vector_store import index_faq
+from tools.db_tool import init_db
+from observability.dashboard import build_dashboard_tab
+
+# ── Başlangıç: DB + FAQ İndeksleme ───────────────────────────────────────────
+init_db()
+try:
+    index_faq()
+except Exception as e:
+    print(f"[Uyarı] FAQ indeksleme atlandı: {e}")
+
+# Aktif oturumlar: session_id → ConversationState
+_sessions: dict = {}
+
+
+def chat(message: str, history: list, session_id: str, model_choice: str) -> str:
+    """
+    Gradio ChatInterface'in çağırdığı ana fonksiyon.
+
+    Args:
+        message: Kullanıcının yazdığı metin
+        history: Önceki mesajlar (Gradio formatı)
+        session_id: Oturum UUID (Gradio state'te saklanır)
+        model_choice: Kullanıcının seçtiği model
+
+    Returns:
+        Chatbot'un cevabı (string)
+    """
+    # Model seçimini config'e yansıt (runtime değişiklik)
+    _apply_model_choice(model_choice)
+
+    compiled = get_compiled_graph()
+    config = get_thread_config(session_id)
+
+    # Oturum state'i yoksa oluştur
+    if session_id not in _sessions:
+        _sessions[session_id] = create_initial_state(session_id)
+
+    state = _sessions[session_id]
+
+    # Kullanıcı mesajını state'e ekle
+    updated_messages = state["messages"] + [HumanMessage(content=message)]
+    state = {**state, "messages": updated_messages}
+    print(f"[DEBUG current state before invoke] {state}", flush=True)
+    import sys
+    print(f"[DEBUG chat] sid={session_id[:8]} msg={message!r} awaited={state.get('awaited_slot')} vtype={state.get('vehicle_type')} step={state.get('current_step')}", flush=True)
+    sys.stdout.flush()
+
+    # Graph'ı çalıştır
+    try:
+        result = compiled.invoke(state, config=config)
+        _sessions[session_id] = result
+        print(f"[DEBUG chat AFTER] awaited={result.get('awaited_slot')} vtype={result.get('vehicle_type')} step={result.get('current_step')} invoice={result.get('invoice_amount')}", flush=True)
+        sys.stdout.flush()
+
+        # Son AI mesajını bul
+        ai_messages = [m for m in result["messages"] if hasattr(m, "type") and m.type == "ai"]
+        if ai_messages:
+            return ai_messages[-1].content
+        return "İşleniyor..."
+    except Exception as e:
+        print(f"[ERROR chat] sid={session_id[:8]} {type(e).__name__}: {e}", flush=True)
+        from litellm.exceptions import ServiceUnavailableError, RateLimitError, Timeout
+        if isinstance(e, (ServiceUnavailableError, RateLimitError, Timeout)):
+            return ("Sistemimiz şu anda yoğun. Lütfen birkaç saniye sonra "
+                    "mesajınızı tekrar gönderir misiniz? 🙏")
+        return "Beklenmeyen bir sorun oluştu. Lütfen tekrar deneyin."
+
+
+def new_session() -> tuple[str, list]:
+    """Yeni oturum başlat — session_id üret, history temizle."""
+    session_id = str(uuid.uuid4())
+    welcome = "Merhaba! 👋 Araç finansmanı ön başvurusu için yardımcı olabilirim.\nYeni araç mı, 2. el araç mı düşünüyorsunuz?"
+    return session_id, [(None, welcome)]
+
+
+def show_workflow() -> str:
+    """Workflow Mermaid diyagramını döndürür."""
+    try:
+        return f"```mermaid\n{get_workflow_mermaid()}\n```"
+    except Exception as e:
+        return f"Diyagram üretilirken hata: {e}"
+
+
+def _apply_model_choice(choice: str):
+    """
+    Model seçimini runtime'da config modülüne uygular.
+    llm/factory.py config.ACTIVE_MODEL'i her çağrıda taze okuduğu için
+    bu değişiklik anında tüm agent'lara yansır — oturum sıfırlanmaz.
+    """
+    import config as cfg
+    model_map = {
+        "GPT-4o":           ("gpt-4o",                        "gpt-4o-mini"),
+        "GPT-4o Mini":      ("gpt-4o-mini",                   "gpt-4o-mini"),
+        "Claude Sonnet":    ("claude-sonnet-4-6",              "claude-haiku-4-5-20251001"),
+        "Claude Haiku":     ("claude-haiku-4-5-20251001",      "claude-haiku-4-5-20251001"),
+        "Gemini Flash":     ("gemini/gemini-2.5-flash",      "gemini/gemini-2.5-flash-lite"),
+        "Gemini Flash Lite":("gemini/gemini-2.5-flash-lite", "gemini/gemini-2.5-flash-lite"),
+    }
+    if choice in model_map:
+        cfg.ACTIVE_MODEL, cfg.ROUTER_MODEL = model_map[choice]
+
+
+# ── Gradio UI ─────────────────────────────────────────────────────────────────
+
+MODEL_CHOICES = ["GPT-4o", "GPT-4o Mini", "Claude Sonnet", "Claude Haiku", "Gemini Flash", "Gemini Flash Lite"]
+
+# Config'deki aktif modele göre dropdown başlangıç değerini belirle
+_REVERSE_MODEL_MAP = {
+    "gpt-4o":                          "GPT-4o",
+    "gpt-4o-mini":                     "GPT-4o Mini",
+    "claude-sonnet-4-6":               "Claude Sonnet",
+    "claude-haiku-4-5-20251001":       "Claude Haiku",
+    "gemini/gemini-2.5-flash":         "Gemini Flash",
+    "gemini/gemini-2.5-flash-lite":    "Gemini Flash Lite",
+    "gemini/gemini-2.0-flash":         "Gemini Flash",
+    "gemini/gemini-flash-latest":      "Gemini Flash",
+    "gemini/gemini-2.0-flash-latest":  "Gemini Flash",
+    "gemini/gemini-2.0-flash-lite":    "Gemini Flash Lite",
+}
+
+import config as _init_cfg
+_DEFAULT_MODEL_CHOICE = _REVERSE_MODEL_MAP.get(_init_cfg.ACTIVE_MODEL, "GPT-4o")
+
+with gr.Blocks(title=GRADIO_TITLE) as demo:
+    gr.Markdown(f"# {GRADIO_TITLE}")
+    gr.Markdown("> Agentic AI öğrenme demosu — LangGraph + LiteLLM + ChromaDB/Jina RAG")
+
+    # Oturum state'i (tarayıcıda saklanır)
+    session_state = gr.State(value=str(uuid.uuid4()))
+
+    with gr.Tab("💬 Chatbot"):
+        with gr.Row():
+            model_dropdown = gr.Dropdown(
+                choices=MODEL_CHOICES,
+                value=_DEFAULT_MODEL_CHOICE,
+                label="🤖 Dil Modeli",
+                scale=2,
+            )
+            import config as _cfg
+            active_model_label = gr.Textbox(
+                value=f"{_cfg.ACTIVE_MODEL}  |  router: {_cfg.ROUTER_MODEL}",
+                label="Aktif Model",
+                interactive=False,
+                scale=3,
+            )
+            new_session_btn = gr.Button("🔄 Yeni Oturum", scale=1)
+
+        chatbot_ui = gr.Chatbot(
+            label="Arac Finansmani Chatbot",
+            height=500,
+        )
+
+        with gr.Row():
+            msg_input = gr.Textbox(
+                placeholder="Mesajınızı yazın... (örn: yeni araç finansmanı istiyorum)",
+                label="",
+                scale=5,
+                container=False,
+            )
+            send_btn = gr.Button("Gönder", scale=1, variant="primary")
+
+        # Model değişince etiketi güncelle (oturum SIFIRLANMAZ)
+        def on_model_change(choice):
+            _apply_model_choice(choice)
+            import config as cfg
+            return f"{cfg.ACTIVE_MODEL}  |  router: {cfg.ROUTER_MODEL}"
+
+        model_dropdown.change(
+            fn=on_model_change,
+            inputs=[model_dropdown],
+            outputs=[active_model_label],
+        )
+
+        # Mesaj gönderme
+        def respond(message, history, session_id, model):
+            if not message.strip():
+                return history, ""
+            response = chat(message, history, session_id, model)
+            history = history + [
+                {"role": "user", "content": message},
+                {"role": "assistant", "content": response},
+            ]
+            return history, ""
+
+        send_btn.click(
+            fn=respond,
+            inputs=[msg_input, chatbot_ui, session_state, model_dropdown],
+            outputs=[chatbot_ui, msg_input],
+        )
+        msg_input.submit(
+            fn=respond,
+            inputs=[msg_input, chatbot_ui, session_state, model_dropdown],
+            outputs=[chatbot_ui, msg_input],
+        )
+
+        # Yeni oturum
+        def start_new(old_sid):
+            new_sid = str(uuid.uuid4())
+            welcome = "Merhaba! 👋 Araç finansmanı ön başvurusu için yardımcı olabilirim.\nYeni araç mı, 2. el araç mı düşünüyorsunuz?"
+            return new_sid, [{"role": "assistant", "content": welcome}]
+
+        new_session_btn.click(
+            fn=start_new,
+            inputs=[session_state],
+            outputs=[session_state, chatbot_ui],
+        )
+
+    with gr.Tab("🗺️ Workflow Diyagramı"):
+        gr.Markdown("LangGraph state machine görselleştirmesi:")
+        diagram_output = gr.Markdown()
+        show_btn = gr.Button("Diyagramı Göster")
+        show_btn.click(fn=show_workflow, outputs=diagram_output)
+
+    # Audit/Metrik Dashboard sekmesi
+    build_dashboard_tab()
+
+    with gr.Tab("ℹ️ Agentic Pattern'ler"):
+        gr.Markdown("""
+## Bu Projede Kullanılan Agentic Pattern'ler
+
+| Pattern | Dosya | Açıklama |
+|---|---|---|
+| **State Machine** | `graph/workflow.py` | LangGraph StateGraph — tüm akış |
+| **Supervisor** | `agents/supervisor.py` | Intent sınıflandırma + dal yönlendirme |
+| **Tool Use** | `tools/` | @tool ile iş kuralları kapsülleme |
+| **ReAct** | `agents/validation_agent.py` | Reason + Act döngüsü |
+| **RAG** | `agents/faq_agent.py` | Jina embed + ChromaDB retrieval |
+| **Reflection** | `agents/reflection_agent.py` | Self-check onay öncesi |
+| **Short-Term Memory** | `memory/checkpointer.py` | LangGraph MemorySaver |
+| **Long-Term Memory** | `memory/vector_store.py` | ChromaDB persist |
+| **Least-Privilege** | `agents/crosssell_agent.py` | Scoped tool access |
+| **Input/Output Guard** | `guardrails/` | PII + injection filter |
+| **Audit Log** | `observability/audit_logger.py` | KVKK/BDDK uyumlu log |
+| **Streaming** | `app.py` | Gradio token streaming |
+""")
+
+
+if __name__ == "__main__":
+    demo.launch(
+        server_name="0.0.0.0",
+        server_port=int(os.environ.get("GRADIO_SERVER_PORT", 7860)),
+        share=GRADIO_SHARE,
+    )

chatbot/config.py

@@ -0,0 +1,58 @@
+"""
+config.py — Merkezi konfigürasyon dosyası.
+
+Burası tüm çevresel değişkenleri ve model seçimini yönetir.
+Model değiştirmek için sadece ACTIVE_MODEL ve ROUTER_MODEL'i güncelle;
+başka hiçbir dosyaya dokunman gerekmez.
+"""
+import os
+from dotenv import load_dotenv
+
+load_dotenv()
+
+# ── LLM Model Seçimi ─────────────────────────────────────────────────────────
+# Büyük model: FAQ cevaplama, çok adımlı muhakeme
+# Küçük model: Intent sınıflandırma, slot çıkarımı, kısa onaylar
+ACTIVE_MODEL: str = os.getenv("ACTIVE_MODEL", "gpt-4o")
+ROUTER_MODEL: str = os.getenv("ROUTER_MODEL", "gpt-4o-mini")
+
+# ── API Key'ler ───────────────────────────────────────────────────────────────
+OPENAI_API_KEY: str = os.getenv("OPENAI_API_KEY", "")
+ANTHROPIC_API_KEY: str = os.getenv("ANTHROPIC_API_KEY", "")
+GOOGLE_API_KEY: str = os.getenv("GOOGLE_API_KEY", "")
+JINA_API_KEY: str = os.getenv("JINA_API_KEY", "")
+
+# ── Vektör DB ─────────────────────────────────────────────────────────────────
+CHROMA_PERSIST_DIR: str = os.path.join(os.path.dirname(__file__), "data", "chroma")
+FAQ_COLLECTION_NAME: str = "faq_chunks"
+
+# ── SQLite ────────────────────────────────────────────────────────────────────
+DB_PATH: str = os.path.join(os.path.dirname(__file__), "data", "applications.db")
+
+# ── İş Kuralları ─────────────────────────────────────────────────────────────
+# Yeni araç
+NEW_CAR_MAX_INVOICE: float = 7_000_000.0          # TL — üst fatura limiti
+NEW_CAR_FINANCE_RATIO: float = 0.60               # maks finansman / fatura
+NEW_CAR_GUARANTOR_THRESHOLD: float = 5_000_000.0  # bu tutarın üstünde kefil zorunlu
+
+# 2. el araç
+USED_CAR_MAX_AGE: int = 5                         # yıl
+USED_CAR_FINANCE_RATIO: float = 0.40              # maks finansman / kasko
+USED_CAR_MAX_FINANCE: float = 3_000_000.0         # TL — mutlak üst limit
+
+# ── Embedding ─────────────────────────────────────────────────────────────────
+JINA_EMBEDDING_MODEL: str = "jina-embeddings-v3"
+JINA_API_URL: str = "https://api.jina.ai/v1/embeddings"
+RAG_TOP_K: int = 3                                # kaç chunk getirilecek
+
+# ── Güvenlik ─────────────────────────────────────────────────────────────────
+# Prompt injection tespit için anahtar kelime listesi
+INJECTION_KEYWORDS: list[str] = [
+    "tüm talimatları unut", "ignore previous", "ignore all", "system:",
+    "disregard", "jailbreak", "pretend you are", "roleplay as",
+    "önceki talimatları sil", "artık farklı davran",
+]
+
+# ── Gradio ───────────────────────────────────────────────────────────────────
+GRADIO_TITLE: str = "Araç Finansmanı Chatbot — Agentic Demo"
+GRADIO_SHARE: bool = False   # HuggingFace Spaces'te True olur

chatbot/data/faq.md

@@ -0,0 +1,180 @@
+# Araç Finansmanı Sıkça Sorulan Sorular
+
+## Genel Taşıt Finansmanı
+
+### Taşıt finansmanı nedir?
+Taşıt finansmanı, banka aracılığıyla araç satın alımınız için sağlanan kredili ödeme çözümüdür. Belirlenen vade ve faiz oranı üzerinden aylık taksitlerle ödeme yaparsınız.
+
+### Taşıt finansmanına kimler başvurabilir?
+Bankamızın mobil uygulamasına kayıtlı, 18 yaş üzeri, Türkiye Cumhuriyeti vatandaşı veya Türk vatandaşlığı bulunan yabancı uyruklu bireyler başvurabilir.
+
+### Başvuru ne kadar sürer?
+Chatbot üzerinden ön başvuru birkaç dakika içinde tamamlanır. Ön başvuru onayı genellikle 1 iş günü içinde yapılır; nihai onay için gerekli belgelerin tamamlanması 2-3 iş günü sürebilir.
+
+### Finansman başvurusu için şubeye gitmem gerekir mi?
+Ön başvuruyu tamamen mobil uygulama üzerinden yapabilirsiniz. Ancak nihai onay için bazı durumlarda şubeye gidilmesi gerekebilir.
+
+### Araç finansmanı ile normal kredi arasındaki fark nedir?
+Araç finansmanı, satın alınan araç güvence (teminat) olarak gösterildiği için genellikle daha düşük faiz oranıyla kullandırılır. Araç üzerine rehin konulur; kredi tamamlanınca rehin kalkar.
+
+---
+
+## Yeni Araç Finansman Koşulları
+
+### Yeni araç finansmanında maksimum ne kadar kredi alabilirim?
+Proforma fatura tutarının en fazla %60'ı kadar finansman kullanabilirsiniz. Örneğin 5.000.000 TL'lik bir araç için maksimum 3.000.000 TL finansman alabilirsiniz.
+
+### Yeni araç finansmanında fatura tutarı üst sınırı nedir?
+Proforma fatura tutarı 7.000.000 TL'yi geçemez. Bu tutarın üzerindeki araçlar için şubemizi ziyaret etmenizi öneririz.
+
+### Fatura tutarım 5.000.000 TL üzerindeyse ne olur?
+5.000.000 TL ve üzeri fatura tutarlarında kefil göstermek zorunludur. Kefilinizin TC kimlik numarasını hazır bulundurmanız gerekmektedir.
+
+### Kefil olarak kim gösterilebilir?
+Kefil; 18 yaş üzeri, düzenli geliri olan ve bankamız sisteminde negatif kaydı bulunmayan herhangi bir kişi olabilir. Kefil, başvuru sahibi ile aynı kişi olamaz.
+
+### Ticari araçlar için finansman yapılıyor mu?
+Hayır, bankamız yeni araç finansmanında yalnızca binek araçlara finansman sağlamaktadır. Ticari araç finansmanı için işletme kredisi ürünlerimizi inceleyebilirsiniz.
+
+### Proforma fatura nedir?
+Proforma fatura, araç bayisinin size önceden düzenlediği, kesin satış öncesi tahmini fiyatı gösteren belgedir. Gerçek fatura ile farklılık gösterebilir; nihai onay için gerçek fatura gerekir.
+
+### Yeni araçta vade seçenekleri nelerdir?
+Yeni araç finansmanında 12, 24, 36, 48 ve 60 ay vade seçenekleri sunulmaktadır. Daha uzun vadeler için şube ile görüşmenizi öneririz.
+
+---
+
+## 2. El Araç Finansman Koşulları
+
+### 2. el araç finansmanı nasıl işler?
+2. el araç finansmanında aracın güncel kasko değeri ve yaşı esas alınır. Kasko değerinin %40'ı ile 3.000.000 TL arasındaki düşük tutar maksimum finansman olarak belirlenir.
+
+### 2. el araçta maksimum finansman tutarı nedir?
+İki sınır vardır:
+- Kasko değerinin %40'ı
+- Mutlak üst limit: 3.000.000 TL
+Bu ikisinden düşük olanı uygulanır.
+
+### 2. el araçta araç yaşı sınırı nedir?
+Araç yaşı başvuru tarihi itibarıyla 5 yılı geçemez. 5 yıldan eski araçlara finansman sağlanmamaktadır.
+
+### 2. el araç alırken satıcı TCKN'si gerekli mi?
+Satıcı TC kimlik numarası zorunlu değildir; isteğe bağlı olarak girebilirsiniz. Satıcı TCKN'si sağlandığında işlem güvenliğiniz artmaktadır.
+
+### 2. el araçta kasko değeri nasıl tespit edilir?
+Kasko değerini sigorta şirketinizden veya bağımsız ekspertiz raporundan öğrenebilirsiniz. Başvuru sırasında tahmini değer girebilirsiniz; nihai onayda ekspertiz raporu istenebilir.
+
+### 2. el araçta vade seçenekleri nelerdir?
+2. el araç finansmanında 12, 24 ve 36 ay vade seçenekleri sunulmaktadır.
+
+### Yurt dışından araç alımında finansman yapılıyor mu?
+Yurt dışından getirilen araçlara finansman sağlanmamaktadır. Yalnızca Türkiye'de kayıtlı araçlara hizmet verilmektedir.
+
+---
+
+## Kefil Gereksinimleri
+
+### Kefil her başvuruda zorunlu mu?
+Hayır. Kefil yalnızca yeni araç başvurularında ve proforma fatura tutarı 5.000.000 TL veya üzerinde olduğunda zorunludur.
+
+### Kefilin geliri yeterli mi olmalı?
+Evet, kefilin kredi notunun yeterli ve düzenli gelirinin bulunması gerekmektedir. Kefilin geliri, aylık taksit tutarının en az 3 katı olmalıdır.
+
+### Kefil olmak kefilim için risk yaratır mı?
+Evet. Asıl borçlunun ödeme yapmaması durumunda kefil ödeme yükümlülüğünü üstlenir.
+
+### Kefil TCKN'sini nasıl girmeliyim?
+11 haneli TC kimlik numarasını rakamlarla yazmanız yeterlidir. Chatbot TCKN'nizi anında doğrulayacaktır.
+
+---
+
+## Başvuru Süreci ve Gerekli Belgeler
+
+### Ön başvuru için hangi belgeler gerekli?
+Ön başvuru için herhangi bir belge yüklemeniz gerekmez; bilgileri chatbot üzerinden girmeniz yeterlidir. Nihai onay aşamasında:
+- Nüfus cüzdanı
+- Gelir belgesi (maaş bordrosu veya vergi levhası)
+- Araç fatura veya tescil belgesi
+istenebilir.
+
+### Başvurumun durumunu nasıl takip edebilirim?
+Mobil uygulamanın "Başvurularım" bölümünden başvuru numaranızla takip edebilirsiniz.
+
+### Başvuru reddedilirse ne yapabilirim?
+Red kararına itiraz için en yakın şubemizi ziyaret edebilir veya müşteri hizmetlerimizi arayabilirsiniz.
+
+### Birden fazla başvuru yapabilir miyim?
+Aynı anda yalnızca bir aktif başvurunuz olabilir. Önceki başvurunuz sonuçlanmadan yeni başvuru açamazsınız.
+
+---
+
+## HGS Ürünü
+
+### HGS nedir?
+HGS (Hızlı Geçiş Sistemi), köprü ve otoyol geçişlerinde kullanılan elektronik ödeme sistemidir. Araç camına yerleştirilen etiket sayesinde bariyer açılmadan geçiş yapabilirsiniz.
+
+### Bankamız üzerinden HGS nasıl tanımlatılır?
+Araç finansmanı başvurusu tamamlandıktan sonra chatbot size HGS tanımlatma seçeneği sunar. Onaylamanız halinde hesabınıza otomatik olarak HGS tanımlanır.
+
+### HGS için ek ücret var mı?
+HGS etiket ücreti ve ilk yükleme miktarı için şube veya müşteri hizmetlerimizden güncel bilgi alabilirsiniz.
+
+### Zaten HGS'm varsa ne olur?
+Aktif HGS'iniz varsa chatbot otomatik olarak bu adımı atlayacaktır.
+
+### HGS bakiyesini nasıl yükleyebilirim?
+Mobil uygulama, internet bankacılığı veya ATM üzerinden HGS bakiyenizi yükleyebilirsiniz.
+
+---
+
+## Ödeme Planı ve Vade Seçenekleri
+
+### Taksit tutarım nasıl hesaplanır?
+Aylık taksit = (Finansman tutarı × Aylık faiz oranı) / (1 - (1 + Aylık faiz oranı)^(-Vade)) formülüyle hesaplanır. Kesin taksit tutarı için güncel faiz oranlarına göre hesaplama yapılır.
+
+### Erken ödeme yapabilir miyim?
+Evet, erken kapatma mümkündür. Erken ödeme komisyonu olup olmadığını sözleşme aşamasında öğrenebilirsiniz.
+
+### Taksit ödeme tarihimi değiştirebilir miyim?
+Ödeme günü değişikliği için şubenize başvurmanız gerekmektedir.
+
+### Taksitimi geç ödersem ne olur?
+Gecikme faizi uygulanır ve kredi notunuz olumsuz etkilenebilir. Ödeme güçlüğü yaşarsanız önceden müşteri hizmetlerimizle iletişime geçmenizi öneririz.
+
+### Sabit faizli ve değişken faizli seçenek var mı?
+Bankamız taşıt finansmanında sabit faiz oranı uygulamaktadır. Bu sayede ödeme planınız baştan bellidir.
+
+### Finansmanımı yeniden yapılandırabilir miyim?
+Yapılandırma talepleri şube üzerinden değerlendirilmektedir. Koşullara bağlı olarak uygulanabilir.
+
+---
+
+## Sigorta ve Güvenceler
+
+### Araç zorunlu trafik sigortası gerekli mi?
+Evet, finansman kullandırılan araçların zorunlu trafik sigortası (trafik sigortası) yaptırılması zorunludur.
+
+### Kasko sigortası zorunlu mu?
+2. el araç finansmanında kasko sigortası zorunludur. Yeni araç finansmanında önerilmekle birlikte zorunluluk koşula bağlıdır.
+
+### Araç üzerine rehin konulur mu?
+Evet. Finansman süresi boyunca araç üzerine bankamız lehine rehin (trafik siciline şerh) konulur. Kredi kapatıldığında rehin otomatik olarak kaldırılır.
+
+---
+
+## Teknik ve Uygulama
+
+### Chatbot hangi saatlerde hizmet veriyor?
+Chatbot 7/24 hizmet vermektedir. İnsan operatörler hafta içi 08:00-20:00 saatleri arasında ulaşılabilirdir.
+
+### Bilgilerimi yanlış girdim, düzeltebilir miyim?
+Evet. Tüm bilgileri girdikten sonra onay ekranında istediğiniz alanı değiştirebilirsiniz.
+
+### Başvuruyu yarıda bırakırsam ne olur?
+Bilgileriniz oturum süresince saklanır. Oturum kapandığında taslak başvurunuz silinir; tekrar başlamak gerekir.
+
+### Kişisel verilerim güvende mi?
+Kişisel verileriniz KVKK kapsamında işlenmektedir. TC kimlik numaranız gibi hassas veriler sistemimizde maskelenmiş olarak saklanır ve banka dışına çıkmaz.
+
+### İnternet bağlantım kesilirse başvuruma ne olur?
+Bağlantı kesildiğinde o ana kadar girilen bilgiler geçici olarak saklanır. Bağlantı yeniden kurulduğunda kaldığınız yerden devam edebilirsiniz.

chatbot/data/vehicle_catalog.json

@@ -0,0 +1,150 @@
+[
+  {"brand": "Toyota", "model": "Corolla", "type": "binek", "variants": ["1.5 Flame", "1.5 Dream", "1.8 Hybrid", "2.0 GR Sport"]},
+  {"brand": "Toyota", "model": "Yaris", "type": "binek", "variants": ["1.5 Flame", "1.5 Dream", "1.5 GR Sport"]},
+  {"brand": "Toyota", "model": "C-HR", "type": "binek", "variants": ["1.8 Hybrid", "2.0 GR Sport"]},
+  {"brand": "Toyota", "model": "RAV4", "type": "binek", "variants": ["2.5 Hybrid", "2.0 Adventure"]},
+  {"brand": "Toyota", "model": "Camry", "type": "binek", "variants": ["2.5 Hybrid", "2.5 Executive"]},
+  {"brand": "Toyota", "model": "Proace", "type": "ticari", "variants": ["L1H1", "L2H1", "Proace City"]},
+  {"brand": "Toyota", "model": "Hilux", "type": "ticari", "variants": ["4x4 Adventure", "4x4 Executive"]},
+
+  {"brand": "Honda", "model": "Civic", "type": "binek", "variants": ["1.5 Elegance", "1.5 Executive", "2.0 RS"]},
+  {"brand": "Honda", "model": "Jazz", "type": "binek", "variants": ["1.5 i-MMD Elegant", "1.5 i-MMD Executive"]},
+  {"brand": "Honda", "model": "HR-V", "type": "binek", "variants": ["1.5 i-MMD Comfort", "1.5 i-MMD Advance"]},
+  {"brand": "Honda", "model": "CR-V", "type": "binek", "variants": ["2.0 i-MMD Comfort", "2.0 i-MMD Executive"]},
+  {"brand": "Honda", "model": "e:NY1", "type": "binek", "variants": ["Standard"]},
+
+  {"brand": "Volkswagen", "model": "Golf", "type": "binek", "variants": ["1.0 TSI Life", "1.5 TSI Life", "1.5 TSI Style", "2.0 GTI"]},
+  {"brand": "Volkswagen", "model": "Polo", "type": "binek", "variants": ["1.0 TSI Comfortline", "1.0 TSI Highline"]},
+  {"brand": "Volkswagen", "model": "Passat", "type": "binek", "variants": ["1.5 TSI Life", "2.0 TDI Business", "2.0 TDI Elegance"]},
+  {"brand": "Volkswagen", "model": "Tiguan", "type": "binek", "variants": ["1.5 TSI Life", "2.0 TDI Elegance"]},
+  {"brand": "Volkswagen", "model": "T-Roc", "type": "binek", "variants": ["1.0 TSI Style", "1.5 TSI Sport"]},
+  {"brand": "Volkswagen", "model": "Arteon", "type": "binek", "variants": ["2.0 TSI Elegance", "2.0 TSI R-Line"]},
+  {"brand": "Volkswagen", "model": "Transporter", "type": "ticari", "variants": ["T6.1 Camlı Van", "T6.1 City Van", "Caravelle"]},
+  {"brand": "Volkswagen", "model": "Caddy", "type": "ticari", "variants": ["1.5 TSI Life", "2.0 TDI Life"]},
+  {"brand": "Volkswagen", "model": "Crafter", "type": "ticari", "variants": ["35 Uzun", "50 Uzun"]},
+
+  {"brand": "BMW", "model": "1 Serisi", "type": "binek", "variants": ["118i M Sport", "120i M Sport"]},
+  {"brand": "BMW", "model": "2 Serisi", "type": "binek", "variants": ["220i M Sport", "218d M Sport", "M240i xDrive"]},
+  {"brand": "BMW", "model": "3 Serisi", "type": "binek", "variants": ["318i", "320i", "330i", "330e", "M340i xDrive"]},
+  {"brand": "BMW", "model": "4 Serisi", "type": "binek", "variants": ["420i Coupe", "430i Coupe", "M440i Coupe"]},
+  {"brand": "BMW", "model": "5 Serisi", "type": "binek", "variants": ["520i", "530i xDrive", "530e", "M550i xDrive"]},
+  {"brand": "BMW", "model": "X1", "type": "binek", "variants": ["sDrive18i", "xDrive23i", "iX1 xDrive30"]},
+  {"brand": "BMW", "model": "X3", "type": "binek", "variants": ["xDrive20i", "xDrive30i", "M40i"]},
+  {"brand": "BMW", "model": "X5", "type": "binek", "variants": ["xDrive40i", "xDrive50e", "M60i"]},
+  {"brand": "BMW", "model": "iX", "type": "binek", "variants": ["xDrive40", "xDrive50", "M60"]},
+
+  {"brand": "Mercedes-Benz", "model": "A Serisi", "type": "binek", "variants": ["A 180 AMG Line", "A 200 AMG Line", "A 250 e AMG Line"]},
+  {"brand": "Mercedes-Benz", "model": "C Serisi", "type": "binek", "variants": ["C 180", "C 200 AMG Line", "C 300 AMG Line", "C 300 e AMG Line"]},
+  {"brand": "Mercedes-Benz", "model": "E Serisi", "type": "binek", "variants": ["E 200 Avantgarde", "E 220 d AMG Line", "E 450 AMG Line"]},
+  {"brand": "Mercedes-Benz", "model": "GLA", "type": "binek", "variants": ["GLA 180 AMG Line", "GLA 200 AMG Line"]},
+  {"brand": "Mercedes-Benz", "model": "GLC", "type": "binek", "variants": ["GLC 200 AMG Line", "GLC 300 e AMG Line"]},
+  {"brand": "Mercedes-Benz", "model": "EQA", "type": "binek", "variants": ["EQA 250", "EQA 350 4MATIC"]},
+  {"brand": "Mercedes-Benz", "model": "Sprinter", "type": "ticari", "variants": ["314 CDI L2H2", "316 CDI L3H2", "319 CDI L3H2"]},
+  {"brand": "Mercedes-Benz", "model": "Vito", "type": "ticari", "variants": ["114 CDI Uzun", "116 CDI Uzun", "119 CDI Extra Uzun"]},
+
+  {"brand": "Ford", "model": "Fiesta", "type": "binek", "variants": ["1.0 EcoBoost Titanium", "1.5 EcoBoost ST"]},
+  {"brand": "Ford", "model": "Focus", "type": "binek", "variants": ["1.0 EcoBoost Titanium", "1.5 EcoBoost ST-Line", "2.3 ST"]},
+  {"brand": "Ford", "model": "Mondeo", "type": "binek", "variants": ["2.0 EcoBlue Titanium"]},
+  {"brand": "Ford", "model": "Kuga", "type": "binek", "variants": ["1.5 EcoBlue ST-Line", "2.5 PHEV Titanium"]},
+  {"brand": "Ford", "model": "Puma", "type": "binek", "variants": ["1.0 EcoBoost mHEV ST-Line", "1.0 EcoBoost mHEV Titanium"]},
+  {"brand": "Ford", "model": "Mustang Mach-E", "type": "binek", "variants": ["Standard Range RWD", "Extended Range AWD"]},
+  {"brand": "Ford", "model": "Transit", "type": "ticari", "variants": ["Transit 350 L2H2", "Transit Custom 320", "Transit Connect"]},
+  {"brand": "Ford", "model": "Ranger", "type": "ticari", "variants": ["2.0 EcoBlue XLT", "3.0 V6 Raptor"]},
+  {"brand": "Ford", "model": "Transit Courier", "type": "ticari", "variants": ["1.0 EcoBoost Trend"]},
+
+  {"brand": "Fiat", "model": "Egea", "type": "binek", "variants": ["1.4 Fire Easy", "1.6 Multijet Easy Plus", "1.6 Multijet Lounge"]},
+  {"brand": "Fiat", "model": "Panda", "type": "binek", "variants": ["1.0 Hybrid Pop", "1.0 Hybrid Urban"]},
+  {"brand": "Fiat", "model": "500", "type": "binek", "variants": ["1.0 Hybrid Pop Star", "Electric 42 kWh"]},
+  {"brand": "Fiat", "model": "Tipo", "type": "binek", "variants": ["1.6 Multijet Urban", "1.6 Multijet Lounge"]},
+  {"brand": "Fiat", "model": "Doblo", "type": "ticari", "variants": ["1.3 Multijet Cargo", "1.6 Multijet Combi"]},
+  {"brand": "Fiat", "model": "Ducato", "type": "ticari", "variants": ["2.3 Multijet L2H2", "2.3 Multijet L3H2"]},
+
+  {"brand": "Renault", "model": "Clio", "type": "binek", "variants": ["1.0 TCe Joy", "1.0 TCe Touch", "1.6 E-Tech Hybrid"]},
+  {"brand": "Renault", "model": "Megane", "type": "binek", "variants": ["1.3 TCe Touch", "1.6 E-Tech PHEV RS Line", "E-Tech Electric 60 kWh"]},
+  {"brand": "Renault", "model": "Kadjar", "type": "binek", "variants": ["1.3 TCe Touch", "1.5 Blue dCi Intens"]},
+  {"brand": "Renault", "model": "Captur", "type": "binek", "variants": ["1.0 TCe Joy", "1.6 E-Tech PHEV RS Line"]},
+  {"brand": "Renault", "model": "Zoe", "type": "binek", "variants": ["R110", "R135"]},
+  {"brand": "Renault", "model": "Austral", "type": "binek", "variants": ["1.2 TCe Mild Hybrid Equilibre", "E-Tech 200 Esprit Alpine"]},
+  {"brand": "Renault", "model": "Trafic", "type": "ticari", "variants": ["2.0 dCi L1H1", "2.0 dCi L2H1"]},
+  {"brand": "Renault", "model": "Master", "type": "ticari", "variants": ["2.3 dCi L2H2", "2.3 dCi L3H2"]},
+
+  {"brand": "Hyundai", "model": "i10", "type": "binek", "variants": ["1.0 MPI Style", "1.2 MPI Elite"]},
+  {"brand": "Hyundai", "model": "i20", "type": "binek", "variants": ["1.0 T-GDI Style", "1.0 T-GDI Elite", "N Line 1.0 T-GDI"]},
+  {"brand": "Hyundai", "model": "i30", "type": "binek", "variants": ["1.0 T-GDI Style", "1.5 T-GDI N Line", "2.0 N"]},
+  {"brand": "Hyundai", "model": "Tucson", "type": "binek", "variants": ["1.6 T-GDI Style", "1.6 T-GDI Hybrid", "1.6 T-GDI PHEV"]},
+  {"brand": "Hyundai", "model": "Kona", "type": "binek", "variants": ["1.0 T-GDI Style", "Electric 65.4 kWh"]},
+  {"brand": "Hyundai", "model": "IONIQ 6", "type": "binek", "variants": ["RWD Standard Range", "AWD Long Range"]},
+  {"brand": "Hyundai", "model": "IONIQ 5", "type": "binek", "variants": ["RWD Standard", "AWD Boost"]},
+
+  {"brand": "Kia", "model": "Picanto", "type": "binek", "variants": ["1.2 MPI Cool", "1.2 MPI Comfort"]},
+  {"brand": "Kia", "model": "Rio", "type": "binek", "variants": ["1.2 MPI Cool", "1.4 MPI Style Plus"]},
+  {"brand": "Kia", "model": "Ceed", "type": "binek", "variants": ["1.0 T-GDI Cool", "1.5 T-GDI Style"]},
+  {"brand": "Kia", "model": "Sportage", "type": "binek", "variants": ["1.6 T-GDI Cool", "1.6 T-GDI Hybrid", "1.6 T-GDI PHEV"]},
+  {"brand": "Kia", "model": "Niro", "type": "binek", "variants": ["Hybrid 1.6 GDI", "PHEV 1.6 GDI", "EV 64.8 kWh"]},
+  {"brand": "Kia", "model": "EV6", "type": "binek", "variants": ["RWD Standard", "AWD Long Range GT-Line"]},
+
+  {"brand": "Dacia", "model": "Sandero", "type": "binek", "variants": ["1.0 SCe Essential", "1.0 TCe Comfort", "1.0 TCe Stepway"]},
+  {"brand": "Dacia", "model": "Duster", "type": "binek", "variants": ["1.0 TCe Essential 4x2", "1.3 TCe Prestige 4x2"]},
+  {"brand": "Dacia", "model": "Logan", "type": "binek", "variants": ["1.0 SCe Essential", "1.0 TCe Expression"]},
+  {"brand": "Dacia", "model": "Spring", "type": "binek", "variants": ["Comfort", "Extreme"]},
+  {"brand": "Dacia", "model": "Jogger", "type": "binek", "variants": ["1.0 TCe Expression 7+1", "1.6 Hybrid Expression"]},
+
+  {"brand": "Peugeot", "model": "208", "type": "binek", "variants": ["1.2 PureTech Active Pack", "1.2 PureTech Allure", "e-208 EV 50 kWh"]},
+  {"brand": "Peugeot", "model": "308", "type": "binek", "variants": ["1.2 PureTech Active Pack", "1.6 Hybrid Allure", "1.6 PHEV GT"]},
+  {"brand": "Peugeot", "model": "2008", "type": "binek", "variants": ["1.2 PureTech Active Pack", "e-2008 EV 50 kWh"]},
+  {"brand": "Peugeot", "model": "3008", "type": "binek", "variants": ["1.2 PureTech Allure", "1.6 PHEV GT", "E-3008 Long Range"]},
+  {"brand": "Peugeot", "model": "Partner", "type": "ticari", "variants": ["1.5 BlueHDi 100 Standard", "e-Partner EV 50 kWh"]},
+  {"brand": "Peugeot", "model": "Expert", "type": "ticari", "variants": ["1.5 BlueHDi 120 L1", "2.0 BlueHDi 145 L2"]},
+  {"brand": "Peugeot", "model": "Boxer", "type": "ticari", "variants": ["2.2 BlueHDi L2H2", "2.2 BlueHDi L3H2"]},
+
+  {"brand": "Citroen", "model": "C3", "type": "binek", "variants": ["1.2 PureTech Feel", "1.2 PureTech Shine"]},
+  {"brand": "Citroen", "model": "C4", "type": "binek", "variants": ["1.2 PureTech Feel Pack", "e-C4 EV 50 kWh"]},
+  {"brand": "Citroen", "model": "C5 X", "type": "binek", "variants": ["1.2 PureTech Shine", "1.6 PHEV Shine Pack"]},
+  {"brand": "Citroen", "model": "Berlingo", "type": "ticari", "variants": ["1.5 BlueHDi 100 Standard", "e-Berlingo EV 50 kWh"]},
+
+  {"brand": "Skoda", "model": "Fabia", "type": "binek", "variants": ["1.0 MPI Ambition", "1.0 TSI Style"]},
+  {"brand": "Skoda", "model": "Octavia", "type": "binek", "variants": ["1.0 TSI Ambition", "1.5 TSI Style", "2.0 TDI Sportline"]},
+  {"brand": "Skoda", "model": "Superb", "type": "binek", "variants": ["2.0 TDI Style", "2.0 TSI Sportline"]},
+  {"brand": "Skoda", "model": "Kamiq", "type": "binek", "variants": ["1.0 TSI Ambition", "1.5 TSI Style"]},
+  {"brand": "Skoda", "model": "Karoq", "type": "binek", "variants": ["1.5 TSI Ambition", "2.0 TDI Style"]},
+  {"brand": "Skoda", "model": "Kodiaq", "type": "binek", "variants": ["2.0 TDI Style", "2.0 TSI Sportline 4x4"]},
+
+  {"brand": "Audi", "model": "A1", "type": "binek", "variants": ["25 TFSI Advanced", "30 TFSI S Line"]},
+  {"brand": "Audi", "model": "A3", "type": "binek", "variants": ["30 TFSI Advanced", "35 TFSI S Line", "40 TFSI e S Line"]},
+  {"brand": "Audi", "model": "A4", "type": "binek", "variants": ["35 TFSI Advanced", "35 TDI Advanced", "40 TFSI S Line"]},
+  {"brand": "Audi", "model": "A6", "type": "binek", "variants": ["40 TDI Advanced", "55 TFSI e S Line"]},
+  {"brand": "Audi", "model": "Q2", "type": "binek", "variants": ["30 TFSI Advanced", "35 TFSI S Line"]},
+  {"brand": "Audi", "model": "Q3", "type": "binek", "variants": ["35 TFSI Advanced", "35 TDI S Line"]},
+  {"brand": "Audi", "model": "Q5", "type": "binek", "variants": ["40 TDI S Line", "55 TFSI e S Line quattro"]},
+  {"brand": "Audi", "model": "e-tron", "type": "binek", "variants": ["55 quattro Advanced", "S quattro"]},
+
+  {"brand": "Opel", "model": "Corsa", "type": "binek", "variants": ["1.2 Edition", "1.2 GS Line", "Corsa-e 50 kWh"]},
+  {"brand": "Opel", "model": "Astra", "type": "binek", "variants": ["1.2 T GS Line", "1.6 PHEV GS Line"]},
+  {"brand": "Opel", "model": "Mokka", "type": "binek", "variants": ["1.2 T Edition", "Mokka-e 50 kWh"]},
+  {"brand": "Opel", "model": "Crossland", "type": "binek", "variants": ["1.2 T Edition", "1.5 D GS Line"]},
+  {"brand": "Opel", "model": "Vivaro", "type": "ticari", "variants": ["2.0 CDTi L1H1", "Vivaro-e 75 kWh L2"]},
+  {"brand": "Opel", "model": "Combo", "type": "ticari", "variants": ["1.5 CDTi L1 Standard", "Combo-e EV 50 kWh"]},
+
+  {"brand": "Volvo", "model": "XC40", "type": "binek", "variants": ["B3 FWD Core", "Recharge Twin AWD"]},
+  {"brand": "Volvo", "model": "XC60", "type": "binek", "variants": ["B4 FWD Core", "T8 PHEV AWD Plus"]},
+  {"brand": "Volvo", "model": "S60", "type": "binek", "variants": ["B4 FWD Core", "T8 PHEV AWD Plus"]},
+  {"brand": "Volvo", "model": "V60", "type": "binek", "variants": ["B4 FWD Core", "T8 PHEV AWD Plus"]},
+
+  {"brand": "Seat", "model": "Ibiza", "type": "binek", "variants": ["1.0 TSI Reference", "1.0 TSI FR"]},
+  {"brand": "Seat", "model": "Leon", "type": "binek", "variants": ["1.0 TSI Reference", "1.5 TSI FR", "1.4 e-Hybrid FR"]},
+  {"brand": "Seat", "model": "Ateca", "type": "binek", "variants": ["1.0 TSI Reference", "1.5 TSI FR"]},
+
+  {"brand": "Cupra", "model": "Born", "type": "binek", "variants": ["150 kW V1", "170 kW V2"]},
+  {"brand": "Cupra", "model": "Formentor", "type": "binek", "variants": ["1.5 TSI 150 HP", "2.0 TSI 4Drive 310 HP"]},
+
+  {"brand": "Tesla", "model": "Model 3", "type": "binek", "variants": ["Standard Range RWD", "Long Range AWD", "Performance AWD"]},
+  {"brand": "Tesla", "model": "Model Y", "type": "binek", "variants": ["Long Range AWD", "Performance AWD"]},
+  {"brand": "Tesla", "model": "Model S", "type": "binek", "variants": ["Dual Motor AWD", "Plaid"]},
+
+  {"brand": "Isuzu", "model": "D-Max", "type": "ticari", "variants": ["2.5 LS 4x4", "3.0 LS 4x4"]},
+  {"brand": "Isuzu", "model": "N-Series", "type": "ticari", "variants": ["N35", "N50", "N75"]},
+
+  {"brand": "Iveco", "model": "Daily", "type": "ticari", "variants": ["35S14 L3H2", "35S18 L4H2", "70C18"]},
+
+  {"brand": "MAN", "model": "TGE", "type": "ticari", "variants": ["3.180 L3H2 FWD", "5.180 L4H3 4WD"]}
+]

chatbot/graph/edges.py

@@ -0,0 +1,168 @@
+"""
+graph/edges.py — Koşullu Kenar Fonksiyonları
+
+AGENTIC PATTERN: State Machine — Conditional Transitions
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+LangGraph'ta conditional_edge, bir node'dan çıkan "karar noktalarını"
+temsil eder. Her edge fonksiyonu state'i okur ve bir sonraki
+node'un adını string olarak döndürür.
+
+Bu dosya SADECE yönlendirme kararlarını içerir — iş mantığı yok.
+İş mantığı: agent dosyalarında (intake, validation vb.)
+"""
+from graph.state import ConversationState
+from observability.audit_logger import log_routing
+
+
+def route_after_supervisor(state: ConversationState) -> str:
+    """
+    Supervisor'ın intent kararına göre hangi dala gidileceğini belirler.
+
+    new_car  → intake_new node'una
+    used_car → intake_used node'una
+    faq      → faq_agent node'una
+    out_of_scope / clarifying → END (akış kapanır veya tekrar bekler)
+    """
+    step = state.get("current_step", "")
+    decision, reason = _decide_after_supervisor(state, step)
+
+    try:
+        sid = state.get("session_id")
+        if sid:
+            log_routing(sid, "supervisor", decision, reason)
+    except Exception:
+        pass  # routing log hatası akışı bozmasın
+
+    return decision
+
+
+def _decide_after_supervisor(state: ConversationState, step: str) -> tuple[str, str]:
+    if state.get("flow_ended"):
+        return "END", "flow_ended"
+
+    # Başvuru zaten oluşturuldu → HGS adımındayız; recap/submission tekrarlanmamalı
+    if state.get("application_id"):
+        return "crosssell", "application already submitted, resume HGS step"
+
+    if step == "clarifying":
+        return "wait_for_input", "supervisor asked for clarification"
+
+    intent = step.replace("supervisor_routed_", "")
+
+    if intent == "faq":
+        return "faq_agent", "faq intent"
+
+    if intent == "new_car" or state.get("vehicle_type") == "new":
+        # Bekleyen bir slot varsa önce kullanıcının cevabını parse et (veri kaybını önler)
+        if state.get("awaited_slot"):
+            return "intake_new", "parse awaited slot first"
+        if _all_new_slots_filled(state):
+            return "reflection", "new_car: all slots filled"
+        return "intake_new", f"new_car intent (step={step})"
+
+    if intent == "used_car" or state.get("vehicle_type") == "used":
+        if state.get("awaited_slot"):
+            return "intake_used", "parse awaited slot first"
+        if _all_used_slots_filled(state):
+            return "reflection", "used_car: all slots filled"
+        return "intake_used", f"used_car intent (step={step})"
+
+    return "END", f"no matching route (intent={intent!r}, step={step!r})"
+
+
+def route_after_intake_new(state: ConversationState) -> str:
+    """Yeni araç intake'i bitince nereye gideceğini belirler."""
+    if state.get("flow_ended"):
+        return "END"
+    if state.get("current_step") == "intake_new_complete":
+        return "validation_new"
+    # Slot dolmadı → bir sonraki turda supervisor yeniden yönlendirir
+    return "wait_for_input"
+
+
+def route_after_intake_used(state: ConversationState) -> str:
+    """2. El intake'i bitince nereye gideceğini belirler."""
+    if state.get("flow_ended"):
+        return "END"
+    if state.get("current_step") == "intake_used_complete":
+        return "validation_used"
+    return "wait_for_input"
+
+
+def route_after_validation(state: ConversationState) -> str:
+    """Validation sonucuna göre yönlendir."""
+    if state.get("flow_ended"):
+        return "END"
+    step = state.get("current_step", "")
+    if step == "validation_passed":
+        return "reflection"
+    if step == "validation_needs_retry":
+        # Hangi dal?
+        return "intake_new" if state.get("vehicle_type") == "new" else "intake_used"
+    return "END"
+
+
+def route_after_reflection(state: ConversationState) -> str:
+    """Reflection tamamsa recap'e, sorun varsa ilgili intake'e dön."""
+    if state.get("flow_ended"):
+        return "END"
+    step = state.get("current_step", "")
+    if step == "reflection_passed":
+        return "recap"
+    # Eksik slot varsa o intake'e geri dön
+    return "intake_new" if state.get("vehicle_type") == "new" else "intake_used"
+
+
+def route_after_recap(state: ConversationState) -> str:
+    """Onay ekranı kararına göre yönlendir."""
+    if state.get("recap_confirmed"):
+        return "submission"
+    if state.get("edit_target_slot"):
+        # Hangi dal?
+        return "intake_new" if state.get("vehicle_type") == "new" else "intake_used"
+    # Cevap bekliyoruz
+    return "wait_for_input"
+
+
+def route_after_submission(state: ConversationState) -> str:
+    if state.get("flow_ended") or state.get("current_step") == "submission_failed":
+        return "END"
+    return "crosssell"
+
+
+def route_after_crosssell(state: ConversationState) -> str:
+    if state.get("flow_ended"):
+        return "END"
+    if state.get("current_step") == "crosssell_waiting":
+        return "wait_for_input"
+    return "END"
+
+
+def route_after_faq(state: ConversationState) -> str:
+    """FAQ cevabından sonra turu bitir — kullanıcıdan yeni mesaj beklenir.
+
+    NOT: supervisor'a geri DÖNMEMELİ. Aksi halde supervisor, FAQ agent'ın
+    ürettiği AI cevabını yeni bir kullanıcı mesajı sanıp yeniden sınıflandırır
+    ve bir döngüye girer (faq → supervisor → faq → ... → clarifying).
+    Mid-flow resume bir sonraki turda supervisor'ın mid-flow bypass'ı ile olur.
+    """
+    return "wait_for_input"
+
+
+# ── Yardımcı Fonksiyonlar ─────────────────────────────────────────────────────
+
+def _all_new_slots_filled(state: ConversationState) -> bool:
+    base = all([state.get("invoice_amount"), state.get("vehicle_model"), state.get("requested_amount_new")])
+    if not base:
+        return False
+    if state.get("kefil_required") and not state.get("guarantor_tckn"):
+        return False
+    return True
+
+
+def _all_used_slots_filled(state: ConversationState) -> bool:
+    return (
+        bool(state.get("kasko_value"))
+        and state.get("vehicle_age") is not None
+        and bool(state.get("requested_amount_used"))
+    )

chatbot/graph/nodes.py

@@ -0,0 +1,242 @@
+"""
+graph/nodes.py — LangGraph Node Fonksiyonları
+
+AGENTIC PATTERN: State Machine — Nodes
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Her node, state'i alır, bir işlem yapar ve güncellenmiş
+state parçasını döndürür. LangGraph bu parçaları mevcut
+state ile birleştirerek yeni state oluşturur.
+
+Not: Bu dosya agent modüllerini çağıran ince bir sarmalayıcıdır.
+İş mantığı agent dosyalarında; bağlantı mantığı burada.
+"""
+import time
+from langchain_core.messages import AIMessage, HumanMessage
+from graph.state import ConversationState
+from guardrails.input_guard import check_input, get_block_message
+from guardrails.output_guard import check_output
+from agents.supervisor import run_supervisor
+from agents.intake_new import run_intake_new
+from agents.intake_used import run_intake_used
+from agents.faq_agent import run_faq_agent
+from agents.validation_agent import validate_new_car_state, validate_used_car_state
+from agents.reflection_agent import run_reflection
+from agents.submission_agent import run_submission
+from agents.crosssell_agent import run_crosssell
+from observability.audit_logger import log_guard_event
+
+
+def input_guard_node(state: ConversationState) -> dict:
+    """
+    L4 — Input Guard Node.
+    Her turda ilk çalışan node; güvenlik geçmezse akış durur.
+    """
+    last_message = state["messages"][-1]
+    user_text = last_message.content if hasattr(last_message, "content") else ""
+
+    guard_result = check_input(user_text, state["session_id"])
+
+    if not guard_result["allowed"]:
+        block_msg = get_block_message()
+        # flow_ended set etme — sadece bu mesajı engelle, session'ı öldürme;
+        # bir sonraki normal mesajda kaldığı yerden devam edilebilsin.
+        return {
+            "current_step": state.get("current_step", "input_blocked"),
+            "messages": state["messages"] + [AIMessage(content=block_msg)],
+        }
+
+    # PII maskelenmişse mesajı güncelle
+    if guard_result["pii_detected"]:
+        updated_messages = state["messages"][:-1] + [
+            HumanMessage(content=guard_result["sanitized_text"])
+        ]
+        return {"messages": updated_messages, "current_step": "input_guard_passed"}
+
+    return {"current_step": "input_guard_passed"}
+
+
+def supervisor_node(state: ConversationState) -> dict:
+    """Supervisor / Router Agent."""
+    return run_supervisor(state)
+
+
+def intake_new_node(state: ConversationState) -> dict:
+    """Yeni Araç Slot Toplama."""
+    return run_intake_new(state)
+
+
+def intake_used_node(state: ConversationState) -> dict:
+    """2. El Araç Slot Toplama."""
+    return run_intake_used(state)
+
+
+def faq_agent_node(state: ConversationState) -> dict:
+    """FAQ / RAG Agent."""
+    # FAQ moduna girerken snapshot kaydet
+    if not state.get("faq_snapshot"):
+        state = {**state, "faq_snapshot": {"step": state.get("current_step")}}
+    return run_faq_agent(state)
+
+
+def validation_new_node(state: ConversationState) -> dict:
+    """Yeni Araç Doğrulama."""
+    return validate_new_car_state(state)
+
+
+def validation_used_node(state: ConversationState) -> dict:
+    """2. El Araç Doğrulama."""
+    return validate_used_car_state(state)
+
+
+def reflection_node(state: ConversationState) -> dict:
+    """Self-Check / Reflection."""
+    return run_reflection(state)
+
+
+_EDIT_SLOT_KEYWORDS_USED = {
+    "kasko_value":          ["kasko"],
+    "vehicle_age":          ["yaş", "model yılı", "yıl"],
+    "requested_amount_used":["finansman", "tutar", "kredi", "miktar"],
+    "seller_tckn":          ["satıcı tckn", "satıcı kimlik", "satıcının tc"],
+}
+_EDIT_SLOT_KEYWORDS_NEW = {
+    "invoice_amount":       ["fatura", "proforma"],
+    "vehicle_model":        ["model", "marka"],
+    "requested_amount_new": ["finansman", "tutar", "kredi", "miktar"],
+    "guarantor_tckn":       ["kefil", "garantör"],
+}
+_RECAP_SLOT_QUESTIONS = {
+    "kasko_value":          "Aracın güncel kasko değeri nedir? (TL olarak)",
+    "vehicle_age":          "Aracın model yılı veya yaşı nedir? (örn: 2021 model veya 3 yaşında)",
+    "requested_amount_used":"Ne kadar finansman almak istiyorsunuz? (TL olarak)",
+    "seller_tckn":          "Satıcının TC kimlik numarası nedir? (Bilmiyorsanız 'geç' yazabilirsiniz)",
+    "invoice_amount":       "Aracın proforma fatura tutarı nedir? (TL olarak)",
+    "vehicle_model":        "Hangi marka ve model aracı düşünüyorsunuz?",
+    "requested_amount_new": "Ne kadar finansman almak istiyorsunuz? (TL olarak)",
+    "guarantor_tckn":       "Kefilinizin TC kimlik numarası nedir?",
+}
+
+
+def _detect_edit_slot(lower: str, vehicle_type: str) -> str | None:
+    keywords = _EDIT_SLOT_KEYWORDS_USED if vehicle_type == "used" else _EDIT_SLOT_KEYWORDS_NEW
+    for slot, words in keywords.items():
+        if any(w in lower for w in words):
+            return slot
+    return None
+
+
+def recap_node(state: ConversationState) -> dict:
+    """
+    Onay Ekranı Node.
+    Tüm slot'ları müşteriye gösterir; onay veya düzenleme bekler.
+    """
+    last_message = state["messages"][-1]
+    user_text = last_message.content if hasattr(last_message, "content") else ""
+
+    # Eğer son mesaj kullanıcıdan geldiyse → onay / düzenleme parse et
+    if hasattr(last_message, "type") and last_message.type != "ai":
+        lower = user_text.lower().strip()
+        # Onay yalnızca tam "onaylıyorum" ile verilir — "evet/tamam" gibi ifadeler yetmez
+        if lower == "onaylıyorum":
+            return {"recap_confirmed": True, "current_step": "recap_confirmed"}
+
+        # Araç türü değişikliği → tüm slotları sıfırla, baştan başla
+        vehicle_type_words = ["araç türü", "arac turu", "araç tipi", "yeni araç", "2.el", "2. el", "ikinci el", "sıfır araç"]
+        if any(w in lower for w in vehicle_type_words):
+            return {
+                "current_step": "start",
+                "vehicle_type": None,
+                "invoice_amount": None, "vehicle_model": None, "requested_amount_new": None,
+                "guarantor_tckn": None, "kefil_required": False,
+                "kasko_value": None, "vehicle_age": None, "requested_amount_used": None,
+                "seller_tckn": None,
+                "awaited_slot": None, "edit_target_slot": None, "recap_confirmed": False,
+                "errors": [],
+                "messages": state["messages"] + [AIMessage(content="Yeni araç mı, 2. el araç mı düşünüyorsunuz?")],
+            }
+
+        # Hangi slot güncellenmek isteniyor?
+        target_slot = _detect_edit_slot(lower, state.get("vehicle_type"))
+        if target_slot:
+            question = _RECAP_SLOT_QUESTIONS.get(target_slot, "Yeni değeri giriniz.")
+            return {
+                "current_step": "recap_edit_requested",
+                "recap_confirmed": False,
+                "edit_target_slot": target_slot,
+                "awaited_slot": target_slot,
+                target_slot: None,
+                "messages": state["messages"] + [AIMessage(content=question)],
+            }
+
+        # Düzenleme niyeti var ama hangi alan belli değil → sor
+        edit_words = ["değiştir", "düzelt", "güncelle", "yanlış", "hata", "değiştirmek", "güncellemek"]
+        if any(w in lower for w in edit_words):
+            msg = "Hangi bilgiyi güncellemek istersiniz? (örn: kasko değeri, finansman tutarı, araç yaşı)"
+            return {
+                "current_step": "recap_shown",
+                "messages": state["messages"] + [AIMessage(content=msg)],
+            }
+
+    # İlk kez Recap (veya son mesaj AI ise) → özet göster
+    summary = _build_recap_message(state)
+    return {
+        "current_step": "recap_shown",
+        "messages": state["messages"] + [AIMessage(content=summary)],
+    }
+
+
+def submission_node(state: ConversationState) -> dict:
+    """Başvuru Kayıt Agent."""
+    return run_submission(state)
+
+
+def crosssell_node(state: ConversationState) -> dict:
+    """HGS Çapraz Satış."""
+    return run_crosssell(state)
+
+
+def wait_node(state: ConversationState) -> dict:
+    """
+    Pasif bekleme node'u — kullanıcı cevabı bekliyor.
+    current_step'e DOKUNMAZ: önceki node'un set ettiği "asking_xxx" değeri
+    korunmalı ki bir sonraki turda intake hangi slot'u beklediğini bilsin.
+    """
+    return {}
+
+
+# ── Yardımcı: Özet Mesajı ─────────────────────────────────────────────────────
+
+def _build_recap_message(state: ConversationState) -> str:
+    lines = ["📋 **Başvuru Özeti** — Bilgilerinizi kontrol edin:\n"]
+
+    if state.get("vehicle_type") == "new":
+        lines.append(f"• Araç Türü: Yeni Araç")
+        if state.get("invoice_amount"):
+            lines.append(f"• Proforma Fatura: {_fmt(state['invoice_amount'])} TL")
+        if state.get("vehicle_model"):
+            lines.append(f"• Araç Modeli: {state['vehicle_model']}")
+        if state.get("requested_amount_new"):
+            lines.append(f"• İstenen Finansman: {_fmt(state['requested_amount_new'])} TL")
+        if state.get("guarantor_tckn"):
+            from tools.tckn_tool import _mask
+            lines.append(f"• Kefil TCKN: {_mask(state['guarantor_tckn'])}")
+    else:
+        lines.append(f"• Araç Türü: 2. El Araç")
+        if state.get("kasko_value"):
+            lines.append(f"• Kasko Değeri: {_fmt(state['kasko_value'])} TL")
+        if state.get("vehicle_age"):
+            lines.append(f"• Araç Yaşı: {state['vehicle_age']} yıl")
+        if state.get("requested_amount_used"):
+            lines.append(f"• İstenen Finansman: {_fmt(state['requested_amount_used'])} TL")
+        if state.get("seller_tckn"):
+            from tools.tckn_tool import _mask
+            lines.append(f"• Satıcı TCKN: {_mask(state['seller_tckn'])}")
+
+    lines.append("\n✅ Bilgiler doğruysa **'onaylıyorum'** yazın.")
+    lines.append("✏️ Değişiklik için hangi alanı düzeltmek istediğinizi belirtin.")
+
+    return "\n".join(lines)
+
+
+def _fmt(amount: float) -> str:
+    return f"{int(amount):,}".replace(",", ".")

chatbot/graph/state.py

@@ -0,0 +1,105 @@
+"""
+graph/state.py — Merkezi Konuşma Durumu (State Machine Pattern)
+
+AGENTIC PATTERN: State Machine
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+LangGraph'ta her şey bir "state" etrafında döner. Bu TypedDict:
+- Konuşmanın hangi adımında olduğumuzu (current_step)
+- Hangi slot'ların dolu olduğunu (invoice_amount, vehicle_model vb.)
+- Konuşma geçmişini (messages)
+- Hata ve meta bilgilerini
+tüm agent'lar arasında paylaşılan tek gerçek kaynaktır.
+
+Her node bu state'i okur, değiştirir ve geri yazar.
+LangGraph, iki çağrı arasında state'i otomatik saklar (MemorySaver ile).
+"""
+from __future__ import annotations
+from typing import Literal, Optional
+from typing_extensions import TypedDict
+from langchain_core.messages import BaseMessage
+
+
+class ConversationState(TypedDict):
+    """
+    Bir oturumun tüm bilgisini taşıyan merkezi veri yapısı.
+
+    LangGraph bu TypedDict'i her node çağrısında günceller ve
+    bir sonraki node'a aktarır. Siz node fonksiyonlarında
+    sadece değişen alanları döndürmeniz yeterlidir.
+    """
+
+    # ── Oturum Kimliği ────────────────────────────────────────────────────────
+    session_id: str                     # her konuşma için benzersiz UUID
+    current_step: str                   # hangi graph node'undayız (debug için)
+
+    # ── Araç Türü ─────────────────────────────────────────────────────────────
+    vehicle_type: Optional[Literal["new", "used"]]   # None = henüz belirlenmedi
+
+    # ── Yeni Araç Slot'ları (Dal A) ───────────────────────────────────────────
+    invoice_amount: Optional[float]     # Proforma fatura tutarı (TL)
+    vehicle_model: Optional[str]        # Normalize edilmiş marka + model
+    vehicle_model_type: Optional[Literal["binek", "ticari"]]  # katalog sonucu
+    requested_amount_new: Optional[float]  # İstenen finansman tutarı
+    guarantor_tckn: Optional[str]       # Maskelenmiş kefil TCKN (***7890***)
+    kefil_required: bool                # fatura >= 5M ise True
+
+    # ── 2. El Araç Slot'ları (Dal B) ─────────────────────────────────────────
+    kasko_value: Optional[float]        # Güncel kasko değeri (TL)
+    vehicle_age: Optional[int]          # Araç yaşı (yıl)
+    requested_amount_used: Optional[float]  # İstenen finansman tutarı
+    seller_tckn: Optional[str]          # Satıcı TCKN (opsiyonel, maskelenmiş)
+
+    # ── Konuşma Geçmişi ───────────────────────────────────────────────────────
+    messages: list[BaseMessage]         # tüm kullanıcı + asistan mesajları
+
+    # ── Meta / Akış Kontrolü ──────────────────────────────────────────────────
+    application_id: Optional[str]       # Başvuru tamamlandığında UUID
+    hgs_consent: Optional[bool]         # HGS çapraz satış kabulü
+    errors: list[str]                   # biriken hata mesajları
+    flow_ended: bool                    # akış bitti mi (red, tamamlanma)
+
+    # ── FAQ Snapshot ──────────────────────────────────────────────────────────
+    # FAQ moduna girerken mevcut adım buraya kaydedilir;
+    # FAQ tamamlanınca geri dönülür. Slot'lar SİLİNMEZ.
+    faq_snapshot: Optional[dict]        # {"step": "A2", "pending_question": "..."}
+
+    # ── Onay Ekranı ───────────────────────────────────────────────────────────
+    recap_confirmed: bool               # müşteri tüm bilgileri onayladı mı
+    edit_target_slot: Optional[str]     # düzenlemek istenen alan adı
+
+    # ── Beklenen Slot (intake için kalıcı) ────────────────────────────────────
+    # current_step her node'da değişiyor, bu yüzden hangi slot'un cevabını
+    # beklediğimizi ayrı bir alanda tutuyoruz. intake_new/used buraya yazar
+    # ve bir sonraki turda buradan okur.
+    awaited_slot: Optional[str]
+
+
+def create_initial_state(session_id: str) -> ConversationState:
+    """
+    Yeni bir oturum için boş başlangıç state'i döndürür.
+    Tüm slot'lar None, tüm listeler boş, bool'lar False.
+    """
+    return ConversationState(
+        session_id=session_id,
+        current_step="start",
+        vehicle_type=None,
+        invoice_amount=None,
+        vehicle_model=None,
+        vehicle_model_type=None,
+        requested_amount_new=None,
+        guarantor_tckn=None,
+        kefil_required=False,
+        kasko_value=None,
+        vehicle_age=None,
+        requested_amount_used=None,
+        seller_tckn=None,
+        messages=[],
+        application_id=None,
+        hgs_consent=None,
+        errors=[],
+        flow_ended=False,
+        faq_snapshot=None,
+        recap_confirmed=False,
+        edit_target_slot=None,
+        awaited_slot=None,
+    )

chatbot/graph/workflow.py

@@ -0,0 +1,220 @@
+"""
+graph/workflow.py — LangGraph StateGraph Tanımı
+
+AGENTIC PATTERN: State Machine (LangGraph)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+LangGraph'ta bir "graph" şunlardan oluşur:
+  - StateGraph: state type + node'lar + edge'ler
+  - Node: state alan, state parçası döndüren fonksiyon
+  - Edge: iki node arasındaki bağlantı
+  - Conditional Edge: state'e göre dinamik yönlendirme
+
+compile() çağrısı graph'ı çalıştırılabilir hale getirir.
+MemorySaver ile her thread (oturum) kendi checkpoint'ını korur.
+
+Görsel üretmek için:
+  from graph.workflow import create_graph
+  g = create_graph()
+  print(g.get_graph().draw_mermaid())
+"""
+from langgraph.graph import StateGraph, END
+from langgraph.checkpoint.memory import MemorySaver
+
+from graph.state import ConversationState
+from graph.nodes import (
+    input_guard_node,
+    supervisor_node,
+    intake_new_node,
+    intake_used_node,
+    faq_agent_node,
+    validation_new_node,
+    validation_used_node,
+    reflection_node,
+    recap_node,
+    submission_node,
+    crosssell_node,
+    wait_node,
+)
+from graph.edges import (
+    route_after_supervisor,
+    route_after_intake_new,
+    route_after_intake_used,
+    route_after_validation,
+    route_after_reflection,
+    route_after_recap,
+    route_after_submission,
+    route_after_crosssell,
+    route_after_faq,
+)
+
+# Singleton compiled graph
+_compiled_graph = None
+
+
+def create_graph():
+    """
+    LangGraph StateGraph'ı oluşturur ve compile eder.
+
+    Graf Yapısı:
+      input_guard → supervisor → [intake_new | intake_used | faq_agent]
+                                    ↓              ↓
+                              validation_new  validation_used
+                                    ↓              ↓
+                                     reflection
+                                         ↓
+                                       recap
+                                         ↓
+                                     submission
+                                         ↓
+                                      crosssell
+                                         ↓
+                                        END
+    """
+    graph = StateGraph(ConversationState)
+
+    # ── Node'ları Ekle ─────────────────────────────────────────────────────────
+    graph.add_node("input_guard", input_guard_node)
+    graph.add_node("supervisor", supervisor_node)
+    graph.add_node("intake_new", intake_new_node)
+    graph.add_node("intake_used", intake_used_node)
+    graph.add_node("faq_agent", faq_agent_node)
+    graph.add_node("validation_new", validation_new_node)
+    graph.add_node("validation_used", validation_used_node)
+    graph.add_node("reflection", reflection_node)
+    graph.add_node("recap", recap_node)
+    graph.add_node("submission", submission_node)
+    graph.add_node("crosssell", crosssell_node)
+    graph.add_node("wait_for_input", wait_node)
+
+    # ── Başlangıç Node'u ───────────────────────────────────────────────────────
+    # Her kullanıcı mesajı input_guard'dan girer
+    graph.set_entry_point("input_guard")
+
+    # ── Sabit Edge'ler (her zaman aynı yönlendirme) ───────────────────────────
+    graph.add_edge("input_guard", "supervisor")
+
+    # ── Koşullu Edge'ler (state'e göre dinamik yönlendirme) ──────────────────
+    # Supervisor kararı
+    # route_after_supervisor(state) fonksiyonu state'e bakar ve bir string döner. 
+    # LangGraph bu string'i aşağıdaki dictionary'den lookup'tan geçirip ilgili node'a atlar.
+    graph.add_conditional_edges(
+        "supervisor",
+        route_after_supervisor,
+        {
+            "intake_new": "intake_new",
+            "intake_used": "intake_used",
+            "faq_agent": "faq_agent",
+            "reflection": "reflection",
+            "crosssell": "crosssell",
+            "wait_for_input": "wait_for_input",
+            "END": END,
+        },
+    )
+
+    # Yeni araç intake
+    graph.add_conditional_edges(
+        "intake_new",
+        route_after_intake_new,
+        {
+            "validation_new": "validation_new",
+            "wait_for_input": "wait_for_input",
+            "END": END,
+        },
+    )
+
+    # 2. El intake
+    graph.add_conditional_edges(
+        "intake_used",
+        route_after_intake_used,
+        {
+            "validation_used": "validation_used",
+            "wait_for_input": "wait_for_input",
+            "END": END,
+        },
+    )
+
+    # Validation
+    graph.add_conditional_edges(
+        "validation_new",
+        route_after_validation,
+        {"reflection": "reflection", "intake_new": "intake_new", "END": END},
+    )
+    graph.add_conditional_edges(
+        "validation_used",
+        route_after_validation,
+        {"reflection": "reflection", "intake_used": "intake_used", "END": END},
+    )
+
+    # Reflection
+    graph.add_conditional_edges(
+        "reflection",
+        route_after_reflection,
+        {"recap": "recap", "intake_new": "intake_new", "intake_used": "intake_used", "END": END},
+    )
+
+    # Recap → Submission
+    graph.add_conditional_edges(
+        "recap",
+        route_after_recap,
+        {
+            "submission": "submission",
+            "intake_new": "intake_new",
+            "intake_used": "intake_used",
+            "wait_for_input": "wait_for_input",
+            "END": END,
+        },
+    )
+
+    # Submission → CrossSell
+    graph.add_conditional_edges(
+        "submission",
+        route_after_submission,
+        {"crosssell": "crosssell", "END": END},
+    )
+
+    # CrossSell → END
+    graph.add_conditional_edges(
+        "crosssell",
+        route_after_crosssell,
+        {"wait_for_input": "wait_for_input", "END": END},
+    )
+
+    # FAQ cevabından kaldığı yere dön
+    graph.add_conditional_edges(
+        "faq_agent",
+        route_after_faq,
+        {
+            "supervisor": "supervisor",
+            "intake_new": "intake_new",
+            "intake_used": "intake_used",
+            "recap": "recap",
+            "wait_for_input": "wait_for_input",
+        },
+    )
+
+    # Bekleme node'u her zaman durur (kullanıcı girdisi bekliyor)
+    graph.add_edge("wait_for_input", END)
+
+    return graph
+
+
+def get_compiled_graph():
+    """
+    MemorySaver ile compile edilmiş graph'ı döndürür (singleton).
+
+    MemorySaver: Her thread_id için ayrı checkpoint tutar.
+    thread_id = session_id → her kullanıcı oturumu bağımsız.
+    """
+    global _compiled_graph
+    if _compiled_graph is None:
+        checkpointer = MemorySaver()
+        graph = create_graph()
+        _compiled_graph = graph.compile(checkpointer=checkpointer)
+    return _compiled_graph
+
+
+def get_workflow_mermaid() -> str:
+    """Graf yapısını Mermaid diyagramı olarak döndürür (görsel için)."""
+    graph = create_graph()
+    compiled = graph.compile()
+    return compiled.get_graph().draw_mermaid()

chatbot/guardrails/input_guard.py

@@ -0,0 +1,93 @@
+"""
+guardrails/input_guard.py — Giriş Güvenlik Katmanı
+
+REPORT Karşılığı: L4 — Input Guard
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Müşteri mesajı Orchestrator'a ulaşmadan önce şu dört kontrol:
+
+1. PII Maskeleme: TCKN, IBAN, kart no gibi değerleri maskele
+   (müşteri güvenlik amacıyla paylaşmış olabilir — güvenli saklama)
+2. Prompt Injection Tespiti: "tüm talimatları unut" gibi ifadeler
+3. Kapsam Dışı Ön Filtre: açıkça alakasız kısa mesajlar
+4. Uzunluk Kontrolü: aşırı uzun mesajlar sınırlandırılır
+
+Kural bazlı (deterministik) çalışır — ek LLM çağrısı yapmaz.
+Hız kritik: her kullanıcı turunda çalışır.
+"""
+import re
+from config import INJECTION_KEYWORDS
+from observability.audit_logger import log_guard_event
+
+
+# ── Regex Kalıpları ───────────────────────────────────────────────────────────
+_TCKN_RE = re.compile(r"\b[1-9]\d{10}\b")
+_IBAN_RE = re.compile(r"\bTR\d{2}[\s]?\d{4}[\s]?\d{4}[\s]?\d{4}[\s]?\d{4}[\s]?\d{4}[\s]?\d{2}\b", re.IGNORECASE)
+_CARD_RE = re.compile(r"\b\d{4}[\s\-]?\d{4}[\s\-]?\d{4}[\s\-]?\d{4}\b")
+
+MAX_MESSAGE_LENGTH = 1000  # karakter
+
+
+def check_input(message: str, session_id: str) -> dict:
+    """
+    Giriş mesajını güvenlik kontrollerinden geçirir.
+
+    Returns:
+        {
+            "allowed": bool,
+            "sanitized_text": str,      # PII maskelenmiş metin
+            "block_reason": str | None, # neden engellendi
+            "pii_detected": bool,
+            "injection_detected": bool,
+        }
+    """
+    result = {
+        "allowed": True,
+        "sanitized_text": message,
+        "block_reason": None,
+        "pii_detected": False,
+        "injection_detected": False,
+    }
+
+    # 1. Uzunluk kontrolü
+    if len(message) > MAX_MESSAGE_LENGTH:
+        result["allowed"] = False
+        result["block_reason"] = f"Mesaj çok uzun ({len(message)} karakter, limit {MAX_MESSAGE_LENGTH})."
+        log_guard_event(session_id, "input_guard", True, "message_too_long")
+        return result
+
+    # 2. PII Maskeleme (engelleme değil — sadece maskele)
+    sanitized = message
+    if _TCKN_RE.search(sanitized):
+        sanitized = _TCKN_RE.sub(lambda m: m.group()[:3] + "****" + m.group()[7:], sanitized)
+        result["pii_detected"] = True
+
+    if _IBAN_RE.search(sanitized):
+        sanitized = _IBAN_RE.sub("[IBAN GİZLENDİ]", sanitized)
+        result["pii_detected"] = True
+
+    if _CARD_RE.search(sanitized):
+        sanitized = _CARD_RE.sub("[KART NO GİZLENDİ]", sanitized)
+        result["pii_detected"] = True
+
+    if result["pii_detected"]:
+        log_guard_event(session_id, "input_guard", True, "pii_detected", sanitized)
+
+    result["sanitized_text"] = sanitized
+
+    # 3. Prompt Injection Tespiti
+    lower = message.lower()
+    for keyword in INJECTION_KEYWORDS:
+        if keyword.lower() in lower:
+            result["allowed"] = False
+            result["injection_detected"] = True
+            result["block_reason"] = "Güvenlik politikası: bu ifadeyle devam edilemiyor."
+            log_guard_event(session_id, "input_guard", True, f"injection_keyword:{keyword}", sanitized[:100])
+            return result
+
+    log_guard_event(session_id, "input_guard", False, "passed")
+    return result
+
+
+def get_block_message() -> str:
+    """Engellenen mesaj için standart yanıt."""
+    return "Üzgünüm, bu mesajla devam edemiyorum. Lütfen araç finansmanı konusunda sorunuzu yeniden yazın."

chatbot/guardrails/output_guard.py

@@ -0,0 +1,97 @@
+"""
+guardrails/output_guard.py — Çıkış Güvenlik Katmanı
+
+REPORT Karşılığı: L7 — Output Guard
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+LLM çıktısı müşteriye iletilmeden önce üç kontrol:
+
+1. PII Redaction: Çıktıda kalan hassas veri parçaları temizlenir
+2. Finansal Taahhüt Filtresi: Faiz oranı garantisi, kesin onay vb.
+   ifadeler engellenir → yasal ve itibar riski önlenir
+3. FAQ Kaynak Zorunluluğu: FAQ cevabı referans chunk olmadan geçemez
+
+Basit kural listesi tabanlı — ek LLM çağrısı yapmaz.
+"""
+import re
+from observability.audit_logger import log_guard_event
+
+# Yasak finansal taahhüt ifadeleri (Türkçe + İngilizce)
+FINANCIAL_COMMITMENT_PATTERNS = [
+    r"%\s*0[,.]?[05]?\s*(faiz|interest)",
+    r"kesinlikle onaylan",
+    r"garantili kredi",
+    r"anında onay",
+    r"100\s*%\s*onay",
+    r"faiz\s*almıyoruz",
+    r"faizsiz",
+    r"guaranteed approval",
+    r"interest free",
+]
+
+_TCKN_RE = re.compile(r"\b[1-9]\d{10}\b")
+_IBAN_RE = re.compile(r"\bTR\d{2}[\s]?\d{4}[\s]?\d{4}[\s]?\d{4}[\s]?\d{4}[\s]?\d{4}[\s]?\d{2}\b", re.IGNORECASE)
+
+
+def check_output(text: str, session_id: str, is_faq_response: bool = False, source_chunks: list = None) -> dict:
+    """
+    LLM çıktısını güvenlik kontrollerinden geçirir.
+
+    Args:
+        text: LLM'in ürettiği metin
+        session_id: Audit log için
+        is_faq_response: FAQ cevabıysa kaynak chunk kontrolü yapılır
+        source_chunks: RAG'dan gelen kaynak chunk'lar
+
+    Returns:
+        {
+            "allowed": bool,
+            "cleaned_text": str,
+            "block_reason": str | None,
+            "redacted_pii": bool,
+            "financial_block": bool,
+        }
+    """
+    result = {
+        "allowed": True,
+        "cleaned_text": text,
+        "block_reason": None,
+        "redacted_pii": False,
+        "financial_block": False,
+    }
+
+    # 1. PII Redaction
+    cleaned = text
+    if _TCKN_RE.search(cleaned):
+        cleaned = _TCKN_RE.sub("[KİŞİSEL VERİ GİZLENDİ]", cleaned)
+        result["redacted_pii"] = True
+        log_guard_event(session_id, "output_guard", True, "pii_in_output")
+
+    if _IBAN_RE.search(cleaned):
+        cleaned = _IBAN_RE.sub("[IBAN GİZLENDİ]", cleaned)
+        result["redacted_pii"] = True
+
+    result["cleaned_text"] = cleaned
+
+    # 2. Finansal Taahhüt Filtresi
+    lower = text.lower()
+    for pattern in FINANCIAL_COMMITMENT_PATTERNS:
+        if re.search(pattern, lower):
+            result["allowed"] = False
+            result["financial_block"] = True
+            result["block_reason"] = "Finansal taahhüt ifadesi tespit edildi."
+            log_guard_event(session_id, "output_guard", True, f"financial_commitment:{pattern[:30]}")
+            return result
+
+    # 3. FAQ kaynak zorunluluğu
+    if is_faq_response and not source_chunks:
+        result["allowed"] = False
+        result["block_reason"] = "FAQ cevabı kaynak chunk olmadan iletilemez."
+        log_guard_event(session_id, "output_guard", True, "faq_no_source")
+        return result
+
+    log_guard_event(session_id, "output_guard", False, "passed")
+    return result
+
+
+def get_financial_block_message() -> str:
+    return "Bu konuda kesin bilgi veremiyorum. Güncel faiz oranları ve koşullar için lütfen şubemizi veya müşteri hizmetlerimizi arayın."

chatbot/llm/factory.py

@@ -0,0 +1,141 @@
+"""
+llm/factory.py — LLM Model Switcher (LiteLLM Wrapper)
+
+AGENTIC PATTERN: Unified LLM Interface
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+LiteLLM, OpenAI / Anthropic / Google API'lerini TEK bir interface
+uzerinden kullanmana izin verir.
+
+Model degistirmek icin config.py'deki ACTIVE_MODEL'i guncelle:
+  "gpt-4o"                         -> OpenAI GPT-4o
+  "claude-sonnet-4-6"              -> Anthropic Claude Sonnet
+  "gemini/gemini-flash-latest"     -> Google Gemini Flash
+
+Iki katmanli mimari (REPORT Q6):
+  - ROUTER (kucuk/hizli): intent siniflandirma, slot cikarimi
+  - MAIN   (buyuk/guclu): FAQ cevaplama, karmasik muhakeme
+"""
+import time
+import litellm
+from litellm.exceptions import (
+    ServiceUnavailableError,
+    RateLimitError,
+    Timeout,
+    InternalServerError,
+    APIConnectionError,
+)
+import config
+
+# LiteLLM verbose loglamasini kapat
+litellm.set_verbose = False
+
+# Gecici (transient) hatalarda yeniden dene
+_RETRYABLE_ERRORS = (
+    ServiceUnavailableError,  # 503 - model yogun
+    RateLimitError,           # 429
+    Timeout,
+    InternalServerError,      # 500
+    APIConnectionError,
+)
+_MAX_RETRIES = 3
+_BASE_DELAY = 1.0  # saniye
+
+
+class LLMResponse:
+    """LLM cevabini tasimak icin minimal wrapper."""
+    def __init__(self, content: str):
+        self.content = content
+
+
+class LiteLLMWrapper:
+    """
+    litellm.completion() uzerinde LangChain benzeri invoke() arayuzu.
+    Tum agent'lar llm.invoke(messages) -> response.content seklinde kullanir.
+    """
+
+    def __init__(self, model: str, temperature: float = 0.0):
+        self.model = model
+        self.temperature = temperature
+
+    def invoke(self, messages: list) -> LLMResponse:
+        """
+        messages: dict listesi [{"role": "system", "content": "..."}]
+                  veya LangChain BaseMessage listesi
+        """
+        formatted = _format_messages(messages)
+        last_error = None
+        for attempt in range(_MAX_RETRIES):
+            try:
+                response = litellm.completion(
+                    model=self.model,
+                    messages=formatted,
+                    temperature=self.temperature,
+                )
+                choice = response.choices[0]
+                content = choice.message.content
+                # Gemini bazen güvenlik/RECITATION filtresinde None içerik döndürür.
+                # Çağrı noktaları .split() vb. çağırdığı için None'ı boş string'e çevir.
+                if content is None:
+                    finish = getattr(choice, "finish_reason", "unknown")
+                    print(f"[WARN llm] {self.model} boş içerik döndü (finish_reason={finish})", flush=True)
+                    content = ""
+                return LLMResponse(content=content)
+            except _RETRYABLE_ERRORS as e:
+                last_error = e
+                if attempt < _MAX_RETRIES - 1:
+                    time.sleep(_BASE_DELAY * (2 ** attempt))  # 1s, 2s, 4s
+        raise last_error
+
+    def bind_tools(self, tools):
+        """Tool binding destegi (validation_agent icin)."""
+        return BoundLLM(self, tools)
+
+
+class BoundLLM:
+    """bind_tools() sonrasi tool-calling destekli wrapper."""
+
+    def __init__(self, llm: LiteLLMWrapper, tools: list):
+        self.llm = llm
+        self.model = llm.model
+        self.tools = tools
+
+    def invoke(self, messages: list) -> LLMResponse:
+        # Basit fallback: tool'lar olmadan normal invoke
+        return self.llm.invoke(messages)
+
+
+def _format_messages(messages: list) -> list[dict]:
+    """LangChain mesaj nesnelerini ya da dict'leri litellm formatina donustur."""
+    result = []
+    for m in messages:
+        if isinstance(m, dict):
+            result.append(m)
+        elif hasattr(m, "type"):
+            # LangChain BaseMessage: HumanMessage, AIMessage, SystemMessage
+            role_map = {"human": "user", "ai": "assistant", "system": "system"}
+            role = role_map.get(m.type, "user")
+            result.append({"role": role, "content": m.content})
+        else:
+            result.append({"role": "user", "content": str(m)})
+    return result
+
+
+def get_llm(size: str = "large", temperature: float = 0.0) -> LiteLLMWrapper:
+    """
+    size="large" -> Ana model (ACTIVE_MODEL)
+    size="small" -> Router model (ROUTER_MODEL)
+
+    config modulu direkt okunur -> UI'dan model degisikliginde aninda yansir.
+    """
+    model_name = config.ACTIVE_MODEL if size == "large" else config.ROUTER_MODEL
+    return LiteLLMWrapper(model=model_name, temperature=temperature)
+
+
+def get_router_llm() -> LiteLLMWrapper:
+    """Kisayol: intent ve slot gorevleri icin kucuk hizli model."""
+    return get_llm(size="small")
+
+
+def get_main_llm() -> LiteLLMWrapper:
+    """Kisayol: FAQ ve karmasik gorevler icin buyuk guclu model."""
+    return get_llm(size="large")

chatbot/llm/json_utils.py

@@ -0,0 +1,31 @@
+"""LLM JSON cevaplarını güvenli parse etme yardımcıları.
+
+LLM'ler bazen ```json ... ``` markdown code fence ile sarar veya
+JSON öncesi/sonrası açıklama metni ekler. Bu helper bu varyasyonları temizler.
+"""
+import json
+import re
+
+_FENCE_RE = re.compile(r"^```(?:json)?\s*|\s*```$", re.IGNORECASE | re.MULTILINE)
+
+
+def parse_llm_json(text: str) -> dict | None:
+    """LLM cevabından JSON dict çıkar; başarısızsa None döner."""
+    if not text:
+        return None
+    s = text.strip()
+    # Markdown code fence'i kaldır
+    s = _FENCE_RE.sub("", s).strip()
+    # Direkt dene
+    try:
+        return json.loads(s)
+    except Exception:
+        pass
+    # İlk { ... } bloğunu yakalamayı dene
+    match = re.search(r"\{[\s\S]*\}", s)
+    if match:
+        try:
+            return json.loads(match.group())
+        except Exception:
+            return None
+    return None

chatbot/llm/prompts.py

@@ -0,0 +1,151 @@
+"""
+llm/prompts.py — Tüm Sistem Prompt'ları
+
+Her agent'ın kendi sistem prompt'u vardır. Bu tasarım:
+1. Her agent'ı bağımsız test etmeyi kolaylaştırır.
+2. Prompt mühendisliğini merkezi bir yerde tutar.
+3. Farklı modeller için ince ayar yapılabilir.
+
+KURAL: LLM'e hiçbir zaman "şu tutarı onayla" veya "kuralı uygula"
+denmez. LLM sadece ÇIKARIM yapar (sayı parse, intent anlama).
+Kurallar validation agent'ında KOD olarak çalışır.
+"""
+
+# ── Supervisor / Router ───────────────────────────────────────────────────────
+SUPERVISOR_SYSTEM = """Sen bir araç finansmanı chatbot'unun yönlendirici bileşenisin.
+Müşterinin mesajını analiz edip aşağıdaki 4 kategoriden birini JSON olarak döndür.
+
+Kategoriler:
+- "new_car"    : Yeni araç finansmanı başvurusu YAPMAK / BAŞLATMAK istiyor
+                 (örn: "yeni araç almak istiyorum", "sıfır araç finansmanı")
+- "used_car"   : 2. el araç finansmanı başvurusu YAPMAK istiyor
+                 (örn: "ikinci el için başvurmak istiyorum")
+- "faq"        : Araç finansmanı, kefil, vade, faiz, fatura limiti, HGS, kasko,
+                 belgeler, ödeme, sigorta, kredi/finansman tutarı veya limiti hakkında BİLGİ / SORU soruyor
+                 (örn: "fatura tutarım 5M üzerindeyse ne olur?",
+                       "kefil zorunlu mu?", "kaç yaşa kadar 2. el alınır?",
+                       "HGS ücretli mi?", "vade seçenekleri neler?",
+                       "yeni araç finansmanı olarak 5 milyondan fazla alabilir miyim?",
+                       "ne kadar kredi çekebilirim?", "maksimum tutar nedir?")
+- "out_of_scope": Araç finansmanıyla TAMAMEN alakasız konu
+                 (örn: hava durumu, başka banka ürünleri, kişisel sohbet)
+
+ÖNEMLİ KURALLAR:
+1. Mesaj soru içeriyorsa ("?", "ne olur", "nedir", "nasıl", "kaç", "mı/mi/mu/mü")
+   ve konu araç finansmanı ile ilgiliyse → MUTLAKA "faq" döndür.
+2. "Yeni araç" veya "2. el" geçmesi tek başına new_car/used_car anlamına gelmez.
+   Niyet "başvuru yapma" mı yoksa "bilgi alma" mı ona bak.
+3. Araç finansmanı kapsamındaki her bilgi sorusu "faq"tır — "out_of_scope" sadece
+   tamamen alakasız konular içindir.
+
+Çıktı formatı (sadece JSON, başka metin yok):
+{"intent": "<kategori>", "confidence": <0.0-1.0>}
+
+Eğer gerçekten belirsizse (örn. "merhaba", "yardım"):
+{"intent": "unclear", "confidence": 0.4, "clarification": "Yeni mi 2. el mi araç düşünüyorsunuz, yoksa bir bilgi mi almak istersiniz?"}
+"""
+
+# ── Slot Çıkarımı (Sayı Parse) ────────────────────────────────────────────────
+SLOT_EXTRACTION_SYSTEM = """Müşterinin mesajından sayısal değerleri parse etmeni istiyorum.
+Türkçe sayı ifadelerini rakama çevir:
+
+Örnekler:
+- "iki buçuk milyon" → 2500000
+- "2.5M TL" → 2500000
+- "beş yüz bin" → 500000
+- "1,200,000" → 1200000
+
+Araç yaşı örnekleri:
+- "2020 model" → mevcut yıldan çıkar (yaş = 2026 - 2020 = 6)
+- "5 yaşında" → 5
+- "Kasım 2021 model" → 2026 - 2021 = 5
+
+TCKN çıkarımı:
+- "TC'si 12345678901 olan" → "12345678901"
+- "geçmek istiyorum / yok / bilmiyorum" → null
+
+Çıktı formatı (sadece JSON):
+{"value": <sayı veya null>, "original": "<müşterinin yazdığı>"}
+"""
+
+# ── Araç Modeli Çıkarımı ─────────────────────────────────────────────────────
+VEHICLE_MODEL_EXTRACTION_SYSTEM = """Müşterinin mesajından araç markası ve modelini çıkar.
+Kısaltmaları ve yazım hatalarını normalize et.
+
+Örnekler:
+- "bmw 3 serisi" → {"brand": "BMW", "model": "3 Serisi"}
+- "volkswagen golf" → {"brand": "Volkswagen", "model": "Golf"}
+- "reno megane" → {"brand": "Renault", "model": "Megane"}
+- "toyota" → {"brand": "Toyota", "model": null, "needs_clarification": true}
+
+Çıktı (sadece JSON):
+{"brand": "<marka>", "model": "<model veya null>", "needs_clarification": <bool>}
+"""
+
+# ── FAQ Agent ─────────────────────────────────────────────────────────────────
+FAQ_SYSTEM = """Sen bir banka araç finansmanı uzmanısın. Yalnızca sana verilen
+referans metinlerden (SSS dokümanı) cevap üret. Referansta olmayan bilgiyi
+kesinlikle ekleme veya uydurma.
+
+Kurallar:
+1. Her cevabın sonuna kaynağını belirt: [Kaynak: <chunk başlığı>]
+2. Faiz oranı, kesin onay veya garanti ifadesi kullanma.
+3. Yanıtın kısa ve net olsun (max 3 paragraf).
+4. Bilgi yoksa "Bu konuda elimde bilgi yok, şubeyi arayabilirsiniz" de.
+
+Referans metinler:
+{context}
+"""
+
+# ── Onay Ekranı Düzenleme ─────────────────────���───────────────────────────────
+EDIT_DETECTION_SYSTEM = """Müşteri onay ekranında bir alanı değiştirmek istiyor.
+Hangi alan değiştirilmek isteniyor?
+
+Geçerli alan adları:
+- invoice_amount      (proforma fatura tutarı)
+- vehicle_model       (araç modeli)
+- requested_amount_new (istenen finansman - yeni araç)
+- guarantor_tckn      (kefil TCKN)
+- kasko_value         (kasko değeri)
+- vehicle_age         (araç yaşı)
+- requested_amount_used (istenen finansman - 2. el)
+- seller_tckn         (satıcı TCKN)
+
+Çıktı (sadece JSON):
+{"target_slot": "<alan adı veya null>", "new_value_hint": "<varsa yeni değer ipucu>"}
+"""
+
+# ── Reflection / Self-check ───────────────────────────────────────────────────
+REFLECTION_SYSTEM = """Araç finansmanı başvurusu için toplanan bilgileri kontrol ediyorsun.
+Araç türüne göre eksik veya hatalı alan var mı tespit et.
+
+Yeni araç için zorunlu alanlar: invoice_amount, vehicle_model, requested_amount_new
+Yeni araçta kefil: invoice_amount >= 5000000 ise guarantor_tckn zorunlu
+
+2. El araç için zorunlu alanlar: kasko_value, vehicle_age, requested_amount_used
+
+Mevcut state:
+{state_summary}
+
+Çıktı (sadece JSON):
+{{"complete": <bool>, "missing_fields": [<alan adları>], "issues": [<açıklama>]}}
+"""
+
+# ── HGS Çapraz Satış ─────────────────────────────────────────────────────────
+HGS_PITCH = """Başvurunuz başarıyla oluşturuldu! 🎉
+
+Başvuru Numaranız: {application_id}
+
+─────────────────────────────────────
+💳 HGS (Hızlı Geçiş Sistemi) Teklifi
+─────────────────────────────────────
+Yeni aracınız için HGS tanımlatmak ister misiniz?
+Bankamız üzerinden anında aktif edebilirsiniz.
+
+Devam etmek istiyor musunuz?"""
+
+# ── Genel Hata Mesajları ──────────────────────────────────────────────────────
+MSG_WELCOME = "Merhaba! Araç finansmanı ön başvurusu için yardımcı olabilirim. Yeni araç mı, 2. el araç mı düşünüyorsunuz?"
+MSG_OUT_OF_SCOPE = "Üzgünüm, bu konuda yardımcı olamıyorum. Araç finansmanı veya ilgili sorularınız için buradayım."
+MSG_OPERATOR_REDIRECT = "Bu konuyu daha iyi değerlendirmek için sizi müşteri hizmetlerimize yönlendiriyorum. 0850 XXX XX XX numaralı hattı arayabilirsiniz."
+MSG_FLOW_ENDED_LIMIT = "Maalesef bu başvuru kriterleri karşılamadığı için devam edemiyoruz. Farklı bir seçenek için şubemizi ziyaret edebilirsiniz."

chatbot/memory/checkpointer.py

@@ -0,0 +1,34 @@
+"""
+memory/checkpointer.py — LangGraph MemorySaver Konfigürasyonu
+
+AGENTIC PATTERN: Short-Term Memory (Checkpointing)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+LangGraph MemorySaver, her oturum (thread_id) için state'i
+in-memory olarak saklar. Kullanıcı yeni mesaj gönderdiğinde
+graph, önceki state'ten devam eder — slot'lar kaybolmaz.
+
+thread_id = session_id: Her kullanıcı oturumu tamamen bağımsız.
+İki oturumun state'i birbirine karışamaz.
+
+Üretimde: SqliteSaver veya RedisSaver kullanılır.
+Öğrenme için: MemorySaver yeterli.
+"""
+from langgraph.checkpoint.memory import MemorySaver
+
+# Uygulama genelinde tek bir checkpointer instance
+_checkpointer = MemorySaver()
+
+
+def get_checkpointer() -> MemorySaver:
+    """Global checkpointer instance'ını döndürür."""
+    return _checkpointer
+
+
+def get_thread_config(session_id: str) -> dict:
+    """
+    LangGraph invoke/stream için gerekli config dict'ini döndürür.
+
+    Kullanım:
+        graph.invoke(state, config=get_thread_config(session_id))
+    """
+    return {"configurable": {"thread_id": session_id}}

chatbot/memory/vector_store.py

@@ -0,0 +1,173 @@
+"""
+memory/vector_store.py — Jina Embedding + ChromaDB RAG Altyapısı
+
+AGENTIC PATTERN: Long-Term Memory (RAG)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Uzun vadeli hafıza = SSS dokümanının vektörleştirilmiş hali.
+Uygulama her başladığında FAQ dokümanı chunk'lara bölünür,
+Jina API ile embed edilir ve ChromaDB'ye kaydedilir.
+
+ChromaDB, veritabanını diske persist eder (data/chroma/).
+Uygulama yeniden başlatılınca aynı vektörler tekrar kullanılır
+(re-indeksleme yapılmaz).
+
+Jina AI free tier: https://jina.ai/embeddings/
+  - Model: jina-embeddings-v3
+  - 1M token/ay ücretsiz
+  - 8192 token context window
+  - Türkçe dahil çok dilli destek
+"""
+from __future__ import annotations
+import os
+import re
+import httpx
+import chromadb
+from config import (
+    CHROMA_PERSIST_DIR,
+    FAQ_COLLECTION_NAME,
+    JINA_API_KEY,
+    JINA_API_URL,
+    JINA_EMBEDDING_MODEL,
+    RAG_TOP_K,
+)
+
+FAQ_PATH = os.path.join(os.path.dirname(__file__), "..", "data", "faq.md")
+
+# ChromaDB istemcisi (singleton)
+_client: chromadb.PersistentClient | None = None
+_collection = None
+
+
+def _get_client():
+    global _client, _collection
+    if _client is None:
+        os.makedirs(CHROMA_PERSIST_DIR, exist_ok=True)
+        _client = chromadb.PersistentClient(path=CHROMA_PERSIST_DIR)
+        _collection = _client.get_or_create_collection(FAQ_COLLECTION_NAME)
+    return _client, _collection
+
+
+def embed_texts(texts: list[str]) -> list[list[float]]:
+    """
+    Jina AI API ile metinleri vektörleştirir.
+
+    Jina'nın 'retrieval.passage' görevi embedding üretim içindir.
+    Sorgu zamanında 'retrieval.query' kullanılır (asimetrik retrieval).
+    """
+    if not JINA_API_KEY:
+        raise ValueError("JINA_API_KEY tanımlı değil. .env dosyasını kontrol edin.")
+
+    response = httpx.post(
+        JINA_API_URL,
+        headers={"Authorization": f"Bearer {JINA_API_KEY}", "Content-Type": "application/json"},
+        json={"model": JINA_EMBEDDING_MODEL, "task": "retrieval.passage", "input": texts},
+        timeout=30.0,
+    )
+    response.raise_for_status()
+    return [item["embedding"] for item in response.json()["data"]]
+
+
+def embed_query(query: str) -> list[float]:
+    """
+    Sorgu metnini vektörleştirir (passage'dan farklı görev).
+    Asimetrik retrieval: soru ve cevap farklı embedding uzayında.
+    """
+    response = httpx.post(
+        JINA_API_URL,
+        headers={"Authorization": f"Bearer {JINA_API_KEY}", "Content-Type": "application/json"},
+        json={"model": JINA_EMBEDDING_MODEL, "task": "retrieval.query", "input": [query]},
+        timeout=30.0,
+    )
+    response.raise_for_status()
+    return response.json()["data"][0]["embedding"]
+
+
+def _chunk_faq(faq_text: str) -> list[dict]:
+    """
+    FAQ dokümanını başlık + içerik çiftlerine böler.
+    ### başlığı bir chunk sınırıdır.
+
+    Returns:
+        [{"id": str, "text": str, "title": str}, ...]
+    """
+    chunks = []
+    sections = re.split(r"\n### ", faq_text)
+
+    for i, section in enumerate(sections):
+        if not section.strip():
+            continue
+        lines = section.strip().split("\n", 1)
+        title = lines[0].strip("# ").strip()
+        content = lines[1].strip() if len(lines) > 1 else ""
+        if content:
+            chunks.append({
+                "id": f"faq_{i:03d}",
+                "text": f"Soru: {title}\nCevap: {content}",
+                "title": title,
+            })
+    return chunks
+
+
+def index_faq(force_reindex: bool = False):
+    """
+    FAQ dokümanını okuyup ChromaDB'ye indeksler.
+    force_reindex=False → zaten indekslenmişse atla.
+    """
+    _, collection = _get_client()
+
+    # Zaten indekslenmişse atla
+    if not force_reindex and collection.count() > 0:
+        print(f"[VectorStore] {collection.count()} chunk zaten indeksli, atlanıyor.")
+        return
+
+    with open(FAQ_PATH, encoding="utf-8") as f:
+        faq_text = f.read()
+
+    chunks = _chunk_faq(faq_text)
+    print(f"[VectorStore] {len(chunks)} chunk indeksleniyor...")
+
+    # Jina API limitleri için batch halinde embed et
+    batch_size = 20
+    for i in range(0, len(chunks), batch_size):
+        batch = chunks[i: i + batch_size]
+        texts = [c["text"] for c in batch]
+        embeddings = embed_texts(texts)
+
+        collection.upsert(
+            ids=[c["id"] for c in batch],
+            documents=[c["text"] for c in batch],
+            embeddings=embeddings,
+            metadatas=[{"title": c["title"]} for c in batch],
+        )
+
+    print(f"[VectorStore] İndeksleme tamamlandı. Toplam: {collection.count()} chunk")
+
+
+def search_faq(query: str, top_k: int = RAG_TOP_K) -> list[dict]:
+    """
+    Sorguya en alakalı FAQ chunk'larını döndürür.
+
+    Returns:
+        [{"text": str, "title": str, "distance": float}, ...]
+    """
+    _, collection = _get_client()
+
+    if collection.count() == 0:
+        return []
+
+    query_embedding = embed_query(query)
+    results = collection.query(
+        query_embeddings=[query_embedding],
+        n_results=min(top_k, collection.count()),
+        include=["documents", "metadatas", "distances"],
+    )
+
+    chunks = []
+    for doc, meta, dist in zip(
+        results["documents"][0],
+        results["metadatas"][0],
+        results["distances"][0],
+    ):
+        chunks.append({"text": doc, "title": meta["title"], "distance": dist})
+
+    return chunks

chatbot/observability/audit_logger.py

@@ -0,0 +1,207 @@
+"""
+observability/audit_logger.py — Değiştirilemez Denetim Kaydı
+
+REPORT Karşılığı: "Audit Log + Trace" (Gözlem & Denetim)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Her LLM çağrısı, tool çağrısı, guard olayı ve slot değişimi
+değiştirilemez (APPEND-ONLY) SQLite tablosuna kaydedilir.
+
+KVKK ve BDDK uyumu için:
+- TCKN, kart no gibi hassas veriler maskelenmiş haliyle yazılır
+- Ham kişisel veri loga girmez
+- Audit kayıtları silinemez (soft-delete bile yok)
+
+Event tipleri:
+  llm_call    : LLM'e giden/dönen her çağrı
+  tool_call   : @tool fonksiyonu çağrıları
+  guard_event : Input/output guard tetiklenmeleri
+  slot_change : Konuşma state'inde slot değişimleri
+"""
+import json
+import sqlite3
+import uuid
+from datetime import datetime, timezone
+from config import DB_PATH
+
+
+def log_event(
+    session_id: str,
+    event_type: str,           # llm_call | tool_call | guard_event | slot_change
+    agent: str,                # hangi agent oluşturdu
+    details: dict,             # olay detayları (model, latency, token vb.)
+    masked_input: str = "",    # maskelenmiş kullanıcı girdisi
+) -> str:
+    """
+    Tek bir denetim olayı kaydeder.
+
+    Returns:
+        event_id: Oluşturulan kayıt UUID'si
+    """
+    event_id = str(uuid.uuid4())
+    timestamp = datetime.now(timezone.utc).isoformat()
+
+    conn = sqlite3.connect(DB_PATH)
+    conn.execute(
+        """INSERT INTO audit_events (id, session_id, timestamp, event_type, agent, details, masked_input)
+           VALUES (?, ?, ?, ?, ?, ?, ?)""",
+        (event_id, session_id, timestamp, event_type, agent, json.dumps(details, ensure_ascii=False), masked_input),
+    )
+    conn.commit()
+    conn.close()
+    return event_id
+
+
+def log_llm_call(
+    session_id: str,
+    agent: str,
+    model: str,
+    latency_ms: int,
+    tokens_in: int,
+    tokens_out: int,
+    prompt=None,
+    response=None,
+    max_chars: int = 4000,
+):
+    """LLM çağrısı için kısayol.
+
+    prompt: str | list[dict] | None — LLM'e giden mesaj(lar). list verilirse
+            role/content'e indirgenip JSON-serialize edilir.
+    response: str | None — LLM'in ürettiği ham içerik.
+    max_chars: prompt/response için karakter üst limiti (DB'yi şişirmemek için).
+    """
+    details = {
+        "model": model,
+        "latency_ms": latency_ms,
+        "tokens_in": tokens_in,
+        "tokens_out": tokens_out,
+    }
+
+    if prompt is not None:
+        details["prompt"] = _trim(_normalize_prompt(prompt), max_chars)
+    if response is not None:
+        details["response"] = _trim(str(response), max_chars)
+
+    return log_event(
+        session_id=session_id,
+        event_type="llm_call",
+        agent=agent,
+        details=details,
+    )
+
+
+def _normalize_prompt(prompt) -> str:
+    """Prompt'u loglanabilir stringe çevir; system mesajlarını ele (gürültü)."""
+    if isinstance(prompt, str):
+        return prompt
+    if isinstance(prompt, list):
+        parts = []
+        for m in prompt:
+            if isinstance(m, dict):
+                role = m.get("role", "?")
+                if role == "system":
+                    continue  # system prompt'u görüntülemeden gizle
+                content = m.get("content", "")
+                parts.append(f"[{role}] {content}")
+            else:
+                parts.append(str(m))
+        return "\n".join(parts)
+    return str(prompt)
+
+
+def _trim(text: str, limit: int) -> str:
+    if len(text) <= limit:
+        return text
+    return text[:limit] + f"... <truncated {len(text) - limit} chars>"
+
+
+def log_tool_call(session_id: str, agent: str, tool_name: str, args: dict, result: dict, success: bool):
+    """Tool çağrısı için kısayol."""
+    return log_event(
+        session_id=session_id,
+        event_type="tool_call",
+        agent=agent,
+        details={"tool": tool_name, "args": _sanitize(args), "result": _sanitize(result), "success": success},
+    )
+
+
+def log_guard_event(session_id: str, guard_type: str, triggered: bool, reason: str, masked_text: str = ""):
+    """Guard tetiklenmesi için kısayol."""
+    return log_event(
+        session_id=session_id,
+        event_type="guard_event",
+        agent=guard_type,
+        details={"triggered": triggered, "reason": reason},
+        masked_input=masked_text,
+    )
+
+
+def log_routing(session_id: str, from_node: str, to_node: str, reason: str = ""):
+    """Edge fonksiyonunun verdiği yönlendirme kararını kaydet."""
+    return log_event(
+        session_id=session_id,
+        event_type="routing",
+        agent=from_node,
+        details={"from": from_node, "to": to_node, "reason": reason},
+    )
+
+
+def log_slot_change(session_id: str, slot_name: str, old_value, new_value):
+    """Slot değişimi için kısayol — hassas alanları maskele."""
+    sensitive = {"guarantor_tckn", "seller_tckn"}
+    if slot_name in sensitive:
+        old_value = _mask_tckn(str(old_value)) if old_value else None
+        new_value = _mask_tckn(str(new_value)) if new_value else None
+
+    return log_event(
+        session_id=session_id,
+        event_type="slot_change",
+        agent="orchestrator",
+        details={"slot": slot_name, "old": old_value, "new": new_value},
+    )
+
+
+def get_session_events(session_id: str) -> list[dict]:
+    """Bir oturumun tüm audit olaylarını döndürür."""
+    conn = sqlite3.connect(DB_PATH)
+    rows = conn.execute(
+        "SELECT id, timestamp, event_type, agent, details, masked_input FROM audit_events WHERE session_id=? ORDER BY timestamp",
+        (session_id,),
+    ).fetchall()
+    conn.close()
+
+    return [
+        {
+            "id": r[0], "timestamp": r[1], "event_type": r[2],
+            "agent": r[3], "details": json.loads(r[4]), "masked_input": r[5],
+        }
+        for r in rows
+    ]
+
+
+def get_recent_events(limit: int = 50) -> list[dict]:
+    """Son N olayı döndürür (dashboard için)."""
+    conn = sqlite3.connect(DB_PATH)
+    rows = conn.execute(
+        "SELECT id, session_id, timestamp, event_type, agent, details FROM audit_events ORDER BY timestamp DESC LIMIT ?",
+        (limit,),
+    ).fetchall()
+    conn.close()
+    return [{"id": r[0], "session": r[1][:8], "time": r[2][11:19], "type": r[3], "agent": r[4], "details": r[5]} for r in rows]
+
+
+def _sanitize(data: dict) -> dict:
+    """Dict içindeki hassas alanları maskele."""
+    sensitive_keys = {"tckn", "tc", "card", "iban", "password"}
+    result = {}
+    for k, v in data.items():
+        if any(s in k.lower() for s in sensitive_keys) and isinstance(v, str):
+            result[k] = _mask_tckn(v)
+        else:
+            result[k] = v
+    return result
+
+
+def _mask_tckn(value: str) -> str:
+    if len(value) >= 7:
+        return value[:3] + "****" + value[7:]
+    return "***"

chatbot/observability/dashboard.py

@@ -0,0 +1,81 @@
+"""
+observability/dashboard.py — Gradio Audit/Metrik Dashboard Sekmesi
+
+REPORT Karşılığı: Metric/Alert dashboard görselleştirmesi.
+Gradio'nun Tab bileşeni ile ana chat'in yanında ikinci bir sekme olarak gösterilir.
+"""
+import gradio as gr
+from observability.metrics import get_summary_metrics, get_audit_table, get_llm_calls
+
+
+def build_dashboard_tab():
+    """
+    Gradio Tab bileşeni döndürür — app.py'deki Blocks içine eklenir.
+    """
+    with gr.Tab("📊 İzleme Paneli"):
+        gr.Markdown("## Gerçek Zamanlı Metrikler")
+
+        with gr.Row():
+            total_apps = gr.Number(label="Toplam Başvuru", interactive=False)
+            hgs_rate = gr.Number(label="HGS Dönüşüm %", interactive=False)
+            guard_count = gr.Number(label="Guard Tetiklenme", interactive=False)
+            p50 = gr.Number(label="LLM Latency p50 (ms)", interactive=False)
+            p95 = gr.Number(label="LLM Latency p95 (ms)", interactive=False)
+
+        refresh_btn = gr.Button("🔄 Yenile")
+        audit_table = gr.Dataframe(
+            headers=["Oturum", "Saat", "Tür", "Agent", "Özet", "Prompt", "Response"],
+            label="Son Denetim Olayları",
+            interactive=False,
+            wrap=True,
+        )
+
+        gr.Markdown("## 🤖 LLM Çağrıları (prompt + response)")
+        llm_session_filter = gr.Textbox(
+            label="Oturum filtresi (boş = tümü, kısmî UUID kabul)",
+            placeholder="örn: 3f9a1b2c",
+        )
+        llm_table = gr.Dataframe(
+            headers=["Oturum", "Saat", "Agent", "Model", "Latency (ms)", "Tok In", "Tok Out", "Prompt", "Response"],
+            label="Son LLM Çağrıları",
+            interactive=False,
+            wrap=True,
+        )
+
+        def refresh_metrics(sid_filter: str):
+            m = get_summary_metrics()
+            rows = get_audit_table(30)
+            table_data = [
+                [r["session"], r["time"], r["type"], r["agent"], r["summary"],
+                 r.get("prompt", ""), r.get("response", "")]
+                for r in rows
+            ]
+
+            sid = sid_filter.strip() or None
+            llm_rows = get_llm_calls(50, session_id=None)
+            if sid:
+                llm_rows = [r for r in llm_rows if sid in r["session"]]
+            llm_data = [
+                [r["session"], r["time"], r["agent"], r["model"],
+                 r["latency_ms"], r["tokens_in"], r["tokens_out"],
+                 r["prompt"], r["response"]]
+                for r in llm_rows
+            ]
+
+            return (
+                m["total_applications"],
+                m["hgs_conversion_rate"],
+                m["guard_triggers"],
+                m["llm_latency_p50_ms"],
+                m["llm_latency_p95_ms"],
+                table_data,
+                llm_data,
+            )
+
+        refresh_btn.click(
+            fn=refresh_metrics,
+            inputs=[llm_session_filter],
+            outputs=[total_apps, hgs_rate, guard_count, p50, p95, audit_table, llm_table],
+        )
+
+    return refresh_btn

chatbot/observability/metrics.py

@@ -0,0 +1,172 @@
+"""
+observability/metrics.py — İş ve Teknik Metrikler
+
+REPORT Karşılığı: "Metric / Alert" (Gözlem & Denetim)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Audit log tablosundan gerçek zamanlı metrik hesaplamaları yapar.
+Dashboard bu modülü sorguladığında güncel sayılar döner.
+
+Teknik metrikler:
+  - LLM latency (p50, p95 hesaplaması)
+  - Token kullanımı (model bazında)
+
+İş metrikleri:
+  - Başvuru tamamlama oranı
+  - Adım bazlı terk (en çok hangi adımda bırakılıyor)
+  - Guard tetiklenme sayısı (injection girişimi vb.)
+  - HGS dönüşüm oranı
+  - FAQ kullanım sıklığı
+"""
+import json
+import sqlite3
+from datetime import datetime, timezone
+from config import DB_PATH
+
+
+def _fmt_local_time(ts: str) -> str:
+    """ISO UTC timestamp'i yerel saate çevirip HH:MM:SS döndürür."""
+    if not ts:
+        return ""
+    try:
+        dt = datetime.fromisoformat(ts.replace("Z", "+00:00"))
+        if dt.tzinfo is None:
+            dt = dt.replace(tzinfo=timezone.utc)
+        return dt.astimezone().strftime("%H:%M:%S")
+    except Exception:
+        return ts[11:19] if len(ts) >= 19 else ts
+
+
+def get_summary_metrics() -> dict:
+    """Dashboard için özet metrik paketi."""
+    conn = sqlite3.connect(DB_PATH)
+
+    # Toplam başvuru sayısı
+    total_apps = conn.execute("SELECT COUNT(*) FROM applications").fetchone()[0]
+
+    # HGS kayıt sayısı
+    hgs_count = conn.execute("SELECT COUNT(*) FROM hgs_registrations").fetchone()[0]
+
+    # Guard tetiklenme sayısı
+    guard_triggers = conn.execute(
+        "SELECT COUNT(*) FROM audit_events WHERE event_type='guard_event' AND details LIKE '%\"triggered\": true%'"
+    ).fetchone()[0]
+
+    # Son 100 LLM çağrısından latency hesapla
+    latencies = conn.execute(
+        "SELECT details FROM audit_events WHERE event_type='llm_call' ORDER BY timestamp DESC LIMIT 100"
+    ).fetchall()
+
+    lat_values = []
+    total_tokens_in = 0
+    total_tokens_out = 0
+    for (det,) in latencies:
+        d = json.loads(det)
+        if "latency_ms" in d:
+            lat_values.append(d["latency_ms"])
+        total_tokens_in += d.get("tokens_in", 0)
+        total_tokens_out += d.get("tokens_out", 0)
+
+    lat_values.sort()
+    p50 = lat_values[len(lat_values) // 2] if lat_values else 0
+    p95 = lat_values[int(len(lat_values) * 0.95)] if lat_values else 0
+
+    # Araç türü dağılımı
+    type_dist = conn.execute(
+        "SELECT vehicle_type, COUNT(*) FROM applications GROUP BY vehicle_type"
+    ).fetchall()
+
+    conn.close()
+
+    return {
+        "total_applications": total_apps,
+        "hgs_registrations": hgs_count,
+        "hgs_conversion_rate": round(hgs_count / total_apps * 100, 1) if total_apps > 0 else 0,
+        "guard_triggers": guard_triggers,
+        "llm_latency_p50_ms": p50,
+        "llm_latency_p95_ms": p95,
+        "total_tokens_in": total_tokens_in,
+        "total_tokens_out": total_tokens_out,
+        "vehicle_type_distribution": {r[0]: r[1] for r in type_dist},
+    }
+
+
+def get_audit_table(limit: int = 30) -> list[dict]:
+    """Dashboard audit log tablosu için son olaylar."""
+    conn = sqlite3.connect(DB_PATH)
+    rows = conn.execute(
+        """SELECT session_id, timestamp, event_type, agent, details
+           FROM audit_events ORDER BY timestamp DESC LIMIT ?""",
+        (limit,),
+    ).fetchall()
+    conn.close()
+
+    result = []
+    for r in rows:
+        details = json.loads(r[4])
+        # Latency veya triggered gibi özet bilgi çıkar
+        summary = ""
+        if "latency_ms" in details:
+            summary = f"{details['latency_ms']}ms"
+        elif "triggered" in details:
+            summary = "✓ Tetiklendi" if details["triggered"] else "- Geçti"
+        elif "slot" in details:
+            summary = f"{details['slot']}: {details.get('new')}"
+        elif "from" in details and "to" in details:
+            summary = f"{details['from']} → {details['to']}"
+            if details.get("reason"):
+                summary += f" ({details['reason']})"
+
+        prompt_preview = _preview(details.get("prompt"))
+        response_preview = _preview(details.get("response"))
+
+        result.append({
+            "session": r[0][:8] + "...",
+            "time": _fmt_local_time(r[1]),
+            "type": r[2],
+            "agent": r[3],
+            "summary": summary,
+            "prompt": prompt_preview,
+            "response": response_preview,
+        })
+    return result
+
+
+def _preview(text, limit: int = 200) -> str:
+    if text is None:
+        return ""
+    s = str(text).replace("\n", " ⏎ ")
+    return s if len(s) <= limit else s[:limit] + "…"
+
+
+def get_llm_calls(limit: int = 50, session_id: str | None = None) -> list[dict]:
+    """LLM çağrılarını prompt+response ile birlikte döndür (izleme için)."""
+    conn = sqlite3.connect(DB_PATH)
+    if session_id:
+        rows = conn.execute(
+            """SELECT session_id, timestamp, agent, details FROM audit_events
+               WHERE event_type='llm_call' AND session_id=? ORDER BY timestamp DESC LIMIT ?""",
+            (session_id, limit),
+        ).fetchall()
+    else:
+        rows = conn.execute(
+            """SELECT session_id, timestamp, agent, details FROM audit_events
+               WHERE event_type='llm_call' ORDER BY timestamp DESC LIMIT ?""",
+            (limit,),
+        ).fetchall()
+    conn.close()
+
+    out = []
+    for sid, ts, agent, det in rows:
+        d = json.loads(det)
+        out.append({
+            "session": sid[:8] + "...",
+            "time": _fmt_local_time(ts),
+            "agent": agent,
+            "model": d.get("model", ""),
+            "latency_ms": d.get("latency_ms", 0),
+            "tokens_in": d.get("tokens_in", 0),
+            "tokens_out": d.get("tokens_out", 0),
+            "prompt": d.get("prompt", ""),
+            "response": d.get("response", ""),
+        })
+    return out

chatbot/observability/tracer.py

@@ -0,0 +1,65 @@
+"""
+observability/tracer.py — OpenTelemetry Distributed Tracing
+
+REPORT Karşılığı: "Audit Log + Trace" (OpenTelemetry ile distributed tracing)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Her konuşma turu bir TRACE; her agent çağrısı bir SPAN olarak kaydedilir.
+
+Span hiyerarşisi:
+  conversation_turn (root span)
+  ├── input_guard
+  ├── supervisor
+  │   └── llm_call
+  ├── intake_agent / faq_agent / validation_agent
+  │   ├── llm_call
+  │   └── tool_call
+  └── output_guard
+
+Geliştirmede: ConsoleSpanExporter ile terminale yazdırılır.
+Üretimde: OTLP exporter ile Jaeger/Grafana Tempo'ya gönderilir.
+"""
+from contextlib import contextmanager
+from opentelemetry import trace
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor, ConsoleSpanExporter
+from opentelemetry.sdk.resources import Resource
+
+# Uygulama kimliği
+resource = Resource.create({"service.name": "arac-finansman-chatbot", "service.version": "1.0.0"})
+
+# Provider kurulumu (uygulama başında bir kez yapılır)
+_provider = TracerProvider(resource=resource)
+_provider.add_span_processor(BatchSpanProcessor(ConsoleSpanExporter()))
+trace.set_tracer_provider(_provider)
+
+tracer = trace.get_tracer("chatbot.tracer")
+
+
+@contextmanager
+def trace_span(name: str, attributes: dict = None):
+    """
+    Context manager olarak span başlatır.
+
+    Kullanım:
+        with trace_span("validation_agent", {"session_id": "abc"}):
+            # bu blok içindeki işlemler span içinde yer alır
+            ...
+    """
+    with tracer.start_as_current_span(name) as span:
+        if attributes:
+            for k, v in attributes.items():
+                span.set_attribute(k, str(v))
+        try:
+            yield span
+        except Exception as e:
+            span.record_exception(e)
+            span.set_status(trace.StatusCode.ERROR, str(e))
+            raise
+
+
+def get_current_trace_id() -> str:
+    """Aktif trace ID'sini döndürür (log korelasyonu için)."""
+    ctx = trace.get_current_span().get_span_context()
+    if ctx.is_valid:
+        return format(ctx.trace_id, "032x")
+    return "no-trace"

chatbot/requirements.txt

@@ -0,0 +1,40 @@
+# Bu proje Python 3.10+ gerektirir.
+# Sanal ortam olusturmak icin:
+#   python3.11 -m venv .venv
+#   .venv\Scripts\activate
+#   pip install -r requirements.txt
+
+# Agentic Framework (Python 3.10+ zorunlu)
+langgraph>=0.2.0
+langchain>=0.3.0
+langchain-community>=0.3.0
+
+# LLM API (GPT / Claude / Gemini hepsini tek interfaceyle)
+litellm>=1.40.0
+langchain-openai>=0.2.0
+
+# Backend
+fastapi>=0.115.0
+uvicorn[standard]>=0.30.0
+
+# UI (HuggingFace Spaces uyumlu)
+gradio>=4.44.0
+
+# Vector DB (Docker gerektirmez)
+chromadb>=0.5.0
+
+# Embedding (Jina AI - httpx ile direkt cagri)
+httpx>=0.27.0
+
+# Veri dogrulama
+pydantic>=2.0.0
+
+# Ortam degiskenleri
+python-dotenv>=1.0.0
+
+# Gozlem & Denetim
+opentelemetry-sdk>=1.25.0
+opentelemetry-exporter-otlp>=1.25.0
+
+# Yardimci
+python-dateutil>=2.9.0

chatbot/setup.py

@@ -0,0 +1,108 @@
+"""
+setup.py — Kurulum ve İlk Çalıştırma Scripti
+
+Çalıştır:
+    python setup.py
+
+Bu script:
+1. Gerekli klasörleri oluşturur
+2. .env dosyasını kontrol eder
+3. SQLite tabloları oluşturur
+4. FAQ dokümanını ChromaDB'ye indeksler
+5. Temel yapıyı doğrular
+"""
+import os
+import sys
+
+# Proje kök dizini
+BASE_DIR = os.path.dirname(__file__)
+sys.path.insert(0, BASE_DIR)
+
+
+def check_env():
+    """API key'lerin tanımlı olduğunu kontrol et."""
+    from dotenv import load_dotenv
+    load_dotenv()
+
+    env_path = os.path.join(BASE_DIR, ".env")
+    if not os.path.exists(env_path):
+        example_path = os.path.join(BASE_DIR, ".env.example")
+        print(f"[UYARI] .env dosyası bulunamadı.")
+        print(f"        .env.example dosyasını kopyalayın: cp {example_path} {env_path}")
+        print(f"        Ardından API key'lerinizi doldurun.\n")
+    else:
+        print("[✓] .env dosyası bulundu.")
+
+    import config as cfg
+    missing = []
+    if not cfg.OPENAI_API_KEY and "gpt" in cfg.ACTIVE_MODEL:
+        missing.append("OPENAI_API_KEY")
+    if not cfg.ANTHROPIC_API_KEY and "claude" in cfg.ACTIVE_MODEL:
+        missing.append("ANTHROPIC_API_KEY")
+    if not cfg.GOOGLE_API_KEY and "gemini" in cfg.ACTIVE_MODEL:
+        missing.append("GOOGLE_API_KEY")
+    if not cfg.JINA_API_KEY:
+        missing.append("JINA_API_KEY (FAQ RAG için gerekli)")
+
+    if missing:
+        print(f"[UYARI] Eksik API key'ler: {', '.join(missing)}")
+    else:
+        print(f"[✓] API key'ler tanımlı. Aktif model: {cfg.ACTIVE_MODEL}")
+
+
+def setup_db():
+    """SQLite tabloları oluştur."""
+    from tools.db_tool import init_db
+    init_db()
+    print("[✓] SQLite tabloları hazır.")
+
+
+def index_faq():
+    """FAQ dokümanını ChromaDB'ye indeksle."""
+    from config import JINA_API_KEY
+    if not JINA_API_KEY:
+        print("[UYARI] JINA_API_KEY eksik — FAQ indeksleme atlandı.")
+        return
+
+    from memory.vector_store import index_faq as _index
+    try:
+        _index()
+        print("[✓] FAQ dokümanı indekslendi.")
+    except Exception as e:
+        print(f"[HATA] FAQ indeksleme başarısız: {e}")
+
+
+def verify_catalog():
+    """Araç kataloğunun yüklendiğini doğrula."""
+    import json
+    catalog_path = os.path.join(BASE_DIR, "data", "vehicle_catalog.json")
+    with open(catalog_path, encoding="utf-8") as f:
+        catalog = json.load(f)
+    print(f"[✓] Araç kataloğu: {len(catalog)} marka/model grubu yüklendi.")
+
+
+def main():
+    print("=" * 50)
+    print("Araç Finansmanı Chatbot — Kurulum")
+    print("=" * 50 + "\n")
+
+    # Data klasörünü oluştur
+    os.makedirs(os.path.join(BASE_DIR, "data"), exist_ok=True)
+    os.makedirs(os.path.join(BASE_DIR, "data", "chroma"), exist_ok=True)
+
+    check_env()
+    setup_db()
+    verify_catalog()
+    index_faq()
+
+    print("\n" + "=" * 50)
+    print("Kurulum tamamlandı!")
+    print("\nUygulamayı başlatmak için:")
+    print("  python app.py")
+    print("\nVeya doğrudan Gradio ile:")
+    print("  gradio app.py")
+    print("=" * 50)
+
+
+if __name__ == "__main__":
+    main()

chatbot/tools/amount_tool.py

@@ -0,0 +1,129 @@
+"""
+tools/amount_tool.py — Finansman Tutarı Hesap ve Doğrulama
+
+AGENTIC PATTERN: Tool Use — Deterministik İş Kuralları
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Tüm finansman kuralları (üst limitler, oranlar) burada KOD olarak
+çalışır. LLM bu kuralları ne hesaplar ne de doğrular — sadece
+hangi tool'u çağıracağını seçer.
+
+Bu sayede:
+- Kural hataları test edilebilir (birim test)
+- Kural değişikliği için tek bir yer
+- LLM halüsinasyonu → iş kararlarına etki edemez
+"""
+from langchain_core.tools import tool
+from config import (
+    NEW_CAR_MAX_INVOICE,
+    NEW_CAR_FINANCE_RATIO,
+    NEW_CAR_GUARANTOR_THRESHOLD,
+    USED_CAR_MAX_AGE,
+    USED_CAR_FINANCE_RATIO,
+    USED_CAR_MAX_FINANCE,
+)
+
+
+@tool
+def validate_new_car_amount(invoice_amount: float, requested_amount: float) -> dict:
+    """
+    Yeni araç finansman tutarını iş kurallarına göre doğrular.
+
+    Kurallar:
+    - Fatura tutarı ≤ 7.000.000 TL
+    - Finansman ≤ %60 × fatura tutarı
+
+    Returns:
+        {"valid": bool, "max_allowed": float, "error": str | None,
+         "kefil_required": bool}
+    """
+    # Kural 1: Fatura üst limiti
+    if invoice_amount > NEW_CAR_MAX_INVOICE:
+        return {
+            "valid": False,
+            "max_allowed": NEW_CAR_MAX_INVOICE,
+            "error": f"Proforma fatura tutarı {_fmt(NEW_CAR_MAX_INVOICE)} TL üst limitini aşıyor.",
+            "kefil_required": False,
+        }
+
+    # Kural 2: Finansman oranı
+    max_finance = invoice_amount * NEW_CAR_FINANCE_RATIO
+    if requested_amount > max_finance:
+        return {
+            "valid": False,
+            "max_allowed": max_finance,
+            "error": (
+                f"İstenen finansman ({_fmt(requested_amount)} TL), "
+                f"fatura tutarının %{int(NEW_CAR_FINANCE_RATIO*100)}'ini aşıyor. "
+                f"Maksimum: {_fmt(max_finance)} TL"
+            ),
+            "kefil_required": invoice_amount >= NEW_CAR_GUARANTOR_THRESHOLD,
+        }
+
+    return {
+        "valid": True,
+        "max_allowed": max_finance,
+        "error": None,
+        "kefil_required": invoice_amount >= NEW_CAR_GUARANTOR_THRESHOLD,
+    }
+
+
+@tool
+def validate_used_car_amount(kasko_value: float, vehicle_age: int, requested_amount: float) -> dict:
+    """
+    2. El araç finansman tutarını iş kurallarına göre doğrular.
+
+    Kurallar:
+    - Araç yaşı ≤ 5 yıl
+    - Finansman ≤ min(%40 × kasko_value, 3.000.000 TL)
+
+    Returns:
+        {"valid": bool, "max_allowed": float, "error": str | None}
+    """
+    # Kural 1: Yaş kontrolü
+    if vehicle_age > USED_CAR_MAX_AGE:
+        return {
+            "valid": False,
+            "max_allowed": 0,
+            "error": f"Araç yaşı {vehicle_age} yıl, maksimum kabul edilen {USED_CAR_MAX_AGE} yıldır.",
+        }
+
+    # Kural 2: Finansman oranı (min ile sınırla)
+    ratio_limit = kasko_value * USED_CAR_FINANCE_RATIO
+    max_finance = min(ratio_limit, USED_CAR_MAX_FINANCE)
+
+    if requested_amount > max_finance:
+        return {
+            "valid": False,
+            "max_allowed": max_finance,
+            "error": (
+                f"İstenen finansman ({_fmt(requested_amount)} TL) limiti aşıyor. "
+                f"Kasko oranı limiti: {_fmt(ratio_limit)} TL, "
+                f"mutlak üst limit: {_fmt(USED_CAR_MAX_FINANCE)} TL."
+            ),
+        }
+
+    return {"valid": True, "max_allowed": max_finance, "error": None}
+
+
+@tool
+def calculate_max_finance_new(invoice_amount: float) -> dict:
+    """Yeni araç için alınabilecek maksimum finansmanı hesaplar."""
+    max_f = invoice_amount * NEW_CAR_FINANCE_RATIO
+    return {
+        "max_finance": max_f,
+        "ratio": NEW_CAR_FINANCE_RATIO,
+        "kefil_required": invoice_amount >= NEW_CAR_GUARANTOR_THRESHOLD,
+    }
+
+
+@tool
+def calculate_max_finance_used(kasko_value: float) -> dict:
+    """2. El araç için alınabilecek maksimum finansmanı hesaplar."""
+    ratio_limit = kasko_value * USED_CAR_FINANCE_RATIO
+    max_f = min(ratio_limit, USED_CAR_MAX_FINANCE)
+    return {"max_finance": max_f, "ratio": USED_CAR_FINANCE_RATIO, "absolute_cap": USED_CAR_MAX_FINANCE}
+
+
+def _fmt(amount: float) -> str:
+    """Sayıyı Türkçe binlik ayırıcıyla formatlar: 3000000 → '3.000.000'"""
+    return f"{int(amount):,}".replace(",", ".")

chatbot/tools/catalog_tool.py

@@ -0,0 +1,69 @@
+"""
+tools/catalog_tool.py — Araç Modeli Kataloğu
+
+AGENTIC PATTERN: Tool Use
+━━━━━━━━━━━━━━━━━━━━━━━━
+Araç modeli → binek/ticari sınıflandırması bu tool ile yapılır.
+LLM modeli çıkarır, katalog nihai kararı verir.
+O(1) lookup: JSON yüklenip dict'e çevrilir, uygulama başında bir kez.
+"""
+import json
+import os
+from functools import lru_cache
+from langchain_core.tools import tool
+
+CATALOG_PATH = os.path.join(os.path.dirname(__file__), "..", "data", "vehicle_catalog.json")
+
+
+@lru_cache(maxsize=1)
+def _load_catalog() -> dict:
+    """
+    Kataloğu bir kez yükle, in-memory cache'de tut.
+    lru_cache(maxsize=1) → uygulama hayatı boyunca sadece bir kez okur.
+    """
+    with open(CATALOG_PATH, encoding="utf-8") as f:
+        entries = json.load(f)
+
+    # Arama kolaylığı için düzleştirilmiş dict: "bmw_3 serisi" → {type, brand, model}
+    catalog: dict = {}
+    for entry in entries:
+        key = f"{entry['brand'].lower()}_{entry['model'].lower()}"
+        catalog[key] = entry
+        # Variant'ları da ekle
+        for variant in entry.get("variants", []):
+            vkey = f"{entry['brand'].lower()}_{variant.lower()}"
+            catalog[vkey] = {**entry, "model": variant}
+    return catalog
+
+
+@tool
+def lookup_vehicle(brand: str, model: str) -> dict:
+    """
+    Araç marka ve modelinin binek/ticari sınıfını katalogdan döndürür.
+
+    Args:
+        brand: Araç markası (örn. "BMW", "Ford")
+        model: Araç modeli (örn. "3 Serisi", "Transit")
+
+    Returns:
+        {"found": bool, "type": "binek"|"ticari"|None, "brand": str, "model": str}
+    """
+    catalog = _load_catalog()
+    key = f"{brand.lower()}_{model.lower()}"
+
+    if key in catalog:
+        entry = catalog[key]
+        return {"found": True, "type": entry["type"], "brand": entry["brand"], "model": entry["model"]}
+
+    # Fuzzy: sadece marka eşleşmesi
+    brand_matches = [v for k, v in catalog.items() if k.startswith(brand.lower() + "_")]
+    if brand_matches:
+        return {
+            "found": False,
+            "type": None,
+            "brand": brand,
+            "model": model,
+            "suggestions": [f"{m['brand']} {m['model']}" for m in brand_matches[:5]],
+        }
+
+    return {"found": False, "type": None, "brand": brand, "model": model, "suggestions": []}

chatbot/tools/db_tool.py

@@ -0,0 +1,113 @@
+"""
+tools/db_tool.py — SQLite Başvuru Yazma Aracı
+
+AGENTIC PATTERN: Tool Use — Least-Privilege
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+LLM doğrudan veritabanına erişemez. Orchestrator bu tool'u çağırır.
+TCKN ve hassas veriler maskelenmiş haliyle yazılır.
+Sadece submission_agent bu tool'a erişebilir (least-privilege).
+"""
+import sqlite3
+import uuid
+from datetime import datetime
+from langchain_core.tools import tool
+from config import DB_PATH
+
+
+def init_db():
+    """Uygulama başlarken tabloları oluştur (yoksa)."""
+    conn = sqlite3.connect(DB_PATH)
+    conn.execute("""
+        CREATE TABLE IF NOT EXISTS applications (
+            id TEXT PRIMARY KEY,
+            session_id TEXT,
+            vehicle_type TEXT,
+            created_at TEXT,
+            -- Yeni araç alanları
+            invoice_amount REAL,
+            vehicle_model TEXT,
+            requested_amount_new REAL,
+            guarantor_tckn_masked TEXT,
+            -- 2. el alanları
+            kasko_value REAL,
+            vehicle_age INTEGER,
+            requested_amount_used REAL,
+            seller_tckn_masked TEXT,
+            -- Meta
+            status TEXT DEFAULT 'pending'
+        )
+    """)
+    conn.execute("""
+        CREATE TABLE IF NOT EXISTS audit_events (
+            id TEXT PRIMARY KEY,
+            session_id TEXT,
+            timestamp TEXT,
+            event_type TEXT,
+            agent TEXT,
+            details TEXT,
+            masked_input TEXT
+        )
+    """)
+    conn.execute("""
+        CREATE TABLE IF NOT EXISTS hgs_registrations (
+            id TEXT PRIMARY KEY,
+            application_id TEXT,
+            session_id TEXT,
+            created_at TEXT,
+            status TEXT DEFAULT 'active'
+        )
+    """)
+    conn.commit()
+    conn.close()
+
+
+@tool
+def write_application(
+    session_id: str,
+    vehicle_type: str,
+    invoice_amount: float | None = None,
+    vehicle_model: str | None = None,
+    requested_amount_new: float | None = None,
+    guarantor_tckn_masked: str | None = None,
+    kasko_value: float | None = None,
+    vehicle_age: int | None = None,
+    requested_amount_used: float | None = None,
+    seller_tckn_masked: str | None = None,
+) -> dict:
+    """
+    Onaylanmış başvuruyu veritabanına yazar.
+
+    Returns:
+        {"success": bool, "application_id": str, "error": str | None}
+    """
+    app_id = str(uuid.uuid4())[:8].upper()  # Kısa, okunabilir başvuru no
+
+    try:
+        conn = sqlite3.connect(DB_PATH)
+        conn.execute(
+            """INSERT INTO applications VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?)""",
+            (
+                app_id, session_id, vehicle_type,
+                datetime.utcnow().isoformat(),
+                invoice_amount, vehicle_model, requested_amount_new, guarantor_tckn_masked,
+                kasko_value, vehicle_age, requested_amount_used, seller_tckn_masked,
+                "pending",
+            ),
+        )
+        conn.commit()
+        conn.close()
+        return {"success": True, "application_id": app_id, "error": None}
+    except Exception as e:
+        return {"success": False, "application_id": None, "error": str(e)}
+
+
+@tool
+def get_application_history(session_id: str) -> dict:
+    """Bir oturumun geçmiş başvurularını listeler."""
+    conn = sqlite3.connect(DB_PATH)
+    rows = conn.execute(
+        "SELECT id, vehicle_type, created_at, status FROM applications WHERE session_id=? ORDER BY created_at DESC",
+        (session_id,),
+    ).fetchall()
+    conn.close()
+    return {"applications": [{"id": r[0], "type": r[1], "date": r[2], "status": r[3]} for r in rows]}

chatbot/tools/hgs_tool.py

@@ -0,0 +1,53 @@
+"""
+tools/hgs_tool.py — HGS Mock Servisi
+
+AGENTIC PATTERN: Tool Use — Scoped Access
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Çapraz satış agent'ı YALNIZCA bu tool'a erişebilir.
+Ön Başvuru DB'ye dokunamaz (least-privilege prensibi).
+
+Gerçek entegrasyonda: Karayolları HGS API çağrısı yapılır.
+Burada: in-memory mock (öğrenme amaçlı).
+"""
+import uuid
+import sqlite3
+from datetime import datetime
+from langchain_core.tools import tool
+from config import DB_PATH
+
+
+@tool
+def check_hgs_status(session_id: str) -> dict:
+    """
+    Müşterinin aktif HGS kaydı var mı kontrol eder.
+    Aktif HGS varsa çapraz satış adımı gösterilmez.
+
+    Returns:
+        {"has_active_hgs": bool}
+    """
+    # Mock: session_id'e göre rastgele sonuç (gerçekte CRM'e sorgu)
+    # Basitlik için: id'nin son hanesi çifts → HGS var
+    has_hgs = (ord(session_id[-1]) % 2 == 0)
+    return {"has_active_hgs": has_hgs}
+
+
+@tool
+def register_hgs(session_id: str, application_id: str) -> dict:
+    """
+    HGS başvurusunu kaydeder.
+
+    Returns:
+        {"success": bool, "hgs_id": str, "error": str | None}
+    """
+    hgs_id = "HGS-" + str(uuid.uuid4())[:6].upper()
+    try:
+        conn = sqlite3.connect(DB_PATH)
+        conn.execute(
+            "INSERT INTO hgs_registrations VALUES (?,?,?,?,?)",
+            (hgs_id, application_id, session_id, datetime.utcnow().isoformat(), "active"),
+        )
+        conn.commit()
+        conn.close()
+        return {"success": True, "hgs_id": hgs_id, "error": None}
+    except Exception as e:
+        return {"success": False, "hgs_id": None, "error": str(e)}

chatbot/tools/rag_tool.py

@@ -0,0 +1,44 @@
+"""
+tools/rag_tool.py — RAG Retrieval Aracı
+
+AGENTIC PATTERN: Tool Use + Long-Term Memory
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+FAQ agent bu tool'u çağırarak ChromaDB'den ilgili chunk'ları getirir.
+Tool; embed et → ara → döndür işlemini kapsüller.
+FAQ agent'ı sadece READ yetkisine sahiptir; slot okuyamaz/yazamaz.
+"""
+from langchain_core.tools import tool
+from memory.vector_store import search_faq
+from config import RAG_TOP_K
+
+
+@tool
+def retrieve_faq(query: str, top_k: int = RAG_TOP_K) -> dict:
+    """
+    Kullanıcı sorusuna en alakalı SSS içeriklerini getirir.
+
+    Args:
+        query: Kullanıcının sorusu
+        top_k: Kaç chunk getirileceği (varsayılan config'den)
+
+    Returns:
+        {"chunks": [{"text": str, "title": str, "distance": float}],
+         "context": str}  # LLM'e doğrudan verilecek birleşik metin
+    """
+    chunks = search_faq(query, top_k=top_k)
+
+    if not chunks:
+        return {
+            "chunks": [],
+            "context": "Bu konuda SSS dokümanında bilgi bulunamadı.",
+        }
+
+    # LLM'e verilecek context metnini oluştur
+    context_parts = []
+    for i, chunk in enumerate(chunks, 1):
+        context_parts.append(f"[{i}] {chunk['title']}\n{chunk['text']}")
+
+    return {
+        "chunks": chunks,
+        "context": "\n\n".join(context_parts),
+    }

chatbot/tools/tckn_tool.py

@@ -0,0 +1,62 @@
+"""
+tools/tckn_tool.py — TCKN Doğrulama Aracı
+
+AGENTIC PATTERN: Tool Use
+━━━━━━━━━━━━━━━━━━━━━━━━
+@tool decorator ile LangChain/LangGraph'a kayıt edilir.
+Agent, "bu TCKN geçerli mi?" sorusunu cevaplamak için
+bu tool'u çağırır. LLM kendi başına checksum hesaplamaz;
+sadece hangi tool'u çağıracağına karar verir.
+
+Algoritma: Türk TC Kimlik No mod-11 doğrulama standardı
+- 11 haneli, ilk hane 0 olamaz
+- 10. hane: (d1+d3+d5+d7+d9)*7 - (d2+d4+d6+d8) mod 10
+- 11. hane: (d1+d2+...+d10) mod 10
+
+API çağrısı YOK — tamamen deterministik, senkron.
+"""
+from langchain_core.tools import tool
+
+
+@tool
+def validate_tckn(tckn: str) -> dict:
+    """
+    Türk TC Kimlik Numarasını mod-11 algoritmasıyla doğrular.
+
+    Args:
+        tckn: Doğrulanacak TCKN (11 hane, string)
+
+    Returns:
+        {"valid": bool, "error": str | None, "masked": str}
+    """
+    # Boşluk ve tire temizle
+    tckn = tckn.strip().replace(" ", "").replace("-", "")
+
+    # Format kontrolü
+    if not tckn.isdigit():
+        return {"valid": False, "error": "TCKN yalnızca rakamlardan oluşmalı.", "masked": ""}
+    if len(tckn) != 11:
+        return {"valid": False, "error": f"TCKN 11 hane olmalı, {len(tckn)} hane girildi.", "masked": ""}
+    if tckn[0] == "0":
+        return {"valid": False, "error": "TCKN 0 ile başlayamaz.", "masked": ""}
+
+    digits = [int(c) for c in tckn]
+
+    # 10. hane kontrolü
+    check10 = ((sum(digits[i] for i in range(0, 9, 2)) * 7) - sum(digits[i] for i in range(1, 8, 2))) % 10
+    if digits[9] != check10:
+        return {"valid": False, "error": "TCKN doğrulama hatası (10. hane).", "masked": _mask(tckn)}
+
+    # 11. hane kontrolü
+    check11 = sum(digits[:10]) % 10
+    if digits[10] != check11:
+        return {"valid": False, "error": "TCKN doğrulama hatası (11. hane).", "masked": _mask(tckn)}
+
+    return {"valid": True, "error": None, "masked": _mask(tckn)}
+
+
+def _mask(tckn: str) -> str:
+    """TCKN'nin ortasını gizler: 123****8901 formatında döner."""
+    if len(tckn) != 11:
+        return "***"
+    return tckn[:3] + "****" + tckn[7:]