[Refactor] Simplify package structure and enhance API surface; add multi-strategy comparison tools

Author: KarhouTam

src/quanteval/__init__.py

@@ -1,64 +1,29 @@
-"""
-QuantEval - 量化策略与因子评估平台
-A comprehensive platform for evaluating quantitative trading strategies and factors.
+"""QuantEval public package surface.
 
-Author: KarhouTam
-License: MIT
+Expose a minimal, stable API for most users. Keep surface area small to
+avoid importing heavy internals on package import.
 """
 
 __version__ = '1.0.0'
 
-# Core components
+# Core
 from quanteval.core.strategy import Strategy
-from quanteval.core.backtester import (
-    Backtester,
-    BacktestResults,
-    MultiBacktestResults,
-    MetricsSnapshot,
-)
+from quanteval.core.backtester import Backtester, BacktestResults
 from quanteval.core.transaction import TransactionCost, HKTransactionCost
 
-# Data management
+# Data
 from quanteval.data.loader import DataLoader
 
 # Metrics
 from quanteval.metrics.performance import PerformanceMetrics
 
-# Factors
+# Factor base
 from quanteval.factors.base import Factor
-from quanteval.factors.technical import (
-    SMA,
-    EMA,
-    RSI,
-    MACD,
-    BollingerBands,
-    ATR,
-    Momentum,
-    VolumeMA,
-    ROC,
-    StochasticOscillator,
-)
-from quanteval.aggregators import (
-    FactorAggregator,
-    EqualWeightAggregator,
-    ICWeightedAggregator,
-)
-from quanteval.strategies.multi_factor_model import MultiFactorModel
-
-# Benchmark strategies
-from quanteval.strategies.dual_ma import DualMAStrategy
-from quanteval.strategies.bollinger_mean_reversion import BollingerMeanReversionStrategy
-from quanteval.strategies.buy_hold import BuyAndHoldStrategy
 
-# Optimization
-from quanteval.optimization import GridSearch, WalkForwardAnalysis
-
-# Comparison
-from quanteval.comparison import StrategyComparator, StrategyComparison
+# Small set of utility helpers
 from quanteval.utils.helpers import (
     calculate_returns,
     calculate_cumulative_returns,
-    align_series,
     configure_chinese_font,
 )
 
@@ -67,8 +32,7 @@
     'Strategy',
     'Backtester',
     'BacktestResults',
-    'MultiBacktestResults',
-    'MetricsSnapshot',
+    # Transaction Costs
     'TransactionCost',
     'HKTransactionCost',
     # Data
@@ -77,37 +41,10 @@
     'PerformanceMetrics',
     # Factors
     'Factor',
-    'SMA',
-    'EMA',
-    'RSI',
-    'MACD',
-    'BollingerBands',
-    'ATR',
-    'Momentum',
-    'VolumeMA',
-    'ROC',
-    'StochasticOscillator',
-    # Factor Aggregators
-    'FactorAggregator',
-    'EqualWeightAggregator',
-    'ICWeightedAggregator',
-    # Factor Models
-    'FactorModel',
-    'CompositeFactorModel',
-    'MomentumValueModel',
-    # Strategies
-    'DualMAStrategy',
-    'BollingerMeanReversionStrategy',
-    'BuyAndHoldStrategy',
-    # Optimization
-    'GridSearch',
-    'WalkForwardAnalysis',
-    'MultiFactorModel',
-    # Comparison
-    'StrategyComparator',
-    'StrategyComparison',
+    # Utilities
     'calculate_returns',
-    'calculate_cumulative_returns',
     'align_series',
-    'configure_chinese_font',
+    'calculate_cumulative_returns',
 ]
+
+configure_chinese_font()

src/quanteval/strategies/__init__.py

@@ -6,6 +6,7 @@
 from quanteval.strategies.dual_ma import DualMAStrategy
 from quanteval.strategies.dual_thrust import DualThrustStrategy
 from quanteval.strategies.rsi_reversion import RSIStrategy
+from quanteval.strategies.multi_factor_model import MultiFactorModel
 
 __all__ = [
     'DualMAStrategy',
@@ -14,4 +15,5 @@
     'DualThrustStrategy',
     'RSIStrategy',
     'DonchianChannel',
+    'MultiFactorModel',
 ]

src/quanteval/utils/__init__.py

@@ -6,10 +6,13 @@
     align_series,
     configure_chinese_font,
 )
+from quanteval.utils.comparison import StrategyComparator, StrategyComparison
 
 __all__ = [
     'calculate_returns',
     'calculate_cumulative_returns',
     'align_series',
     'configure_chinese_font',
+    'StrategyComparator',
+    'StrategyComparison',
 ]

src/quanteval/comparison.py src/quanteval/utils/comparison.pysrc/quanteval/comparison.py renamed to src/quanteval/utils/comparison.py

@@ -16,10 +16,10 @@
 
 logger = logging.getLogger(__name__)
 
-from .core.strategy import Strategy
-from .core.backtester import Backtester, BacktestResults
-from .core.transaction import TransactionCost
-from .utils.helpers import configure_chinese_font
+from ..core.strategy import Strategy
+from ..core.backtester import Backtester, BacktestResults
+from ..core.transaction import TransactionCost
+from .helpers import configure_chinese_font
 
 
 @dataclass
@@ -514,7 +514,7 @@ def create_equal_weight_portfolio(
         benchmark_equity = None if benchmark_returns is None else (1 + benchmark_returns).cumprod()
 
         # Calculate metrics
-        from .metrics.performance import PerformanceMetrics
+        from ..metrics.performance import PerformanceMetrics
 
         perf = PerformanceMetrics(
             strategy_returns=portfolio_returns,

tests/test_comparison.py

@@ -1,6 +1,7 @@
 import pandas as pd
 
-from quanteval import BollingerMeanReversionStrategy, DualMAStrategy, StrategyComparator
+from quanteval.strategies import BollingerMeanReversionStrategy, DualMAStrategy
+from quanteval.utils.comparison import StrategyComparator
 
 
 def test_strategy_comparison_builds_metrics_table(sample_market_data: pd.DataFrame) -> None:

tests/test_core.py

@@ -1,7 +1,9 @@
 import pandas as pd
 import pytest
 
-from quanteval import Backtester, DualMAStrategy, TransactionCost
+from quanteval.core.backtester import Backtester
+from quanteval.strategies import DualMAStrategy
+from quanteval.core.transaction import TransactionCost
 
 
 def test_backtester_adds_returns_when_missing(sample_market_data: pd.DataFrame) -> None:

tests/test_data_loader.py

@@ -4,7 +4,7 @@
 import pandas as pd
 import pytest
 
-from quanteval import DataLoader
+from quanteval.data.loader import DataLoader
 
 
 def test_load_stock_uses_cache_when_available(

tests/test_factors.py

@@ -1,6 +1,6 @@
 import pandas as pd
 
-from quanteval import (
+from quanteval.factors import (
     ATR,
     BollingerBands,
     MACD,

tests/test_multi_factor_model.py

@@ -4,77 +4,76 @@
 
 from quanteval.strategies.multi_factor_model import MultiFactorModel
 from quanteval.aggregators.weighted import (
-	EqualWeightAggregator,
-	ICWeightedAggregator,
+    EqualWeightAggregator,
+    ICWeightedAggregator,
 )
 from quanteval.factors.base import Factor
 
 
 def test_equal_weight_aggregator_without_normalize(sample_market_data: pd.DataFrame) -> None:
-	data = sample_market_data
-	idx = data.index
-	s1 = data['Close'].pct_change().fillna(0)
-	s2 = -s1
+    data = sample_market_data
+    idx = data.index
+    s1 = data['Close'].pct_change().fillna(0)
+    s2 = -s1
 
-	agg = EqualWeightAggregator(normalize=False)
-	composite = agg.aggregate({'s1': s1, 's2': s2}, data)
+    agg = EqualWeightAggregator(normalize=False)
+    composite = agg.aggregate({'s1': s1, 's2': s2}, data)
 
-	expected = (s1.reindex(idx) + s2.reindex(idx)) / 2
-	pd.testing.assert_series_equal(composite, expected, check_names=False)
+    expected = (s1.reindex(idx) + s2.reindex(idx)) / 2
+    pd.testing.assert_series_equal(composite, expected, check_names=False)
 
 
 def test_icweighted_fallback_to_equal_weights(sample_market_data: pd.DataFrame) -> None:
-	# Force forward returns to be NaN so IC is unavailable and aggregator falls
-	# back to equal weights.
-	data = sample_market_data.copy()
-	data['Close'] = np.nan
-	idx = data.index
+    # Force forward returns to be NaN so IC is unavailable and aggregator falls
+    # back to equal weights.
+    data = sample_market_data.copy()
+    data['Close'] = np.nan
+    idx = data.index
 
-	s1 = pd.Series(np.arange(len(idx)), index=idx, name='s1')
-	s2 = pd.Series(np.arange(len(idx)) * 2.0, index=idx, name='s2')
+    s1 = pd.Series(np.arange(len(idx)), index=idx, name='s1')
+    s2 = pd.Series(np.arange(len(idx)) * 2.0, index=idx, name='s2')
 
-	agg = ICWeightedAggregator(normalize=False, ic_window=3, min_periods=1)
-	composite = agg.aggregate({'s1': s1, 's2': s2}, data)
+    agg = ICWeightedAggregator(normalize=False, ic_window=3, min_periods=1)
+    composite = agg.aggregate({'s1': s1, 's2': s2}, data)
 
-	expected = (s1 + s2) / 2
-	pd.testing.assert_series_equal(composite, expected, check_names=False)
+    expected = (s1 + s2) / 2
+    pd.testing.assert_series_equal(composite, expected, check_names=False)
 
 
 class ConstantFactor(Factor):
-	def __init__(self, name: str, series: pd.Series):
-		super().__init__(name=name)
-		self._series = series
+    def __init__(self, name: str, series: pd.Series):
+        super().__init__(name=name)
+        self._series = series
 
-	def calculate(self, data: pd.DataFrame) -> pd.Series:
-		return self._series.reindex(data.index)
+    def calculate(self, data: pd.DataFrame) -> pd.Series:
+        return self._series.reindex(data.index)
 
 
 def test_multi_factor_model_signals_and_type_error(sample_market_data: pd.DataFrame) -> None:
-	data = sample_market_data.iloc[:4]
-	idx = data.index
+    data = sample_market_data.iloc[:4]
+    idx = data.index
 
-	s = pd.Series([0.0, 1.0, 0.0, 1.0], index=idx)
-	f1 = ConstantFactor('f1', s)
-	f2 = ConstantFactor('f2', s)
+    s = pd.Series([0.0, 1.0, 0.0, 1.0], index=idx)
+    f1 = ConstantFactor('f1', s)
+    f2 = ConstantFactor('f2', s)
 
-	agg = EqualWeightAggregator(normalize=False)
-	model = MultiFactorModel([f1, f2], aggregator=agg, threshold=0.5)
+    agg = EqualWeightAggregator(normalize=False)
+    model = MultiFactorModel([f1, f2], aggregator=agg, threshold=0.5)
 
-	signals = model.generate_signals(data)
-	expected = (((s + s) / 2) > 0.5).astype(float).ffill().fillna(0.0)
-	expected.name = signals.name
-	pd.testing.assert_series_equal(signals, expected)
+    signals = model.generate_signals(data)
+    expected = (((s + s) / 2) > 0.5).astype(float).ffill().fillna(0.0)
+    expected.name = signals.name
+    pd.testing.assert_series_equal(signals, expected)
 
-	# Factor returning a dict should raise TypeError
-	class DictFactor(Factor):
-		def __init__(self):
-			super().__init__(name='dict')
+    # Factor returning a dict should raise TypeError
+    class DictFactor(Factor):
+        def __init__(self):
+            super().__init__(name='dict')
 
-		def calculate(self, data: pd.DataFrame):
-			return {'a': pd.Series([1] * len(data), index=data.index)}
-
-	bad = DictFactor()
-	model2 = MultiFactorModel([bad], aggregator=agg)
-	with pytest.raises(TypeError):
-		model2.generate_signals(data)
+        def calculate(self, data: pd.DataFrame):
+            return {'a': pd.Series([1] * len(data), index=data.index)}
 
+    bad = DictFactor()
+    model2 = MultiFactorModel([bad], aggregator=agg)
+    with pytest.raises(TypeError):
+        model2.generate_signals(data)

tests/test_optimization.py

@@ -1,6 +1,7 @@
 import pandas as pd
 
-from quanteval import DualMAStrategy, GridSearch, WalkForwardAnalysis
+from quanteval.strategies import DualMAStrategy
+from quanteval.optimization import GridSearch, WalkForwardAnalysis
 
 
 def test_grid_search_finds_best_params(sample_market_data: pd.DataFrame) -> None: