# mohithpeta/graph-based-rag architecture

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

- Interactive diagram: https://gitdiagram.com/mohithpeta/graph-based-rag
- Repository: https://github.com/mohithpeta/graph-based-rag

## Overview

AGRAG is a fashion recommendation system that turns image or text queries into recommendations. Its principal runtime flow is query embedding, Neo4j vector retrieval with optional category and gender constraints, then reranking and diversification. The README also documents a model-training and catalog-ingestion path that prepares the embeddings and knowledge graph. Evaluation scripts measure retrieval quality and diversity. Graph-neighbor expansion is a documented capability, but its implementation was not visible in the sampled source, so that relationship is identified as documented rather than inferred from code.

Main entry points: [`agrag/agent.py`](https://github.com/mohithpeta/graph-based-rag/blob/main/agrag/agent.py) (AGRAG agent), [`agrag/retriever.py`](https://github.com/mohithpeta/graph-based-rag/blob/main/agrag/retriever.py) (Vector retriever), [`build_embeddings.py`](https://github.com/mohithpeta/graph-based-rag/blob/main/build_embeddings.py) (Embedding builder), [`evaluate_retrieval.py`](https://github.com/mohithpeta/graph-based-rag/blob/main/evaluate_retrieval.py) (Retrieval evaluation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_catalog["Catalog preparation"]
  node_fashion_data["FashionGen data"]
  node_embedding_build["Embedding builder"]
  node_embedding_files["Vectors and metadata"]
  node_neo4j_loader["Knowledge graph loader<br/>[load_to_neo4j.py]"]
  node_neo4j[("Neo4j catalog")]
end

subgraph group_retrieval["Recommendation runtime"]
  node_query_embedder["Query embedder<br/>[embedder.py]"]
  node_agent["AGRAG agent<br/>[agent.py]"]
  node_retriever["Vector retriever<br/>[retriever.py]"]
  node_graph_expansion["Graph expansion"]
  node_reranking["Hybrid reranking<br/>[agent.py]"]
  node_mmr["MMR diversification<br/>[mmr.py]"]
  node_recommendations["Recommendations"]
  node_cli["Search interface<br/>[run_agrag.py]"]
end

subgraph group_learning["Model training"]
  node_clip_training["CLIP training<br/>[trainer.py]"]
  node_clip_model["Fine-tuned CLIP"]
end

subgraph group_evaluation["Evaluation"]
  node_eval_runner["Retrieval evaluation"]
  node_eval_metrics["Ranking metrics<br/>[metrics.py]"]
end

node_query_actor(("User query"))

node_clip_training -->|"saves model"| node_clip_model
node_clip_model -->|"loads model"| node_embedding_build
node_fashion_data -->|"embeds catalog"| node_embedding_build
node_embedding_build -->|"writes vectors"| node_embedding_files
node_embedding_files -->|"loads data"| node_neo4j_loader
node_neo4j_loader -->|"writes items"| node_neo4j
node_query_actor -->|"enters query"| node_cli
node_cli -->|"calls search"| node_agent
node_agent -->|"embeds query"| node_query_embedder
node_query_embedder -->|"loads model"| node_clip_model
node_agent -->|"retrieves items"| node_retriever
node_retriever -->|"queries vectors"| node_neo4j
node_agent -->|"dispatches rerank"| node_reranking
node_reranking -->|"diversifies"| node_mmr
node_agent -->|"uses traversal"| node_graph_expansion
node_mmr -->|"selects results"| node_recommendations
node_retriever -->|"returns items"| node_recommendations
node_eval_runner -->|"evaluates search"| node_agent
node_eval_runner -->|"computes ranking"| node_eval_metrics

click node_clip_training "https://github.com/mohithpeta/graph-based-rag/blob/main/src/training/trainer.py"
click node_embedding_build "https://github.com/mohithpeta/graph-based-rag/blob/main/build_embeddings.py"
click node_embedding_files "https://github.com/mohithpeta/graph-based-rag/blob/main/build_embeddings.py"
click node_neo4j_loader "https://github.com/mohithpeta/graph-based-rag/blob/main/kg/load_to_neo4j.py"
click node_query_embedder "https://github.com/mohithpeta/graph-based-rag/blob/main/agrag/embedder.py"
click node_agent "https://github.com/mohithpeta/graph-based-rag/blob/main/agrag/agent.py"
click node_retriever "https://github.com/mohithpeta/graph-based-rag/blob/main/agrag/retriever.py"
click node_graph_expansion "https://github.com/mohithpeta/graph-based-rag/tree/main/agrag"
click node_reranking "https://github.com/mohithpeta/graph-based-rag/blob/main/agrag/agent.py"
click node_mmr "https://github.com/mohithpeta/graph-based-rag/blob/main/agrag/mmr.py"
click node_cli "https://github.com/mohithpeta/graph-based-rag/blob/main/agrag/run_agrag.py"
click node_eval_runner "https://github.com/mohithpeta/graph-based-rag/blob/main/evaluate_retrieval.py"
click node_eval_metrics "https://github.com/mohithpeta/graph-based-rag/blob/main/agrag/eval/metrics.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_fashion_data,node_embedding_build,node_embedding_files,node_neo4j_loader,node_neo4j,node_query_actor toneBlue
class node_query_embedder,node_agent,node_retriever,node_graph_expansion,node_reranking,node_mmr,node_recommendations,node_cli toneAmber
class node_clip_training,node_clip_model toneMint
class node_eval_runner,node_eval_metrics toneRose
```

## Components

### Catalog preparation

- **FashionGen data**
- [Embedding builder](https://github.com/mohithpeta/graph-based-rag/blob/main/build_embeddings.py): `build_embeddings.py`
- [Vectors and metadata](https://github.com/mohithpeta/graph-based-rag/blob/main/build_embeddings.py): `build_embeddings.py`
- [Knowledge graph loader](https://github.com/mohithpeta/graph-based-rag/blob/main/kg/load_to_neo4j.py): `kg/load_to_neo4j.py`
- **Neo4j catalog**

### Recommendation runtime

- [Query embedder](https://github.com/mohithpeta/graph-based-rag/blob/main/agrag/embedder.py): `agrag/embedder.py`
- [AGRAG agent](https://github.com/mohithpeta/graph-based-rag/blob/main/agrag/agent.py): `agrag/agent.py`
- [Vector retriever](https://github.com/mohithpeta/graph-based-rag/blob/main/agrag/retriever.py): `agrag/retriever.py`
- [Graph expansion](https://github.com/mohithpeta/graph-based-rag/tree/main/agrag): `agrag`
- [Hybrid reranking](https://github.com/mohithpeta/graph-based-rag/blob/main/agrag/agent.py): `agrag/agent.py`
- [MMR diversification](https://github.com/mohithpeta/graph-based-rag/blob/main/agrag/mmr.py): `agrag/mmr.py`
- **Recommendations**
- [Search interface](https://github.com/mohithpeta/graph-based-rag/blob/main/agrag/run_agrag.py): `agrag/run_agrag.py`

### Model training

- [CLIP training](https://github.com/mohithpeta/graph-based-rag/blob/main/src/training/trainer.py): `src/training/trainer.py`
- **Fine-tuned CLIP**

### Evaluation

- [Retrieval evaluation](https://github.com/mohithpeta/graph-based-rag/blob/main/evaluate_retrieval.py): `evaluate_retrieval.py`
- [Ranking metrics](https://github.com/mohithpeta/graph-based-rag/blob/main/agrag/eval/metrics.py): `agrag/eval/metrics.py`

### Other components

- **User query**

## Connections

- CLIP training → Fine-tuned CLIP: saves model (evidence: `src/training/trainer.py`)
- Fine-tuned CLIP → Embedding builder: loads model (evidence: `build_embeddings.py`)
- FashionGen data → Embedding builder: embeds catalog (evidence: `build_embeddings.py`)
- Embedding builder → Vectors and metadata: writes vectors (evidence: `build_embeddings.py`)
- Vectors and metadata → Knowledge graph loader: loads data (evidence: `kg/load_to_neo4j.py`)
- Knowledge graph loader → Neo4j catalog: writes items (evidence: `kg/load_to_neo4j.py`)
- User query → Search interface: enters query (evidence: `agrag/run_agrag.py`)
- Search interface → AGRAG agent: calls search (evidence: `agrag/run_agrag.py`)
- AGRAG agent → Query embedder: embeds query (evidence: `agrag/agent.py`)
- Query embedder → Fine-tuned CLIP: loads model (evidence: `agrag/embedder.py`)
- AGRAG agent → Vector retriever: retrieves items (evidence: `agrag/agent.py`)
- Vector retriever → Neo4j catalog: queries vectors (evidence: `agrag/retriever.py`)
- AGRAG agent → Hybrid reranking: dispatches rerank (evidence: `agrag/agent.py`)
- Hybrid reranking → MMR diversification: diversifies (evidence: `agrag/agent.py`)
- AGRAG agent → Graph expansion: uses traversal (evidence: `README.md`)
- MMR diversification → Recommendations: selects results
- Vector retriever → Recommendations: returns items
- Retrieval evaluation → AGRAG agent: evaluates search (evidence: `evaluate_retrieval.py`)
- Retrieval evaluation → Ranking metrics: computes ranking (evidence: `evaluate_retrieval.py`)
