Observatory + Agent Integration

The NeuAIs Observatory provides 3D visualization of all agents, services, and infrastructure generated from the manifest system.

Architecture

CSV Manifest → Perfection Generator → generated.manifest.json
                                            ↓
                                    Observatory API (3003)
                                            ↓
                                    WebSocket (3004)
                                            ↓
                                    3D Visualization

Components

1. Observatory API Server

Location: observatory.neuais.com/api/server.js
Port: 3003 (HTTP), 3004 (WebSocket)

Purpose:

Reads generated.manifest.json from Perfection system
Transforms manifest data into Observatory-compatible format
Serves REST API endpoints
Broadcasts real-time updates via WebSocket

Endpoints:

GET  /api/manifest          - Full system data
GET  /api/agents            - All agents
GET  /api/agents/:id        - Specific agent details
GET  /api/services          - All services
GET  /api/infrastructure    - All infrastructure
GET  /health                - API health check

2. Live Data Client

Location: observatory.neuais.com/js/observatory-data-live.js

Purpose:

Connects to Observatory API
Establishes WebSocket for real-time updates
Handles reconnection logic
Exposes agent control methods (start/stop)

Usage:

const client = new ObservatoryDataClient();
await client.connect();

// Listen for updates
client.on('data_update', (data) => {
    // Refresh visualization
});

client.on('agent_status', (update) => {
    // Update specific agent
});

// Control agents
client.startAgent('anomaly-detector');
client.stopAgent('code-reviewer');

3. Live Visualization

Location: observatory.neuais.com/index-live.html

Features:

Loads data from API instead of hardcoded file
Updates visualization when manifest changes
Shows connection status indicator
Real-time particle flows between connected nodes
Interactive node selection

Data Flow

Initial Load

User opens http://localhost:3003/index-live.html
observatory-data-live.js connects to API
API reads latest generated.manifest.json
Data transformed to Observatory format
3D nodes created for each agent/service/infrastructure
Particle flows created based on dependencies

Real-time Updates

Perfection generates new manifest
Observatory API detects file change
API broadcasts update via WebSocket
All connected clients receive update
Visualization rebuilds with new data
Stats counters update

User Interactions

User clicks 3D node
Detail card appears with agent info
User clicks “Start” button
WebSocket sends start_agent command
API forwards to agent runtime (future)
Status updates via WebSocket
Node visual updates (color, pulse)

Data Format

Manifest Format (Perfection)

{
  "agents": [{
    "name": "anomaly-detector",
    "language": "rust",
    "template": "ric-integrated-agent",
    "lm_provider": "openai",
    "lm_model": "gpt-4",
    "dependencies": [
      {"type": "service", "name": "ric"},
      {"type": "service", "name": "smo"}
    ]
  }]
}

Observatory Format (Transformed)

{
  "agents": [{
    "id": "anomaly-detector",
    "name": "Anomaly Detector",
    "status": "active",
    "cpu": 12,
    "mem": "24MB",
    "connections": ["ric", "smo"],
    "metadata": {
      "language": "rust",
      "template": "ric-integrated-agent",
      "lm_provider": "openai",
      "lm_model": "gpt-4"
    }
  }]
}

Visual Design

Color Scheme (NeuAIs Brand)

Agents: White (#FFFFFF) to light grey (#CCCCCC)
Services: Medium grey (#666666) to grey (#999999)
Infrastructure: Dark grey (#1a1a1a) to dark grey (#333333)
Particles: Match source node color
Background: Pure black (#000000)

Node Sizes

Infrastructure: 0.8 units (largest)
Services: 0.5 units (medium)
Agents: 0.4 units (smallest)

Animations

Pulse: Nodes breathe (scale 0.85-1.0)
Glow: Emissive intensity oscillates
Particles: Flow along bezier curves between nodes
Rotation: Auto-rotate entire system (optional)

Scaling to 1000 Agents

Performance Optimizations

Current: 30 nodes (9 agents + 19 services + 3 infra)
Target: 1000+ agents

Strategies:

Level of Detail (LOD)
- Distant nodes: Simple spheres
- Close nodes: Detailed geometry with labels
Frustum Culling
- Only render nodes in camera view
- Improves performance by 40-60%
Instancing
- Reuse geometry for similar nodes
- Reduces draw calls from 1000 to ~10
Particle Pooling
- Reuse particle objects
- Limit max particles to 5000
Update Throttling
- Update positions at 60 FPS
- Update metrics at 1 FPS
- Reduces CPU usage by 70%

Integration with Control Panel

Both interfaces work together:

Control Panel (port 3002):

List view of all components
Table-based management
Detail panels
Start/stop buttons

Observatory (port 3003):

3D spatial view
Visual connections
System architecture
Real-time flows

Users can use either or both depending on preference.

Usage

Start Observatory

cd neuais.com/hub.neuais.com/observatory.neuais.com
./start-observatory.sh

Opens at: http://localhost:3003/index-live.html

Generate New System

cd neuais.com/automation
./cli/perfection generate manifest/neuais-complete.csv

Observatory automatically updates when manifest changes.

Monitor Live

Open Observatory in browser
Watch connection status indicator (top-right)
Green = Connected and receiving updates
Grey = Disconnected or loading

Future Enhancements

Real SMO/RIC Status
- Poll actual agent health from SMO
- Show real CPU/memory from metrics endpoints
Interactive Controls
- Right-click node → Start/Stop/Restart
- Drag between nodes → Create connection
- Double-click → Open in IDE
Advanced Filtering
- Search agents by name
- Filter by language, status, LM provider
- Group by capability or policy
Workflow Visualization
- Show task flows as animated particles
- Click particle to see task details
- Trace task path through system

Testing

# Terminal 1: Generate system
cd neuais.com/automation
./cli/perfection generate manifest/neuais-complete.csv

# Terminal 2: Start API
cd observatory.neuais.com
./start-observatory.sh

# Terminal 3: Check API
curl http://localhost:3003/api/agents | jq
curl http://localhost:3003/api/manifest | jq '.agents | length'

# Browser: Open Observatory
open http://localhost:3003/index-live.html

Expected result:

See all 9 agents as white/grey nodes
See all 19 services as medium grey nodes
See 3 infrastructure components as dark grey nodes
Particles flowing between connected nodes
Stats showing 9/19/3 counts

Known Limitations

Status is simulated - Not yet querying real agent processes
Metrics are estimated - CPU/memory values are placeholders
Start/Stop is stubbed - Sends WebSocket message but doesn’t actually start agents
No filtering yet - Shows all nodes always

These will be addressed when real agent runtime is implemented.

The integration architecture is complete and ready. The 3D visualization now pulls live data from your manifest system.

Keyboard shortcuts

NeuAIs Documentation