Merge pull request #46 from AKKI0511/implement-advanced-market-impact-models

feat(backtest): add intrabar fills and borrow fees

Author: AKKI0511

README.md

@@ -21,7 +21,7 @@
 - 📊 Data: YFinance/AlphaVantage loaders, caching, validation
 - 🧪 Features: technical indicators, custom signals, optional LLM sentiment
 - 🤖 Models: ensemble VotingClassifier (LR, RF, XGBoost) with Optuna tuning
-- 📈 Backtesting: execution costs, slippage, liquidity limits, market impact modeling, portfolio helpers
+- 📈 Backtesting: execution costs, slippage, liquidity limits, adaptive impact, intrabar fills, borrow fees
 - 🛡️ Risk management: drawdown and turnover guards
 - 📟 Live trading: real-time position manager with intraday risk controls
 - 🛠️ CLI: end‑to‑end pipeline, evaluation, and model backtest in one place

docs/README.md

@@ -132,10 +132,11 @@ QuantTradeAI/
 - **Model persistence** and loading
 
 ### Backtesting
-- **Trade simulation** with realistic constraints
+- **Trade simulation** with limit/stop orders and intrabar tick fills
+- **Adaptive market impact modeling** with dynamic spreads and asymmetric coefficients
+- **Borrow fee accounting** for short positions
 - **Risk management** (stop-loss, take-profit)
 - **Performance metrics** (Sharpe ratio, max drawdown)
-- **Market impact modeling** for execution cost realism
 - **Position sizing** based on risk parameters
 
 ### Risk Management

docs/api/backtesting.md

@@ -16,15 +16,18 @@ API documentation for trade simulation and performance metrics.
 
 Simulates trades using label signals.  The ``transaction_cost`` and ``slippage``
 arguments are shorthand for populating the ``execution`` configuration, which
-can also specify liquidity and market impact parameters.
+can also specify liquidity, market impact, borrow fees, and intrabar simulation
+parameters. The engine supports market, limit, and stop orders with partial
+fills.
 
 **Parameters:**
 - `df` (pd.DataFrame or dict[str, pd.DataFrame]): Single DataFrame or mapping of symbol to DataFrame with Close prices and label column
 - `stop_loss_pct` (float, optional): Stop-loss percentage as decimal
 - `take_profit_pct` (float, optional): Take-profit percentage as decimal
 - `transaction_cost` (float, optional): Transaction cost in decimal bps
 - `slippage` (float, optional): Slippage cost in decimal bps
-- `execution` (dict, optional): Detailed execution settings including `transaction_costs`, `slippage`, `liquidity`, and `impact`
+- `execution` (dict, optional): Detailed execution settings including `transaction_costs`, `slippage`, `liquidity`, `impact`,
+  `borrow_fee`, and `intrabar`
 - `portfolio` (PortfolioManager, optional): Portfolio manager required when `df` is a dictionary
 
 **Returns:**
@@ -34,7 +37,7 @@ can also specify liquidity and market impact parameters.
 ```python
 from quanttradeai import simulate_trades
 
-# Simulate trades with market impact
+# Simulate trades with intrabar fills and borrow fees
 df_with_trades = simulate_trades(
     df,
     execution={
@@ -45,7 +48,9 @@ df_with_trades = simulate_trades(
             "beta": 0.0,
             "average_daily_volume": 1_000_000,
             "spread": 0.02,
-        }
+        },
+        "intrabar": {"enabled": True, "synthetic_ticks": 20, "volatility": 0.01},
+        "borrow_fee": {"enabled": True, "rate_bps": 100},
     },
 )
 ```

docs/configuration.md

@@ -114,15 +114,32 @@ execution:
     model: linear        # linear, square_root, almgren_chriss
     alpha: 0.0
     beta: 0.0
+    alpha_buy: 0.0       # optional asymmetric coefficients
+    alpha_sell: 0.0
     decay: 0.0           # temporary impact decay rate
+    decay_volume_coeff: 0.0
     spread: 0.0          # bid-ask spread per share
+    spread_model: {type: dynamic}
     average_daily_volume: 0
+  borrow_fee:
+    enabled: false
+    rate_bps: 0
+  intrabar:
+    enabled: false
+    drift: 0.0
+    volatility: 0.0
+    synthetic_ticks: 0
 ```
 
-The `impact` block activates market impact modeling.  Parameters `alpha`,
-`beta`, and optional `gamma` control the chosen model, while `decay` and
-`spread` apply temporary impact decay and bid-ask spread costs.  Default
-parameter sets per asset class can be defined in `config/impact_config.yaml`.
+The `impact` block activates market impact modeling. Parameters `alpha`/`beta`
+and their buy/sell counterparts control the chosen model, while `decay`,
+`decay_volume_coeff`, and `spread_model` enable dynamic spread and volume-based
+decay. Default parameter sets per asset class can be defined in
+`config/impact_config.yaml`.
+
+The `borrow_fee` block applies financing costs to short positions, and the
+`intrabar` block enables tick-level fill simulation with optional synthetic
+Brownian motion ticks.
 
 ### Position Manager
 

docs/quick-reference.md

@@ -71,7 +71,7 @@ classifier.save_model("models/trained/AAPL")
 ```python
 from quanttradeai import simulate_trades, compute_metrics
 
-# Simulate trades with market impact
+# Simulate trades with intrabar fills and market impact
 df_trades = simulate_trades(
     df_labeled,
     execution={
@@ -81,7 +81,9 @@ df_trades = simulate_trades(
             "alpha": 0.5,
             "beta": 0.0,
             "average_daily_volume": 1_000_000,
-        }
+        },
+        "intrabar": {"enabled": True, "synthetic_ticks": 20, "volatility": 0.01},
+        "borrow_fee": {"enabled": True, "rate_bps": 100},
     },
 )
 

quanttradeai/__init__.py

@@ -1,72 +1,76 @@
-"""QuantTradeAI
-=================
-
-High-level interface for the QuantTradeAI toolkit.  The package bundles
-data acquisition, feature engineering, model training and backtesting
-utilities for quantitative trading research.
-
-Public API:
-    - ``DataSource`` and concrete implementations
-    - ``DataLoader`` and ``DataProcessor``
-    - ``MomentumClassifier`` model
-    - ``PortfolioManager`` and risk helpers
-    - ``simulate_trades`` and ``compute_metrics`` for backtesting
-
-Quick Start:
-    ```python
-    from quanttradeai import DataLoader, DataProcessor, MomentumClassifier
-
-    loader = DataLoader()
-    data = loader.fetch_data()
-    processor = DataProcessor()
-    processed = {s: processor.process_data(df) for s, df in data.items()}
-    model = MomentumClassifier()
-    ```
-"""
-
-from .data.datasource import (
-    DataSource,
-    YFinanceDataSource,
-    AlphaVantageDataSource,
-    WebSocketDataSource,
-)
-
-# Lazily import optional dependencies to keep lightweight usage possible
-from .data.loader import DataLoader
-from .data.processor import DataProcessor
-
-try:  # pragma: no cover - optional heavy dependency
-    from .models.classifier import MomentumClassifier
-except Exception:  # pragma: no cover - tolerate missing ML libs
-    MomentumClassifier = None  # type: ignore[assignment]
-from .trading.portfolio import PortfolioManager
-from .trading.risk import apply_stop_loss_take_profit, position_size
-from .backtest import (
-    simulate_trades,
-    compute_metrics,
-    MarketImpactModel,
-    LinearImpactModel,
-    SquareRootImpactModel,
-    AlmgrenChrissModel,
-    ImpactCalculator,
-)
-
-__all__ = [
-    "DataSource",
-    "YFinanceDataSource",
-    "AlphaVantageDataSource",
-    "WebSocketDataSource",
-    "DataLoader",
-    "DataProcessor",
-    "MomentumClassifier",
-    "PortfolioManager",
-    "apply_stop_loss_take_profit",
-    "position_size",
-    "simulate_trades",
-    "compute_metrics",
-    "MarketImpactModel",
-    "LinearImpactModel",
-    "SquareRootImpactModel",
-    "AlmgrenChrissModel",
-    "ImpactCalculator",
-]
+"""QuantTradeAI
+=================
+
+High-level interface for the QuantTradeAI toolkit.  The package bundles
+data acquisition, feature engineering, model training and backtesting
+utilities for quantitative trading research.
+
+Public API:
+    - ``DataSource`` and concrete implementations
+    - ``DataLoader`` and ``DataProcessor``
+    - ``MomentumClassifier`` model
+    - ``PortfolioManager`` and risk helpers
+    - ``simulate_trades`` and ``compute_metrics`` for backtesting
+
+Quick Start:
+    ```python
+    from quanttradeai import DataLoader, DataProcessor, MomentumClassifier
+
+    loader = DataLoader()
+    data = loader.fetch_data()
+    processor = DataProcessor()
+    processed = {s: processor.process_data(df) for s, df in data.items()}
+    model = MomentumClassifier()
+    ```
+"""
+
+from .data.datasource import (
+    DataSource,
+    YFinanceDataSource,
+    AlphaVantageDataSource,
+    WebSocketDataSource,
+)
+
+# Lazily import optional dependencies to keep lightweight usage possible
+from .data.loader import DataLoader
+from .data.processor import DataProcessor
+
+try:  # pragma: no cover - optional heavy dependency
+    from .models.classifier import MomentumClassifier
+except Exception:  # pragma: no cover - tolerate missing ML libs
+    MomentumClassifier = None  # type: ignore[assignment]
+from .trading.portfolio import PortfolioManager
+from .trading.risk import apply_stop_loss_take_profit, position_size
+from .backtest import (
+    simulate_trades,
+    compute_metrics,
+    MarketImpactModel,
+    LinearImpactModel,
+    SquareRootImpactModel,
+    AlmgrenChrissModel,
+    ImpactCalculator,
+    DynamicSpreadModel,
+    BacktestEngine,
+)
+
+__all__ = [
+    "DataSource",
+    "YFinanceDataSource",
+    "AlphaVantageDataSource",
+    "WebSocketDataSource",
+    "DataLoader",
+    "DataProcessor",
+    "MomentumClassifier",
+    "PortfolioManager",
+    "apply_stop_loss_take_profit",
+    "position_size",
+    "simulate_trades",
+    "compute_metrics",
+    "MarketImpactModel",
+    "LinearImpactModel",
+    "SquareRootImpactModel",
+    "AlmgrenChrissModel",
+    "ImpactCalculator",
+    "DynamicSpreadModel",
+    "BacktestEngine",
+]

quanttradeai/backtest/__init__.py

@@ -15,12 +15,14 @@
 """
 
 from .backtester import simulate_trades, compute_metrics
+from .engine import BacktestEngine
 from .impact import (
     MarketImpactModel,
     LinearImpactModel,
     SquareRootImpactModel,
     AlmgrenChrissModel,
     ImpactCalculator,
+    DynamicSpreadModel,
 )
 
 __all__ = [
@@ -31,4 +33,6 @@
     "SquareRootImpactModel",
     "AlmgrenChrissModel",
     "ImpactCalculator",
+    "DynamicSpreadModel",
+    "BacktestEngine",
 ]