DOLPHIN/nautilus_dolphin/NAUTILUS_BRINGUP_SPEC.md

# 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**