initial: import DOLPHIN baseline 2026-04-21 from dolphinng5_predict working tree
Includes core prod + GREEN/BLUE subsystems: - prod/ (BLUE harness, configs, scripts, docs) - nautilus_dolphin/ (GREEN Nautilus-native impl + dvae/ preserved) - adaptive_exit/ (AEM engine + models/bucket_assignments.pkl) - Observability/ (EsoF advisor, TUI, dashboards) - external_factors/ (EsoF producer) - mc_forewarning_qlabs_fork/ (MC regime/envelope) Excludes runtime caches, logs, backups, and reproducible artifacts per .gitignore.
This commit is contained in:
hjnormey
256
prod/docs/EXF_V2_DEPLOYMENT_SUMMARY.md
Executable file
256
prod/docs/EXF_V2_DEPLOYMENT_SUMMARY.md
Executable file
@@ -0,0 +1,256 @@
|
||||
# ExF System v2.0 - Deployment Summary
|
||||
|
||||
**Date**: 2026-03-17
|
||||
**Status**: ✅ DEPLOYED (with known issues)
|
||||
**Components**: 5 files, ~110KB total
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
Successfully implemented a complete External Factors (ExF) data pipeline with:
|
||||
|
||||
1. **Hot Path**: Hazelcast push every 0.5s for real-time alpha engine
|
||||
2. **Durability**: Disk persistence every 5min (NPZ format) for backtests
|
||||
3. **Integrity**: Continuous monitoring with health checks and alerts
|
||||
|
||||
---
|
||||
|
||||
## Files Delivered
|
||||
|
||||
| File | Size | Purpose | Status |
|
||||
|------|------|---------|--------|
|
||||
| `exf_fetcher_flow.py` | 12.4 KB | Prefect orchestration flow | ✅ Updated |
|
||||
| `exf_persistence.py` | 16.9 KB | Disk writer (NPZ format) | ✅ New |
|
||||
| `exf_integrity_monitor.py` | 15.1 KB | Health monitoring & alerts | ✅ New |
|
||||
| `test_exf_integration.py` | 6.9 KB | Integration tests | ✅ New |
|
||||
| `PROD_BRINGUP_GUIDE.md` | 24.5 KB | Operations documentation | ✅ Updated |
|
||||
|
||||
**Total**: 75.8 KB new code + documentation
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────┐
|
||||
│ EXF SYSTEM v2.0 │
|
||||
├─────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Data Providers (8) │
|
||||
│ ├── Binance (funding, OI, L/S, basis, spread, imbalance) │
|
||||
│ ├── Deribit (volatility, funding) ⚠️ HTTP 400 │
|
||||
│ ├── FRED (VIX, DXY, rates) ✅ │
|
||||
│ ├── Alternative.me (F&G) ✅ │
|
||||
│ ├── Blockchain.info (hashrate) ⚠️ HTTP 404 │
|
||||
│ ├── DeFi Llama (TVL) ✅ │
|
||||
│ └── Coinglass (liquidations) ⚠️ HTTP 500 (needs auth) │
|
||||
│ │
|
||||
│ RealTimeExFService (28 indicators defined) │
|
||||
│ ├── In-memory cache (<1ms read) │
|
||||
│ ├── Per-indicator polling (0.5s to 8h intervals) │
|
||||
│ └── Rate limiting per provider │
|
||||
│ │
|
||||
│ Three Parallel Outputs: │
|
||||
│ │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||
│ │ HAZELCAST │ │ DISK │ │ MONITOR │ │
|
||||
│ │ (Hot Path) │ │ (Off Hot Path) │ │ (Background) │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ Interval: 0.5s │ │ Interval: 5min │ │ Interval: 60s │ │
|
||||
│ │ Latency: <10ms │ │ Latency: N/A │ │ Latency: N/A │ │
|
||||
│ │ Format: JSON │ │ Format: NPZ │ │ Output: Alerts │ │
|
||||
│ │ Key: exf_latest │ │ Path: eigenvalues/YYYY-MM-DD/ │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ Consumer: │ │ Consumer: │ │ Actions: │ │
|
||||
│ │ Alpha Engine │ │ Backtests │ │ Log/Alert │ │
|
||||
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Indicators Status (28 Defined)
|
||||
|
||||
| Category | Indicators | Working | Issues |
|
||||
|----------|-----------|---------|--------|
|
||||
| **Binance** (9) | funding_btc, funding_eth, oi_btc, oi_eth, ls_btc, ls_eth, ls_top, taker, basis, spread, imbal_* | ✅ 9/9 | None |
|
||||
| **Deribit** (4) | dvol_btc, dvol_eth, fund_dbt_btc, fund_dbt_eth | ⚠️ 0/4 | HTTP 400 |
|
||||
| **FRED** (5) | vix, dxy, us10y, sp500, fedfunds | ✅ 5/5 | None |
|
||||
| **Sentiment** (1) | fng | ✅ 1/1 | None |
|
||||
| **On-chain** (1) | hashrate | ⚠️ 0/1 | HTTP 404 |
|
||||
| **DeFi** (1) | tvl | ✅ 1/1 | None |
|
||||
| **Liquidations** (4) | liq_vol_24h, liq_long_ratio, liq_z_score, liq_percentile | ⚠️ 0/4 | HTTP 500 |
|
||||
|
||||
**Total**: ✅ 16/28 working, ⚠️ 12/28 with issues
|
||||
|
||||
---
|
||||
|
||||
## ACB Readiness
|
||||
|
||||
**ACB-Critical Indicators** (must all be present for alpha engine risk calc):
|
||||
|
||||
```python
|
||||
ACB_KEYS = [
|
||||
"funding_btc", "funding_eth", # ✅ Working
|
||||
"dvol_btc", "dvol_eth", # ⚠️ HTTP 400 (Deribit)
|
||||
"fng", # ✅ Working
|
||||
"vix", # ✅ Working
|
||||
"ls_btc", # ✅ Working
|
||||
"taker", # ✅ Working
|
||||
"oi_btc", # ✅ Working
|
||||
]
|
||||
```
|
||||
|
||||
**Current Status**: 6/9 present → `_acb_ready: False`
|
||||
**Impact**: Alpha engine risk sensitivity **degraded** (no volatility overlay)
|
||||
|
||||
---
|
||||
|
||||
## DOLPHIN Compliance
|
||||
|
||||
### NPZ File Format ✅
|
||||
|
||||
```python
|
||||
# Location
|
||||
/mnt/ng6_data/eigenvalues/{YYYY-MM-DD}/
|
||||
extf_snapshot_{timestamp}__Indicators.npz
|
||||
|
||||
# Contents
|
||||
{
|
||||
"_metadata": json.dumps({
|
||||
"_timestamp_utc": "2026-03-17T12:00:00+00:00",
|
||||
"_version": "1.0",
|
||||
"_staleness_s": {...},
|
||||
}),
|
||||
"basis": np.array([0.01178]),
|
||||
"spread": np.array([0.00143]),
|
||||
...
|
||||
}
|
||||
|
||||
# Checksum
|
||||
extf_snapshot_{timestamp}__Indicators.npz.sha256
|
||||
```
|
||||
|
||||
### Data Sufficiency Check ✅
|
||||
|
||||
```python
|
||||
sufficiency = {
|
||||
'sufficient': True/False,
|
||||
'score': 0.0-1.0, # Overall sufficiency score
|
||||
'acb_critical': "6/9", # ACB indicators present
|
||||
'total_indicators': 16, # All indicators present
|
||||
'freshness': 0.95, # % indicators fresh (<60s)
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Operations
|
||||
|
||||
### Start the System
|
||||
|
||||
```bash
|
||||
cd /root/extf_docs
|
||||
|
||||
# Full production mode
|
||||
python exf_fetcher_flow.py --warmup 30
|
||||
|
||||
# Test mode (no persistence/monitoring)
|
||||
python exf_fetcher_flow.py --no-persist --no-monitor --warmup 15
|
||||
```
|
||||
|
||||
### Check Status
|
||||
|
||||
```bash
|
||||
# Health status
|
||||
python3 << 'EOF'
|
||||
import hazelcast, json
|
||||
client = hazelcast.HazelcastClient(cluster_name='dolphin', cluster_members=['localhost:5701'])
|
||||
data = json.loads(client.get_map("DOLPHIN_FEATURES").get("exf_latest").result())
|
||||
print(f"ACB Ready: {data.get('_acb_ready')}")
|
||||
print(f"Indicators: {data.get('_ok_count')}/{data.get('_expected_count')}")
|
||||
print(f"ACB Present: {data.get('_acb_present')}")
|
||||
print(f"Missing: {data.get('_acb_missing', [])}")
|
||||
client.shutdown()
|
||||
EOF
|
||||
|
||||
# Persistence stats
|
||||
ls -la /mnt/ng6_data/eigenvalues/$(date +%Y-%m-%d)/
|
||||
```
|
||||
|
||||
### Run Integration Tests
|
||||
|
||||
```bash
|
||||
python test_exf_integration.py --duration 30 --test all
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Known Issues
|
||||
|
||||
| Issue | Severity | Indicator | Root Cause | Fix |
|
||||
|-------|----------|-----------|------------|-----|
|
||||
| Deribit HTTP 400 | **HIGH** | dvol_btc, dvol_eth, fund_dbt_* | API endpoint changed or auth required | Update Deribit API calls |
|
||||
| Blockchain 404 | **LOW** | hashrate | Endpoint deprecated | Find alternative API |
|
||||
| Coinglass 500 | **MED** | liq_* | Needs API key | Add authentication header |
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
### P0 (Critical)
|
||||
- [ ] Fix Deribit API endpoints for dvol_btc, dvol_eth
|
||||
- [ ] Without these, ACB will never be ready
|
||||
|
||||
### P1 (High)
|
||||
- [ ] Add Coinglass API authentication for liquidation data
|
||||
- [ ] Add redundancy (multiple providers per indicator)
|
||||
|
||||
### P2 (Medium)
|
||||
- [ ] Expand from 28 to 80+ indicators
|
||||
- [ ] Create Grafana dashboards
|
||||
- [ ] Add Prometheus metrics endpoint
|
||||
|
||||
### P3 (Low)
|
||||
- [ ] Implement per-indicator optimal lags (needs 80+ days data)
|
||||
- [ ] Switch to Arrow format for better performance
|
||||
|
||||
---
|
||||
|
||||
## Monitoring Alerts
|
||||
|
||||
The system generates alerts for:
|
||||
|
||||
| Alert | Severity | Condition |
|
||||
|-------|----------|-----------|
|
||||
| `missing_critical` | **CRITICAL** | ACB indicator missing |
|
||||
| `hz_connectivity` | **CRITICAL** | Hazelcast disconnected |
|
||||
| `staleness` | **WARNING** | Indicator stale > 120s |
|
||||
| `divergence` | **WARNING** | HZ/disk data mismatch > 3 indicators |
|
||||
| `persist_connectivity` | **WARNING** | Disk writer unavailable |
|
||||
|
||||
Alerts are logged to structured JSON and can be integrated with PagerDuty/webhooks.
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
✅ **DELIVERED**:
|
||||
- Complete ExF pipeline (fetch → cache → HZ → disk → monitor)
|
||||
- 28 indicators configured (16 working)
|
||||
- NPZ persistence with checksums
|
||||
- Health monitoring with alerts
|
||||
- Integration tests
|
||||
- Comprehensive documentation
|
||||
|
||||
⚠️ **BLOCKING ISSUES**:
|
||||
- Deribit API returns 400 (affects ACB readiness)
|
||||
- Without dvol_btc/dvol_eth, `_acb_ready` stays `False`
|
||||
|
||||
**Recommendation**: Fix Deribit integration before full production deployment.
|
||||
|
||||
---
|
||||
|
||||
*Generated: 2026-03-17*
|
||||
Reference in New Issue
Block a user