How prateek780/q-sim works
Project Type and Purpose
• This is a hybrid classical-quantum network simulator with both CLI and web-based GUI interfaces.
• It provides:
• A core simulation engine for classical and quantum networks
• An API server exposing simulation controls and AI-driven agents
• A React/TypeScript frontend for visualization and interaction
• A collection of AI “agents” for log summarization, topology generation/validation, routing advice, etc.
• Data models for conversations, embeddings, simulation results, and topologies
High-Level Component Breakdown
A. Core Simulation Layer (Python)
• core/ — the simulation engine coordinating events, nodes, worlds
• classical_network/ & quantum_network/ — implementations of nodes, packets, channels
• json_parser.py & main.py — CLI entry points for batch or interactive use
B. AI Agent Layer (Python)
• ai_agent/ — LLM-based agents (log summarizer, topology agent, router, validator)
• orchestration/ — agent_manager and coordinator that drive multi-agent workflows
• data/embedding & data/models — storage and retrieval of embeddings, conversation logs, and simulation data
C. Backend/API Server (Python)
• server/app.py & start.py — starts a REST/WebSocket server (Flask/FastAPI style)
• server/api/ — route handlers for agents, simulations, conversations, topology requests
• server/socket_server/ — real-time updates via websockets
D. Frontend/UI (TypeScript + React)
• ui/src/ — React components for network canvases, labs, metrics, AI chat panels, node detail panels
• ui/services/ — API and socket clients, import/export, local storage
• Vite config, ESLint, package.json — build/test environment
E. Configuration & Utilities
• config/ — YAML/JSON configs for LLM, data paths, simulation parameters
• utils/ — general helpers (debugging, visualization, encryption)
• log_schema.json & validation_report.json — input/output schema definitions
Relationships & Interaction Flows
• Frontend ↔ Backend
• REST calls to /api/simulation, /api/agent, /api/topology, /api/conversation
• WebSocket channel for streaming live simulation and agent messages
• Backend ↔ Core Simulation
• API handlers invoke core.main or simulation manager, passing JSON topologies & params
• core returns simulation events/logs to server
• Backend ↔ AI Agent Layer
• The coordinator instantiates agents (e.g., log summarizer) → they call LLM APIs using prompts in ai_agent/src
• Results are persisted to data/models then pushed back to client via API/socket
• Data Persistence
• In-memory or Redis (data/models/connection/redis.py) for conversation & simulation state
• File-based logs and JSON schemas for offline analysis
Architectural Patterns & Design Principles
• Layered Architecture: UI → API → Core/Agent → Data
• Modular Agents: each AI capability is a plug-in agent class following base_agent interface
• Separation of Concerns: distinct directories for simulation, AI, server, UI, config, utils
• Event-Driven Simulation: core/event.py and orchestration/coordinator coordinate asynchronous tasks
• Extensibility: new network types, new agents, or new UI labs can be added by dropping in modules