.qodo/

/data_cache

/figures

/logs

/run

/logs

/.run

/.vscode

<p align="center">

<img src="./assets/trader_pp_logo.png" alt="Trader++ Logo" width="100%" style="object-fit:cover;height:300px;object-position:center;border-radius:12px;box-shadow:0 4px 24px rgba(0,0,0,0.10);" />

</p>

- Common interface: `BacktestExecutor`, `PaperExecutor`, `LiveExecutor`

- Live broker integration (Alpaca, IBKR, TD Ameritrade)

- Real-time slippage, partial fills, latency simulation

- YAML/DSL config loader for no-code strategies

- Multi-frequency, multi-asset support

- ML model integration (Torch/Sklearn) + MLFlow/W&B logging

- Position sizing (Kelly, risk parity, volatility targeting)

- Real-time rule engine (e.g., freeze strategy on drawdown)

- Hierarchical/nested portfolios with capital/risk constraints

- Alpha, beta, Sharpe, Sortino, Calmar

- Attribution by asset, sector, strategy

- Trade replay and audit trail

- Streamlit/Dash hybrid dashboard

- Trade timeline, rolling metrics, slippage/turnover/holding histograms

- Multiprocessed/multithreaded backtesting core

- GPU acceleration for ML strategies

- Clean, event-driven simulation loop

- SQL/Parquet backend support

- Live feed adapters

- Flexible bar aggregators (time, volume, event)

- Sentiment and alt-data adapters (Reddit, news, Google Trends)

- Cointegration, Kalman filter, auto-correlation modules

- Unit tests for each module

- Example strategies (momentum, mean-reversion, breakout)

- Jupyter/Streamlit demo notebooks

| Feature | Status | Notes |

|-----------------------------------|-------------|----------------------------------------------------------------------------------------------------------------|

| Unified Execution Engine | ✅ Complete | Backtest, Paper, Live modes implemented with shared API. Paper & Live mode requires broker API implementation. |

| Modular Strategy Framework | ✅ Complete | StrategyBase and example strategies present. Plug-and-play. |

| Portfolio/Risk Management | ✅ Complete | Portfolio class, guardrails, position sizing hooks implemented. |

| Analytics & Attribution | ✅ Partial | Core metrics (Sharpe, alpha, etc.) present. Some advanced analytics in progress. |

| Interactive Dashboard | ⚠️ Partial | Streamlit app exists, some features stubbed or in progress. |

| Scalable Simulation Engine | ⚠️ Partial | Event-driven core present; multiprocessing support basic or planned. |

| Data Layer | ✅ Complete | Data ingestion, caching, and basic adapters present. |

| ML/DSL Integration | 🚧 Planned | ML model integration and YAML/DSL loader planned. |

- Expand broker integrations for live trading

- Enhance dashboard with more analytics and controls

- Add ML/DSL strategy support

- Improve test coverage and documentation

- `contracts/` — Core contracts and abstract base classes (Portfolio, StrategyBase, Executor)

- `core/` — Core logic, execution engines, simulation loop

- `strategies/` — Example and user strategies (momentum, buy & hold, etc.)

- `data_ingestion/`, `data_cache/` — Data loaders, adapters, and caching for reproducible research

- `analytics/`, `ml_engine/` — Analytics, reporting, and ML integrations

- `dashboard/` — Streamlit/Dash dashboard for visualization

- `run_backtest.py` — CLI entry point to run backtests

- `main.py`, `run/` — Additional CLI tools and runners

1. **Finalize Core Contracts**

- Audit and refine `Portfolio`, `StrategyBase`, and `PortfolioExecutor` for strict modularity and safety (no future leaks).

2. **Strategy API**

- Enforce and document the `generate_signals` interface. Add more example strategies.

3. **Backtesting Engine**

- Expand test coverage and logging in `run_backtest.py` and `core/executors/backtest.py`.

4. **Data Layer**

- Ensure robust, reproducible data ingestion and caching. Document data contracts.

5. **CLI & Developer Experience**

- Improve CLI usability and add clear usage examples.

6. **Dashboard & Analytics**

- Expand analytics and dashboard integration for portfolio and strategy reporting.

7. **Documentation**

- Add docstrings, inline docs, and contribution guidelines for new modules and strategies.

- 📈 **Backtesting Engine** — Realistic execution, guardrails, cash shares checks

- 🛡️ **GuardrailBase System** — Risk management hooks (stop-loss, asset unregister)

1. **Install Requirements**

```bash

pip install -r requirements.txt

```

2. **Run a Backtest**

```bash

python main.py --start=2022-05-29 --end=2025-05-29 --cash 50000 --plot --export --tickers=META --refresh --strategy=momentum --benchmark=META --guardrail=trailing_stop_loss

```

3. **Add a New Strategy**

- Implement a new class in `strategies/` inheriting from `StrategyBase` and implementing `generate_signals()`.

- Register your strategy by importing it in `strategies/__init__.py`.

4 **Add a New Guardrail**

- Implement a new class in `guardrails/` inheriting from `GuardrailBase` and implementing `evaluate()`.

- Register your guardrail by importing it in `guardrails/__init__.py`.

[//]: # (- See the Development Roadmap above for high-priority areas.)

- Add new strategies, data adapters, or analytics modules as composable units.

- Follow modular design and document your code.

- PRs and issues welcome!

Enjoy building and experimenting with Trader++! 🚀

from typing import Optional, Dict

import pandas as pd

import numpy as np

class PerformanceEvaluator:

"""

def __init__(self,

portfolio_curve: pd.Series,

benchmark_curve: pd.Series,

risk_free_rate: float = 0.0):

"""

self.portfolio_curve = portfolio_curve#.sort_index()

self.benchmark_curve = benchmark_curve#.sort_index()

self.risk_free_rate = risk_free_rate

# self._align_curves()

# def _align_curves(self):

# # Align curves to common dates

# common_idx = self.portfolio_curve.index.intersection(self.benchmark_curve.index)

# self.portfolio_curve = self.portfolio_curve.loc[common_idx]

# self.benchmark_curve = self.benchmark_curve.loc[common_idx]

def compute_metrics(self) -> Dict[str, float]:

"""

port_ret = self.portfolio_curve.pct_change().dropna()

bench_ret = self.benchmark_curve.pct_change().dropna()

# Align returns

port_ret, bench_ret = port_ret.align(bench_ret, join='inner')

# Defensive checks

if len(port_ret) < 2 or len(bench_ret) < 2:

print(f"[WARN] Not enough overlapping data for regression. Portfolio returns: {len(port_ret)}, Benchmark returns: {len(bench_ret)}")

return {

'portfolio_return': np.nan,

'benchmark_return': np.nan,

'active_return': np.nan,

'win': np.nan,

'cagr': np.nan,

'volatility': np.nan,

'sharpe': np.nan,

'alpha': np.nan,

'beta': np.nan,

'max_drawdown': np.nan

}

excess_ret = port_ret - self.risk_free_rate/252

excess_bench = bench_ret - self.risk_free_rate/252

metrics = {}

metrics['portfolio_return'] = (self.portfolio_curve.iloc[-1] / self.portfolio_curve.iloc[0]) - 1

metrics['benchmark_return'] = (self.benchmark_curve.iloc[-1] / self.benchmark_curve.iloc[0]) - 1

metrics['active_return'] = metrics['portfolio_return'] - metrics['benchmark_return']

metrics['win'] = (port_ret > 0).mean()

metrics['cagr'] = port_ret.mean() * 252

metrics['volatility'] = port_ret.std() * np.sqrt(252)

metrics['sharpe'] = excess_ret.mean() / (port_ret.std() + 1e-9) * np.sqrt(252)

# Alpha/Beta via linear regression

try:

X = np.vstack([np.ones(len(excess_bench)), excess_bench.values]).T

alpha, beta = np.linalg.lstsq(X, excess_ret.values, rcond=None)[0]

metrics['alpha'] = alpha * 252 # annualized

metrics['beta'] = beta

except Exception as e:

print(f"[WARN] Could not compute alpha/beta: {e}")

metrics['alpha'] = np.nan

metrics['beta'] = np.nan

# Max drawdown

roll_max = self.portfolio_curve.cummax()

drawdown = (self.portfolio_curve - roll_max) / roll_max

metrics['max_drawdown'] = drawdown.min()

return metrics

def summary(self, as_str: bool = True) -> str | dict[str, float]:

metrics = self.compute_metrics()

if as_str:

return '\n'.join(f"{k}: {v:.4f}" for k, v in metrics.items())

return metrics