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
362
nautilus_dolphin/NAUTILUS_BRINGUP_SPEC.md
Executable file
362
nautilus_dolphin/NAUTILUS_BRINGUP_SPEC.md
Executable file
@@ -0,0 +1,362 @@
|
||||
# Nautilus-Dolphin Bring-Up Specification
|
||||
|
||||
**Date:** 2026-02-19
|
||||
**Status:** Test Suite Analysis Complete
|
||||
**Next Phase:** Fix Import Dependencies
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
Test suite analysis completed. **2 of 10 test files PASS**, 8 require fixes.
|
||||
|
||||
### Test Results Summary
|
||||
|
||||
| Test File | Status | Issue |
|
||||
|-----------|--------|-------|
|
||||
| `test_acb_standalone.py` | **PASS** | None |
|
||||
| `test_acb_nautilus_vs_reference.py` | **PASS** | None (with skips) |
|
||||
| `test_adaptive_circuit_breaker.py` | **FAIL** | ImportError via __init__.py |
|
||||
| `test_circuit_breaker.py` | **FAIL** | ImportError via __init__.py |
|
||||
| `test_metrics_monitor.py` | **FAIL** | ImportError via __init__.py |
|
||||
| `test_position_manager.py` | **FAIL** | ImportError via __init__.py |
|
||||
| `test_signal_bridge.py` | **FAIL** | ImportError - Nautilus Trader missing |
|
||||
| `test_smart_exec_algorithm.py` | **FAIL** | ImportError - Nautilus Trader missing |
|
||||
| `test_strategy.py` | **FAIL** | ImportError via __init__.py |
|
||||
| `test_volatility_detector.py` | **FAIL** | ImportError via __init__.py |
|
||||
|
||||
---
|
||||
|
||||
## Root Cause Analysis
|
||||
|
||||
### Primary Issue: `nautilus/__init__.py` Imports
|
||||
|
||||
The `nautilus_dolphin/nautilus_dolphin/nautilus/__init__.py` file imports ALL modules, including those that depend on Nautilus Trader:
|
||||
|
||||
```python
|
||||
from nautilus_dolphin.nautilus.signal_bridge import SignalBridgeActor # Requires Nautilus
|
||||
from nautilus_dolphin.nautilus.strategy import DolphinExecutionStrategy # Requires Nautilus
|
||||
from nautilus_dolphin.nautilus.smart_exec_algorithm import SmartExecAlgorithm # Requires Nautilus
|
||||
...
|
||||
```
|
||||
|
||||
When ANY test imports from `nautilus`, it triggers the `__init__.py`, which tries to import Nautilus Trader dependencies that don't exist.
|
||||
|
||||
### Secondary Issue: Nautilus Trader Not Installed
|
||||
|
||||
Tests that actually use Nautilus Trader classes fail with:
|
||||
```
|
||||
ModuleNotFoundError: No module named 'nautilus_trader.trading.actor'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Required Fixes (Priority Order)
|
||||
|
||||
### FIX 1: Make `nautilus/__init__.py` Optional (HIGH PRIORITY)
|
||||
|
||||
**File:** `nautilus_dolphin/nautilus_dolphin/nautilus/__init__.py`
|
||||
|
||||
**Problem:** Unconditionally imports all modules, including Nautilus-dependent ones.
|
||||
|
||||
**Solution:** Wrap imports in try/except to allow non-Nautilus modules to be imported:
|
||||
|
||||
```python
|
||||
"""Nautilus components for DOLPHIN NG HD trading system."""
|
||||
|
||||
# Core components (no Nautilus dependency)
|
||||
from nautilus_dolphin.nautilus.circuit_breaker import CircuitBreakerManager, CircuitBreakerReason
|
||||
from nautilus_dolphin.nautilus.metrics_monitor import MetricsMonitor, ThresholdConfig
|
||||
from nautilus_dolphin.nautilus.adaptive_circuit_breaker import (
|
||||
AdaptiveCircuitBreaker, ACBConfig, ACBPositionSizer
|
||||
)
|
||||
|
||||
# Optional Nautilus-dependent components
|
||||
try:
|
||||
from nautilus_dolphin.nautilus.signal_bridge import SignalBridgeActor
|
||||
from nautilus_dolphin.nautilus.strategy import DolphinExecutionStrategy
|
||||
from nautilus_dolphin.nautilus.smart_exec_algorithm import SmartExecAlgorithm
|
||||
from nautilus_dolphin.nautilus.position_manager import PositionManager
|
||||
from nautilus_dolphin.nautilus.volatility_detector import VolatilityRegimeDetector
|
||||
from nautilus_dolphin.nautilus.data_adapter import JSONEigenvalueDataAdapter, BacktestDataLoader
|
||||
NAUTILUS_AVAILABLE = True
|
||||
except ImportError:
|
||||
NAUTILUS_AVAILABLE = False
|
||||
# Log warning or handle gracefully
|
||||
|
||||
__all__ = [
|
||||
# Core (always available)
|
||||
'CircuitBreakerManager',
|
||||
'CircuitBreakerReason',
|
||||
'MetricsMonitor',
|
||||
'ThresholdConfig',
|
||||
'AdaptiveCircuitBreaker',
|
||||
'ACBConfig',
|
||||
'ACBPositionSizer',
|
||||
]
|
||||
|
||||
if NAUTILUS_AVAILABLE:
|
||||
__all__.extend([
|
||||
'SignalBridgeActor',
|
||||
'DolphinExecutionStrategy',
|
||||
'SmartExecAlgorithm',
|
||||
'PositionManager',
|
||||
'VolatilityRegimeDetector',
|
||||
'JSONEigenvalueDataAdapter',
|
||||
'BacktestDataLoader',
|
||||
])
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### FIX 2: Fix Individual Module Imports (MEDIUM PRIORITY)
|
||||
|
||||
For each module that fails, add defensive imports:
|
||||
|
||||
#### `signal_bridge.py`
|
||||
```python
|
||||
try:
|
||||
from nautilus_trader.trading.actor import Actor
|
||||
from nautilus_trader.model.events import SignalEvent
|
||||
NAUTILUS_AVAILABLE = True
|
||||
except ImportError:
|
||||
NAUTILUS_AVAILABLE = False
|
||||
Actor = object # Fallback base class
|
||||
SignalEvent = object
|
||||
```
|
||||
|
||||
#### `strategy.py`
|
||||
```python
|
||||
try:
|
||||
from nautilus_trader.trading.strategy import Strategy
|
||||
from nautilus_trader.model.identifiers import InstrumentId, Venue
|
||||
# ... other imports
|
||||
NAUTILUS_AVAILABLE = True
|
||||
except ImportError:
|
||||
NAUTILUS_AVAILABLE = False
|
||||
Strategy = object
|
||||
# Create mock classes
|
||||
class InstrumentId:
|
||||
@staticmethod
|
||||
def from_str(s): return s
|
||||
class Venue:
|
||||
def __init__(self, s): self.value = s
|
||||
# ... etc
|
||||
```
|
||||
|
||||
#### `smart_exec_algorithm.py`
|
||||
```python
|
||||
try:
|
||||
from nautilus_trader.trading.actor import Actor
|
||||
from nautilus_trader.execution.algorithm import ExecAlgorithm
|
||||
NAUTILUS_AVAILABLE = True
|
||||
except ImportError:
|
||||
NAUTILUS_AVAILABLE = False
|
||||
Actor = object
|
||||
ExecAlgorithm = object
|
||||
```
|
||||
|
||||
#### `position_manager.py`
|
||||
```python
|
||||
try:
|
||||
from nautilus_trader.model.identifiers import InstrumentId
|
||||
from nautilus_trader.model.enums import OrderSide, PositionSide
|
||||
NAUTILUS_AVAILABLE = True
|
||||
except ImportError:
|
||||
NAUTILUS_AVAILABLE = False
|
||||
# Mock classes
|
||||
class OrderSide:
|
||||
BUY = "BUY"
|
||||
SELL = "SELL"
|
||||
class PositionSide:
|
||||
LONG = "LONG"
|
||||
SHORT = "SHORT"
|
||||
```
|
||||
|
||||
#### `volatility_detector.py`
|
||||
```python
|
||||
try:
|
||||
from nautilus_trader.model.data import Bar
|
||||
NAUTILUS_AVAILABLE = True
|
||||
except ImportError:
|
||||
NAUTILUS_AVAILABLE = False
|
||||
Bar = dict # Use dict as fallback
|
||||
```
|
||||
|
||||
#### `data_adapter.py`
|
||||
```python
|
||||
try:
|
||||
from nautilus_trader.model.data import Bar, QuoteTick
|
||||
NAUTILUS_AVAILABLE = True
|
||||
except ImportError:
|
||||
NAUTILUS_AVAILABLE = False
|
||||
Bar = dict
|
||||
QuoteTick = dict
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### FIX 3: Update Test Files (LOW PRIORITY)
|
||||
|
||||
Once modules have defensive imports, tests should work. But some tests may need adjustment:
|
||||
|
||||
#### `test_smart_exec_algorithm.py`
|
||||
- Currently fails: `No module named 'nautilus_trader.trading.actor'`
|
||||
- After FIX 2, should import but tests may fail on mock objects
|
||||
- May need to add `pytest.skipif(not NAUTILUS_AVAILABLE)` decorators
|
||||
|
||||
#### `test_strategy.py`
|
||||
- Similar to above
|
||||
- May need mocking framework for Nautilus classes
|
||||
|
||||
---
|
||||
|
||||
## Implementation Plan
|
||||
|
||||
### Phase 1: Core Module Fixes (Day 1)
|
||||
|
||||
1. **Update `nautilus/__init__.py`**
|
||||
- Wrap Nautilus-dependent imports in try/except
|
||||
- Keep ACB imports unconditional (they work standalone)
|
||||
|
||||
2. **Update `circuit_breaker.py`**
|
||||
- Verify no Nautilus dependencies (should be clean)
|
||||
|
||||
3. **Update `adaptive_circuit_breaker.py`**
|
||||
- Verify standalone operation (already tested)
|
||||
|
||||
4. **Update `metrics_monitor.py`**
|
||||
- Check for Nautilus dependencies
|
||||
- Add defensive imports if needed
|
||||
|
||||
### Phase 2: Nautilus-Dependent Modules (Day 2-3)
|
||||
|
||||
1. **Update `signal_bridge.py`** with defensive imports
|
||||
2. **Update `strategy.py`** with defensive imports
|
||||
3. **Update `smart_exec_algorithm.py`** with defensive imports
|
||||
4. **Update `position_manager.py`** with defensive imports
|
||||
5. **Update `volatility_detector.py`** with defensive imports
|
||||
6. **Update `data_adapter.py`** with defensive imports
|
||||
|
||||
### Phase 3: Test Verification (Day 4)
|
||||
|
||||
1. Re-run full test suite
|
||||
2. Document remaining failures
|
||||
3. Create mock objects for Nautilus classes if needed
|
||||
4. Add skip decorators for tests requiring real Nautilus
|
||||
|
||||
### Phase 4: Documentation (Day 5)
|
||||
|
||||
1. Update README with bring-up status
|
||||
2. Document which features require Nautilus
|
||||
3. Document standalone vs full-Nautilus operation modes
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria
|
||||
|
||||
### Phase 1 Success
|
||||
- `test_circuit_breaker.py` PASSES
|
||||
- `test_adaptive_circuit_breaker.py` PASSES
|
||||
- `test_metrics_monitor.py` PASSES
|
||||
|
||||
### Phase 2 Success
|
||||
- All modules import without errors
|
||||
- `test_signal_bridge.py` runs (may skip some tests)
|
||||
- `test_strategy.py` runs (may skip some tests)
|
||||
- `test_smart_exec_algorithm.py` runs (may skip some tests)
|
||||
|
||||
### Phase 3 Success
|
||||
- All 10 test files run without import errors
|
||||
- At least 70% of tests pass
|
||||
- Remaining failures documented with reasons
|
||||
|
||||
---
|
||||
|
||||
## Files to Modify
|
||||
|
||||
| File | Priority | Changes Needed |
|
||||
|------|----------|----------------|
|
||||
| `nautilus/__init__.py` | HIGH | Wrap imports in try/except |
|
||||
| `signal_bridge.py` | MEDIUM | Defensive Nautilus imports |
|
||||
| `strategy.py` | MEDIUM | Defensive Nautilus imports |
|
||||
| `smart_exec_algorithm.py` | MEDIUM | Defensive Nautilus imports |
|
||||
| `position_manager.py` | MEDIUM | Defensive Nautilus imports |
|
||||
| `volatility_detector.py` | MEDIUM | Defensive Nautilus imports |
|
||||
| `data_adapter.py` | MEDIUM | Defensive Nautilus imports |
|
||||
| `metrics_monitor.py` | LOW | Verify no Nautilus deps |
|
||||
|
||||
---
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
After each fix:
|
||||
|
||||
```bash
|
||||
# Test the fixed module
|
||||
python -c "from nautilus_dolphin.nautilus.xxx import YYY; print('OK')"
|
||||
|
||||
# Run specific test
|
||||
python -m pytest tests/test_xxx.py -v
|
||||
|
||||
# Run full suite
|
||||
python run_all_tests.py
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Current Working State
|
||||
|
||||
The following components are **fully functional** without Nautilus Trader:
|
||||
|
||||
1. **Adaptive Circuit Breaker (ACB)**
|
||||
- `adaptive_circuit_breaker.py` - ✅ Working
|
||||
- `test_acb_standalone.py` - ✅ 23/23 tests pass
|
||||
- `test_acb_nautilus_vs_reference.py` - ✅ Passes (with skips)
|
||||
|
||||
2. **Circuit Breaker (Basic)**
|
||||
- `circuit_breaker.py` - Should work (no Nautilus deps observed)
|
||||
- Tests failing only due to __init__.py import issue
|
||||
|
||||
---
|
||||
|
||||
## Next Action
|
||||
|
||||
**Start with FIX 1:** Modify `nautilus/__init__.py` to make Nautilus-dependent imports optional.
|
||||
|
||||
This single change should enable:
|
||||
- `test_circuit_breaker.py` to pass
|
||||
- `test_adaptive_circuit_breaker.py` to pass
|
||||
- `test_metrics_monitor.py` to pass
|
||||
- `test_position_manager.py` to pass (if no other issues)
|
||||
|
||||
---
|
||||
|
||||
## Appendix: Test Error Log
|
||||
|
||||
### test_adaptive_circuit_breaker.py
|
||||
```
|
||||
ImportError while importing test module
|
||||
nautilus_dolphin.nautilus.circuit_breaker import CircuitBreakerManager
|
||||
```
|
||||
Root cause: __init__.py imports signal_bridge which fails
|
||||
|
||||
### test_circuit_breaker.py
|
||||
```
|
||||
ImportError while importing test module
|
||||
nautilus_dolphin.nautilus.circuit_breaker import CircuitBreakerManager
|
||||
```
|
||||
Root cause: __init__.py imports signal_bridge which fails
|
||||
|
||||
### test_smart_exec_algorithm.py
|
||||
```
|
||||
ModuleNotFoundError: No module named 'nautilus_trader.trading.actor'
|
||||
```
|
||||
Root cause: Direct Nautilus dependency
|
||||
|
||||
### test_strategy.py, test_position_manager.py, test_volatility_detector.py
|
||||
Similar ImportError patterns via __init__.py
|
||||
|
||||
---
|
||||
|
||||
**END OF SPECIFICATION**
|
||||
Reference in New Issue
Block a user