# riku-afk/ai-rag architecture

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

- Interactive diagram: https://gitdiagram.com/riku-afk/ai-rag
- Repository: https://github.com/riku-afk/ai-rag

## Overview

AiRAG is a local document assistant with two principal workflows: ingest documents into a Redis vector index, then search that index or answer questions from retrieved context. The generation path also checks a semantic answer cache and maintains expiring Redis conversation history. Edges reflect calls visible in the supplied source excerpts or capabilities explicitly documented in the README; Redis and Ollama are external services. app.py is an unused placeholder.

Main entry points: [`generate.py`](https://github.com/riku-afk/ai-rag/blob/master/generate.py) (RAG answer workflow), [`ingest.py`](https://github.com/riku-afk/ai-rag/blob/master/ingest.py) (Document vector index), [`query.py`](https://github.com/riku-afk/ai-rag/blob/master/query.py) (Retrieval test CLI), [`data`](https://github.com/riku-afk/ai-rag/tree/master/data) (Local documents)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingestion["Document ingestion"]
  node_ingest["Ingest and chunk<br/>[ingest.py]"]
  node_embed["Ollama embeddings<br/>[ingest.py]"]
end

subgraph group_retrieval["Retrieval and answers"]
  node_query["Retrieval test CLI<br/>[query.py]"]
  node_query_embed["Query embeddings<br/>[query.py]"]
  node_generator["RAG answer workflow<br/>[generate.py]"]
  node_context["Context and sources<br/>[generate.py]"]
  node_prompt["Grounded prompt<br/>[generate.py]"]
  node_cache_logic["Semantic cache<br/>[generate.py]"]
  node_history_logic["Session history<br/>[generate.py]"]
end

subgraph group_state["Redis state"]
  node_vector_index[("Document vector index<br/>[ingest.py]")]
  node_cache_index[("Answer cache index<br/>[generate.py]")]
  node_redis_history[("Redis session keys<br/>[generate.py]")]
end

node_user(("CLI user"))
node_documents["Local documents"]
node_ollama{{"Ollama service"}}
node_chat_model{{"Ollama chat model"}}
node_redis{{"Redis service"}}
node_app["Unused app placeholder<br/>[app.py]"]

node_user -->|"runs ingestion"| node_ingest
node_documents -->|"loads files"| node_ingest
node_ingest -->|"embeds chunks"| node_embed
node_embed -->|"requests embeddings"| node_ollama
node_ingest -->|"stores chunks"| node_vector_index
node_vector_index -->|"uses Redis"| node_redis
node_user -->|"asks question"| node_query
node_query -->|"creates embeddings"| node_query_embed
node_query_embed -->|"requests embeddings"| node_ollama
node_query -->|"searches chunks"| node_vector_index
node_vector_index -->|"uses Redis"| node_redis
node_user -->|"asks question"| node_generator
node_generator -->|"checks cache"| node_cache_logic
node_cache_logic -->|"searches and stores"| node_cache_index
node_cache_index -->|"uses Redis"| node_redis
node_generator -->|"retrieves chunks"| node_vector_index
node_vector_index -->|"uses Redis"| node_redis
node_generator -->|"formats retrieved chunks"| node_context
node_generator -->|"loads and saves turns"| node_history_logic
node_history_logic -->|"reads and writes"| node_redis_history
node_redis_history -->|"uses Redis"| node_redis
node_generator -->|"builds prompt"| node_prompt
node_context -->|"supplies context"| node_prompt
node_prompt -->|"generates answer"| node_chat_model
node_generator -->|"caches answer"| node_cache_logic

click node_documents "https://github.com/riku-afk/ai-rag/tree/master/data"
click node_ingest "https://github.com/riku-afk/ai-rag/blob/master/ingest.py"
click node_embed "https://github.com/riku-afk/ai-rag/blob/master/ingest.py"
click node_vector_index "https://github.com/riku-afk/ai-rag/blob/master/ingest.py"
click node_query "https://github.com/riku-afk/ai-rag/blob/master/query.py"
click node_query_embed "https://github.com/riku-afk/ai-rag/blob/master/query.py"
click node_generator "https://github.com/riku-afk/ai-rag/blob/master/generate.py"
click node_context "https://github.com/riku-afk/ai-rag/blob/master/generate.py"
click node_prompt "https://github.com/riku-afk/ai-rag/blob/master/generate.py"
click node_cache_logic "https://github.com/riku-afk/ai-rag/blob/master/generate.py"
click node_cache_index "https://github.com/riku-afk/ai-rag/blob/master/generate.py"
click node_history_logic "https://github.com/riku-afk/ai-rag/blob/master/generate.py"
click node_redis_history "https://github.com/riku-afk/ai-rag/blob/master/generate.py"
click node_app "https://github.com/riku-afk/ai-rag/blob/master/app.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_ingest,node_embed,node_user toneBlue
class node_query,node_query_embed,node_generator,node_context,node_prompt,node_cache_logic,node_history_logic,node_redis toneAmber
class node_vector_index,node_cache_index,node_redis_history toneMint
class node_documents,node_app toneTeal
class node_ollama,node_chat_model toneIndigo
```

## Components

### Document ingestion

- [Ingest and chunk](https://github.com/riku-afk/ai-rag/blob/master/ingest.py): `ingest.py`
- [Ollama embeddings](https://github.com/riku-afk/ai-rag/blob/master/ingest.py): `ingest.py`

### Retrieval and answers

- [Retrieval test CLI](https://github.com/riku-afk/ai-rag/blob/master/query.py): `query.py`
- [Query embeddings](https://github.com/riku-afk/ai-rag/blob/master/query.py): `query.py`
- [RAG answer workflow](https://github.com/riku-afk/ai-rag/blob/master/generate.py): `generate.py`
- [Context and sources](https://github.com/riku-afk/ai-rag/blob/master/generate.py): `generate.py`
- [Grounded prompt](https://github.com/riku-afk/ai-rag/blob/master/generate.py): `generate.py`
- [Semantic cache](https://github.com/riku-afk/ai-rag/blob/master/generate.py): `generate.py`
- [Session history](https://github.com/riku-afk/ai-rag/blob/master/generate.py): `generate.py`

### Redis state

- [Document vector index](https://github.com/riku-afk/ai-rag/blob/master/ingest.py): `ingest.py`
- [Answer cache index](https://github.com/riku-afk/ai-rag/blob/master/generate.py): `generate.py`
- [Redis session keys](https://github.com/riku-afk/ai-rag/blob/master/generate.py): `generate.py`

### Other components

- **CLI user**
- [Local documents](https://github.com/riku-afk/ai-rag/tree/master/data): `data`
- **Ollama service**
- **Ollama chat model**
- **Redis service**
- [Unused app placeholder](https://github.com/riku-afk/ai-rag/blob/master/app.py): `app.py`

## Connections

- CLI user → Ingest and chunk: runs ingestion (evidence: `README.md`)
- Local documents → Ingest and chunk: loads files (evidence: `ingest.py`)
- Ingest and chunk → Ollama embeddings: embeds chunks (evidence: `ingest.py`)
- Ollama embeddings → Ollama service: requests embeddings (evidence: `ingest.py`)
- Ingest and chunk → Document vector index: stores chunks (evidence: `ingest.py`)
- Document vector index → Redis service: uses Redis (evidence: `ingest.py`)
- CLI user → Retrieval test CLI: asks question (evidence: `README.md`)
- Retrieval test CLI → Query embeddings: creates embeddings (evidence: `query.py`)
- Query embeddings → Ollama service: requests embeddings (evidence: `query.py`)
- Retrieval test CLI → Document vector index: searches chunks (evidence: `query.py`)
- Document vector index → Redis service: uses Redis
- CLI user → RAG answer workflow: asks question (evidence: `README.md`)
- RAG answer workflow → Semantic cache: checks cache (evidence: `generate.py`)
- Semantic cache → Answer cache index: searches and stores (evidence: `generate.py`)
- Answer cache index → Redis service: uses Redis (evidence: `generate.py`)
- RAG answer workflow → Document vector index: retrieves chunks (evidence: `generate.py`)
- Document vector index → Redis service: uses Redis
- RAG answer workflow → Context and sources: formats retrieved chunks (evidence: `generate.py`)
- RAG answer workflow → Session history: loads and saves turns (evidence: `generate.py`)
- Session history → Redis session keys: reads and writes (evidence: `generate.py`)
- Redis session keys → Redis service: uses Redis (evidence: `generate.py`)
- RAG answer workflow → Grounded prompt: builds prompt (evidence: `generate.py`)
- Context and sources → Grounded prompt: supplies context (evidence: `generate.py`)
- Grounded prompt → Ollama chat model: generates answer (evidence: `generate.py`)
- RAG answer workflow → Semantic cache: caches answer (evidence: `generate.py`)