# varunnaikr/genai-rag-predictive-semantic-caching architecture

> Architecture diagram of the GitHub repository varunnaikr/genai-rag-predictive-semantic-caching, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/varunnaikr/genai-rag-predictive-semantic-caching
- Repository: https://github.com/varunnaikr/genai-rag-predictive-semantic-caching

## Overview

This repository is a Python research simulation for predictive semantic caching in mobile edge-assisted RAG networks, not an end-to-end retrieval or language-model service. A researcher runs the experiment; the simulation models mobility and semantic demand, applies one of five cache policies, realizes requests and computes performance metrics, then supports comparative evaluation. The README documents the major strategies and evaluation capabilities. The sampled implementation is concentrated in one source file; links for unsampled internals are omitted where their wiring cannot be confirmed.

Main entry points: [`src/semantic_cache_experiment.py`](https://github.com/varunnaikr/genai-rag-predictive-semantic-caching/blob/main/src/semantic_cache_experiment.py) (Simulation loop)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_environment["Network Environment"]
  node_environment["Simulation environment"]
  node_mobility["User mobility"]
  node_wireless["Wireless links"]
end

subgraph group_demand["Semantic Demand"]
  node_semantic_model["Semantic embeddings"]
  node_forecast_oracle["Demand forecasts"]
  node_requests["Request sampling"]
end

subgraph group_control["Cache Control"]
  node_rmp["RMP-SC policy"]
  node_tsk["TSK-SC policy"]
  node_ldp["LDP-SC policy"]
  node_pop["POP policy"]
  node_lru["LRU policy"]
  node_association["Edge association"]
  node_cache_state["Edge cache state"]
end

subgraph group_evaluation["Evaluation"]
  node_experiment["Experiment entry"]
  node_evaluation_suite["Evaluation suite"]
  node_simulation_loop["Simulation loop"]
  node_service_metrics["Service metrics"]
  node_utility["System utility"]
  node_comparison["Strategy comparison"]
  node_visualization["Evaluation plots"]
end

node_researcher(("Researcher"))

node_researcher -->|"runs"| node_experiment
node_experiment -->|"dispatches"| node_evaluation_suite
node_evaluation_suite -->|"runs trials"| node_simulation_loop
node_simulation_loop -->|"initializes"| node_environment
node_environment -->|"models"| node_mobility
node_environment -->|"computes links"| node_wireless
node_environment -->|"initializes"| node_semantic_model
node_semantic_model -->|"provides embeddings"| node_forecast_oracle
node_simulation_loop -->|"steps policy"| node_rmp
node_simulation_loop -->|"steps policy"| node_tsk
node_simulation_loop -->|"steps policy"| node_ldp
node_simulation_loop -->|"steps policy"| node_pop
node_simulation_loop -->|"steps policy"| node_lru
node_rmp -->|"requests forecasts"| node_forecast_oracle
node_tsk -->|"requests forecasts"| node_forecast_oracle
node_ldp -->|"requests forecasts"| node_forecast_oracle
node_pop -->|"requests forecasts"| node_forecast_oracle
node_rmp -->|"chooses edges"| node_association
node_tsk -->|"chooses edges"| node_association
node_ldp -->|"chooses edges"| node_association
node_rmp -->|"updates cache"| node_cache_state
node_tsk -->|"updates cache"| node_cache_state
node_ldp -->|"updates cache"| node_cache_state
node_pop -->|"updates cache"| node_cache_state
node_lru -->|"updates cache"| node_cache_state
node_simulation_loop -->|"samples requests"| node_requests
node_semantic_model -->|"supplies demand"| node_requests
node_simulation_loop -->|"evaluates service"| node_service_metrics
node_cache_state -->|"serves lookups"| node_service_metrics
node_association -->|"routes users"| node_service_metrics
node_wireless -->|"supplies link metrics"| node_service_metrics
node_requests -->|"provides items"| node_service_metrics
node_service_metrics -->|"provides metrics"| node_utility
node_simulation_loop -->|"computes utility"| node_utility
node_evaluation_suite -->|"compares strategies"| node_comparison
node_comparison -->|"plots results"| node_visualization

click node_experiment "https://github.com/varunnaikr/genai-rag-predictive-semantic-caching/blob/main/src/semantic_cache_experiment.py"
click node_evaluation_suite "https://github.com/varunnaikr/genai-rag-predictive-semantic-caching/blob/main/src/semantic_cache_experiment.py"
click node_simulation_loop "https://github.com/varunnaikr/genai-rag-predictive-semantic-caching/blob/main/src/semantic_cache_experiment.py"
click node_environment "https://github.com/varunnaikr/genai-rag-predictive-semantic-caching/blob/main/src/semantic_cache_experiment.py"
click node_mobility "https://github.com/varunnaikr/genai-rag-predictive-semantic-caching/blob/main/src/semantic_cache_experiment.py"
click node_wireless "https://github.com/varunnaikr/genai-rag-predictive-semantic-caching/blob/main/src/semantic_cache_experiment.py"
click node_semantic_model "https://github.com/varunnaikr/genai-rag-predictive-semantic-caching/blob/main/src/semantic_cache_experiment.py"
click node_forecast_oracle "https://github.com/varunnaikr/genai-rag-predictive-semantic-caching/blob/main/src/semantic_cache_experiment.py"
click node_rmp "https://github.com/varunnaikr/genai-rag-predictive-semantic-caching/blob/main/src/semantic_cache_experiment.py"
click node_tsk "https://github.com/varunnaikr/genai-rag-predictive-semantic-caching/blob/main/src/semantic_cache_experiment.py"
click node_ldp "https://github.com/varunnaikr/genai-rag-predictive-semantic-caching/blob/main/src/semantic_cache_experiment.py"
click node_pop "https://github.com/varunnaikr/genai-rag-predictive-semantic-caching/blob/main/src/semantic_cache_experiment.py"
click node_lru "https://github.com/varunnaikr/genai-rag-predictive-semantic-caching/blob/main/src/semantic_cache_experiment.py"
click node_association "https://github.com/varunnaikr/genai-rag-predictive-semantic-caching/blob/main/src/semantic_cache_experiment.py"
click node_cache_state "https://github.com/varunnaikr/genai-rag-predictive-semantic-caching/blob/main/src/semantic_cache_experiment.py"
click node_requests "https://github.com/varunnaikr/genai-rag-predictive-semantic-caching/blob/main/src/semantic_cache_experiment.py"
click node_service_metrics "https://github.com/varunnaikr/genai-rag-predictive-semantic-caching/blob/main/src/semantic_cache_experiment.py"
click node_utility "https://github.com/varunnaikr/genai-rag-predictive-semantic-caching/blob/main/src/semantic_cache_experiment.py"
click node_comparison "https://github.com/varunnaikr/genai-rag-predictive-semantic-caching/blob/main/src/semantic_cache_experiment.py"
click node_visualization "https://github.com/varunnaikr/genai-rag-predictive-semantic-caching/blob/main/src/semantic_cache_experiment.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_environment,node_mobility,node_wireless toneBlue
class node_semantic_model,node_forecast_oracle,node_requests toneAmber
class node_rmp,node_tsk,node_ldp,node_pop,node_lru,node_association,node_cache_state toneMint
class node_experiment,node_evaluation_suite,node_simulation_loop,node_service_metrics,node_utility,node_comparison,node_visualization toneRose
class node_researcher toneIndigo
```

## Components

### Network Environment

- [Simulation environment](https://github.com/varunnaikr/genai-rag-predictive-semantic-caching/blob/main/src/semantic_cache_experiment.py): `src/semantic_cache_experiment.py`
- [User mobility](https://github.com/varunnaikr/genai-rag-predictive-semantic-caching/blob/main/src/semantic_cache_experiment.py): `src/semantic_cache_experiment.py`
- [Wireless links](https://github.com/varunnaikr/genai-rag-predictive-semantic-caching/blob/main/src/semantic_cache_experiment.py): `src/semantic_cache_experiment.py`

### Semantic Demand

- [Semantic embeddings](https://github.com/varunnaikr/genai-rag-predictive-semantic-caching/blob/main/src/semantic_cache_experiment.py): `src/semantic_cache_experiment.py`
- [Demand forecasts](https://github.com/varunnaikr/genai-rag-predictive-semantic-caching/blob/main/src/semantic_cache_experiment.py): `src/semantic_cache_experiment.py`
- [Request sampling](https://github.com/varunnaikr/genai-rag-predictive-semantic-caching/blob/main/src/semantic_cache_experiment.py): `src/semantic_cache_experiment.py`

### Cache Control

- [RMP-SC policy](https://github.com/varunnaikr/genai-rag-predictive-semantic-caching/blob/main/src/semantic_cache_experiment.py): `src/semantic_cache_experiment.py`
- [TSK-SC policy](https://github.com/varunnaikr/genai-rag-predictive-semantic-caching/blob/main/src/semantic_cache_experiment.py): `src/semantic_cache_experiment.py`
- [LDP-SC policy](https://github.com/varunnaikr/genai-rag-predictive-semantic-caching/blob/main/src/semantic_cache_experiment.py): `src/semantic_cache_experiment.py`
- [POP policy](https://github.com/varunnaikr/genai-rag-predictive-semantic-caching/blob/main/src/semantic_cache_experiment.py): `src/semantic_cache_experiment.py`
- [LRU policy](https://github.com/varunnaikr/genai-rag-predictive-semantic-caching/blob/main/src/semantic_cache_experiment.py): `src/semantic_cache_experiment.py`
- [Edge association](https://github.com/varunnaikr/genai-rag-predictive-semantic-caching/blob/main/src/semantic_cache_experiment.py): `src/semantic_cache_experiment.py`
- [Edge cache state](https://github.com/varunnaikr/genai-rag-predictive-semantic-caching/blob/main/src/semantic_cache_experiment.py): `src/semantic_cache_experiment.py`

### Evaluation

- [Experiment entry](https://github.com/varunnaikr/genai-rag-predictive-semantic-caching/blob/main/src/semantic_cache_experiment.py): `src/semantic_cache_experiment.py`
- [Evaluation suite](https://github.com/varunnaikr/genai-rag-predictive-semantic-caching/blob/main/src/semantic_cache_experiment.py): `src/semantic_cache_experiment.py`
- [Simulation loop](https://github.com/varunnaikr/genai-rag-predictive-semantic-caching/blob/main/src/semantic_cache_experiment.py): `src/semantic_cache_experiment.py`
- [Service metrics](https://github.com/varunnaikr/genai-rag-predictive-semantic-caching/blob/main/src/semantic_cache_experiment.py): `src/semantic_cache_experiment.py`
- [System utility](https://github.com/varunnaikr/genai-rag-predictive-semantic-caching/blob/main/src/semantic_cache_experiment.py): `src/semantic_cache_experiment.py`
- [Strategy comparison](https://github.com/varunnaikr/genai-rag-predictive-semantic-caching/blob/main/src/semantic_cache_experiment.py): `src/semantic_cache_experiment.py`
- [Evaluation plots](https://github.com/varunnaikr/genai-rag-predictive-semantic-caching/blob/main/src/semantic_cache_experiment.py): `src/semantic_cache_experiment.py`

### Other components

- **Researcher**

## Connections

- Researcher → Experiment entry: runs
- Experiment entry → Evaluation suite: dispatches
- Evaluation suite → Simulation loop: runs trials
- Simulation loop → Simulation environment: initializes
- Simulation environment → User mobility: models
- Simulation environment → Wireless links: computes links
- Simulation environment → Semantic embeddings: initializes
- Semantic embeddings → Demand forecasts: provides embeddings
- Simulation loop → RMP-SC policy: steps policy
- Simulation loop → TSK-SC policy: steps policy
- Simulation loop → LDP-SC policy: steps policy
- Simulation loop → POP policy: steps policy
- Simulation loop → LRU policy: steps policy
- RMP-SC policy → Demand forecasts: requests forecasts
- TSK-SC policy → Demand forecasts: requests forecasts
- LDP-SC policy → Demand forecasts: requests forecasts
- POP policy → Demand forecasts: requests forecasts
- RMP-SC policy → Edge association: chooses edges
- TSK-SC policy → Edge association: chooses edges
- LDP-SC policy → Edge association: chooses edges
- RMP-SC policy → Edge cache state: updates cache
- TSK-SC policy → Edge cache state: updates cache
- LDP-SC policy → Edge cache state: updates cache
- POP policy → Edge cache state: updates cache
- LRU policy → Edge cache state: updates cache
- Simulation loop → Request sampling: samples requests
- Semantic embeddings → Request sampling: supplies demand
- Simulation loop → Service metrics: evaluates service
- Edge cache state → Service metrics: serves lookups
- Edge association → Service metrics: routes users
- Wireless links → Service metrics: supplies link metrics
- Request sampling → Service metrics: provides items
- Service metrics → System utility: provides metrics
- Simulation loop → System utility: computes utility
- Evaluation suite → Strategy comparison: compares strategies
- Strategy comparison → Evaluation plots: plots results