2125_GCE/fedmart_ui/README.md

# FedMart UI - XIC Real-Time Pipeline Monitor

Real-time telemetry dashboard for XIC (eXtended Infrastructure Cognition) symbolic pipeline execution with interactive guardrail controls and glyph resonance visualization.

## Overview

The FedMart UI provides a browser-based monitoring interface for the XIC v1.5 symbolic pipeline. It connects to the telemetry ingestion service via WebSocket to receive real-time updates about pipeline execution, multi-glyph resonance scores, and guardrail events.

### Key Features

- **Pipeline Timeline**: Step-by-step execution trace with timing information
- **Glyph Resonance Heatmap**: Visual representation of resonance weights across glyphs using a color-coded canvas
- **Glyph Inspector**: Detailed metrics for individual glyphs (weight, lineage score, contributor score, etc.)
- **Guardrail Control**: Live guardrail status display with pause and throttle buttons
- **Specification Coverage**: Track XIC instruction implementation status and test coverage
- **Real-time Updates**: WebSocket-based live streaming of telemetry events

## Architecture

```
┌─────────────────────────────────────────────────────────┐
│  React/Browser (or Static HTML)                         │
│  ┌─────────────────────────────────────────────────┐   │
│  │  XIC Panel (index.html)                          │   │
│  │  ├─ Timeline Visualization                      │   │
│  │  ├─ Heatmap Canvas                              │   │
│  │  ├─ Glyph Inspector                             │   │
│  │  ├─ Guardrail Control                           │   │
│  │  └─ Spec Coverage                               │   │
│  └─────────────────────────────────────────────────┘   │
│           ↓ WebSocket & REST                           │
├─────────────────────────────────────────────────────────┤
│  FastAPI Backend (server.py)                            │
│  ├─ /ws/fedmart/xic (WebSocket broadcast)             │
│  ├─ /fedmart/ingest/xic (Telemetry ingestion)         │
│  ├─ /fedmart/control/pause (Pause signal)             │
│  ├─ /fedmart/control/throttle (Throttle signal)       │
│  └─ /fedmart/status (System status)                   │
├─────────────────────────────────────────────────────────┤
│  XIC Pipeline                                           │
│  └─ Emits telemetry via FedMartAdapter                │
└─────────────────────────────────────────────────────────┘
```

## Installation & Setup

### Prerequisites

- FastAPI server running (see `/home/dave/server.py`)
- Python 3.9+ with uvicorn
- Modern web browser with WebSocket support

### Quick Start

1. **Start the FastAPI server** (if not already running):
   ```bash
   python3 server.py
   # Server starts on http://localhost:8000
   ```

2. **Open the UI in a browser**:
   ```
   http://localhost:8000/fedmart_ui/modules/xic_panel/
   ```

3. **Click "Connect to Feed"**:
   - UI establishes WebSocket connection to `/ws/fedmart/xic`
   - Status indicator changes to "Connected ✓"
   - UI is ready to receive telemetry

4. **Run an XIC pipeline**:
   - Execute any XIC program that emits telemetry
   - Telemetry events appear in real-time in the dashboard
   - Timeline updates, heatmap renders, metrics display

## Module Structure

```
fedmart_ui/
├── README.md                    (this file)
└── modules/
    └── xic_panel/
        ├── index.html           (UI template with all panels)
        ├── xic_panel.css        (Professional dark-theme styling)
        ├── xic_panel.js         (Real-time data handling & rendering)
        └── README.md            (Detailed component documentation)
```

## File Descriptions

### index.html

HTML5 template with:
- Responsive grid layout (2 columns on desktop, 1 on mobile)
- Six main panels: header, timeline, heatmap, inspector, guardrail control, spec coverage
- Canvas element for heatmap rendering
- Dropdown for glyph selection
- Buttons for feed connection and guardrail controls

### xic_panel.css

Stylesheet with:
- Dark theme (#1e1e1e background, #667eea accent colors)
- Responsive media queries for mobile compatibility
- Color-coded elements:
  - Blue: Standard pipeline steps
  - Orange: Control/warning events
  - Red: Guardrail triggers
- Gradient heatmap legend (blue → green → orange)
- Smooth transitions and hover effects

### xic_panel.js

JavaScript module (ES6) with:
- `XICMonitor` class managing the entire UI state
- WebSocket subscription with automatic reconnection
- Telemetry processing and buffer management
- Timeline rendering from step metadata
- Canvas-based heatmap visualization with color gradients
- Glyph selector population and inspector rendering
- Guardrail alert display with action buttons
- REST API calls to control endpoints

## Telemetry Schema

The dashboard expects telemetry in this format:

```json
{
  "event_type": "symbolic_pipeline_run",
  "timestamp": "2026-05-21T12:00:00Z",
  "run_id": "xic_1234567890",
  "program": "demo_symbolic.gx.json",
  "chain_label": "analysis_1",
  "glyph_ids": ["glyph://a", "glyph://b", "glyph://c"],
  "glyph_count": 3,
  "global_resonance_score": 0.847,
  "steps_executed": 20,
  "guardrails_triggered": [],
  "resonance_map_summary": {
    "top_glyphs": [
      {"glyph_id": "glyph://a", "weight": 0.95},
      {"glyph_id": "glyph://b", "weight": 0.73},
      {"glyph_id": "glyph://c", "weight": 0.81}
    ],
    "average_resonance": 0.83
  },
  "raw_payload": {
    "output_text": "Pipeline execution complete",
    "fused_symbol_summary": { ... }
  }
}
```

**Required Fields:**
- `event_type`: Always "symbolic_pipeline_run"
- `timestamp`: ISO 8601 UTC timestamp
- `run_id`: Unique identifier for the execution
- `glyph_count`: Number of glyphs involved
- `global_resonance_score`: 0.0-1.0 float
- `steps_executed`: Integer count
- `guardrails_triggered`: Array (empty if none)

**Optional Fields:**
- `program`, `chain_label`: Execution context metadata
- `glyph_ids`, `resonance_map_summary`: Multi-glyph analysis
- `raw_payload`: Raw pipeline output

## UI Components

### Pipeline Timeline
Shows execution steps in chronological order:
- Program loading
- Chain entry
- Multi-glyph resonance computation
- Guardrail enforcement
- Symbolic fusion

Each step displays as a colored bar with the step name.

### Glyph Resonance Heatmap
Canvas-based visualization:
- X-axis: Individual glyphs
- Y-axis: Resonance weight (0.0-1.0)
- Color: Blue (low) → Green (mid) → Orange (high)
- Hover-friendly with clear labels

### Glyph Inspector
Detailed metrics for selected glyph:
- Glyph ID
- Resonance Weight (%)
- Status (Active/Inactive)
- (Extensible for additional metrics)

### Guardrail Control
- Live list of triggered guardrails
- Pause Run button (sends control signal)
- Throttle 50% button (reduces execution speed)
- Enabled only when guardrails are active

### Specification Coverage
Status grid showing XIC instruction implementation:
- Instructions grouped by phase
- Color-coded by status: green (implemented), blue (validated), orange (pending)
- Coverage percentage per instruction

## REST API Endpoints

### Telemetry Ingestion

**POST /fedmart/ingest/xic**

Ingest a telemetry event:
```bash
curl -X POST http://localhost:8000/fedmart/ingest/xic \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "symbolic_pipeline_run",
    "glyph_count": 3,
    "global_resonance_score": 0.847,
    "steps_executed": 20,
    "guardrails_triggered": []
  }'
```

Response:
```json
{
  "status": "accepted",
  "run_id": "xic_1234567890",
  "buffer_size": 42
}
```

### Control Actions

**POST /fedmart/control/pause**

Send pause signal to a running pipeline:
```bash
curl -X POST http://localhost:8000/fedmart/control/pause \
  -H "Content-Type: application/json" \
  -d '{"run_id": "xic_1234567890"}'
```

**POST /fedmart/control/throttle**

Throttle a pipeline's execution:
```bash
curl -X POST http://localhost:8000/fedmart/control/throttle \
  -H "Content-Type: application/json" \
  -d '{"run_id": "xic_1234567890", "factor": 0.5}'
```

### Telemetry Retrieval

**GET /fedmart/telemetry/recent?limit=10**

Retrieve recent telemetry events from buffer.

### Status

**GET /fedmart/status**

System health and statistics.

## WebSocket API

### Connection

```javascript
const ws = new WebSocket('ws://localhost:8000/ws/fedmart/xic');
```

### Message Format

Incoming telemetry (same as POST schema):
```json
{
  "event_type": "symbolic_pipeline_run",
  "timestamp": "2026-05-21T12:00:00Z",
  ...
}
```

## Color Scheme

The dashboard uses a professional dark theme:

| Element | Color | Use |
|---------|-------|-----|
| Background | #1e1e1e | Main surface |
| Header | Gradient (#667eea → #764ba2) | Top bar |
| Text | #e0e0e0 | Primary text |
| Accent | #667eea | Highlights, borders |
| Success | #4caf50 | Active status, implemented specs |
| Warning | #ff9800 | Control events, pending specs |
| Error | #f44336 | Guardrails, failures |
| Heatmap Low | #0066cc | Blue (low resonance) |
| Heatmap Mid | #00cc66 | Green (mid resonance) |
| Heatmap High | #ff9900 | Orange (high resonance) |

## Performance Considerations

- **Buffer Size**: Limited to 1000 telemetry events (oldest discarded)
- **WebSocket**: Efficient binary-free JSON transport
- **Canvas Rendering**: Optimized for 600×200px heatmap
- **Responsive Design**: CSS Grid adapts to viewport size
- **Client-side State**: All rendering happens in the browser (no server-side session needed)

## Troubleshooting

### "Cannot connect to WebSocket"
- Verify FastAPI server is running on port 8000
- Check browser console for CORS/network errors
- Ensure firewall allows WebSocket traffic (port 8000)

### Heatmap not rendering
- Browser must support HTML5 Canvas API
- Check browser console for JavaScript errors
- Verify telemetry includes `resonance_map_summary` with `top_glyphs`

### No telemetry appearing
- Click "Connect to Feed" first
- Ensure XIC pipeline is emitting telemetry to `/fedmart/ingest/xic`
- Check `/fedmart/telemetry/recent` endpoint to see if events are buffered
- Monitor browser network tab (F12) for WebSocket messages

### Slow performance with many events
- Clear browser cache (Ctrl+Shift+Del)
- Reduce WebSocket message frequency in source
- Check browser memory usage (F12 Performance tab)

## Testing

Run the validation suite:

```bash
# Test FedMart adapter
python3 tests/validate_fedmart_integration.py

# Test UI components
python3 tests/validate_ui_integration.py
```

All tests should show ✅ PASS status.

## Future Enhancements

- [ ] Export telemetry timeline as CSV
- [ ] Real-time performance profiling graphs
- [ ] Custom guardrail threshold configuration
- [ ] Multi-run comparison view
- [ ] Historical analysis dashboard
- [ ] Integration with third-party monitoring (Grafana, Prometheus)

## Architecture Notes

The UI is deliberately **framework-agnostic**:
- Pure HTML5 + CSS3 + ES6 JavaScript
- No external dependencies (no npm, no build step)
- Single 50KB JavaScript module
- Easy to integrate into React, Vue, or standalone

For a larger project, consider:
- Wrapping `XICMonitor` as a React component
- Using a state management library (Redux, Zustand)
- Adding TypeScript for type safety
- Building a D3.js visualization layer for complex graphs

## Support

For issues, questions, or feature requests:
1. Check the troubleshooting section above
2. Review telemetry schema in FedMart adapter (`integrations/fedmart/xic_adapter.py`)
3. Check FastAPI server logs for backend errors
4. Inspect browser console (F12) for frontend errors

---

**Status**: ✅ Production Ready  
**Last Updated**: 2026-05-21  
**Version**: 1.5.0