CarlBot

Setup, Development, and Debugging Guide

Prerequisites

Clean Setup

1. Python Virtual Environment

Windows PowerShell

py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

macOS / Linux

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

2. Frontend Dependencies

cd frontend
npm install
cd ..

Running the Application

python scripts/run_local.py

This starts all five services concurrently:

  1. Operations Web UI: http://localhost:5173 (Vite dev server)
  2. Helpdesk API: http://127.0.0.1:8001 (Swagger docs)
  3. Operations Portal API: http://127.0.0.1:8002 (Swagger docs)
  4. Agent API: http://127.0.0.1:8003 (Swagger docs)
  5. Agent Autonomous Loop: Polling simulator every 5s

Press Ctrl+C in the terminal to cleanly terminate all 5 processes.

Running Individual Services (for Granular Development)

Run each command in its own terminal tab with the virtual environment activated:

# Terminal 1: Helpdesk Service
uvicorn services.helpdesk.app:app --port 8001 --reload

# Terminal 2: Operations Portal Service
uvicorn services.portal.app:app --port 8002 --reload

# Terminal 3: Agent API Service
uvicorn services.agent.app:app --port 8003 --reload

# Terminal 4: Autonomous Background Polling Loop
python -m services.agent.agent

# Terminal 5: Operations Web Console (Vite)
cd frontend
npm run dev

Frontend Architecture

The Operations Web UI is designed specifically for technical support engineers and Network Operations Center (NOC) operators.

Tech Stack

Directory Structure

frontend/
├── src/
│   ├── api/                  # Typed API clients for each backend service
│   │   ├── client.ts         # Generic fetch wrapper & ApiError
│   │   ├── helpdesk.ts       # Tickets, search, comments, notes
│   │   ├── portal.ts         # Assets, health, faults, actions, sites
│   │   ├── agent.ts          # State, policy, knowledge, run-once, investigate
│   │   └── types.ts          # TypeScript interfaces matching backend models
│   ├── components/           # Reusable UI & diagnostic components
│   │   ├── chat/             # AI Assistant chat components
│   │   │   ├── ChatContainer.tsx
│   │   │   ├── ChatSidebar.tsx
│   │   │   ├── ChatMessageItem.tsx
│   │   │   └── ChatToolStep.tsx
│   │   ├── common/           # Atomic badges, cards, skeletons, empty states
│   │   │   ├── Badge.tsx
│   │   │   ├── PolicyBadge.tsx
│   │   │   ├── Card.tsx
│   │   │   ├── Skeleton.tsx
│   │   │   └── EmptyState.tsx
│   │   ├── layout/           # Global chrome layout
│   │   │   ├── Header.tsx
│   │   │   ├── Sidebar.tsx
│   │   │   ├── AppLayout.tsx
│   │   │   └── LabControlsModal.tsx
│   │   ├── timeline/         # Diagnostic evidence timeline
│   │   │   └── InvestigationTimeline.tsx
│   │   └── topology/         # Network dependency & outage graph
│   │       └── TopologyGraph.tsx
│   ├── context/
│   │   └── LabContext.tsx    # Global telemetry, polling (6s), notification state
│   ├── pages/                # 10 dedicated operations views
│   │   ├── DashboardPage.tsx
│   │   ├── IncidentsPage.tsx
│   │   ├── IncidentDetailPage.tsx
│   │   ├── DevicesPage.tsx
│   │   ├── DeviceDetailPage.tsx
│   │   ├── SitesPage.tsx
│   │   ├── SiteDetailPage.tsx
│   │   ├── AssistantPage.tsx
│   │   ├── KnowledgePage.tsx
│   │   └── AuditPage.tsx
│   ├── test/                 # Component and unit test suites
│   ├── App.tsx               # Route definitions
│   ├── index.css             # Design tokens and custom scrollbars
│   └── main.tsx              # Application entry point
├── package.json
├── tailwind.config.js
├── tsconfig.json
└── vite.config.ts

API Connection & State Management

Service Endpoints

The frontend connects directly to backend services using configurable environment variables (defaulting to localhost):

Each service enables CORSMiddleware allowlisting all origins in development mode.

Global State (LabContext)

AI Assistant & Slash Commands

The conversational assistant console (/assistant) allows technicians to query state and trigger targeted autonomous investigations.

Supported Slash Commands

  1. /investigate <ASSET_ID>
    • Triggers targeted investigation on the asset via POST /investigate/{asset_id}.
    • Executes real checks (Ping, TCP, RTSP, System metrics).
    • Retrieves matching tickets and authoritative SOP documents.
    • Evaluates the policy engine.
    • If SAFE_REVERSIBLE, executes recovery and verifies outcome.
    • If HUMAN_ONLY or APPROVAL_REQUIRED, safely halts and flags for technician review.
  2. /status <ASSET_ID>
    • Performs an instant telemetry snapshot of the asset without altering ticket state.
    • Returns IP, firmware, status, RTSP state, ping latency, and resource metrics.
  3. /site <SITE_ID>
    • Retrieves site-wide rollups and checks for correlated multi-device outages (e.g., gateway down, switch power failure).
  4. /history <QUERY>
    • Searches historical tickets and technician notes for past resolutions to similar symptoms.
  5. /help
    • Lists all supported commands, syntax examples, and safety constraints.
  6. /clear
    • Behavior: Clears the active chat messages and session context in the UI.
    • Safety Boundary: Preserves all tickets in the helpdesk, device states in the portal, fault logs, and audit entries. It does not wipe backend databases or reset lab state.

Tool Execution Transparency

When executing commands, the UI renders interactive status pills:

Technicians can click any tool pill to inspect the exact input arguments and JSON output received from the backend simulator.

Safety Policy Enforcement & Visualization

Every diagnostic finding and proposed remediation displays its assigned safety class:

Architectural Invariant: Policy is enforced strictly on the backend (services/agent/policy.py). The frontend reflects policy states visually but has zero ability to bypass safety rules.

Extending the Lab

Adding a New Page / Route

  1. Create your component in frontend/src/pages/MyNewPage.tsx.
  2. Add the route in frontend/src/App.tsx: 
    <Route path="my-page" element={<MyNewPage />} />
  3. Add the navigation item in frontend/src/components/layout/Sidebar.tsx with a Lucide icon.

Adding a New UI Component

  1. Place atomic/shared components in frontend/src/components/common/.
  2. Use existing design tokens (bg-slate-900, border-slate-800, text-cyan-400, text-slate-100).
  3. Add a corresponding test file in frontend/src/test/ to verify rendering and user interactions.

Adding a New AI Diagnostic Tool

  1. In services/agent/agent.py:
    • Implement the diagnostic check function (e.g. check_audio_stream(asset)).
    • Integrate it into investigate_single_asset() or diagnose().
  2. In services/agent/policy.py:
    • Classify the action into READ, SAFE_REVERSIBLE, APPROVAL_REQUIRED, or HUMAN_ONLY.
  3. In frontend/src/components/chat/ChatContainer.tsx:
    • Add the tool execution step to toolSteps during command execution so operators can see it running live.

Testing & Production Build

Running Backend Tests

# 60 automated unit, API, recovery, and regression tests
python -m pytest -q
python -m ruff check .

Running Frontend Tests

cd frontend
npm test

Vitest executes tests across:

Production Build

cd frontend
npm run build

Build output is generated under frontend/dist/ with full type validation and bundle optimization.

Resetting Lab State

To reset all tickets, faults, device status overrides, and agent state back to the seed baseline:

python scripts/reset_lab.py

On the next cycle or page refresh, all demo assets return to a healthy state and default sample tickets are restored.