# duembi/rag architecture

> Architecture diagram of the GitHub repository duembi/rag, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/duembi/rag
- Repository: https://github.com/duembi/rag

## Overview

#### Amaç ve depo düzeni
Depo, OSB/parsel Excel envanterini doğrulanabilir doğal dil soru-cevap için iki farklı RAG uygulamasıyla işler. `custom-rag/` eğitim amaçlı, sıralı prototip; `rag_with_ai/` ise üretim odaklı çok-ajanlı uygulamadır. Ana operasyonel giriş noktası ikinci projenin API’sidir: `rag_with_ai/src/api/main.py`. İlk proje, numaralı Python betiklerinin sırayla çalıştırıldığı bir öğrenme hattıdır.

#### Klasik RAG öğrenme hattı
`custom-rag/` veri hazırlama, chunk üretme, Chroma’ya yükleme, retrieval, bağlam kurma ve sohbet katmanlarını aşamalı olarak ayırır. Temel akış Excel/veri → parçalar → embedding/Chroma → sorgu sonuçları → LLM bağlamı → chatbot şeklindedir.
- `custom-rag/003.DataPreparation.py`
- `custom-rag/005.LoadChunksToChroma.py`
- `custom-rag/008.RAGChatbot.py`

Bu yaklaşım anlamsal retrieval’a dayanır; yapılandırılmış toplama, sayım ve çoklu filtreleme soruları için daha gelişmiş projenin Text-to-SQL yoluna mimari gerekçe sağlar.

#### Çok-ajanlı orkestrasyon ve yönlendirme
`rag_with_ai` merkezi durum ve kontrol akışını bir graph üzerinden yürütür. Graph, kullanıcı isteğini uygun işleme yoluna yönlendirir; graph state, ajanlar arası çalışma verisini taşır.
- `rag_with_ai/src/graph.py`
- `rag_with_ai/src/graph_state.py`
- `rag_with_ai/src/agents/rag_pipeline_agent.py`

Ana ayrım şudur: yapısal/aggregasyon talepleri SQL tabanlı veri erişimine, açıklayıcı veya semantik talepler embedding tabanlı retrieval’a gider. Bu, LLM’nin tablo gerçeklerini üretmek yerine veri kaynağından almasını hedefler.

#### Veri hazırlama ve kalıcılık sınırı
Kaynak, dönemsel OSB/parsel Excel dosyalarıdır; ham ve impute edilmiş sürümler depoda bulunur. İmputation ajanı eksik veri sorununu retrieval ve cevaplama öncesinde ayrı bir veri-kalitesi aşaması olarak ele alır.
- `rag_with_ai/src/agents/data_imputation_agent.py`
- `rag_with_ai/data/raw/2026-2__Çeyrek__Nisan-Mayıs-Haziran__Parsel_Tablosu (4).xlsx`
- `rag_with_ai/data/parsel.sqlite`

Yapılandırılmış sorgu sınırı SQLite’daki parsel verisidir. Semantik indeks ise yerel, kalıcı Chroma deposudur: `rag_with_ai/data/chroma_index/chroma.sqlite3`.

#### Retrieval ve cevap güvenilirliği
Retrieval kurulum ajanı Chroma/embedding tabanlı indeksi hazırlar veya kullanıma açar; RAG pipeline agent sorgu, alınan bağlam ve LLM cevabını birleştirir. QA değerlendirme ajanı cevabın bağlama sadakatini doğrulamaya yönelik ayrı bir kalite kapısıdır.
- `rag_with_ai/src/agents/retrieval_setup_agent.py`
- `rag_with_ai/src/agents/qa_eval_agent.py`
- `rag_with_ai/data/chroma_index/chroma.sqlite3`

Bu katmanlar, veri erişimi ile üretken model çıktısı arasındaki temel güven sınırını oluşturur: SQL/retrieval kanıt sağlar, LLM yalnızca yanıt sentezler.

#### API, oturumlar ve çalışma ortamı
HTTP API ve statik kullanıcı arayüzü aynı API alanında sunulur; konuşma geçmişi ayrı SQLite depolamasında kalıcıdır.
- `rag_with_ai/src/api/main.py`
- `rag_with_ai/src/api/conversation_store.py`
- `rag_with_ai/data/conversations.sqlite`

Çalışma zamanı Python’dır; bağımlılıklar `rag_with_ai/requirements.txt` içinde tanımlanır. Harici model hizmeti yerel Ollama’dır: klasik projede `gemma3:4b`, çok-ajanlı projede `Qwen2.5-7B`. Yerel GPU/VRAM kaynak yönetimi ayrıca ele alınır: `rag_with_ai/src/vram_manager.py`.

Main entry points: [`rag_with_ai/src/graph.py`](https://github.com/duembi/rag/blob/main/rag_with_ai/src/graph.py) (İstek orkestrasyon graphı), [`rag_with_ai/src/agents/rag_pipeline_agent.py`](https://github.com/duembi/rag/blob/main/rag_with_ai/src/agents/rag_pipeline_agent.py) (RAG pipeline ajanı), [`rag_with_ai/src/agents/data_imputation_agent.py`](https://github.com/duembi/rag/blob/main/rag_with_ai/src/agents/data_imputation_agent.py) (Veri imputation ajanı), [`rag_with_ai/src/api/main.py`](https://github.com/duembi/rag/blob/main/rag_with_ai/src/api/main.py) (HTTP API ve statik UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_classic["Klasik RAG prototipi"]
  node_classic_prep["Veri hazırlama<br/>Python aşaması"]
  node_classic_chroma_load["Chunk ve Chroma yükleme<br/>Python aşaması"]
  node_classic_chatbot["RAG chatbot<br/>Python aşaması<br/>[008.RAGChatbot.py]"]
end

subgraph group_production["Çok-ajanlı RAG"]
  node_api["HTTP API ve statik UI<br/>API giriş noktası<br/>[main.py]"]
  node_conversation_store["Konuşma deposu<br/>oturum kalıcılığı"]
  node_graph{{"İstek orkestrasyon graphı<br/>ajan graphı<br/>[graph.py]"}}
  node_graph_state["Graph state<br/>çalışma durumu<br/>[graph_state.py]"]
  node_imputation["Veri imputation ajanı<br/>veri kalitesi ajanı"]
  node_retrieval_setup["Retrieval kurulum ajanı<br/>indeks ajanı"]
  node_rag_agent["RAG pipeline ajanı<br/>yanıt ajanı"]
  node_qa_eval["QA değerlendirme ajanı<br/>kalite kapısı<br/>[qa_eval_agent.py]"]
  node_vram["VRAM yöneticisi<br/>GPU kaynak yönetimi<br/>[vram_manager.py]"]
end

subgraph group_storage["Yerel veri depoları"]
  node_raw_excel["Ham parsel Excel<br/>kaynak veri"]
  node_parsel_db[("Parsel SQLite<br/>yapılandırılmış veri<br/>[parsel.sqlite]")]
  node_chroma[("Kalıcı Chroma indeksi<br/>vektör indeks<br/>[chroma.sqlite3]")]
  node_conversations_db[("Konuşmalar SQLite<br/>oturum verisi")]
end

node_ollama(("Yerel Ollama<br/>LLM hizmeti"))

node_classic_prep -->|"hazırlanmış veri"| node_classic_chroma_load
node_classic_chroma_load -->|"embedding ve retrieval"| node_classic_chatbot
node_api -->|"oturum işlemleri"| node_conversation_store
node_conversation_store -->|"kalıcı geçmiş"| node_conversations_db
node_api -->|"kullanıcı isteği"| node_graph
node_graph -->|"durumu yönetir"| node_graph_state
node_raw_excel -->|"eksik kaynak veri"| node_imputation
node_imputation -->|"iyileştirilmiş tablo verisi"| node_parsel_db
node_imputation -->|"retrieval öncesi kalite"| node_retrieval_setup
node_retrieval_setup -->|"indeksi hazırlar/kullanır"| node_chroma
node_graph -->|"yapısal ve agregasyon sorguları"| node_parsel_db
node_graph -->|"semantik istekler"| node_rag_agent
node_chroma -->|"alınan bağlam"| node_rag_agent
node_rag_agent -->|"taslak yanıt ve kanıt"| node_qa_eval
node_qa_eval -->|"doğrulanmış yanıt"| node_api
node_rag_agent -->|"yanıt sentezi"| node_ollama
node_vram -.->|"yerel GPU/VRAM"| node_ollama

click node_classic_prep "https://github.com/duembi/rag/blob/main/custom-rag/003.DataPreparation.py"
click node_classic_chroma_load "https://github.com/duembi/rag/blob/main/custom-rag/005.LoadChunksToChroma.py"
click node_classic_chatbot "https://github.com/duembi/rag/blob/main/custom-rag/008.RAGChatbot.py"
click node_api "https://github.com/duembi/rag/blob/main/rag_with_ai/src/api/main.py"
click node_conversation_store "https://github.com/duembi/rag/blob/main/rag_with_ai/src/api/conversation_store.py"
click node_graph "https://github.com/duembi/rag/blob/main/rag_with_ai/src/graph.py"
click node_graph_state "https://github.com/duembi/rag/blob/main/rag_with_ai/src/graph_state.py"
click node_imputation "https://github.com/duembi/rag/blob/main/rag_with_ai/src/agents/data_imputation_agent.py"
click node_retrieval_setup "https://github.com/duembi/rag/blob/main/rag_with_ai/src/agents/retrieval_setup_agent.py"
click node_rag_agent "https://github.com/duembi/rag/blob/main/rag_with_ai/src/agents/rag_pipeline_agent.py"
click node_qa_eval "https://github.com/duembi/rag/blob/main/rag_with_ai/src/agents/qa_eval_agent.py"
click node_vram "https://github.com/duembi/rag/blob/main/rag_with_ai/src/vram_manager.py"
click node_raw_excel "https://github.com/duembi/rag/blob/main/rag_with_ai/data/raw/2026-2__%C3%87eyrek__Nisan-May%C4%B1s-Haziran__Parsel_Tablosu%20(4).xlsx"
click node_parsel_db "https://github.com/duembi/rag/blob/main/rag_with_ai/data/parsel.sqlite"
click node_chroma "https://github.com/duembi/rag/blob/main/rag_with_ai/data/chroma_index/chroma.sqlite3"
click node_conversations_db "https://github.com/duembi/rag/blob/main/rag_with_ai/data/conversations.sqlite"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_classic_prep,node_classic_chroma_load,node_classic_chatbot toneBlue
class node_api,node_conversation_store,node_graph,node_graph_state,node_imputation,node_retrieval_setup,node_rag_agent,node_qa_eval,node_vram toneAmber
class node_raw_excel,node_parsel_db,node_chroma,node_conversations_db toneMint
class node_ollama toneNeutral
```

## Components

### Klasik RAG prototipi

Sıralı eğitim hattı.

- [Veri hazırlama](https://github.com/duembi/rag/blob/main/custom-rag/003.DataPreparation.py): Python aşaması · `custom-rag/003.DataPreparation.py`
- [Chunk ve Chroma yükleme](https://github.com/duembi/rag/blob/main/custom-rag/005.LoadChunksToChroma.py): Python aşaması · `custom-rag/005.LoadChunksToChroma.py`
- [RAG chatbot](https://github.com/duembi/rag/blob/main/custom-rag/008.RAGChatbot.py): Python aşaması · `custom-rag/008.RAGChatbot.py`

### Çok-ajanlı RAG

API üzerinden çalışan üretim hattı.

- [HTTP API ve statik UI](https://github.com/duembi/rag/blob/main/rag_with_ai/src/api/main.py): API giriş noktası · `rag_with_ai/src/api/main.py`
- [Konuşma deposu](https://github.com/duembi/rag/blob/main/rag_with_ai/src/api/conversation_store.py): oturum kalıcılığı · `rag_with_ai/src/api/conversation_store.py`
- [İstek orkestrasyon graphı](https://github.com/duembi/rag/blob/main/rag_with_ai/src/graph.py): ajan graphı · İsteği SQL veya semantik RAG yoluna yönlendirir. · `rag_with_ai/src/graph.py`
- [Graph state](https://github.com/duembi/rag/blob/main/rag_with_ai/src/graph_state.py): çalışma durumu · Ajanlar arası istek, kanıt ve yanıt verisini taşır. · `rag_with_ai/src/graph_state.py`
- [Veri imputation ajanı](https://github.com/duembi/rag/blob/main/rag_with_ai/src/agents/data_imputation_agent.py): veri kalitesi ajanı · Eksik veriyi retrieval öncesi ele alır. · `rag_with_ai/src/agents/data_imputation_agent.py`
- [Retrieval kurulum ajanı](https://github.com/duembi/rag/blob/main/rag_with_ai/src/agents/retrieval_setup_agent.py): indeks ajanı · `rag_with_ai/src/agents/retrieval_setup_agent.py`
- [RAG pipeline ajanı](https://github.com/duembi/rag/blob/main/rag_with_ai/src/agents/rag_pipeline_agent.py): yanıt ajanı · Sorgu ve alınan bağlamdan LLM yanıtı sentezler. · `rag_with_ai/src/agents/rag_pipeline_agent.py`
- [QA değerlendirme ajanı](https://github.com/duembi/rag/blob/main/rag_with_ai/src/agents/qa_eval_agent.py): kalite kapısı · Yanıtın bağlama sadakatini denetler. · `rag_with_ai/src/agents/qa_eval_agent.py`
- [VRAM yöneticisi](https://github.com/duembi/rag/blob/main/rag_with_ai/src/vram_manager.py): GPU kaynak yönetimi · `rag_with_ai/src/vram_manager.py`

### Yerel veri depoları

- [Ham parsel Excel](https://github.com/duembi/rag/blob/main/rag_with_ai/data/raw/2026-2__%C3%87eyrek__Nisan-May%C4%B1s-Haziran__Parsel_Tablosu%20(4).xlsx): kaynak veri · `rag_with_ai/data/raw/2026-2__Çeyrek__Nisan-Mayıs-Haziran__Parsel_Tablosu (4).xlsx`
- [Parsel SQLite](https://github.com/duembi/rag/blob/main/rag_with_ai/data/parsel.sqlite): yapılandırılmış veri · Sayım, toplama ve çoklu filtre sorgularının kaynak sınırı. · `rag_with_ai/data/parsel.sqlite`
- [Kalıcı Chroma indeksi](https://github.com/duembi/rag/blob/main/rag_with_ai/data/chroma_index/chroma.sqlite3): vektör indeks · `rag_with_ai/data/chroma_index/chroma.sqlite3`
- [Konuşmalar SQLite](https://github.com/duembi/rag/blob/main/rag_with_ai/data/conversations.sqlite): oturum verisi · `rag_with_ai/data/conversations.sqlite`

### Other components

- **Yerel Ollama**: LLM hizmeti · Üretim yolunda Qwen2.5-7B kullanılır.

## Connections

- Veri hazırlama → Chunk ve Chroma yükleme: hazırlanmış veri
- Chunk ve Chroma yükleme → RAG chatbot: embedding ve retrieval
- HTTP API ve statik UI → Konuşma deposu: oturum işlemleri
- Konuşma deposu → Konuşmalar SQLite: kalıcı geçmiş
- HTTP API ve statik UI → İstek orkestrasyon graphı: kullanıcı isteği
- İstek orkestrasyon graphı → Graph state: durumu yönetir
- Ham parsel Excel → Veri imputation ajanı: eksik kaynak veri
- Veri imputation ajanı → Parsel SQLite: iyileştirilmiş tablo verisi
- Veri imputation ajanı → Retrieval kurulum ajanı: retrieval öncesi kalite
- Retrieval kurulum ajanı → Kalıcı Chroma indeksi: indeksi hazırlar/kullanır
- İstek orkestrasyon graphı → Parsel SQLite: yapısal ve agregasyon sorguları
- İstek orkestrasyon graphı → RAG pipeline ajanı: semantik istekler
- Kalıcı Chroma indeksi → RAG pipeline ajanı: alınan bağlam
- RAG pipeline ajanı → QA değerlendirme ajanı: taslak yanıt ve kanıt
- QA değerlendirme ajanı → HTTP API ve statik UI: doğrulanmış yanıt
- RAG pipeline ajanı → Yerel Ollama: yanıt sentezi
- VRAM yöneticisi → Yerel Ollama: yerel GPU/VRAM