Merge pull request #5 from WiseLabCMU/nicegui-control-plane

Nicegui control plane

Author: mwfarb

python/control_plane/README.md

@@ -0,0 +1,51 @@
+# AllSpark Control Plane
+
+This directory contains the NiceGUI-based reactive control plane for the AllSpark Edge Server.
+
+The control plane runs as a decoupled **sidecar** UI alongside the core edge network server. This separation ensures the high-throughput WebSocket operations of the main node remain unaffected by the UI data rendering.
+
+## Setup Requirements
+
+The control plane shares dependencies with the Python Edge Server. Ensure all dependencies are installed:
+
+```bash
+cd ../  # Navigate up to the python edge server root
+pip install -r requirements.txt
+```
+
+> **Note**: The core edge server must run to generate the default `config.json` before the control plane can read the settings correctly.
+
+## Running the Servers (Order of Operations)
+
+Because the control plane binds asynchronously and depends on the main edge configuration and API (`/api/status`), you should boot up the edge server **first**.
+
+**Step 1. Run the Core Edge Server**
+In your first terminal:
+```bash
+cd allspark_agent/edge_server/python
+python server.py
+```
+*You should see output indicating it is running on `http://0.0.0.0:8080` (and `wss://...`). If this is the first run, it will automatically generate a default `config.json` in the `edge_server/` root.*
+
+**Step 2. Run the Control Plane Sidecar**
+In a second terminal:
+```bash
+cd allspark_agent/edge_server/python
+python control_plane/main.py
+```
+*NiceGUI will automatically read your `config.json` and start the remote dashboard on `http://127.0.0.1:8081` (Edge Server Port + 1).*
+
+**Step 3. (Optional) Run the Mock Rerun.io Viewer**
+To populate the `/rerun` visualization iframe in the control plane dashboard with dummy data until the true data plane is integrated, launch the rerun mock script in a third terminal:
+```bash
+cd allspark_agent/edge_server/python
+python control_plane/dummy_rerun_server.py
+```
+*This will spin up a local rerun web viewer on port `9090` which the control plane will iFrame natively.*
+
+## Key Features
+
+1. **Reactive Dashboard:** Monitors your local MQTT anomaly topic streams on `127.0.0.1:1883` in real-time.
+2. **Client Health UI:** Actively polls the `/api/status` endpoint to display connected mobile rigs and trigger on-demand data uploads.
+3. **Capture Browser:** Traverses the local `.quic`, `.mp4`, and `.json` files inside your edge upload directory and streams them natively to the browser.
+4. **Agent Testing Stub:** Quick shortcut for sending anomalies to the main Agentic framework for resolution.

python/control_plane/architecture.md

@@ -0,0 +1,63 @@
+# AllSpark Edge Control Plane - Architecture & Design Decisions
+
+This document captures the core architectural choices and design patterns implemented for the AllSpark Edge Control Plane.
+
+## 1. Framework Selection: NiceGUI
+**Decision:** We chose [NiceGUI](https://nicegui.io/) over traditional decoupled SPA frameworks (like React, Vue, or Angular) or heavy template rendering (like Django/Jinja).
+**Rationale:** 
+- **Python-Native:** NiceGUI allows the entire frontend and backend logic to reside in pure Python. This ensures that the AI/backend engineers maintaining the AllSpark ecosystem can easily extend the UI without needing specialized frontend context switching.
+- **Reactive Data Binding:** It provides Vue-like reactivity natively in Python, making it trivial to auto-update lists, tables, and graphs without writing websocket/polling boilerplate manually.
+
+## 2. The Sidecar Architecture Pattern
+**Decision:** The control plane executes as a completely detached **Sidecar Process** (`python control_plane/main.py`) rather than being tightly integrated into the main `aiohttp` edge server (`server.py`).
+**Rationale:**
+- **Isolation of Concerns:** The primary Edge Server manages high-frequency WebSocket streams, large QUIC video blob uploads, and Bonjour service discovery. Keeping the UI rendering and polling decoupled ensures that an expensive UI redraw or long-running query doesn't block the asyncio event loop handling critical edge ingestion.
+- **Port Offset:** The sidecar automatically reads the Edge Server's configured port (e.g., `8080`) from `config.json` and binds itself to `port + 1` (e.g., `8081`), ensuring no port collisions while remaining predictable.
+
+## 3. Single Source of Truth Configuration
+**Decision:** Both the Edge Server and the Sidecar UI read from a unified `config.json` in the root `edge_server/` directory.
+**Rationale:** 
+- **Bootstrapping:** Whichever service boots first (typically `server.py` or the `node` equivalent) checks for `config.json`. If it's missing, it dynamically generates it with internal defaults.
+- **Synchronization:** The control plane reliably knows exactly where the `uploadPath` is located, what IP constraints exist, and what the base port is without duplicated environment variables.
+
+## 4. Integration Strategies for Edge Data
+
+We utilized three distinct strategies for populating the reactive UI, optimizing for speed and footprint:
+
+### A. Polling for Client State (REST API)
+- **Method:** `aiohttp` loop polling `/api/status` via `ui.timer(5.0)`.
+- **Reasoning:** Rather than constructing an inter-process WebSocket bridge between the Edge Server and the Sidecar to sync mobile rig connections, the sidecar leverages the Edge Server's existing lightweight REST API.
+
+### B. Shared File Mounts (Capture Browser)
+- **Method:** `os.path` and `glob` traversal to `app.add_media_files()`.
+- **Reasoning:** Instead of creating file transfer endpoints, the Sidecar reads the absolute system path defined in `config.json` (`uploads/orgs/default/...`). It dynamically builds UI cards based on what exists on disk in real-time, allowing native HTML5 `video` playback over HTTP immediately.
+
+### C. Direct Broker Attachment (MQTT Anomalies)
+- **Method:** Background `paho-mqtt` thread processing wildcard topics (`#`).
+- **Reasoning:** System anomalies generated by AllSpark agents bypass the core Edge Server entirely and hit the local MQTT broker (`1883`). The control plane runs a dedicated Paho subscriber thread that captures, structures, and limits anomaly events in memory, pushing updates to the UI natively.
+
+## 5. Rerun.io Data Plane Mocking
+**Decision:** Integrated an `iframe` pointing to a local `rerun-sdk` web viewer (`http://localhost:9090`).
+**Rationale:** Allows the control plane to seamlessly wrap complex, high-performance rust-rendered robotics 3D visualizations inside the standard Python UI workflow until a unified authentication and embedding pipeline is established.
+
+---
+
+## Next Steps & Future Work
+
+While Phase 1 and 2 established the decoupled control plane, the following steps are planned for the evolution of the AllSpark Edge architecture:
+
+1. **Native Integration (Merging the Sidecar):**
+   - Although the detached Sidecar pattern (running on `port + 1`) is currently used to guarantee the Edge Server's critical event loop remains unblocked, the ultimate goal is to **natively integrate** the control plane into the main Edge Server application. This will unify the deployment footprint and eliminate the need to run two separate Python processes.
+
+2. **Real Rerun.io Server Integration:**
+   - Replace the `dummy_rerun_server.py` mock with the actual `rerun-sdk` data integration pipeline. This involves piping the live telemetry and `.quic` video streams directly into the native Rerun data plane for real-time 3D and spatial debugging.
+
+3. **Expanded Configuration & Data Discovery:**
+   - Extend the `config.json` schema to encompass a broader range of telemetry locations and application logs.
+   - Update `pages/capture.py` to ingest and parse these diverse logs globally, providing a centralized diagnostic view beyond just the MQTT streams and media uploads.
+
+4. **Agentic Framework Hookup:**
+   - Replace the UI stubs in `pages/agent.py` with actual programmatic calls to the underlying AllSpark Agentic nodes. This will allow the control plane to seamlessly dispatch identified MQTT anomalies directly to the Vertex/LLM-Farm agents and display their diagnostic reports dynamically within the dashboard.
+
+5. **Unified Security & Authentication:**
+   - Sync the SSL context and authentication layers from the main Edge app into the control plane to ensure that remote debugging over the network is properly secured with JWT or token-based guards.

python/control_plane/dummy_rerun_server.py

@@ -0,0 +1,45 @@
+"""
+A lightweight dummy script to run a rerun.io web viewer for the AllSpark dashboard demo.
+Requirements: pip install rerun-sdk
+"""
+import rerun as rr
+import rerun.blueprint as rrb
+import time
+import math
+
+def main():
+    # Initialize the rerun SDK and set it to serve over WebSocket + HTTP mapping for web viewer
+    rr.init("AllSpark_Demo", spawn=False)
+    
+    # Create the web viewer
+    rr.serve_web_viewer(web_port=9090, open_browser=False)
+    
+    print("Dummy Rerun Server running at http://127.0.0.1:9090")
+    print("Populating example dummy data...")
+    
+    # Try sending initial blueprint and some data
+    rr.send_blueprint(rrb.Blueprint(
+        rrb.Horizontal(
+            rrb.Spatial2DView(name="Camera View", origin="camera"),
+            rrb.TextDocumentView(name="Agent Response", origin="agent_response")
+        )
+    ))
+
+    # Static UI init
+    rr.log("agent_response", rr.TextDocument("AllSpark Agentic Analysis Results\n\nResults from using the AllSpark Agentic Framework will appear here."))
+
+    i = 0
+    try:
+        while True:
+            # Removed time sequence for backward/forward compatibility
+            # rr.set_time_sequence("frame", i)
+            # Log a simple moving point payload
+            rr.log("camera/tracked_point", rr.Points2D([[math.sin(i * 0.1) * 10, math.cos(i * 0.1) * 10]], colors=[255, 0, 0]))
+            
+            time.sleep(0.1)
+            i += 1
+    except KeyboardInterrupt:
+        print("Shutting down dummy rerun server.")
+
+if __name__ == "__main__":
+    main()

python/control_plane/main.py

@@ -0,0 +1,28 @@
+from nicegui import app, ui
+import os
+
+# Import all pages to register their routes
+from pages import dashboard, clients, capture, agent, rerun_view, settings
+
+# Initialize pages
+dashboard.create_page()
+clients.create_page()
+capture.create_page()
+agent.create_page()
+rerun_view.create_page()
+settings.create_page()
+
+if __name__ in {"__main__", "__mp_main__"}:
+    # Read port from config.json and start NiceGUI on config['port'] + 1 (default 8081).
+    config = settings.load_config()
+    edge_port = config.get('port', 8080)
+    sidecar_port = edge_port + 1
+    
+    # Mount the dynamic video storage directory for browser playback
+    upload_path = config.get('uploadPath', 'uploads/orgs/default')
+    abs_upload_path = os.path.abspath(os.path.join(os.path.dirname(__file__), '..', '..', upload_path))
+    os.makedirs(abs_upload_path, exist_ok=True)
+    app.add_media_files('/videos', abs_upload_path)
+
+    # Run the control plane
+    ui.run(title='AllSpark Control Plane', port=sidecar_port, storage_secret='allspark-secret')

python/control_plane/pages/__init__.py

@@ -0,0 +1 @@
+# Makes pages a module

python/control_plane/pages/agent.py

@@ -0,0 +1,29 @@
+from nicegui import ui
+from theme import menu
+
+def create_page():
+    @ui.page('/agent')
+    def agent_page():
+        with menu('Agentic Framework Control'):
+            
+            with ui.row().classes('w-full gap-6'):
+                with ui.column().classes('w-1/3'):
+                    ui.label('Investigate Issue').classes('text-xl font-bold mb-4')
+                    ui.select(['Latency > 500ms (Camera Rig A)', 'Connection Dropped (Mobile Client B)'], label='Target Anomaly').classes('w-full mb-4')
+                    ui.textarea(label='Context / Prompt', value='Analyze the provided QUIC videos and MQTT logs to determine why the latency spiked over 500ms on Rig A.').classes('w-full h-32 mb-4')
+                    ui.button('Execute Investigation', icon='science', on_click=lambda: ui.notify('Agent investigation dispatched! Context sent to agentic frameworks.')).classes('w-full bg-blue-600')
+
+                with ui.column().classes('flex-1 w-full'):
+                    ui.label('Recent Responses').classes('text-xl font-bold mb-4')
+                    
+                    with ui.card().classes('w-full bg-gray-50'):
+                        with ui.row().classes('w-full justify-between mb-2'):
+                            ui.label('Analysis: Issue 742 - Camera Frame Drop').classes('font-bold')
+                            ui.label('2026-03-24 14:02:11').classes('text-xs text-gray-500')
+                        ui.markdown('''
+**Agent Summary:**
+I have reviewed the logs between 14:00 and 14:05. The frame drop was caused by an underlying network buffer overflow on the edge interface when `agent_client` transmitted a high-frequency telemetry burst.
+
+I have generated a visualization of the synchronized data streams.
+                        ''')
+                        ui.button('View in Rerun.io', icon='open_in_new', on_click=lambda: ui.navigate.to('/rerun')).classes('mt-2')

python/control_plane/pages/capture.py

@@ -0,0 +1,56 @@
+from nicegui import ui
+import os
+import glob
+from theme import menu
+from pages.settings import load_config
+
+def create_page():
+    @ui.page('/capture')
+    def capture_page():
+        config = load_config()
+        upload_path = config.get('uploadPath', 'uploads/orgs/default')
+        abs_upload_path = os.path.abspath(os.path.join(os.path.dirname(__file__), '..', '..', '..', upload_path))
+        
+        with menu('Data Capture'):
+            ui.label('Logs & QUIC Videos Review').classes('text-xl font-bold mb-4')
+            
+            with ui.tabs().classes('w-full') as tabs:
+                videos_tab = ui.tab('Videos')
+                logs_tab = ui.tab('Logs')
+            
+            with ui.tab_panels(tabs, value=videos_tab).classes('w-full bg-transparent'):
+                with ui.tab_panel(videos_tab):
+                    with ui.row().classes('w-full gap-4 flex-wrap mt-2'):
+                        if os.path.exists(abs_upload_path):
+                            files = glob.glob(os.path.join(abs_upload_path, '*.*'))
+                            vid_files = [f for f in files if f.endswith(('.mp4', '.quic', '.json'))]
+                            if not vid_files:
+                                ui.label('No capture files found in upload path yet.').classes('text-gray-500 italic p-4 mt-2')
+                            
+                            for f in sorted(vid_files, reverse=True):
+                                filename = os.path.basename(f)
+                                size_mb = os.path.getsize(f) / (1024 * 1024)
+                                with ui.card().classes('w-64 relative'):
+                                    if filename.endswith('.mp4'):
+                                        ui.video(f'/videos/{filename}').classes('w-full h-32 bg-black object-contain')
+                                    elif filename.endswith('.quic'):
+                                        ui.html(f'<div class="w-full text-center p-8 bg-blue-100 text-blue-500 rounded"><i class="fas fa-video fa-2x"></i><br><b>.QUIC</b></div>')
+                                    else:
+                                        ui.html(f'<div class="w-full text-center p-8 bg-gray-100 text-gray-500 rounded"><i class="fas fa-file fa-2x"></i><br><b>.JSON</b></div>')
+                                    
+                                    ui.label(filename).classes('font-bold mt-2 truncate max-w-full').tooltip(filename)
+                                    ui.label(f'Size: {size_mb:.2f} MB').classes('text-sm text-gray-500')
+                                    # Create a simple direct download link or trigger notify for quic
+                                    ui.button('Play' if filename.endswith('.mp4') else 'Download', 
+                                              icon='play_arrow' if filename.endswith('.mp4') else 'download', 
+                                              on_click=lambda fn=filename: ui.download(f'/videos/{fn}')).classes('w-full mt-2')
+                        else:
+                            ui.label('Upload directory not created yet. Awaiting initial mobile rig connection.').classes('text-gray-500 italic')
+
+                with ui.tab_panel(logs_tab):
+                    ui.label('Recent Edge Logs (simulated tail)').classes('font-bold mb-2')
+                    log_text = "[2026-03-25 10:15:01] INFO - Connected to rig_alpha\n" \
+                               "[2026-03-25 10:15:05] WARN - Latency spike detected: 154ms\n" \
+                               "[2026-03-25 10:16:22] ERROR - Disconnected from rig_beta\n" \
+                               "[2026-03-25 10:16:45] INFO - Reconnected to rig_beta"
+                    ui.textarea(value=log_text).props('readonly').classes('w-full font-mono text-sm bg-black text-green-400 p-2 rounded h-64')