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:

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:

"""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

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

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

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

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

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

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:

# 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