# duembi/silsilsilsils architecture

> Architecture diagram of the GitHub repository duembi/silsilsilsils, 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/silsilsilsils
- Repository: https://github.com/duembi/silsilsilsils

## Overview

#### Purpose and Entry Points
This repository implements an AI-assisted retrieval workflow over parcel-table Excel data, with data imputation, retrieval setup, RAG answering, QA evaluation, and a server-facing conversation layer. The primary application entry point is `rag_with_ai/src/api/main.py`; Windows server startup is provided by `rag_with_ai/scripts/run_server.ps1`. Workflow orchestration appears centered on `rag_with_ai/src/graph.py`.

#### Source Data and Persistence
The domain source is quarterly Turkish parcel-table workbooks, including an imputed variant: `rag_with_ai/2026-2__Çeyrek__Nisan-Mayıs-Haziran__Parsel_Tablosu (4).xlsx` and `rag_with_ai/2026-2__Çeyrek__Nisan-Mayıs-Haziran__Parsel_Tablosu_Imputed.xlsx`. Raw copies are maintained under `rag_with_ai/data/raw/`. Structured parcel data persists in `rag_with_ai/data/parsel.sqlite`; conversation history persists separately in `rag_with_ai/data/conversations.sqlite`.

#### Graph-Orchestrated Processing
`rag_with_ai/src/graph.py` and `rag_with_ai/src/graph_state.py` define the control-flow boundary between stages. Routing tests indicate that graph decisions select among processing paths rather than exposing every agent directly. The graph likely carries request, retrieval, and response state through specialized agents, isolating orchestration from API transport and individual AI/data operations.

#### Data Quality and Imputation
`rag_with_ai/src/agents/data_imputation_agent.py` owns completing or correcting missing source values before downstream use. Its output is represented by the imputed workbook and is validated independently. This forms an important boundary: retrieval and QA should consume the normalized/imputed dataset rather than mutating the raw Excel input.

#### Retrieval Index Construction
`rag_with_ai/src/agents/retrieval_setup_agent.py` prepares searchable retrieval assets from parcel data. The persisted Chroma store is under `rag_with_ai/data/chroma_index/`, with catalog metadata in `rag_with_ai/data/chroma_index/chroma.sqlite3` and multiple binary vector-index segments. This is a durable local retrieval boundary: indexing can be performed separately from request-time answering.

#### RAG Answering and Runtime Resource Control
`rag_with_ai/src/agents/rag_pipeline_agent.py` is the request-time retrieval-and-generation stage. It should obtain relevant indexed context, then produce an answer for the graph/API layer. `rag_with_ai/src/vram_manager.py` is architecturally material because it suggests local model or embedding inference with explicit GPU-memory lifecycle management; model-runtime resource handling is separated from RAG business flow.

#### API and Conversation Boundary
`rag_with_ai/src/api/main.py` exposes the application-facing interface, while `rag_with_ai/src/api/conversation_store.py` isolates durable chat/session persistence. `rag_with_ai/src/api/static/index.html` provides a bundled browser client, but the API remains the key integration boundary. Request flow is therefore: client/API → graph routing → retrieval/RAG or related agent → persisted conversation and response.

#### Evaluation and Operational Verification
`rag_with_ai/src/agents/qa_eval_agent.py` evaluates answer quality against curated expectations. Golden questions are stored in `rag_with_ai/tests/golden/qa_pairs.json`; evaluation execution is available through `rag_with_ai/scripts/run_golden_eval.py`. Spreadsheet correctness and end-to-end QA are additionally represented by `rag_with_ai/scripts/verify_against_excel.py` and reports in `rag_with_ai/docs/`, providing a separate validation boundary for source fidelity versus generated-answer quality.

Main entry points: [`rag_with_ai/src/api/main.py`](https://github.com/duembi/silsilsilsils/blob/main/rag_with_ai/src/api/main.py) (Application API), [`rag_with_ai/2026-2__Çeyrek__Nisan-Mayıs-Haziran__Parsel_Tablosu_Imputed.xlsx`](https://github.com/duembi/silsilsilsils/blob/main/rag_with_ai/2026-2__%C3%87eyrek__Nisan-May%C4%B1s-Haziran__Parsel_Tablosu_Imputed.xlsx) (Imputed parcel workbook), [`rag_with_ai/src/graph.py`](https://github.com/duembi/silsilsilsils/blob/main/rag_with_ai/src/graph.py) (Workflow graph), [`rag_with_ai/src/agents/rag_pipeline_agent.py`](https://github.com/duembi/silsilsilsils/blob/main/rag_with_ai/src/agents/rag_pipeline_agent.py) (RAG pipeline agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data & Index"]
  node_raw_workbooks["Raw parcel workbooks<br/>Excel source"]
  node_imputation["Data imputation agent<br/>data quality stage"]
  node_imputed_workbook["Imputed parcel workbook<br/>normalized Excel"]
  node_parcel_db[("Parcel database<br/>SQLite<br/>[parsel.sqlite]")]
  node_retrieval_setup["Retrieval setup agent<br/>index builder"]
  node_chroma_index[("Chroma retrieval index<br/>vector store")]
end

subgraph group_runtime["Application Runtime"]
  node_browser_client["Bundled browser client<br/>static UI<br/>[index.html]"]
  node_api["Application API<br/>server entry point<br/>[main.py]"]
  node_workflow_graph{{"Workflow graph<br/>orchestrator<br/>[graph.py]"}}
  node_graph_state["Graph state<br/>workflow contract<br/>[graph_state.py]"]
  node_rag_pipeline["RAG pipeline agent<br/>retrieval generation"]
  node_vram_manager["VRAM manager<br/>model resource control<br/>[vram_manager.py]"]
  node_conversation_store["Conversation store<br/>session persistence"]
  node_conversation_db[("Conversation database<br/>SQLite")]
  node_server_startup["Windows server startup<br/>PowerShell launcher<br/>[run_server.ps1]"]
end

subgraph group_validation["Evaluation &amp; Verification"]
  node_golden_pairs["Golden QA pairs<br/>evaluation fixture<br/>[qa_pairs.json]"]
  node_qa_eval["QA evaluation agent<br/>answer evaluator<br/>[qa_eval_agent.py]"]
  node_golden_eval["Golden evaluation runner<br/>evaluation command<br/>[run_golden_eval.py]"]
  node_excel_verification["Excel verification<br/>source fidelity check"]
end

node_raw_workbooks -->|"source data"| node_imputation
node_imputation -->|"writes"| node_imputed_workbook
node_imputed_workbook -->|"persists structured data"| node_parcel_db
node_imputed_workbook -->|"index input"| node_retrieval_setup
node_parcel_db -->|"structured source"| node_retrieval_setup
node_retrieval_setup -->|"builds"| node_chroma_index
node_browser_client -->|"requests"| node_api
node_server_startup -->|"launches"| node_api
node_api -->|"submits request"| node_workflow_graph
node_workflow_graph -->|"uses state"| node_graph_state
node_workflow_graph -->|"routes answering"| node_rag_pipeline
node_rag_pipeline -->|"retrieves context"| node_chroma_index
node_rag_pipeline -->|"uses inference resources"| node_vram_manager
node_workflow_graph -->|"returns response"| node_api
node_api -->|"stores sessions"| node_conversation_store
node_conversation_store -->|"persists"| node_conversation_db
node_golden_pairs -->|"evaluation inputs"| node_golden_eval
node_golden_eval -->|"runs"| node_qa_eval
node_qa_eval -.->|"evaluates answers"| node_rag_pipeline
node_imputed_workbook -->|"verifies fidelity"| node_excel_verification

click node_imputation "https://github.com/duembi/silsilsilsils/blob/main/rag_with_ai/src/agents/data_imputation_agent.py"
click node_imputed_workbook "https://github.com/duembi/silsilsilsils/blob/main/rag_with_ai/2026-2__%C3%87eyrek__Nisan-May%C4%B1s-Haziran__Parsel_Tablosu_Imputed.xlsx"
click node_parcel_db "https://github.com/duembi/silsilsilsils/blob/main/rag_with_ai/data/parsel.sqlite"
click node_retrieval_setup "https://github.com/duembi/silsilsilsils/blob/main/rag_with_ai/src/agents/retrieval_setup_agent.py"
click node_browser_client "https://github.com/duembi/silsilsilsils/blob/main/rag_with_ai/src/api/static/index.html"
click node_api "https://github.com/duembi/silsilsilsils/blob/main/rag_with_ai/src/api/main.py"
click node_workflow_graph "https://github.com/duembi/silsilsilsils/blob/main/rag_with_ai/src/graph.py"
click node_graph_state "https://github.com/duembi/silsilsilsils/blob/main/rag_with_ai/src/graph_state.py"
click node_rag_pipeline "https://github.com/duembi/silsilsilsils/blob/main/rag_with_ai/src/agents/rag_pipeline_agent.py"
click node_vram_manager "https://github.com/duembi/silsilsilsils/blob/main/rag_with_ai/src/vram_manager.py"
click node_conversation_store "https://github.com/duembi/silsilsilsils/blob/main/rag_with_ai/src/api/conversation_store.py"
click node_conversation_db "https://github.com/duembi/silsilsilsils/blob/main/rag_with_ai/data/conversations.sqlite"
click node_golden_pairs "https://github.com/duembi/silsilsilsils/blob/main/rag_with_ai/tests/golden/qa_pairs.json"
click node_qa_eval "https://github.com/duembi/silsilsilsils/blob/main/rag_with_ai/src/agents/qa_eval_agent.py"
click node_golden_eval "https://github.com/duembi/silsilsilsils/blob/main/rag_with_ai/scripts/run_golden_eval.py"
click node_excel_verification "https://github.com/duembi/silsilsilsils/blob/main/rag_with_ai/scripts/verify_against_excel.py"
click node_server_startup "https://github.com/duembi/silsilsilsils/blob/main/rag_with_ai/scripts/run_server.ps1"

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_raw_workbooks,node_imputation,node_imputed_workbook,node_parcel_db,node_retrieval_setup,node_chroma_index toneBlue
class node_browser_client,node_api,node_workflow_graph,node_graph_state,node_rag_pipeline,node_vram_manager,node_conversation_store,node_conversation_db,node_server_startup toneAmber
class node_golden_pairs,node_qa_eval,node_golden_eval,node_excel_verification toneMint
```

## Components

### Data & Index

- **Raw parcel workbooks**: Excel source · Quarterly Turkish parcel-table inputs.
- [Data imputation agent](https://github.com/duembi/silsilsilsils/blob/main/rag_with_ai/src/agents/data_imputation_agent.py): data quality stage · Completes or corrects missing source values. · `rag_with_ai/src/agents/data_imputation_agent.py`
- [Imputed parcel workbook](https://github.com/duembi/silsilsilsils/blob/main/rag_with_ai/2026-2__%C3%87eyrek__Nisan-May%C4%B1s-Haziran__Parsel_Tablosu_Imputed.xlsx): normalized Excel · Downstream retrieval input. · `rag_with_ai/2026-2__Çeyrek__Nisan-Mayıs-Haziran__Parsel_Tablosu_Imputed.xlsx`
- [Parcel database](https://github.com/duembi/silsilsilsils/blob/main/rag_with_ai/data/parsel.sqlite): SQLite · `rag_with_ai/data/parsel.sqlite`
- [Retrieval setup agent](https://github.com/duembi/silsilsilsils/blob/main/rag_with_ai/src/agents/retrieval_setup_agent.py): index builder · Builds searchable assets from parcel data. · `rag_with_ai/src/agents/retrieval_setup_agent.py`
- **Chroma retrieval index**: vector store · Durable local retrieval assets and metadata.

### Application Runtime

- [Bundled browser client](https://github.com/duembi/silsilsilsils/blob/main/rag_with_ai/src/api/static/index.html): static UI · `rag_with_ai/src/api/static/index.html`
- [Application API](https://github.com/duembi/silsilsilsils/blob/main/rag_with_ai/src/api/main.py): server entry point · Application-facing request and response boundary. · `rag_with_ai/src/api/main.py`
- [Workflow graph](https://github.com/duembi/silsilsilsils/blob/main/rag_with_ai/src/graph.py): orchestrator · Routes request state among processing paths. · `rag_with_ai/src/graph.py`
- [Graph state](https://github.com/duembi/silsilsilsils/blob/main/rag_with_ai/src/graph_state.py): workflow contract · Carries request, retrieval, and response state. · `rag_with_ai/src/graph_state.py`
- [RAG pipeline agent](https://github.com/duembi/silsilsilsils/blob/main/rag_with_ai/src/agents/rag_pipeline_agent.py): retrieval generation · Retrieves indexed context and generates answers. · `rag_with_ai/src/agents/rag_pipeline_agent.py`
- [VRAM manager](https://github.com/duembi/silsilsilsils/blob/main/rag_with_ai/src/vram_manager.py): model resource control · Manages local inference GPU-memory lifecycle. · `rag_with_ai/src/vram_manager.py`
- [Conversation store](https://github.com/duembi/silsilsilsils/blob/main/rag_with_ai/src/api/conversation_store.py): session persistence · `rag_with_ai/src/api/conversation_store.py`
- [Conversation database](https://github.com/duembi/silsilsilsils/blob/main/rag_with_ai/data/conversations.sqlite): SQLite · `rag_with_ai/data/conversations.sqlite`
- [Windows server startup](https://github.com/duembi/silsilsilsils/blob/main/rag_with_ai/scripts/run_server.ps1): PowerShell launcher · `rag_with_ai/scripts/run_server.ps1`

### Evaluation & Verification

- [Golden QA pairs](https://github.com/duembi/silsilsilsils/blob/main/rag_with_ai/tests/golden/qa_pairs.json): evaluation fixture · Curated expected questions and answers. · `rag_with_ai/tests/golden/qa_pairs.json`
- [QA evaluation agent](https://github.com/duembi/silsilsilsils/blob/main/rag_with_ai/src/agents/qa_eval_agent.py): answer evaluator · Evaluates generated-answer quality. · `rag_with_ai/src/agents/qa_eval_agent.py`
- [Golden evaluation runner](https://github.com/duembi/silsilsilsils/blob/main/rag_with_ai/scripts/run_golden_eval.py): evaluation command · `rag_with_ai/scripts/run_golden_eval.py`
- [Excel verification](https://github.com/duembi/silsilsilsils/blob/main/rag_with_ai/scripts/verify_against_excel.py): source fidelity check · Separately verifies spreadsheet correctness. · `rag_with_ai/scripts/verify_against_excel.py`

## Connections

- Raw parcel workbooks → Data imputation agent: source data
- Data imputation agent → Imputed parcel workbook: writes
- Imputed parcel workbook → Parcel database: persists structured data
- Imputed parcel workbook → Retrieval setup agent: index input
- Parcel database → Retrieval setup agent: structured source
- Retrieval setup agent → Chroma retrieval index: builds
- Bundled browser client → Application API: requests
- Windows server startup → Application API: launches
- Application API → Workflow graph: submits request
- Workflow graph → Graph state: uses state
- Workflow graph → RAG pipeline agent: routes answering
- RAG pipeline agent → Chroma retrieval index: retrieves context
- RAG pipeline agent → VRAM manager: uses inference resources
- Workflow graph → Application API: returns response
- Application API → Conversation store: stores sessions
- Conversation store → Conversation database: persists
- Golden QA pairs → Golden evaluation runner: evaluation inputs
- Golden evaluation runner → QA evaluation agent: runs
- QA evaluation agent → RAG pipeline agent: evaluates answers
- Imputed parcel workbook → Excel verification: verifies fidelity