# boliupro/rag2-mp architecture

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

## Overview

RAG²-MP predicts a user’s next grid location by combining retrieved historical mobility patterns, gravity-based spatial candidates, and LLM reasoning. The documented workflow runs from trajectory preprocessing and sample loading through prediction; separate preparation utilities build the retrieval index and fit gravity weights. The graph retains both standard and detailed evaluation entry points and shared spatial utilities. Relationships for unsampled implementation details are omitted; documented capability links use the README as evidence.

Main entry points: [`model/Predictor.py`](https://github.com/boliupro/rag2-mp/blob/main/model/Predictor.py) (Mobility predictor), [`model/LLM.py`](https://github.com/boliupro/rag2-mp/blob/main/model/LLM.py) (LLM decision), [`raw_data/mobility_process.py`](https://github.com/boliupro/rag2-mp/blob/main/raw_data/mobility_process.py) (Trajectory preprocessing), [`dataset/dataset.py`](https://github.com/boliupro/rag2-mp/blob/main/dataset/dataset.py) (Sample loading)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Mobility data"]
  node_preprocess["Trajectory preprocessing"]
  node_poi_preprocess["POI preprocessing<br/>[poi_process.py]"]
  node_samples["Sample loading<br/>[dataset.py]"]
end

subgraph group_knowledge["Knowledge preparation"]
  node_rag_builder["RAG index builder"]
  node_rag_store[("Retrieval index")]
  node_weight_fitter["Gravity weight fitting"]
  node_weight_files["City gravity weights"]
end

subgraph group_prediction["Prediction engine"]
  node_predictor["Mobility predictor<br/>[Predictor.py]"]
  node_rag["Mobility retrieval<br/>[RAG.py]"]
  node_gravity["Gravity candidates<br/>[Gravity.py]"]
  node_llm["LLM decision<br/>[LLM.py]"]
end

subgraph group_evaluation["Experiment workflows"]
  node_standard["Train and evaluate<br/>[trainer.py]"]
  node_detailed["Detailed analysis"]
  node_config["Experiment configuration<br/>[config.yaml]"]
end

subgraph group_shared["Shared spatial layer"]
  node_spatial_utils["Spatial utilities<br/>[utils.py]"]
end

node_data_provider(("Trajectory data"))
node_predicted_result["Next-location predictions"]

node_data_provider -->|"supplies traces"| node_preprocess
node_preprocess -->|"prepares trajectories"| node_samples
node_poi_preprocess -.->|"prepares POI data"| node_gravity
node_samples -->|"provides samples"| node_standard
node_samples -->|"provides samples"| node_detailed
node_preprocess -->|"provides history"| node_rag_builder
node_rag_builder -->|"generates embeddings"| node_llm
node_rag_builder -->|"writes index"| node_rag_store
node_weight_fitter -->|"fits weights"| node_weight_files
node_predictor -->|"initializes retrieval"| node_rag
node_predictor -->|"coordinates candidates"| node_gravity
node_predictor -->|"initializes decision"| node_llm
node_rag -->|"queries index"| node_rag_store
node_rag -->|"summarizes patterns"| node_llm
node_gravity -->|"uses distances"| node_spatial_utils
node_llm -->|"reasons next location"| node_predicted_result
node_standard -->|"runs prediction"| node_predictor
node_detailed -->|"runs prediction"| node_predictor
node_standard -->|"loads settings"| node_config
node_detailed -->|"loads settings"| node_config
node_spatial_utils -->|"supports formatting"| node_predictor

click node_preprocess "https://github.com/boliupro/rag2-mp/blob/main/raw_data/mobility_process.py"
click node_poi_preprocess "https://github.com/boliupro/rag2-mp/blob/main/raw_data/poi_process.py"
click node_samples "https://github.com/boliupro/rag2-mp/blob/main/dataset/dataset.py"
click node_rag_builder "https://github.com/boliupro/rag2-mp/blob/main/util/build_rag_database.py"
click node_rag_store "https://github.com/boliupro/rag2-mp/tree/main/util/rag_database"
click node_weight_fitter "https://github.com/boliupro/rag2-mp/blob/main/util/fit_gravity_weight.py"
click node_weight_files "https://github.com/boliupro/rag2-mp/tree/main/util/gravity_weight"
click node_predictor "https://github.com/boliupro/rag2-mp/blob/main/model/Predictor.py"
click node_rag "https://github.com/boliupro/rag2-mp/blob/main/model/RAG.py"
click node_gravity "https://github.com/boliupro/rag2-mp/blob/main/model/Gravity.py"
click node_llm "https://github.com/boliupro/rag2-mp/blob/main/model/LLM.py"
click node_standard "https://github.com/boliupro/rag2-mp/blob/main/trainer/trainer.py"
click node_detailed "https://github.com/boliupro/rag2-mp/blob/main/trainer/detailed_trainer.py"
click node_config "https://github.com/boliupro/rag2-mp/blob/main/config/config.yaml"
click node_spatial_utils "https://github.com/boliupro/rag2-mp/blob/main/util/utils.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_preprocess,node_poi_preprocess,node_samples toneBlue
class node_rag_builder,node_rag_store,node_weight_fitter,node_weight_files toneAmber
class node_predictor,node_rag,node_gravity,node_llm toneMint
class node_standard,node_detailed,node_config toneRose
class node_spatial_utils,node_data_provider,node_predicted_result toneIndigo
```

## Components

### Mobility data

- [Trajectory preprocessing](https://github.com/boliupro/rag2-mp/blob/main/raw_data/mobility_process.py): `raw_data/mobility_process.py`
- [POI preprocessing](https://github.com/boliupro/rag2-mp/blob/main/raw_data/poi_process.py): `raw_data/poi_process.py`
- [Sample loading](https://github.com/boliupro/rag2-mp/blob/main/dataset/dataset.py): `dataset/dataset.py`

### Knowledge preparation

- [RAG index builder](https://github.com/boliupro/rag2-mp/blob/main/util/build_rag_database.py): `util/build_rag_database.py`
- [Retrieval index](https://github.com/boliupro/rag2-mp/tree/main/util/rag_database): `util/rag_database`
- [Gravity weight fitting](https://github.com/boliupro/rag2-mp/blob/main/util/fit_gravity_weight.py): `util/fit_gravity_weight.py`
- [City gravity weights](https://github.com/boliupro/rag2-mp/tree/main/util/gravity_weight): `util/gravity_weight`

### Prediction engine

- [Mobility predictor](https://github.com/boliupro/rag2-mp/blob/main/model/Predictor.py): `model/Predictor.py`
- [Mobility retrieval](https://github.com/boliupro/rag2-mp/blob/main/model/RAG.py): `model/RAG.py`
- [Gravity candidates](https://github.com/boliupro/rag2-mp/blob/main/model/Gravity.py): `model/Gravity.py`
- [LLM decision](https://github.com/boliupro/rag2-mp/blob/main/model/LLM.py): `model/LLM.py`

### Experiment workflows

- [Train and evaluate](https://github.com/boliupro/rag2-mp/blob/main/trainer/trainer.py): `trainer/trainer.py`
- [Detailed analysis](https://github.com/boliupro/rag2-mp/blob/main/trainer/detailed_trainer.py): `trainer/detailed_trainer.py`
- [Experiment configuration](https://github.com/boliupro/rag2-mp/blob/main/config/config.yaml): `config/config.yaml`

### Shared spatial layer

- [Spatial utilities](https://github.com/boliupro/rag2-mp/blob/main/util/utils.py): `util/utils.py`

### Other components

- **Trajectory data**
- **Next-location predictions**

## Connections

- Trajectory data → Trajectory preprocessing: supplies traces (evidence: `README.md`)
- Trajectory preprocessing → Sample loading: prepares trajectories (evidence: `README.md`)
- POI preprocessing → Gravity candidates: prepares POI data
- Sample loading → Train and evaluate: provides samples (evidence: `README.md`)
- Sample loading → Detailed analysis: provides samples (evidence: `README.md`)
- Trajectory preprocessing → RAG index builder: provides history (evidence: `README.md`)
- RAG index builder → LLM decision: generates embeddings (evidence: `util/build_rag_database.py`)
- RAG index builder → Retrieval index: writes index (evidence: `util/build_rag_database.py`)
- Gravity weight fitting → City gravity weights: fits weights (evidence: `README.md`)
- Mobility predictor → Mobility retrieval: initializes retrieval (evidence: `model/Predictor.py`)
- Mobility predictor → Gravity candidates: coordinates candidates (evidence: `README.md`)
- Mobility predictor → LLM decision: initializes decision (evidence: `model/Predictor.py`)
- Mobility retrieval → Retrieval index: queries index (evidence: `README.md`)
- Mobility retrieval → LLM decision: summarizes patterns (evidence: `README.md`)
- Gravity candidates → Spatial utilities: uses distances (evidence: `model/Gravity.py`)
- LLM decision → Next-location predictions: reasons next location (evidence: `README.md`)
- Train and evaluate → Mobility predictor: runs prediction (evidence: `README.md`)
- Detailed analysis → Mobility predictor: runs prediction (evidence: `README.md`)
- Train and evaluate → Experiment configuration: loads settings (evidence: `README.md`)
- Detailed analysis → Experiment configuration: loads settings (evidence: `README.md`)
- Spatial utilities → Mobility predictor: supports formatting (evidence: `model/Predictor.py`)
