README.md

metadata

title: K1RL QUASAR Executo Hub
emoji: 🛰️
colorFrom: indigo
colorTo: blue
sdk: docker
pinned: false

K1RL QUASAR — Executo Hub

Central WebSocket hub for the K1RL QUASAR system.
Receives live training and voting metrics from all Asset Spaces, normalizes them, and broadcasts snapshots to the Ranker Space in real time.

---

Architecture Role

Asset Space A ──┐
Asset Space B ──┼──► /ws/publish/{space_name} ──► HUB ──► /ws/subscribe ──► Ranker Space
Asset Space C ──┘                                   │
                                                    └──► /rankings  (REST fallback)

The hub sits between publishers (Asset Spaces) and subscribers (Ranker Space). It is strictly one-way — the hub never writes back to publishers, and subscribers never send data to publishers.

---

What This Space Does

• Accepts WebSocket connections from Asset Spaces on /ws/publish/{space_name}
• Accepts WebSocket connections from the Ranker Space on /ws/subscribe
• Validates and normalizes every inbound payload against a strict data model
• Stores the latest snapshot only per asset (no history)
• Broadcasts each update immediately to all connected subscribers
• Serves a live dashboard at / and a REST fallback at /rankings

---

Endpoints

Endpoint	Protocol	Direction	Description
/ws/publish/{space_name}	WebSocket	Asset Space → Hub	Publishers send metrics here
/ws/subscribe	WebSocket	Hub → Ranker	Subscribers receive broadcasts here
/	HTTP GET	—	Live dashboard UI
/rankings	HTTP GET	—	Latest snapshot for all assets
/metrics/{space_name}	HTTP GET	—	Latest snapshot for one asset
/health	HTTP GET	—	Hub health and publisher status
/api/state	HTTP GET	—	Full state polled by dashboard every 2s

---

Data Model

Only these fields are permitted through the hub. All others are silently dropped.

Training

training_steps    int
actor_loss        float
critic_loss       float
avn_loss          float
avn_accuracy      float  (0.0 – 1.0)

Voting

dominant_signal   str    ("BUY" | "SELL" | "NEUTRAL")
buy_count         int
sell_count        int
last_price        float
signal_source     str

---

Accepted Publisher Message Types

Asset Spaces may send any of the following JSON message formats:

// Combined payload
{ "type": "metrics", "training": { ... }, "voting": { ... } }

// Training only
{ "type": "training", "data": { ... } }

// Voting only
{ "type": "voting", "data": { ... } }

// Keep-alive (silently acknowledged, no reply)
{ "type": "heartbeat" }
{ "type": "identify", "space": "space-name" }
{ "type": "ping" }

---

Subscriber Message Types

Newly connected subscribers receive a full current state dump, then live updates as they arrive:

// Sent once on connection
{ "type": "initial_state", "snapshots": { ... }, "hub_timestamp": 1234567890.0 }

// Sent on every inbound publish
{ "type": "metrics_update", "space_name": "...", "snapshot": { ... }, "hub_timestamp": 1234567890.0 }

---

AXRVI Ranking Formula

The /rankings and /api/state endpoints rank assets using:

signal_confidence = max(buy_count, sell_count) / (buy_count + sell_count)
score             = signal_confidence - avn_accuracy

Assets are sorted descending by score.

---

Connecting an Asset Space

Asset Spaces connect using log_metrics_reader.py. The hub URL is resolved automatically from the SPACE_ID environment variable — no configuration is needed inside the asset space files.

The hardcoded target for all asset spaces is:

wss://karlquant-quasar-executo.hf.space/ws/publish/{space_name}

If the hub restarts, asset spaces auto-reconnect within 30 seconds via the built-in exponential back-off in AssetSpacePublisher._run_loop. No intervention is needed.

---

Deploying a New Hub Version

To update the hub without triggering any asset space restarts:

1. Upload the new websocket_hub.py to this Space only
2. This Space restarts and begins accepting connections on the same URL
3. Asset spaces detect the disconnection and reconnect automatically

No changes are needed to log_metrics_reader.py or any asset space env vars.

---

Files

File	Purpose
websocket_hub.py	Hub server — FastAPI + WebSocket engine
hub_dashboard.html	Live dashboard UI served at /
requirements.txt	fastapi, uvicorn, websockets

---

Runtime

Setting	Value
Default port	7860 (override via PORT env var)
Dashboard HTML path	Override via DASHBOARD_HTML env var
Host	0.0.0.0

---

Version

v2.0-arch-strict — strict data model, event-driven broadcast, deep-copy safe ingestion pipeline.