An Open-Source, Carrier-Grade RAN Diagnosing and Root-Cause-Analysis (RAG) System
Copyright 2026 Rajveer Singh. Licensed under the Apache License, Version 2.0.
RAN Diagnostics RAG is an advanced, carrier-grade, real-time diagnostic system for Radio Access Networks (RAN). In cellular network infrastructures (such as urban macro 4G/5G cells), telecom engineers face high volumes of diverse metrics, alarms, and coverage overlap matrices. Manually identifying the root cause of performance anomalies is slow and error-prone.
This project implements the OSCR (Operational Signature Classification and Reasoning) framework to automate:
- Telemetry Ingestion & Anomaly Detection (Phase 1): Processes rolling timeseries network metrics, computing normalized statistics, trend slopes, oscillation intensity, and saturation proximity.
- Temporal Trend Analysis & Primitives (Phase 2): Tracks cell state transitions, evaluates persistence levels, and fires alert triggers.
- Causal Progression Matching & Exclusions (Phase 3): Automatically evaluates anomaly signatures against a strict catalog and eliminates incorrect hypotheses using a Class-A/Class-B exclusion rules engine.
- Context-Grounded Retrieval & Optimization (Phase 4): Uses a FAISS-based vector index of 3GPP and TeleQnA telecom specification standards to retrieve domain-grounded context, passing it to an LLM to generate precise, hallucination-free action plans.
- Dynamic 3D Control Center (Web UI): Renders real-time telemetry, network topologies, causal transition timelines, and provides developer consoles for fault injection in a futuristic glassmorphic Three.js dashboard.
The codebase leverages a decoupled, high-performance microservices architecture that communicates asynchronously via ZeroMQ (zmq) message buses:
[ C++ Network Simulator ]
│ (ZMQ: 5555)
▼
[ telemetry_simulator.py ]
│ (ZMQ: 5555)
▼
[ anomaly_detector.py ]
│ (ZMQ: 5556)
▼
[ pipeline_orchestrator.py ] <──> [ temporal_engine.py ]
│ (ZMQ: 5560) [ causal_progression.py ]
▼
[ rca_engine.py ]
│ (ZMQ: 5557)
▼
[ rag_pipeline.py ] <──> [ knowledge_base.py ] (FAISS)
│ (ZMQ: 5558)
▼
[ llm_engine.py ] <──> [ optimization_engine.py ]
│ (ZMQ: 5559)
▼
[ web_server.py ]
│ (WebSockets: 8765)
▼
[ 3D HTML5 Dashboard ] (HTTP: 8000)
- Telemetry Bus (5555): Simulates macroscopic cell telemetry under baseline noise or injected faults (congestions, hardware degradations, interference, scheduler collapses).
- Anomaly Bus (5556): Standardizes rolling statistical evaluations to determine if a performance KPI is spiking, dropping, or oscillating.
- Orchestration Bus (5560): Orchestrates the OSCR pipeline, feeding the temporal state tracker, establishing transition state audits, and building structured signature evidence packages.
- RCA Bus (5557): Aggregates state-occupancy and causal-progression reports to converge on a single, high-confidence Root Cause.
- RAG Grounding Bus (5558): Vector embeds queries using Sentence-Transformers, querying a FAISS vector index built on the TeleQnA corpus.
- LLM generation Bus (5559): Passes grounded context to a generation engine with real-time runtime guardrails to prevent AI hallucinations, outputting concrete step-by-step mitigation recommenders.
- WebSocket Bridge (8765): Bridges ZMQ payload channels to JSON socket structures for client-side rendering.
- OSCR-driven Causal Reasoning Engine: Employs formal state-logic matrices rather than fragile heuristics to identify Root Causes.
- Vector Grounded RAG Pipeline: FAISS-backed retrieval system grounded directly in standard 3GPP operating procedures.
- Robust State Auditing Ledger: Log-based ledger records state history, cryptographically verifying each state transition's legitimacy.
- Interactive 3D Three.js Interface: Renders interactive network topologies, sector coordinates, connection nodes, and dynamic status bars.
- Interactive LLM RAN Assistant: Full chat panel allowing telecom operators to consult the RAG-backed LLM in real-time.
- Deterministic Simulation Controls: Developer console allowing dynamic fault-injection and normal resets to test the system's end-to-end resilience.
The integrated interactive AI RAN Assistant querying the local knowledge base directly from standard 3GPP operating procedures to assist with diagnostic verification. Also supports openai APIs to use natural language for queries.
The codebase is organized into a clean, modern, and professional structure to facilitate maintenance and scaling:
.
├── AUTHORS # Attribution credits
├── CITATION.cff # Research citation metadata
├── CONTRIBUTING.md # Guidelines for open-source contributions
├── DEVELOPMENT.md # Developer workflow and debugging guides
├── INSTALLATION.md # Environment setup and dependencies guide
├── LICENSE # Apache 2.0 License file
├── PROJECT_STRUCTURE.md # Visual map and architecture guidelines
├── README.md # Master documentation (this file)
│
├── launcher.py # Root wrapper script to start all services
├── evaluate.py # RCA performance evaluator
├── evaluate_teleqna.py # TeleQnA retrieval benchmark validator
├── test_all.py # Wrapper to start background test dependencies
├── test_chat.py # ZMQ interactive chat test script
├── test_pipeline.py # End-to-end integration test runner
│
├── frontend/ # Static Web UI code
│ ├── index.html # UI layout and dependencies
│ ├── style.css # Cyberpunk glassmorphic layout styles
│ └── app.js # Three.js 3D renderer and web socket controller
│
├── tests/ # Automated test suites
│ ├── test_primitives.py # normalizations and accuracy tests
│ ├── test_exclusions.py # Signature matches and class-A rule checks
│ ├── test_convergence.py # Scores hysteresis validation
│ └── ...
│
└── src/ # Source package directory
├── __init__.py # Src package declaration
├── pipeline_orchestrator.py # Core orchestrator process
├── web_server.py # WebSocket server and command bridge
│
├── common/ # Shared data schemas
│ ├── contracts.py # Message payloads and transition records
│ ├── oscr_contracts.py # Structured evidence schemas
│ └── semantic_validator.py # Schema validator utility
│
├── config/ # Simulation configurations
│ ├── baseline_profiles.json # Rolling metric calibration baselines
│ ├── cell_config.json # Physical limits parameters
│ └── demo_topology_5tower.json # site azimuth and overlap grids
│
├── datasets/ # Local grounding corpora
│ └── TeleQnA/ # TeleQnA standard dataset texts
│
├── telemetry/ # Telemetry capturing
│ ├── telemetry_simulator.py # Network simulation clock
│ └── anomaly_detector.py # Sliding window statistical checks
│
├── temporal/ # State occupancy
│ ├── temporal_engine.py # Primitives extraction and TSL counter
│ └── causal_state_model.py # Ontology state adapter bridge
│
├── progression/ # Transition chains
│ └── causal_progression.py # OSCR chain matched templates
│
├── rca/ # Diagnostics convergence
│ └── rca_engine.py # Diagnostic evaluator and confidence levels
│
├── retrieval/ # FAISS RAG indexers
│ ├── knowledge_base.py # FAISS VectorDB index builds
│ ├── memory_engine.py # Long-term semantic embedding memory
│ └── rag_pipeline.py # Combined retrieval context engine
│
├── explanation/ # Mitigation recommenders
│ ├── llm_engine.py # OpenAI/Fallback generators
│ └── optimization_engine.py # Deterministic approved actions matrix
│
├── ontology/ # Core ontology adapters
│ └── occupancy_engine.py # Phase transitions logic
│
├── oscr/ # Signature matching layer
│ ├── oscr_signature_engine.py # conformance and invariants checker
│ ├── oscr_evidence_assembler.py # Context evidence packager
│ ├── oscr_exclusion_engine.py # Exclusion criteria engine
│ └── oscr_signatures_catalog.py # Rules configuration catalog
│
└── governance/ # Audit & Ledgers
├── transition_journal.py # transition logger
├── state_audit.py # Timeline verifying script
└── replay_runner.py # Replay capture and check scripts
Ensure you have Python 3.10+ installed. System dependencies such as sentence-transformers, faiss-cpu, and websockets require setup. Refer to INSTALLATION.md for step-by-step setup guides.
Run the launcher script to start all services, background buses, and the static file server:
python3 launcher.pyOpen your web browser and navigate to:
http://localhost:8000
You will be greeted with the real-time dynamic 3D RAN Control Center!
- Select
RAN_CELL_ALPHA_02from the developer console at the bottom. - Choose
HARDWARE_FAULTand click Inject Fault. - In a few seconds, the live 3D tower node in the layout will turn red.
- The right panel will immediately update:
- Root Cause & Diagnosis: Shows
HARDWARE_FAILUREdiagnosed with high confidence. - AI Resolution Plan: Shows a step-by-step physical inspection plan.
- Context Grounding: Displays retrieved standard operating procedures from 3GPP TeleQnA.
- Root Cause & Diagnosis: Shows
A full development and contribution guide is available at DEVELOPMENT.md and CONTRIBUTING.md.
To run the automated integration tests:
python3 test_all.pyTo verify the cryptographic state transition journal ledger:
python3 -m src.governance.state_audit verify- Rajveer Singh (ladybug-me)
- GitHub: https://github.com/ladybug-me
- Email: rajveer2027singh@gmail.com
Licensed under the Apache License, Version 2.0 (the "License"). You may not use this codebase except in compliance with the License. You may obtain a copy of the License in the LICENSE file or at:
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.