Plateforme de Pilotage Radio & Digital Twin avec IA Agentique A unified platform for mobile operator radio network monitoring, KPI analytics, congestion forecasting, what-if simulation, and AI-assisted diagnosis.
- Project Purpose
- Architecture Overview
- Tech Stack
- Data Pipeline
- Implemented Features
- API Reference
- Running the Project
- What Is Not Yet Done
- Known Gaps & Improvements Needed
Radio engineering teams face fragmented data, slow diagnosis workflows, and no safe way to validate configuration changes before deployment. P2M addresses these challenges by providing:
- Unified visibility — consolidate 4G and 5G KPIs, alerts, and performance trends in one place.
- Operational insight — detect congestion, degradation, and anomalies across thousands of cells.
- Forecasting — predict traffic load, PRB utilization, and congestion risk on a 48-hour horizon.
- What-if simulation (Digital Twin) — test antenna tilt, reference signal power, and handover offset changes before any field intervention.
- AI-assisted diagnosis — an LLM-backed agent answers questions about specific cells, explains KPI deviations, and provides trend analysis with structured recommendations.
The platform is designed as a decision-support layer — all impactful actions (simulation runs, recommendations) go through human review, never automated production changes.
┌─────────────────────────────────────────────────────────────────┐
│ Frontend (React) │
│ Dashboard · TimeSeries · RushHour · Alerts · Cells · Sites │
│ Chatbot · Digital Twin · Forecast │
│ port 3000 │
└────────────────────────────┬────────────────────────────────────┘
│ HTTP / REST
┌────────────────────────────▼────────────────────────────────────┐
│ Backend API (Node.js / Express) │
│ DuckDB in-memory · Parquet files · Simulation engine │
│ port 5000 │
└──────────┬──────────────────────────────────┬───────────────────┘
│ proxy /api/cell-analysis │ require()
┌──────────▼──────────────┐ ┌───────────▼───────────────────┐
│ Analysis Agent │ │ Digital Twin Engine │
│ (Python / Flask) │ │ (simulation.js) │
│ Ollama LLM · Parquet │ │ 3GPP physics models │
│ port 5002 │ │ Tilt / RS Power / A3 HO │
└──────────────────────────┘ └───────────────────────────────┘
▲
┌──────────┴──────────────────────────────────────────────────────┐
│ Data Layer (Parquet) │
│ cell_daily_kpis · site_daily_kpis · technology_hourly_kpis │
│ technology_daily_kpis · technology_hourly_forecast │
│ site_hourly_forecast │
│ Data/aggregates/ │
└─────────────────────────────────────────────────────────────────┘
▲
┌──────────┴──────────────────────────────────────────────────────┐
│ DataPipeline (Python) │
│ Raw 4G CSV (~5.26 GB, 16 M rows) │
│ Raw 5G CSV (~700 MB, 1.8 M rows) │
│ profile → normalize → aggregate KPIs → forecast → validate │
└─────────────────────────────────────────────────────────────────┘
| Layer | Technology |
|---|---|
| Frontend | React 18, React Router v6, Recharts, Axios |
| Backend | Node.js, Express 4, DuckDB 1.2, CORS |
| Analysis Agent | Python 3, Flask, Pandas, PyArrow, Ollama |
| Digital Twin | Vanilla JS (simulation.js) — 3GPP physics coefficients |
| Data Storage | Apache Parquet (columnar, read by DuckDB) |
| Data Pipeline | Python — Pandas, NumPy, PyArrow, DuckDB |
| LLM Runtime | Ollama (local, default model: gemma3:4b) |
The pipeline in DataPipeline/ transforms raw operator CSV exports into analytics-ready Parquet files. It must be run once before starting the backend.
| Script | Purpose | Output |
|---|---|---|
profile_raw_datasets.py |
Statistical profiling of raw 4G/5G CSVs | Data/profiling/ |
normalize_4g_5g.py |
Clean, type-cast, unify schema, write Parquet | Data/processed/ |
build_kpi_aggregates.py |
Compute cell/site/technology daily & hourly KPIs | Data/aggregates/ |
build_forecasts.py |
Prophet-based 48-hour forecasts per technology & site | Data/aggregates/ |
validate_processed_data.py |
Schema, null-rate, and range checks across all outputs | Data/validation/ |
| Parameter | 4G/LTE | 5G/NR |
|---|---|---|
| File size | ~5.26 GB | ~700 MB |
| Records | ~16,063,681 | ~1,858,397 |
| Columns | 56 | 67 |
| Date range | 2026-03-21 → 2026-04-20 | 2026-03-21 → 2026-04-20 |
Each cell/site gets the following scores (0–100 scale):
- Composite Health Score — weighted combination of all sub-scores
- Congestion Score — PRB utilization + active user index
- User Experience Score — CQI, throughput, drop rate
- Efficiency Score — throughput per %PRB
- Reliability Score — drop rate, data quality
Boolean alert flags: high_congestion_flag, severe_congestion_flag, low_throughput_flag, high_drop_rate_flag, poor_quality_flag, low_data_quality_flag.
Global network snapshot for the latest available date.
- 6 KPI cards: total cells, average health score (color-coded), active alerts count, average throughput (Mbps), average PRB load (%), total traffic (PB).
- Health distribution bar — Good / Watch / Alert / Critical cell counts.
- Technology split — 4G vs 5G cell count comparison.
- 14-day trend chart — switchable between Throughput, Active Users, PRB Load, and Health Score, split by technology (4G / 5G).
Hourly intra-day 4G vs 5G comparison for any date in the dataset.
- Date selector across the full 30-day range.
- Metrics: Throughput (kbps), Active Users, PRB Load (%).
- Summary stats for the selected day: daily average and peak per technology.
30-day hourly aggregate view to identify systematic peak load patterns.
- Top-3 peak hours highlighted with time-of-day classification (Morning / Afternoon / Evening / Night).
- Combined 4G + 5G bar/line chart switchable by metric.
- Useful for capacity planning and shift scheduling.
Paginated alert table sourced from the latest daily KPI snapshot.
- Filters: severity (critical / high / medium / low), technology (4G / 5G), free-text cell search.
- Displays: cell name, site, technology, severity badge, triggered flag labels.
- Pagination: 100 rows per page with total count.
Per-cell deep-dive combining structured KPI data with LLM-generated diagnosis.
- Cell search and selection (all cells from latest snapshot).
- KPI panel: health score, congestion score, PRB load, throughput, CQI, drop rate, delay, traffic, active users.
- Alert badges for each triggered flag.
- AI Analysis — streaming LLM response from the Analysis Agent (port 5002 via backend proxy), covering:
- 7-day trend analysis (improving / degrading / stable) for each KPI.
- Root cause hypothesis with ranked indicators.
- Actionable recommendations with justification.
- Uncertainty acknowledgment when data is insufficient.
Paginated site-level inventory with aggregated KPIs.
- Filters: technology, health status (Good / Watch / Alert / Critical), free-text search.
- Per-site row: health score, congestion score, throughput, active users, PRB load, CQI, traffic, alert flags.
- Pagination: 50 sites per page.
48-hour forward-looking view per technology (4G / 5G) with risk classification.
- Metrics: PRB Utilization (%), Active Users, DL Throughput (Mbps), Total Traffic (GB), Congestion Score.
- Area/Line chart — historical window + forecast window with a reference line boundary.
- Risk cards — Critical / High / Medium / Low categorization of congestion risk per window.
- Site-level forecast: search any site and view its 48-hour forecast for all metrics.
- Forecast statistics: RMSE, MAPE, and coverage from the last pipeline run.
What-if simulation engine for antenna configuration changes. No MATLAB license required — implemented in JavaScript using 3GPP-derived and data-calibrated coefficients.
Configurable parameters:
| Parameter | Range | Physical Effect |
|---|---|---|
| Electrical Tilt (°) | 0 – 20° | Beam focus: −0.5 %PRB/° and −1.5 dBm RSRP at cell edge |
| RS Power Offset (dBm) | −6 – +6 dBm | RSRP boost: +0.35 CQI/dBm → ~1.25 Mbps/dBm |
| A3 Handover Offset (dB) | −6 – +6 dB | Load balancing: −0.15 users/dB, −1.2 %PRB/dB |
Output (before vs. after):
- Impact cards: ΔCongestion Score, ΔPRB Load, ΔThroughput (kbps), ΔCQI, ΔHealth Score.
- Radar chart: 5-axis before/after comparison (Health, Congestion, Throughput, Quality, Efficiency).
- Engineering constraints enforced: power budget ±3 dBm hard limit, tilt saturation at +15° baseline, A3 offload blocked if neighbour PRB ≥ 70%.
- Confidence levels: LOW confidence triggers a
human_approvalflag requiring review before any real-world action.
Conversational interface for natural-language network queries.
- Backed by the Python Analysis Agent (Ollama,
gemma3:4bdefault). - Pre-built suggestion chips: network health status, congestion ranking, worst 5G cells, throughput queries, alert explanations.
- Sends free-text questions; receives structured text responses.
- Falls back gracefully when the Python service is unavailable.
Standalone microservice powering both the chatbot and the cell analysis streaming endpoint.
- Loads
cell_daily_kpis.parquetonce at startup. - Computes trend direction (improving / degrading / stable) over the last 7 days for each KPI.
- Builds a structured prompt with actual cell data before calling Ollama — responses are grounded in real numbers, not hallucinated.
- Streams the response token-by-token to the frontend via Server-Sent Events.
- Detects Ollama GPU offload status at startup.
All endpoints served by the Node.js backend on http://localhost:5000.
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/kpis |
Global KPI summary for latest date |
| GET | /api/technology-summary |
4G vs 5G cell/KPI breakdown |
| GET | /api/daily-trend |
30-day daily trend per technology |
| GET | /api/rush-hour |
30-day hourly averages by hour-of-day |
| GET | /api/alerts |
Paginated flagged cells (filters: severity, technology, search) |
| GET | /api/cells |
Paginated cell list (filters: technology, health, congestion, search) |
| GET | /api/cells/:cell_name |
Single cell KPI detail |
| GET | /api/sites |
Paginated site list (filters: technology, health, search) |
| GET | /api/sites/:site_name |
Single site KPI detail |
| GET | /api/timeseries/dates |
Available dates for time series |
| GET | /api/timeseries/hourly?date= |
Hourly 4G/5G data for a given date |
| GET | /api/forecast/technology |
48-hour technology-level forecast |
| GET | /api/forecast/site/:site_name |
48-hour site-level forecast |
| GET | /api/forecast/stats |
Forecast accuracy metrics |
| POST | /api/simulate |
Digital Twin simulation run |
| POST | /api/chat |
Proxy to Python agent chat endpoint (port 5002) |
| POST | /api/cell-analysis |
Proxy streaming analysis to Python agent (port 5002) |
- Node.js ≥ 18
- Python ≥ 3.10
- Ollama installed and running locally
- Raw CSV files placed at
Dataset_new/Dataset/Output_ALL_4G_KPI.csvandOutput_ALL_5G_KPI.csv
pip install pandas numpy pyarrow duckdb
# Run all pipeline steps in order
python DataPipeline/profile_raw_datasets.py
python DataPipeline/normalize_4g_5g.py
python DataPipeline/build_kpi_aggregates.py
python DataPipeline/build_forecasts.py
python DataPipeline/validate_processed_data.pyOutputs will be written to Data/aggregates/ as Parquet files.
ollama pull gemma3:4bThe Analysis Agent is launched automatically by the backend — no separate terminal needed. Just install its Python dependencies once:
pip install flask flask-cors pandas pyarrow ollamaThis starts the Node.js API and spawns the Python Analysis Agent as a child process on port 5002.
cd Backend
npm install
npm start
# → http://localhost:5000 (Node.js API)
# → http://localhost:5002 (Analysis Agent, auto-started)Agent logs are prefixed with [Agent] in the same terminal output. If Python is not found or dependencies are missing, the backend still starts and cell analysis falls back to a local structured summary.
cd Frontend
npm install
npm start
# → http://localhost:3000The backend must be running before the frontend loads any data. Stopping the backend (
Ctrl+C) also terminates the Analysis Agent.
The following features are described in the project proposal but have not been implemented yet.
The proposal's first deliverable is an interactive map showing:
- Cell sectors rendered by azimuth angle.
- Heatmaps for congestion, PRB, throughput, and RSRP.
- Filters by band, technology, region, and vendor.
Status: No map component exists. The frontend has no Leaflet, Mapbox, or deck.gl integration. The performance counter CSVs also do not contain latitude, longitude, azimuth, antenna tilt, or transmit power — a separate site inventory/configuration file is required before any map rendering is possible.
The proposal calls for a document-grounded assistant that retrieves from an indexed knowledge base (procedures, standards, RCA reports) and cites sources in every response.
Status: The current chatbot sends free-text questions directly to a locally hosted LLM (Ollama). There is no document corpus, no vector store, no embedding pipeline, and no citation mechanism. The agent is a single-turn conversational interface, not a RAG pipeline.
The proposal defines a full agentic loop: Perceive → Plan → Act → Verify → Synthesize, with tool-calling, multi-step diagnosis plans, automatic KPI queries, alarm/ticket correlation, and structured final reports.
Status: The Analysis Agent does single-turn cell analysis via a structured prompt. There is no planner, no tool registry, no multi-step execution, no plan checklist, and no loop of verify/retry.
The proposal specifies Matlab as the simulation engine with a job queue, API wrapper, timeout management, and before/after result comparison.
Status: The simulation engine is a pure JavaScript implementation using 3GPP-derived linear coefficients. It produces directionally correct and engineering-constrained results but is not a real RF physics simulator. No Matlab integration or job-queue system exists.
The proposal includes correlation of performance alarms with trouble tickets and intervention logs for root cause enrichment.
Status: No alarm management system, no ticket database, and no correlation engine exist in the current codebase.
The proposal requires role-based access control (RBAC) per region and role, full audit logging of actions, and secrets managed server-side.
Status: The platform has no authentication layer. All API endpoints are open with no access control, no session management, and no audit log.
The proposal lists handover success rate and ping-pong handover rate as required KPIs.
Status: These columns are not present in the current dataset. Only capacity, quality, and partial availability KPIs are available.
The proposal describes the agent generating structured PDF or HTML reports that can be exported and shared.
Status: Implemented. After an AI analysis completes on the Cell Analysis page (/cells), a green "↓ Export HTML" button appears next to the Re-analyze button. Clicking it:
- Builds a fully self-contained HTML report with embedded CSS — no server call, no dependencies.
- Report sections: P2M brand header (cell name, site, tech badge, health score), Active Alert Flags, Score Breakdown (5 scores with color-coded progress bars), KPI Snapshot (31-day averages table), AI-Powered Diagnosis (full LLM output converted from markdown to clean HTML).
- Download filename:
P2M_Report_{cell_name}_{date}.html— opens in any browser, renders cleanly, and is also print-friendly (@media printstyles included). - No extra npm packages needed — uses
Blob,URL.createObjectURL, and a synthetic<a>click.
For simulation runs, final recommendations, and report exports the proposal requires an explicit approval step with a traceable action log.
Status: Implemented. When the Digital Twin simulation returns confidence: LOW (i.e. human_approval: true), the UI now:
- Blocks the result header with a "PENDING APPROVAL" badge instead of immediately accepting the recommendation.
- Shows a prominent yellow "Review & Approve" banner above the results.
- Opens a confirmation modal on click — displaying the cell name, parameter deltas, predicted health/PRB deltas, all engineering warnings, and an optional reviewer-notes field.
- On "Approve & Apply": commits the result, marks it "HUMAN APPROVED" (green badge), and writes an entry to the in-session Approval Action Log table below the page.
- On "Dismiss": discards the result and also writes a "DISMISSED" entry to the log.
- The Approval Action Log persists for the session with columns: Timestamp, Cell, Tech, Confidence, Tilt Δ, RS Pwr, A3, Health Δ, PRB Δ, Status, Note.
No backend changes were needed — the human_approval flag was already produced by DigitalTwin/simulation.js.
The proposal recommends enriching forecasts with a public holiday and local events calendar to improve prediction accuracy.
Status: Forecasts are built purely from time-series patterns with no external event context.
| Area | Current State | What Is Needed |
|---|---|---|
| Map rendering | No map | Site inventory CSV with lat/lng/azimuth + Leaflet or deck.gl integration |
| RAG pipeline | Direct LLM calls | Document ingestion, vector embeddings (e.g. ChromaDB), retrieval with citation |
| Agentic loop | Single-turn prompts | Tool registry, planner, multi-step execution, retry/fallback |
| LLM model | gemma3:4b (4-bit local) |
Larger or fine-tuned model for telecom domain; or cloud API fallback |
| Forecasting accuracy | Prophet baseline | Richer models (XGBoost, LSTM) with event-calendar features |
| Anomaly detection | Rule-based flags only | Statistical baseline (z-score, IQR) + lightweight ML (Isolation Forest) |
| Digital Twin physics | Linear 3GPP approximations | Full RF propagation model or validated MATLAB/Python RF library |
| Authentication | None | JWT-based auth, RBAC, per-region data filtering, audit log |
| Chatbot | Fixed — proxies to port 5002, /chat endpoint added to agent |
Working |
| 5G KPI coverage | Limited 5G-specific KPIs | 5G NR-specific metrics: SSB RSRP, beam index, NR PRB, gNB split |
| Report export | Implemented — self-contained HTML download from Cell Analysis page | PDF variant (via browser print or jsPDF) could be added |
| Scenario persistence | Simulation results are ephemeral | Save/load simulation scenarios with versioning |
| Real-time data ingestion | Static Parquet batch pipeline | Streaming ingest (Kafka or file watcher) to refresh dashboards |
| Test coverage | No tests | Unit tests for KPI formulas, pipeline scripts, and API endpoints |
| Containerization | Manual setup required | Docker Compose for backend + agent + Ollama in one command |