# aifabrice/jev-rag architecture

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

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

## Overview

Jev RAG is a local-first knowledge search engine: users index a document folder, select a retrieval pipeline, and receive ranked passages or a streamed answer with file citations. The runtime is primarily implemented in local_kb.py, with taxonomy.py providing taxonomy construction and routing. The README documents the seven pipeline capabilities and their broad stages; source excerpts are partial, so internal calls beyond the shown taxonomy reference are not asserted.

Main entry points: [`local_kb.py`](https://github.com/aifabrice/jev-rag/blob/main/local_kb.py) (Jev reranking), [`taxonomy.py`](https://github.com/aifabrice/jev-rag/blob/main/taxonomy.py) (Taxonomy routing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry points"]
  node_cli["CLI<br/>[local_kb.py]"]
  node_web["Web interface<br/>[local_kb.py]"]
end

subgraph group_index["Local knowledge"]
  node_documents["Document folder"]
  node_ingest["Document ingestion<br/>[local_kb.py]"]
  node_indexer["BM25 indexing<br/>[local_kb.py]"]
  node_sqlite[("SQLite FTS5<br/>[local_kb.py]")]
end

subgraph group_retrieval["Retrieval pipelines"]
  node_bm25["BM25 retrieval<br/>[local_kb.py]"]
  node_agentic["Agentic lexical<br/>[local_kb.py]"]
  node_hybrid["Embedding hybrid<br/>[local_kb.py]"]
  node_agentic_hybrid["Agentic hybrid<br/>[local_kb.py]"]
  node_taxonomy["Taxonomy routing<br/>[taxonomy.py]"]
  node_passage_gate["Passage Gate<br/>[local_kb.py]"]
  node_line_search["Line Search<br/>[local_kb.py]"]
end

subgraph group_answer["Ranking and answers"]
  node_jev["Jev reranking<br/>[local_kb.py]"]
  node_answer_model["Answer generation<br/>[local_kb.py]"]
  node_results["Ranked passages and cited answer"]
end

node_user(("User"))
node_providers["Configured model providers"]

node_user -->|"runs commands"| node_cli
node_user -->|"uses interface"| node_web
node_documents -->|"reads files"| node_ingest
node_ingest -->|"indexes content"| node_indexer
node_indexer -->|"stores passages"| node_sqlite
node_sqlite -->|"searches passages"| node_bm25
node_sqlite -->|"searches lexical terms"| node_agentic
node_sqlite -->|"provides BM25 candidates"| node_hybrid
node_sqlite -->|"provides BM25 candidates"| node_agentic_hybrid
node_hybrid -->|"routes candidates"| node_taxonomy
node_sqlite -->|"provides BM25 candidates"| node_passage_gate
node_hybrid -->|"provides hybrid candidates"| node_passage_gate
node_providers -->|"plans searches"| node_agentic
node_providers -->|"creates embeddings"| node_hybrid
node_providers -->|"plans and embeds"| node_agentic_hybrid
node_providers -->|"embeds corpus"| node_taxonomy
node_providers -->|"scores windows"| node_line_search
node_bm25 -->|"reranks candidates"| node_jev
node_agentic -->|"reranks candidates"| node_jev
node_hybrid -->|"reranks candidates"| node_jev
node_agentic_hybrid -->|"reranks candidates"| node_jev
node_taxonomy -->|"reranks candidates"| node_jev
node_passage_gate -->|"screens evidence"| node_answer_model
node_line_search -->|"selects passages"| node_answer_model
node_jev -->|"supplies ranked evidence"| node_answer_model
node_providers -->|"scores candidates"| node_jev
node_providers -->|"generates answer"| node_answer_model
node_answer_model -->|"streams cited answer"| node_results
node_jev -->|"returns ranked passages"| node_results

click node_cli "https://github.com/aifabrice/jev-rag/blob/main/local_kb.py"
click node_web "https://github.com/aifabrice/jev-rag/blob/main/local_kb.py"
click node_ingest "https://github.com/aifabrice/jev-rag/blob/main/local_kb.py"
click node_indexer "https://github.com/aifabrice/jev-rag/blob/main/local_kb.py"
click node_sqlite "https://github.com/aifabrice/jev-rag/blob/main/local_kb.py"
click node_bm25 "https://github.com/aifabrice/jev-rag/blob/main/local_kb.py"
click node_agentic "https://github.com/aifabrice/jev-rag/blob/main/local_kb.py"
click node_hybrid "https://github.com/aifabrice/jev-rag/blob/main/local_kb.py"
click node_agentic_hybrid "https://github.com/aifabrice/jev-rag/blob/main/local_kb.py"
click node_taxonomy "https://github.com/aifabrice/jev-rag/blob/main/taxonomy.py"
click node_passage_gate "https://github.com/aifabrice/jev-rag/blob/main/local_kb.py"
click node_line_search "https://github.com/aifabrice/jev-rag/blob/main/local_kb.py"
click node_jev "https://github.com/aifabrice/jev-rag/blob/main/local_kb.py"
click node_answer_model "https://github.com/aifabrice/jev-rag/blob/main/local_kb.py"

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_cli,node_web,node_user toneBlue
class node_documents,node_ingest,node_indexer,node_sqlite toneAmber
class node_bm25,node_agentic,node_hybrid,node_agentic_hybrid,node_taxonomy,node_passage_gate,node_line_search toneMint
class node_jev,node_answer_model,node_results toneRose
class node_providers toneIndigo
```

## Components

### User entry points

- [CLI](https://github.com/aifabrice/jev-rag/blob/main/local_kb.py): `local_kb.py`
- [Web interface](https://github.com/aifabrice/jev-rag/blob/main/local_kb.py): `local_kb.py`

### Local knowledge

- **Document folder**
- [Document ingestion](https://github.com/aifabrice/jev-rag/blob/main/local_kb.py): `local_kb.py`
- [BM25 indexing](https://github.com/aifabrice/jev-rag/blob/main/local_kb.py): `local_kb.py`
- [SQLite FTS5](https://github.com/aifabrice/jev-rag/blob/main/local_kb.py): `local_kb.py`

### Retrieval pipelines

- [BM25 retrieval](https://github.com/aifabrice/jev-rag/blob/main/local_kb.py): `local_kb.py`
- [Agentic lexical](https://github.com/aifabrice/jev-rag/blob/main/local_kb.py): `local_kb.py`
- [Embedding hybrid](https://github.com/aifabrice/jev-rag/blob/main/local_kb.py): `local_kb.py`
- [Agentic hybrid](https://github.com/aifabrice/jev-rag/blob/main/local_kb.py): `local_kb.py`
- [Taxonomy routing](https://github.com/aifabrice/jev-rag/blob/main/taxonomy.py): `taxonomy.py`
- [Passage Gate](https://github.com/aifabrice/jev-rag/blob/main/local_kb.py): `local_kb.py`
- [Line Search](https://github.com/aifabrice/jev-rag/blob/main/local_kb.py): `local_kb.py`

### Ranking and answers

- [Jev reranking](https://github.com/aifabrice/jev-rag/blob/main/local_kb.py): `local_kb.py`
- [Answer generation](https://github.com/aifabrice/jev-rag/blob/main/local_kb.py): `local_kb.py`
- **Ranked passages and cited answer**

### Other components

- **User**
- **Configured model providers**

## Connections

- User → CLI: runs commands (evidence: `README.md`)
- User → Web interface: uses interface (evidence: `README.md`)
- Document folder → Document ingestion: reads files (evidence: `README.md`)
- Document ingestion → BM25 indexing: indexes content (evidence: `README.md`)
- BM25 indexing → SQLite FTS5: stores passages (evidence: `README.md`)
- SQLite FTS5 → BM25 retrieval: searches passages (evidence: `README.md`)
- SQLite FTS5 → Agentic lexical: searches lexical terms (evidence: `README.md`)
- SQLite FTS5 → Embedding hybrid: provides BM25 candidates (evidence: `README.md`)
- SQLite FTS5 → Agentic hybrid: provides BM25 candidates (evidence: `README.md`)
- Embedding hybrid → Taxonomy routing: routes candidates (evidence: `README.md`)
- SQLite FTS5 → Passage Gate: provides BM25 candidates (evidence: `README.md`)
- Embedding hybrid → Passage Gate: provides hybrid candidates (evidence: `README.md`)
- Configured model providers → Agentic lexical: plans searches (evidence: `README.md`)
- Configured model providers → Embedding hybrid: creates embeddings (evidence: `README.md`)
- Configured model providers → Agentic hybrid: plans and embeds (evidence: `README.md`)
- Configured model providers → Taxonomy routing: embeds corpus (evidence: `README.md`)
- Configured model providers → Line Search: scores windows (evidence: `README.md`)
- BM25 retrieval → Jev reranking: reranks candidates (evidence: `README.md`)
- Agentic lexical → Jev reranking: reranks candidates (evidence: `README.md`)
- Embedding hybrid → Jev reranking: reranks candidates (evidence: `README.md`)
- Agentic hybrid → Jev reranking: reranks candidates (evidence: `README.md`)
- Taxonomy routing → Jev reranking: reranks candidates (evidence: `README.md`)
- Passage Gate → Answer generation: screens evidence (evidence: `README.md`)
- Line Search → Answer generation: selects passages (evidence: `README.md`)
- Jev reranking → Answer generation: supplies ranked evidence (evidence: `README.md`)
- Configured model providers → Jev reranking: scores candidates (evidence: `README.md`)
- Configured model providers → Answer generation: generates answer (evidence: `README.md`)
- Answer generation → Ranked passages and cited answer: streams cited answer (evidence: `README.md`)
- Jev reranking → Ranked passages and cited answer: returns ranked passages (evidence: `README.md`)
