Automate the repetitive technical work around the technician, not the technician out of the work.
This repository is a safe, fully simulated environment for developing an autonomous technical-support assistant for CCTV, IP cameras, NVRs, AI Boxes, and helpdesk operations. It never connects to real customer systems, real cameras, or production infrastructure.
# Windows PowerShell (Python 3.11 recommended)
py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
# Start everything with one command:
python scripts/run_local.py
# macOS / Linux
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python scripts/run_local.py
This launches all four services: This launches all five components:
Press Ctrl+C to cleanly stop all services.
The frontend is a modern NOC/Operations console built with React 19, TypeScript, Tailwind CSS, Lucide icons, and Vite.
cd frontend
npm install
npm run dev # Start dev server on http://localhost:5173
npm test # Run frontend test suite (Vitest + React Testing Library)
npm run build # Build production bundle with strict TypeScript validation
docker compose up --build
# Backend pytest suite (60 tests) + linter
python -m pytest -q
python -m ruff check .
# Frontend Vitest suite (19 tests)
cd frontend
npm test
npm run build
The Operations Web UI provides 10 purpose-built NOC views and real-time monitoring:
/): Real-time KPI metric cards, site health breakdown, recent incident queue, active fault indicators, and a one-click Quick Fault Simulator modal./incidents, /incidents/:id): Filterable tickets with status tabs, severity indicators, expandable diagnostic timelines, historical matches, and technician note-taking./devices, /devices/:id): Camera/NVR/AI Box cards with RTSP ping/latency indicators, telemetry gauges (CPU, memory, storage, temp), and live fault injection shortcuts./sites, /sites/:id): Multi-site health rollups with visual Topology Graphs visualizing network dependencies (Gateway → NVR → Cameras/AI Box → Cloud Sync) and identifying correlated outages./assistant): Interactive conversational console with rich markdown, tool execution step pills (running, success, failure, blocked), and command auto-completion./knowledge): Full-text searchable Markdown SOP and runbook browser rendered dynamically from data/knowledge/./audit): Filterable chronological log of all autonomous and human actions.| Command | Usage | Description |
|---|---|---|
/investigate <ASSET_ID> |
/investigate CAM-001 |
Runs autonomous diagnostics, checks policy, retrieves SOPs, and reports evidence |
/status <ASSET_ID> |
/status AI-BOX-001 |
Instant telemetry snapshot (health, ping, RTSP, CPU, storage, memory) |
/site <SITE_ID> |
/site SITE-001 |
Full site diagnostics, device statuses, and multi-camera correlated outage analysis |
/history <QUERY> |
/history rtsp error |
Searches historical tickets and past resolution notes |
/help |
/help |
Displays available slash commands, usage examples, and safety constraints |
/clear |
/clear |
Clears conversation state while safely preserving tickets, devices, and audit logs |
Every action displays its strict safety tier:
reconnect_stream, restart_service): Safe to automate autonomously.reboot_host, update_config): Requires human confirmation.hardware_repair, credential_rotation): Blocked from autonomous execution; creates technician alert.ping_check, rtsp_check): Read-only diagnostic checks, always safe.The policy engine (services/agent/policy.py) is authoritative and runs strictly on the backend. Frontend controls reflect policy but can never bypass it.
# Via Web UI:
Click the "Lab Controls" / "Inject Fault" button in the top navigation bar.
# Via API (with services running)
curl -X POST http://localhost:8002/faults/CAM-001 -H "Content-Type: application/json" -d '{"fault":"rtsp_down"}'
# Via CLI helper (works offline against state file)
python scripts/inject_fault.py CAM-001 rtsp_down
# Clear a fault
python scripts/inject_fault.py --clear CAM-001
# List active faults
python scripts/inject_fault.py --list
curl http://localhost:8001/tickets
curl http://localhost:8001/search?q=rtsp
curl -X POST http://localhost:8003/run-once
curl -X POST http://localhost:8003/investigate/CAM-001
curl http://localhost:8003/policy
python scripts/reset_lab.py
| Fault | Auto-recoverable? | Agent action |
|---|---|---|
network_down |
No | Escalate to technician |
rtsp_down |
✅ Yes | reconnect_stream |
rtsp_auth_failure |
No | Escalate to technician |
wrong_rtsp_path |
No | Escalate to technician |
poe_power_off |
No | Escalate (physical repair) |
high_cpu |
No | Escalate to technician |
storage_full |
No | Escalate to technician |
intermittent_connectivity |
✅ Yes | clear_transient |
nvr_unavailable |
No | Escalate to technician |
ai_box_service_failure |
✅ Yes | restart_service |
cloud_sync_failure |
✅ Yes | retry_upload |
multi_camera_site_outage |
No | Escalate (site-level) |