yargi-mcp-nvidia-semantic/
├── README.md                          # Bu dosya
├── PATCHES.md                         # Patch detayları (Seçenek 1 + 3)
├── CHANGELOG.md                       # Sürüm notları
├── LICENSE                            # Orijinal lisans (MIT)
├── pyproject.toml                     # Bağımlılıklar
├── .env.example                       # Çevre değişkenleri şablonu
├── Dockerfile
├── mcp_server_main.py                 # Patched: adaptive batch + retry
├── semantic_search/
│   ├── embedder.py                    # Patched: NVIDIA asimetrik model desteği
│   ├── vector_store.py
│   └── processor.py
├── bedesten_mcp_module/
│   └── client.py                      # BedestenRateLimited exception + rate limiter
├── *_mcp_module/                      # 16 Türk hukuki kurumu modülü
│   ├── anayasa_mcp_module/
│   ├── bedesten_mcp_module/
│   ├── danistay_mcp_module/
│   ├── emsal_mcp_module/
│   ├── gib_mcp_module/
│   ├── kik_mcp_module/
│   ├── kvkk_mcp_module/
│   ├── rekabet_mcp_module/
│   ├── sayistay_mcp_module/
│   ├── sigorta_tahkim_mcp_module/
│   └── ...
├── patches/                           # Diff dosyaları
│   ├── 001_embedder_nvidia_asymmetric_support.diff
│   └── 002_mcp_server_adaptive_batch_retry.diff
└── tests/
    ├── test_yargi_mcp_semantic_search.py    # E2E test (NVIDIA + Bedesten)
    ├── test_nvidia_embeddings.py            # NVIDIA API birim testi
    ├── test_nvidia_local_embedder.py        # LocalEmbedder entegrasyon testi
    └── yargi_mcp_semantic_results.json      # Gerçek test çıktısı (28 belge)

# Repoyu klonla
git clone https://github.com/muhammedturan65/yargi-mcp-nvidia-semantic.git
cd yargi-mcp-nvidia-semantic

# Python >= 3.11 gerekli
python -m venv .venv
source .venv/bin/activate
pip install -e .

# === NVIDIA Embedding ===
export EMBEDDING_PROVIDER=local
export LOCAL_EMBEDDING_BASE_URL=https://integrate.api.nvidia.com/v1
export LOCAL_EMBEDDING_API_KEY=nvapi-XXXXXXXX
export LOCAL_EMBEDDING_MODEL=nvidia/nv-embed-v1
export LOCAL_EMBEDDING_DIMENSION=4096
export LOCAL_EMBEDDING_INPUT_TYPE=auto
export EMBEDDING_PROMPT_STYLE=raw

# === Bedesten Rate-Limit (Patch 2) ===
export BEDESTEN_RATE_CAPACITY=1
export BEDESTEN_RATE_REFILL_S=4.0
export BEDESTEN_RATE_MAX_WAIT_S=60
export BEDESTEN_SEMANTIC_BATCH_SIZE=30
export BEDESTEN_SEMANTIC_MAX_RETRIES=3

# E2E test (NVIDIA + Bedesten gerçek API çağrısı)
python tests/test_yargi_mcp_semantic_search.py

# NVIDIA API birim testi
python tests/test_nvidia_embeddings.py

# LocalEmbedder entegrasyon testi
python tests/test_nvidia_local_embedder.py

[1/4] mcp_server_main yükleniyor...
  SEMANTIC_SEARCH_AVAILABLE = True
  ✓ BedestenApiClient hazır: BedestenApiClient

[2/4] search_bedesten_semantic tool çağrılıyor...

[3/4] Sonuç alındı!
  status: success
  total_documents_processed: 28
  embedding_model: nvidia/nv-embed-v1
  embedding_dimension: 4096
  documents_in_store: 28
  failed_fetches: 2

{
  "mcpServers": {
    "yargi-mcp": {
      "command": "/path/to/.venv/bin/python",
      "args": ["-m", "yargi_mcp"],
      "env": {
        "EMBEDDING_PROVIDER": "local",
        "LOCAL_EMBEDDING_BASE_URL": "https://integrate.api.nvidia.com/v1",
        "LOCAL_EMBEDDING_API_KEY": "nvapi-...",
        "LOCAL_EMBEDDING_MODEL": "nvidia/nv-embed-v1",
        "LOCAL_EMBEDDING_DIMENSION": "4096",
        "LOCAL_EMBEDDING_INPUT_TYPE": "auto",
        "BEDESTEN_RATE_MAX_WAIT_S": "60",
        "BEDESTEN_SEMANTIC_BATCH_SIZE": "30"
      }
    }
  }
}

Kullanıcı sorusu
        │
        ▼
┌────────────────────────────────────────────────┐
│  1. normalize_query(soru)                      │
│     ç→c, ı→i, ğ→g, punct strip, lowercase    │
│     "Mirasçı hangi davayı açar?"               │
│     → "mirasci hangi davayi acar"              │
├────────────────────────────────────────────────┤
│  2. cache_key = sha256(normalized)[:16]         │  ← exact match key
├────────────────────────────────────────────────┤
│  3. LRU lookup (OrderedDict)         ~0 ms     │  ← process içi
│     ├─ HIT → return cached embedding           │
│     └─ MISS ↓                                   │
│  4. ChromaDB persistent lookup     ~5 ms       │  ← process restart'ta kalıcı
│     ├─ HIT → LRU'ya da yaz, return             │
│     └─ MISS ↓                                   │
│  5. NVIDIA encode_query()          ~1000 ms    │  ← gerçek API çağrısı
│     + LRU'ya yaz + ChromaDB'ye yaz             │
└────────────────────────────────────────────────┘

# Query embedding cache (default: açık)
export RAG_QUERY_CACHE=true                          # kapatmak için false
export RAG_QUERY_CACHE_LRU_SIZE=256                  # in-memory LRU max kayıt
export RAG_QUERY_CACHE_COLLECTION=query_embed_cache  # ChromaDB collection adı

                     ┌─────────────────────────────────────┐
                     │  BedestenIndexer (tek seferlik)     │
                     │  v1.2.0 — ChromaDB kalıcı store    │
                     └─────────────────┬───────────────────┘
                                       │ (disk - kalıcı)
                                       ▼
                     ┌─────────────────────────────────────┐
Kullanıcı sorusu ──► │  LegalQARAG.ask()                   │
                     │   1. QueryEmbeddingCache [v1.4.0]   │
                     │      ├─ LRU HIT        → 0 ms       │
                     │      ├─ Persistent HIT → 5 ms       │
                     │      └─ MISS → NVIDIA encode ~1 s   │
                     │   2. ChromaDB.search_with_dedup()   │ ~50ms
                     │   3. AnswerCache.lookup() [v1.3.0]  │ ~4ms
                     │      ├─ HIT → cache'den cevap       │ → RETURN
                     │      └─ MISS → devam                │
                     │   4. LLMClient.chat_async() [v1.3.0]│ ~3-240s
                     │   5. AnswerCache.store() [v1.3.0]   │ ~50ms
                     └─────────────────────────────────────┘

# Hızlı LLM için (önerilen):
export LLM_PROVIDER=groq
export GROQ_API_KEY=gq_...

# Veya OpenAI:
export LLM_PROVIDER=openai
export OPENAI_API_KEY=sk-...

# Veya tamamen local:
export LLM_PROVIDER=ollama
ollama pull llama3.1:8b

from qa_rag import LegalQARAG

rag = LegalQARAG()
await rag.load_corpora()

# İlk sorgu — LLM çağrılır (~60s NVIDIA, ~3s Groq)
r1 = await rag.ask("Mirasçı hangi davayı açar?")
print(f"Süre: {r1.total_time_ms/1000:.1f}s, from_cache: {r1.from_cache}")
# → Süre: 52.5s, from_cache: False

# Aynı soru tekrar — cache HIT, LLM atlanır
r2 = await rag.ask("Mirasçı hangi davayı açar?")
print(f"Süre: {r2.total_time_ms/1000:.1f}s, from_cache: {r2.from_cache}, score: {r2.cache_score:.4f}")
# → Süre: 1.9s, from_cache: True, score: 1.0000

export RAG_ANSWER_CACHE=true             # default — açık
export RAG_CACHE_THRESHOLD=0.92          # cosine threshold (yüksek = daha sıkı eşleşme)
export RAG_CACHE_COLLECTION=qa_cache     # ChromaDB collection adı

                     ┌─────────────────────────────────────┐
                     │  BedestenIndexer (tek seferlik)     │
                     │  v1.2.0 — ChromaDB kalıcı store    │
                     └─────────────────┬───────────────────┘
                                       │ (disk - kalıcı)
                                       ▼
                     ┌─────────────────────────────────────┐
Kullanıcı sorusu ──► │  LegalQARAG.ask()                   │
                     │   1. NVIDIA nv-embed-v1 (query)     │ ~1s
                     │   2. ChromaDB.search_with_dedup()   │ ~50ms
                     │   3. AnswerCache.lookup() [v1.3.0]  │ ~4ms
                     │      ├─ HIT → cache'den cevap       │ → RETURN
                     │      └─ MISS → devam                │
                     │   4. LLMClient.chat_async() [v1.3.0]│ ~3-240s
                     │      └─ NVIDIA / Groq / OpenAI /    │
                     │         Ollama (env'den seçim)      │
                     │   5. AnswerCache.store() [v1.3.0]   │ ~50ms
                     └─────────────────────────────────────┘

# 1. Groq API key al: https://console.groq.com/keys (ücretsiz)
export GROQ_API_KEY=gq_...

# 2. NVIDIA embedding (hâlâ NVIDIA nv-embed-v1 kullanıyoruz — en iyi Türkçe embedding)
export LOCAL_EMBEDDING_API_KEY=nvapi-...
export EMBEDDING_PROVIDER=local
export LOCAL_EMBEDDING_BASE_URL=https://integrate.api.nvidia.com/v1
export LOCAL_EMBEDDING_MODEL=nvidia/nv-embed-v1
export LOCAL_EMBEDDING_DIMENSION=4096
export LOCAL_EMBEDDING_INPUT_TYPE=auto
export EMBEDDING_PROMPT_STYLE=raw

# 3. Provider seç
export LLM_PROVIDER=groq

# 4. Cache açık (default)
export RAG_ANSWER_CACHE=true

# 5. İlk seferlik index (~5-10 dk, ChromaDB'ye yazılır)
yargi-qa --load-corpus

# 6. Sor
yargi-qa --ask "Muvazaalı tapu satışında mirasçı hangi davayı açar?"
# → İlk sorgu: ~3s (Groq LLM)
# → Tekrar: ~1.9s (cache HIT)

                     ┌─────────────────────────────────────┐
                     │  BedestenIndexer (tek seferlik)     │
                     │                                     │
Bedesten API ──────► │  search → fetch full text → chunk   │
                     │     ↓                               │
                     │  NVIDIA nv-embed-v1 (passage)       │
                     │     ↓                               │
                     │  ChromaDB.add_chunks()              │
                     └─────────────────┬───────────────────┘
                                       │ (disk - kalıcı)
                                       ▼
                     ┌─────────────────────────────────────┐
Kullanıcı sorusu ──► │  LegalQARAG.ask()                   │
                     │   1. NVIDIA nv-embed-v1 (query)     │ ~1s
                     │   2. ChromaDB.search_with_dedup()   │ ~50ms
                     │   3. build_context_from_decisions() │
                     │   4. NVIDIA Llama 3.1 70B           │ ~60-240s
                     └─────────────────┬───────────────────┘
                                       ▼
                            Atıflı cevap: "tapu iptali ve tescil davası açar.
                            [1] Yargıtay 7. HD, E.2026/2403, K.2026/3418"

qa_rag/
├── __init__.py        # Modül girişi + exports
├── llm_client.py      # NVIDIA LLM client (sync + async + streaming)
├── prompts.py         # Türk hukuki system prompt + context builder
├── citations.py       # Atıf formatlama
├── rag_engine.py      # LegalQARAG (chroma/memory backend seçimi)
├── chunker.py         # LegalChunker — 512-token, section-aware
├── indexer.py         # BedestenIndexer — Bedesten → ChromaDB pipeline
├── cli.py             # yargi-qa interaktif REPL + --ask modu
└── api.py             # FastAPI app (REST + SSE streaming)

semantic_search/
├── embedder.py        # NVIDIA nv-embed-v1 embedder (query/passage asimetrik)
├── vector_store.py    # In-memory VectorStore (v1.0.0'dan)
└── vector_store_chroma.py  # ChromaDB kalıcı store (v1.2.0)

# ChromaDB + tiktoken otomatik kurulur (pyproject.toml dependencies)
cd yargi-mcp-nvidia-semantic
pip install -e ".[qa]"

# NVIDIA API key
export NVIDIA_API_KEY=nvapi-...

# ChromaDB kalıcı dizini (default: ./chroma_db)
export CHROMA_PERSIST_DIR=/path/to/chroma_db

import asyncio
from qa_rag import LegalQARAG

async def main():
    rag = LegalQARAG(backend="chroma")
    # İlk sefer: 200 belge çek, chunk'la, embed'le, ChromaDB'ye yaz
    result = await rag.load_corpora(
        initial_keyword="muvazaa tapu iptal",
        court_types=["YARGITAYKARARI"],
        target_docs=200,
    )
    print(f"{result['indexed_docs']} belge, {result['total_chunks']} chunk indexlendi")
    print(f"Süre: {result['elapsed_s']}s")

asyncio.run(main())

rag = LegalQARAG(backend="chroma")
# ChromaDB'de veri varsa is_corpora_loaded=True (process restart sonrası bile)
print(rag.is_corpora_loaded)  # True

response = await rag.ask("Mirasçı muvazaalı satışa karşı hangi davayı açar?")
print(response.answer)
print(f"Retrieval: {response.retrieval_time_ms}ms")  # ~1000ms
print(f"LLM: {response.generation_time_ms}ms")       # ~60-240s

# 1. İlk index (tek seferlik, ~5-10 dk)
export NVIDIA_API_KEY=nvapi-...
export CHROMA_PERSIST_DIR=$HOME/yargi_chroma
python -c "
import asyncio
from qa_rag import LegalQARAG
async def m():
    rag = LegalQARAG(backend='chroma')
    r = await rag.load_corpora(target_docs=50)
    print(r)
asyncio.run(m())
"

# 2. API başlat (artık ChromaDB'de veri var, anında hazır)
yargi-qa-api &

# 3. Soru sor (sub-second retrieval)
curl -X POST http://localhost:8001/api/ask \
  -H "Content-Type: application/json" \
  -d '{"question": "Muvazaalı satışta mirasçının hakları nelerdir?"}'

Kullanıcı sorusu
       ↓
[NVIDIA nv-embed-v1] — query embedding (4096d)
       ↓
[VectorStore.search] — top-K en alakalı kararlar (cosine similarity)
       ↓
[build_context_from_decisions] — numaralandırılmış karar metinleri
       ↓
[NVIDIA Llama 3.1 70B Instruct] — atıflı cevap üretimi
       ↓
Atıf listesi: [1] Yargıtay 7. HD, E.2026/2403, K.2026/3418

qa_rag/
├── __init__.py        # Modül girişi
├── llm_client.py      # NVIDIA LLM client (sync + async + streaming)
├── prompts.py         # Türk hukuki system prompt + context builder
├── citations.py       # Atıf formatlama
├── rag_engine.py      # LegalQARAG ana sınıf
├── cli.py             # yargi-qa interaktif REPL + --ask modu
└── api.py             # FastAPI app (REST + SSE streaming)

# Repo'yu klonla
git clone https://github.com/muhammedturan65/yargi-mcp-nvidia-semantic.git
cd yargi-mcp-nvidia-semantic

# Python >= 3.11 ile venv
python -m venv .venv
source .venv/bin/activate
pip install -e ".[qa]"

# NVIDIA API key set et
export NVIDIA_API_KEY=nvapi-XXXXXXXX

yargi-qa

========================================================================
  yargi-qa — Türk Hukuki QA Chatbot (RAG)
  NVIDIA nv-embed-v1 + Llama 3.1 70B + Bedesten emsal kararları
========================================================================

İlk kurulum: Bedesten'den 30 karar yükleniyor (~2 dk)...
  keyword: 'muvazaa tapu iptal'

✓ 28 karar yüklendi (2 fetch hatası)

Komutlar:
  /load <keyword>   Yeni corpus yükle (örn: /load nafaka)
  /info             Mevcut corpus bilgisi
  /examples         Örnek hukuki soruları göster
  /clear            Ekranı temizle
  /help             Bu yardım
  /quit             Çıkış

yargi-qa> Mirasçı, murisin muvazaalı satışına karşı hangi davayı açar?
Düşünüyor...

------------------------------------------------------------------------
Soru: Mirasçı, murisin muvazaalı satışına karşı hangi davayı açar?
------------------------------------------------------------------------

Mirasçı, murisin muvazaalı satışına karşı tapu iptal ve tescil davası açabilir.
...

[1] Yargıtay 7. HD, E.2026/2403, K.2026/3418 (14.03.2002) [skor: 0.3497]
[2] Yargıtay 7. HD, E.2026/4216, K.2026/3514 (29.06.2026) [skor: 0.3422]
[3] Yargıtay 7. HD, E.2026/3025, K.2026/3499 (17.10.2019) [skor: 0.3268]

⏱  Toplam: 76800ms (retrieval: 1003ms, LLM: 75770ms) | Tokens: 1948
------------------------------------------------------------------------

yargi-qa --ask "Muvazaa iddiasında ispat yükü kimin üzerinedir?"

yargi-qa --ask "Tapu iptal davasında süre nedir?" --stream

# API server başlat
yargi-qa-api
# veya
uvicorn qa_rag.api:app --host 0.0.0.0 --port 8001

# Corpus yükle (önce bunu yap)
curl -X POST http://localhost:8001/api/load \
  -H "Content-Type: application/json" \
  -d '{"initial_keyword": "muvazaa tapu iptal"}'

# Soru sor
curl -X POST http://localhost:8001/api/ask \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Mirasçı muvazaalı satışa karşı hangi davayı açar?",
    "top_k": 5,
    "temperature": 0.2
  }'

# Streaming
curl -N -X POST http://localhost:8001/api/ask/stream \
  -H "Content-Type: application/json" \
  -d '{"question": "Tapu iptal davasında süre nedir?"}'

# 1. API başlat
export NVIDIA_API_KEY=nvapi-...
export QA_AUTO_LOAD_CORPUS=1
yargi-qa-api &

# 2. Bekle (corpus yükleniyor, ~2 dk)
sleep 120

# 3. Soru sor
curl -X POST http://localhost:8001/api/ask \
  -H "Content-Type: application/json" \
  -d '{"question": "Muvazaalı satışta mirasçının hakları nelerdir?"}'

# 4. Streaming dene
curl -N -X POST http://localhost:8001/api/ask/stream \
  -H "Content-Type: application/json" \
  -d '{"question": "Tapu iptal davasında karar süresi nedir?"}'