2125_GCE/QUICKSTART.md

# FedMart Telemetry System - Quick Start Guide

Get the XIC pipeline monitoring dashboard running in 3 minutes.

## Prerequisites

- Python 3.9+
- FastAPI and uvicorn installed (`pip install fastapi uvicorn`)
- Web browser (Chrome, Firefox, Safari, Edge)

## 1. Start the Server (if not already running)

```bash
cd /home/dave/superdave
python3 server.py
```

You should see:
```
INFO:     Uvicorn running on http://0.0.0.0:8000 [CTRL+C to quit]
🚀 SuperDave AI 2.0 starting up...
[FEDMART] Connected
```

## 2. Open the Dashboard

In your browser, navigate to:
```
http://localhost:8000/fedmart_ui/modules/xic_panel/
```

You should see a dark-themed dashboard with 6 panels:
- Pipeline Execution Timeline
- Glyph Resonance Heatmap
- Glyph Resonance Inspector
- Guardrail Status & Control
- XIC Specification Coverage
- Header with "Connect to Feed" button

## 3. Connect to the Telemetry Feed

Click the blue **"Connect to Feed"** button at the top right.

You should see:
- Status changes to "Connected ✓" (green)
- Button becomes disabled during connection
- Browser console shows: `[XIC] WebSocket connected`

## 4. Send Telemetry (Optional Test)

Run the validation tests to send sample telemetry:

```bash
cd /home/dave/superdave
python3 tests/validate_fedmart_integration.py
```

This will:
- Create sample XIC telemetry events
- Send them to the `/fedmart/ingest/xic` endpoint
- Broadcast to all connected WebSocket clients
- Dashboard updates in real-time

## 5. Interact with the Dashboard

### View Pipeline Timeline
- Execution steps appear as colored bars
- Steps: Program → Chain → Multi-Glyph → Fusion
- Each step shows timing and context

### Inspect Glyph Resonance
1. Select a glyph from the "Select Glyph" dropdown
2. View metrics in the Glyph Inspector panel:
   - Glyph ID
   - Resonance Weight (0-100%)
   - Status (Active)

### Control Guardrails
- When guardrails trigger, they appear in red in the list
- Click **"⏸ Pause Run"** to pause execution
- Click **"⚠ Throttle 50%"** to reduce speed
- Browser console shows control signal sent

## Running a Real XIC Pipeline

To see live telemetry from an actual XIC symbolic pipeline:

```python
# 1. In a Python REPL or script:
from glyphos.symbolic_pipeline import run_symbolic_pipeline

# This will automatically emit telemetry to /fedmart/ingest/xic
result = run_symbolic_pipeline(
    prompt="Analyze the relationship between compression and meaning",
    context={
        "program": "demo_symbolic.gx.json",
        "chain_label": "analysis_chain"
    }
)

# Dashboard updates in real-time with:
# - Timeline showing execution steps
# - Heatmap of glyph resonance
# - Glyph inspector populated with metrics
# - Spec coverage status
```

## Troubleshooting

### "Cannot connect to WebSocket"
1. Verify server is running: `curl http://localhost:8000/fedmart/status`
2. Check browser console (F12 → Console tab)
3. Ensure no firewall is blocking port 8000

### Dashboard blank or CSS not loading
1. Hard refresh: `Ctrl+Shift+R` (or `Cmd+Shift+R` on Mac)
2. Check browser Network tab (F12) for 404 errors
3. Verify file paths: `ls fedmart_ui/modules/xic_panel/`

### No telemetry appearing
1. Click "Connect to Feed" first
2. Run tests to send sample data:
   ```bash
   python3 tests/validate_fedmart_integration.py
   ```
3. Check if events arrive via REST:
   ```bash
   curl http://localhost:8000/fedmart/telemetry/recent
   ```

### JavaScript errors in browser console
1. Check error message for file path
2. Verify xic_panel.js exists and is accessible
3. Clear browser cache: `Ctrl+Shift+Del` → All Time → Clear

## API Quick Reference

### Ingest Telemetry
```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": []
  }'
```

### Get Recent Telemetry
```bash
curl http://localhost:8000/fedmart/telemetry/recent?limit=5
```

### Pause a Run
```bash
curl -X POST http://localhost:8000/fedmart/control/pause \
  -H "Content-Type: application/json" \
  -d '{"run_id": "xic_test_123"}'
```

### Check System Status
```bash
curl http://localhost:8000/fedmart/status
```

## Browser Developer Tools

### Monitor WebSocket Traffic
1. Open F12 → Network tab
2. Filter by "WS" (WebSocket)
3. Click `/ws/fedmart/xic` connection
4. View Messages tab for incoming telemetry

### Debug JavaScript
1. F12 → Console tab
2. Type: `window.xicMonitor.currentRun` (view latest telemetry)
3. Type: `window.xicMonitor.telemetryBuffer` (view all buffered events)
4. Type: `window.xicMonitor.glyphs` (view parsed glyphs)

## File Locations

```
Dashboard:  http://localhost:8000/fedmart_ui/modules/xic_panel/
HTML:       /home/dave/superdave/fedmart_ui/modules/xic_panel/index.html
CSS:        /home/dave/superdave/fedmart_ui/modules/xic_panel/xic_panel.css
JavaScript: /home/dave/superdave/fedmart_ui/modules/xic_panel/xic_panel.js
Server:     /home/dave/server.py
Adapter:    /home/dave/superdave/integrations/fedmart/xic_adapter.py
Tests:      /home/dave/superdave/tests/validate_fedmart_integration.py
            /home/dave/superdave/tests/validate_ui_integration.py
```

## Architecture Overview

```
┌──────────────────────┐
│  Browser             │
│  ┌────────────────┐  │
│  │ XIC Dashboard  │  │
│  └────────────────┘  │
│         ↓ WS         │
├──────────────────────┤
│  FastAPI Server      │
│  /ws/fedmart/xic     │
│  /fedmart/ingest/... │
└──────────────────────┘
         ↑ HTTP
┌──────────────────────┐
│ XIC Pipeline         │
│ emit_telemetry()     │
└──────────────────────┘
```

## Performance Tips

1. **Close other browser tabs** to reduce memory usage
2. **Disable browser extensions** to improve performance
3. **Reduce telemetry frequency** if seeing lag (edit symbolic_pipeline.py)
4. **Clear buffer periodically** via `curl -X POST /fedmart/buffer/clear`

## Next Steps

- Read full documentation: `fedmart_ui/README.md`
- Review implementation: `FEDMART_IMPLEMENTATION_SUMMARY.md`
- Explore adapter: `integrations/fedmart/xic_adapter.py`
- Check schema: `integrations/fedmart/telemetry_schema.json`

## Commands Reference

```bash
# Start server
python3 server.py

# Run all tests
python3 tests/validate_fedmart_integration.py
python3 tests/validate_ui_integration.py

# Check server status
curl http://localhost:8000/api/status

# View FedMart status
curl http://localhost:8000/fedmart/status

# See API docs
# Visit: http://localhost:8000/docs
```

## Support

**For issues:**
1. Check troubleshooting section above
2. Read `fedmart_ui/README.md` detailed guide
3. Inspect browser console (F12) for errors
4. Check server logs for [FEDMART] messages

---

**Ready?** Click "Connect to Feed" and start monitoring! 🚀