Implement XIC v2 control flow with IF, MATCH, LOOP operations
PHASE A: Safe predicate evaluator (glyphos/control/predicate.py) - AST-based safe expression evaluation - Supports comparisons, boolean ops, attribute access - Helper function: dominant_contains() - Protected against code injection attacks PHASE B: XICContext queue helpers - enqueue_chain(label) for FIFO chain scheduling - pop_next_chain() to get next scheduled chain - jump_to(label) for immediate destination changes PHASE C: Control flow operations (xic_ops.py) - op_IF: Conditional branching with optional else - op_MATCH: Pattern matching against fused fields - op_LOOP: Iterative execution with guardrails - Added to OP_TABLE for operation dispatch PHASE D: Execution loop enhancement (xic_vm.py) - Chain queue scheduling with label matching - Total steps tracking for guardrail enforcement - max_total_steps limit across all operations - Graceful execution stop on guardrail trigger PHASE E: Comprehensive test suite (tests/test_control_flow.py) - 14 unit tests covering all operations - Predicate evaluator tests - IF/MATCH/LOOP operation tests - Queue helper and guardrail tests - All tests passing (14/14) PHASE F: Example programs - demo_control_flow_if.gx.json: IF branching example - demo_control_flow_loop.gx.json: LOOP iteration example PHASE G: Complete documentation - XIC_V2_CONTROL_FLOW_SUMMARY.md: Technical guide - XIC_V2_QUICK_REFERENCE.md: Developer quick reference - FedMart UI and integration documentation Integration points: - FedMart telemetry captures control flow steps - UI dashboard displays control branching - Symbolic pipeline predicate evaluation - 100% backward compatible with XIC v1.5 Test results: 36/36 passing (14 control flow + 12 FedMart + 10 UI) Status: Production ready
This commit is contained in:
GlyphRunner System
+261
@@ -0,0 +1,261 @@
|
||||
# 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! 🚀
|
||||
|
||||
Reference in New Issue
Block a user