# aru911-gethu/ragkitchen architecture

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

- Interactive diagram: https://gitdiagram.com/aru911-gethu/ragkitchen
- Repository: https://github.com/aru911-gethu/ragkitchen

## Overview

RAG Kitchen combines an interactive RAG strategy lab with a recipe assistant that runs a saved pipeline. Users can ingest PDF or web sources, compare chunking and retrieval strategies, transform queries, apply graph-based constraint filtering or deterministic graph traversal, and generate answers; evaluation measures retrieval safety and generation quality. The graph preserves these documented capabilities. Some implementation details are unsampled, so their connections are shown only where the README or source index supports them.

Main entry points: [`src/cognitive_kitchen/rag/pipeline.py`](https://github.com/aru911-gethu/ragkitchen/blob/main/src/cognitive_kitchen/rag/pipeline.py) (Pipeline configuration and execution), [`src/cognitive_kitchen/api.py`](https://github.com/aru911-gethu/ragkitchen/blob/main/src/cognitive_kitchen/api.py) (REST and SSE API), [`src/cognitive_kitchen/ui/pages/3_Kitchen.py`](https://github.com/aru911-gethu/ragkitchen/blob/main/src/cognitive_kitchen/ui/pages/3_Kitchen.py) (Recipe assistant), [`src/cognitive_kitchen/rag/graph/traverse.py`](https://github.com/aru911-gethu/ragkitchen/blob/main/src/cognitive_kitchen/rag/graph/traverse.py) (Graph traversal)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_product["User interfaces"]
  node_api["REST and SSE API<br/>[api.py]"]
  node_lab["RAG strategy lab<br/>[2_RAG_Lab.py]"]
  node_kitchen["Recipe assistant<br/>[3_Kitchen.py]"]
end

subgraph group_ingestion["Ingestion and corpus"]
  node_pdf["PDF ingestion<br/>[pdf_ingest.py]"]
  node_web["Web ingestion<br/>[web_ingest.py]"]
  node_jobs["Ingestion jobs<br/>[jobs.py]"]
  node_corpus["Corpus and loaders<br/>[corpus.py]"]
end

subgraph group_rag["RAG pipeline"]
  node_pipeline["Pipeline configuration and execution<br/>[pipeline.py]"]
  node_chunking["Chunking strategies"]
  node_retrieval["Retrieval strategies"]
  node_query["Query transformations"]
  node_generation["Answer generation<br/>[generation.py]"]
  node_registry["Plugin registry<br/>[registry.py]"]
end

subgraph group_knowledge["Knowledge graph"]
  node_graphretrieval["Graph constraint filtering<br/>[constraints.py]"]
  node_traversal["Graph traversal<br/>[traverse.py]"]
  node_graphdb[("Neo4j<br/>[client.py]")]
  node_vocab["Ingredient vocabulary<br/>[ingredients.py]"]
end

subgraph group_evaluation["Evaluation and observability"]
  node_evaluation["RAG evaluation"]
  node_golden["Golden dataset<br/>[golden.py]"]
  node_telemetry["Run telemetry<br/>[telemetry.py]"]
end

node_user(("User"))

node_user -->|"sends requests"| node_api
node_user -->|"configures strategies"| node_lab
node_user -->|"asks recipes"| node_kitchen
node_api -->|"invokes ingestion"| node_pdf
node_api -->|"invokes ingestion"| node_web
node_api -->|"tracks jobs"| node_jobs
node_pdf -->|"reports progress"| node_jobs
node_web -->|"reports progress"| node_jobs
node_lab -->|"builds and saves"| node_pipeline
node_kitchen -->|"loads and runs"| node_pipeline
node_pipeline -->|"loads corpus"| node_corpus
node_pipeline -->|"builds chunker"| node_chunking
node_pipeline -->|"builds retriever"| node_retrieval
node_pipeline -->|"builds transform"| node_query
node_pipeline -->|"builds generator"| node_generation
node_pipeline -->|"builds plugins"| node_registry
node_retrieval -->|"filters constraints"| node_graphretrieval
node_graphretrieval -->|"checks graph"| node_traversal
node_traversal -->|"queries"| node_graphdb
node_traversal -->|"canonicalizes ingredients"| node_vocab
node_evaluation -->|"scores against"| node_golden
node_evaluation -->|"records metrics"| node_telemetry
node_lab -->|"benchmarks stages"| node_evaluation
node_kitchen -->|"applies safety constraints"| node_graphretrieval
node_kitchen -->|"supports graph answers"| node_traversal

click node_api "https://github.com/aru911-gethu/ragkitchen/blob/main/src/cognitive_kitchen/api.py"
click node_lab "https://github.com/aru911-gethu/ragkitchen/blob/main/src/cognitive_kitchen/ui/pages/2_RAG_Lab.py"
click node_kitchen "https://github.com/aru911-gethu/ragkitchen/blob/main/src/cognitive_kitchen/ui/pages/3_Kitchen.py"
click node_pdf "https://github.com/aru911-gethu/ragkitchen/blob/main/src/cognitive_kitchen/ingest/pdf_ingest.py"
click node_web "https://github.com/aru911-gethu/ragkitchen/blob/main/src/cognitive_kitchen/ingest/web_ingest.py"
click node_jobs "https://github.com/aru911-gethu/ragkitchen/blob/main/src/cognitive_kitchen/jobs.py"
click node_corpus "https://github.com/aru911-gethu/ragkitchen/blob/main/src/cognitive_kitchen/rag/corpus.py"
click node_pipeline "https://github.com/aru911-gethu/ragkitchen/blob/main/src/cognitive_kitchen/rag/pipeline.py"
click node_chunking "https://github.com/aru911-gethu/ragkitchen/tree/main/src/cognitive_kitchen/rag/chunking"
click node_retrieval "https://github.com/aru911-gethu/ragkitchen/tree/main/src/cognitive_kitchen/rag/retrieval"
click node_query "https://github.com/aru911-gethu/ragkitchen/tree/main/src/cognitive_kitchen/rag/query"
click node_generation "https://github.com/aru911-gethu/ragkitchen/blob/main/src/cognitive_kitchen/rag/strategies/generation.py"
click node_registry "https://github.com/aru911-gethu/ragkitchen/blob/main/src/cognitive_kitchen/rag/registry.py"
click node_graphretrieval "https://github.com/aru911-gethu/ragkitchen/blob/main/src/cognitive_kitchen/rag/graph/constraints.py"
click node_traversal "https://github.com/aru911-gethu/ragkitchen/blob/main/src/cognitive_kitchen/rag/graph/traverse.py"
click node_graphdb "https://github.com/aru911-gethu/ragkitchen/blob/main/src/cognitive_kitchen/rag/graph/client.py"
click node_vocab "https://github.com/aru911-gethu/ragkitchen/blob/main/src/cognitive_kitchen/rag/vocab/ingredients.py"
click node_evaluation "https://github.com/aru911-gethu/ragkitchen/tree/main/src/cognitive_kitchen/rag/eval"
click node_golden "https://github.com/aru911-gethu/ragkitchen/blob/main/src/cognitive_kitchen/rag/eval/golden.py"
click node_telemetry "https://github.com/aru911-gethu/ragkitchen/blob/main/src/cognitive_kitchen/rag/telemetry.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_api,node_lab,node_kitchen,node_user toneBlue
class node_pdf,node_web,node_jobs,node_corpus toneAmber
class node_pipeline,node_chunking,node_retrieval,node_query,node_generation,node_registry toneMint
class node_graphretrieval,node_traversal,node_graphdb,node_vocab toneRose
class node_evaluation,node_golden,node_telemetry toneIndigo
```

## Components

### User interfaces

- [REST and SSE API](https://github.com/aru911-gethu/ragkitchen/blob/main/src/cognitive_kitchen/api.py): `src/cognitive_kitchen/api.py`
- [RAG strategy lab](https://github.com/aru911-gethu/ragkitchen/blob/main/src/cognitive_kitchen/ui/pages/2_RAG_Lab.py): `src/cognitive_kitchen/ui/pages/2_RAG_Lab.py`
- [Recipe assistant](https://github.com/aru911-gethu/ragkitchen/blob/main/src/cognitive_kitchen/ui/pages/3_Kitchen.py): `src/cognitive_kitchen/ui/pages/3_Kitchen.py`

### Ingestion and corpus

- [PDF ingestion](https://github.com/aru911-gethu/ragkitchen/blob/main/src/cognitive_kitchen/ingest/pdf_ingest.py): `src/cognitive_kitchen/ingest/pdf_ingest.py`
- [Web ingestion](https://github.com/aru911-gethu/ragkitchen/blob/main/src/cognitive_kitchen/ingest/web_ingest.py): `src/cognitive_kitchen/ingest/web_ingest.py`
- [Ingestion jobs](https://github.com/aru911-gethu/ragkitchen/blob/main/src/cognitive_kitchen/jobs.py): `src/cognitive_kitchen/jobs.py`
- [Corpus and loaders](https://github.com/aru911-gethu/ragkitchen/blob/main/src/cognitive_kitchen/rag/corpus.py): `src/cognitive_kitchen/rag/corpus.py`

### RAG pipeline

- [Pipeline configuration and execution](https://github.com/aru911-gethu/ragkitchen/blob/main/src/cognitive_kitchen/rag/pipeline.py): `src/cognitive_kitchen/rag/pipeline.py`
- [Chunking strategies](https://github.com/aru911-gethu/ragkitchen/tree/main/src/cognitive_kitchen/rag/chunking): `src/cognitive_kitchen/rag/chunking`
- [Retrieval strategies](https://github.com/aru911-gethu/ragkitchen/tree/main/src/cognitive_kitchen/rag/retrieval): `src/cognitive_kitchen/rag/retrieval`
- [Query transformations](https://github.com/aru911-gethu/ragkitchen/tree/main/src/cognitive_kitchen/rag/query): `src/cognitive_kitchen/rag/query`
- [Answer generation](https://github.com/aru911-gethu/ragkitchen/blob/main/src/cognitive_kitchen/rag/strategies/generation.py): `src/cognitive_kitchen/rag/strategies/generation.py`
- [Plugin registry](https://github.com/aru911-gethu/ragkitchen/blob/main/src/cognitive_kitchen/rag/registry.py): `src/cognitive_kitchen/rag/registry.py`

### Knowledge graph

- [Graph constraint filtering](https://github.com/aru911-gethu/ragkitchen/blob/main/src/cognitive_kitchen/rag/graph/constraints.py): `src/cognitive_kitchen/rag/graph/constraints.py`
- [Graph traversal](https://github.com/aru911-gethu/ragkitchen/blob/main/src/cognitive_kitchen/rag/graph/traverse.py): `src/cognitive_kitchen/rag/graph/traverse.py`
- [Neo4j](https://github.com/aru911-gethu/ragkitchen/blob/main/src/cognitive_kitchen/rag/graph/client.py): `src/cognitive_kitchen/rag/graph/client.py`
- [Ingredient vocabulary](https://github.com/aru911-gethu/ragkitchen/blob/main/src/cognitive_kitchen/rag/vocab/ingredients.py): `src/cognitive_kitchen/rag/vocab/ingredients.py`

### Evaluation and observability

- [RAG evaluation](https://github.com/aru911-gethu/ragkitchen/tree/main/src/cognitive_kitchen/rag/eval): `src/cognitive_kitchen/rag/eval`
- [Golden dataset](https://github.com/aru911-gethu/ragkitchen/blob/main/src/cognitive_kitchen/rag/eval/golden.py): `src/cognitive_kitchen/rag/eval/golden.py`
- [Run telemetry](https://github.com/aru911-gethu/ragkitchen/blob/main/src/cognitive_kitchen/rag/telemetry.py): `src/cognitive_kitchen/rag/telemetry.py`

### Other components

- **User**

## Connections

- User → REST and SSE API: sends requests (evidence: `README.md`)
- User → RAG strategy lab: configures strategies (evidence: `README.md`)
- User → Recipe assistant: asks recipes (evidence: `README.md`)
- REST and SSE API → PDF ingestion: invokes ingestion (evidence: `src/cognitive_kitchen/api.py`)
- REST and SSE API → Web ingestion: invokes ingestion (evidence: `src/cognitive_kitchen/api.py`)
- REST and SSE API → Ingestion jobs: tracks jobs (evidence: `src/cognitive_kitchen/api.py`)
- PDF ingestion → Ingestion jobs: reports progress (evidence: `src/cognitive_kitchen/ingest/pdf_ingest.py`)
- Web ingestion → Ingestion jobs: reports progress (evidence: `src/cognitive_kitchen/ingest/web_ingest.py`)
- RAG strategy lab → Pipeline configuration and execution: builds and saves (evidence: `src/cognitive_kitchen/ui/pages/2_RAG_Lab.py`)
- Recipe assistant → Pipeline configuration and execution: loads and runs (evidence: `src/cognitive_kitchen/ui/pages/3_Kitchen.py`)
- Pipeline configuration and execution → Corpus and loaders: loads corpus (evidence: `src/cognitive_kitchen/rag/pipeline.py`)
- Pipeline configuration and execution → Chunking strategies: builds chunker (evidence: `src/cognitive_kitchen/rag/pipeline.py`)
- Pipeline configuration and execution → Retrieval strategies: builds retriever (evidence: `src/cognitive_kitchen/rag/pipeline.py`)
- Pipeline configuration and execution → Query transformations: builds transform (evidence: `README.md`)
- Pipeline configuration and execution → Answer generation: builds generator (evidence: `src/cognitive_kitchen/rag/pipeline.py`)
- Pipeline configuration and execution → Plugin registry: builds plugins (evidence: `src/cognitive_kitchen/rag/pipeline.py`)
- Retrieval strategies → Graph constraint filtering: filters constraints (evidence: `src/cognitive_kitchen/rag/retrieval/graph_hybrid.py`)
- Graph constraint filtering → Graph traversal: checks graph (evidence: `src/cognitive_kitchen/rag/retrieval/graph_hybrid.py`)
- Graph traversal → Neo4j: queries (evidence: `src/cognitive_kitchen/rag/graph/traverse.py`)
- Graph traversal → Ingredient vocabulary: canonicalizes ingredients (evidence: `src/cognitive_kitchen/rag/graph/traverse.py`)
- RAG evaluation → Golden dataset: scores against (evidence: `src/cognitive_kitchen/rag/eval/golden.py`)
- RAG evaluation → Run telemetry: records metrics (evidence: `src/cognitive_kitchen/rag/telemetry.py`)
- RAG strategy lab → RAG evaluation: benchmarks stages (evidence: `src/cognitive_kitchen/ui/pages/2_RAG_Lab.py`)
- Recipe assistant → Graph constraint filtering: applies safety constraints (evidence: `src/cognitive_kitchen/ui/pages/3_Kitchen.py`)
- Recipe assistant → Graph traversal: supports graph answers (evidence: `README.md`)
