Add cellular network architecture analysis and adaptation guide

[belkmouf]

Summary

This PR adds comprehensive documentation for adapting the NIKA agent architecture to wireless telecom/cellular networks (4G/5G). The analysis document provides a detailed roadmap for extending the existing network troubleshooting framework to support cellular-specific domains including RAN (Radio Access Network), Core Network Functions, and transport layers.

Key Changes

• Architecture Analysis Document (docs/AGENT_ARCHITECTURE_ANALYSIS.md):

  • Overview of current NIKA architecture and core components
  • Detailed explanation of key patterns: multi-agent workflows (LangGraph), specialized sub-agents, MCP tool exposure, and fault injection systems
  • Component mapping between NIKA's wired network model and cellular network equivalents
  • Proposed cellular agent architecture with domain-specific agents (RadioDiagnosisAgent, CoreDiagnosisAgent)

• Cellular-Specific MCP Tools:

  • RAN MCP Server: gNB metrics, UE measurements, handover history, interference analysis, RRC state tracking, beam alignment
  • Core Network MCP Server: AMF status, PDU session info, subscriber profiles, user plane tracing, network slice statistics, authentication checks
  • Telemetry MCP Server: PM counters, active alarms, KPI trends, event correlation

• Cellular Problem Categories:

  • RF interference, coverage holes, capacity exhaustion, hardware failures, handover issues
  • Authentication/session/mobility management failures
  • Backhaul/fronthaul issues, transport failures
  • Slice SLA violations, QoS degradation, security threats

• Implementation Roadmap:

  • 5-phase plan: Environment setup → MCP tools → Agent development → Problem library → Integration & benchmarking
  • File structure and technology stack recommendations
  • Example cellular scenarios (urban macro, rural, enterprise campus, highway mobility, stadium, IoT)

Notable Details

• Maintains NIKA's modular design philosophy while extending it to cellular domains
• Proposes specialized diagnosis agents for RAN and Core network layers, reflecting the distinct expertise required
• Includes example system prompts and tool definitions ready for implementation
• Provides clear mapping between existing NIKA components and their cellular equivalents
• Recommends open-source cellular simulators (UERANSIM, Open5GS, srsRAN) compatible with the existing architecture

Purpose

This document serves as a design specification and implementation guide for teams looking to build AI-powered troubleshooting agents for cellular networks using the NIKA framework as a foundation.

https://claude.ai/code/session_01Qr4uiSXnGDrYU97og9wAex

[belkmouf]

add

[belkmouf]

adding new

[zhihao1998]

Hi belkmouf, thanks for the detailed roadmap. We’re very interested in extending NIKA to wireless/cellular scenarios.

Would you be interested in leading an extension PR for this? A good starting point could be an ns-3-based or similar wireless simulation/emulation prototype, exposing RAN/cellular telemetry and fault scenarios.

[alessandrocornacchia]

@belkmouf do you have any progress or future plans for this? Otherwise, we will creare an issue for this and close the PR due to inactivity.