ml4t-backtest 0.1.0a2__tar.gz

ml4t_backtest-0.1.0a2/.gitignore

@@ -0,0 +1,36 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.egg-info/
+dist/
+build/
+eggs/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+
+# mypy
+.mypy_cache/
+
+# Jupyter
+.ipynb_checkpoints/
+src/ml4t/backtest/_version.py

ml4t_backtest-0.1.0a2/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: ml4t-backtest
+Version: 0.1.0a2
+Summary: State-of-the-art event-driven backtesting engine for quantitative trading
+Project-URL: Homepage, https://github.com/ml4t/ml4t-backtest
+Project-URL: Documentation, https://ml4t-backtest.readthedocs.io
+Project-URL: Repository, https://github.com/ml4t/ml4t-backtest
+Project-URL: Issues, https://github.com/ml4t/ml4t-backtest/issues
+Project-URL: Changelog, https://github.com/ml4t/ml4t-backtest/blob/main/CHANGELOG.md
+Author-email: QuantLab Team <info@quantlab.io>
+Maintainer-email: QuantLab Contributors <dev@quantlab.io>
+License: MIT
+Keywords: algorithmic-trading,backtesting,event-driven,execution,finance,polars,portfolio,quantitative-finance,risk-management,simulation,trading
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: numba>=0.57.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: pandas-market-calendars>=4.0.0
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: polars>=0.20.0
+Requires-Dist: pyarrow>=14.0.0
+Requires-Dist: pydantic<3.0.0,>=1.10.0
+Requires-Dist: python-dateutil>=2.8.0
+Requires-Dist: pyyaml>=6.0.0
+Requires-Dist: sortedcontainers>=2.4.0
+Requires-Dist: structlog>=23.0.0
+Requires-Dist: tables>=3.8.0
+Provides-Extra: advanced
+Requires-Dist: cvxpy>=1.3.0; extra == 'advanced'
+Requires-Dist: networkx>=3.0; extra == 'advanced'
+Provides-Extra: all
+Requires-Dist: cvxpy>=1.3.0; extra == 'all'
+Requires-Dist: dash>=2.11.0; extra == 'all'
+Requires-Dist: hypothesis>=6.80.0; extra == 'all'
+Requires-Dist: ipdb>=0.13.0; extra == 'all'
+Requires-Dist: ipython>=8.14.0; extra == 'all'
+Requires-Dist: matplotlib>=3.7.0; extra == 'all'
+Requires-Dist: mypy>=1.5.0; extra == 'all'
+Requires-Dist: myst-parser>=2.0.0; extra == 'all'
+Requires-Dist: nbsphinx>=0.9.0; extra == 'all'
+Requires-Dist: networkx>=3.0; extra == 'all'
+Requires-Dist: plotly>=5.15.0; extra == 'all'
+Requires-Dist: pre-commit>=3.3.0; extra == 'all'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'all'
+Requires-Dist: pytest-benchmark>=4.0.0; extra == 'all'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'all'
+Requires-Dist: pytest-timeout>=2.1.0; extra == 'all'
+Requires-Dist: pytest-xdist>=3.3.0; extra == 'all'
+Requires-Dist: pytest>=7.4.0; extra == 'all'
+Requires-Dist: ruff>=0.1.0; extra == 'all'
+Requires-Dist: sphinx-autodoc-typehints>=1.24.0; extra == 'all'
+Requires-Dist: sphinx-rtd-theme>=1.3.0; extra == 'all'
+Requires-Dist: sphinx>=7.0.0; extra == 'all'
+Provides-Extra: comparison
+Requires-Dist: backtrader>=1.9.0; extra == 'comparison'
+Requires-Dist: vectorbt>=0.24.0; extra == 'comparison'
+Requires-Dist: zipline-reloaded>=2.4.0; extra == 'comparison'
+Provides-Extra: dev
+Requires-Dist: hypothesis>=6.80.0; extra == 'dev'
+Requires-Dist: ipdb>=0.13.0; extra == 'dev'
+Requires-Dist: ipython>=8.14.0; extra == 'dev'
+Requires-Dist: mypy>=1.5.0; extra == 'dev'
+Requires-Dist: pre-commit>=3.3.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-benchmark>=4.0.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
+Requires-Dist: pytest-timeout>=2.1.0; extra == 'dev'
+Requires-Dist: pytest-xdist>=3.3.0; extra == 'dev'
+Requires-Dist: pytest>=7.4.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: myst-parser>=2.0.0; extra == 'docs'
+Requires-Dist: nbsphinx>=0.9.0; extra == 'docs'
+Requires-Dist: sphinx-autodoc-typehints>=1.24.0; extra == 'docs'
+Requires-Dist: sphinx-rtd-theme>=1.3.0; extra == 'docs'
+Requires-Dist: sphinx>=7.0.0; extra == 'docs'
+Provides-Extra: viz
+Requires-Dist: dash>=2.11.0; extra == 'viz'
+Requires-Dist: matplotlib>=3.7.0; extra == 'viz'
+Requires-Dist: plotly>=5.15.0; extra == 'viz'
+Description-Content-Type: text/markdown
+
+# ml4t-backtest
+
+Event-driven backtesting engine for ML4T quantitative trading strategies.
+
+## Features
+
+- **Event-Driven Architecture**: Point-in-time correctness with no look-ahead bias
+- **Exit-First Processing**: Matches real broker order execution behavior
+- **VectorBT Validation**: Results validated against VectorBT Pro
+- **Account Policies**: Cash and margin account support
+- **Minimal Core**: ~2,800 lines of focused, maintainable code
+- **100k+ events/sec**: High-performance event processing
+
+## Installation
+
+```bash
+pip install ml4t-backtest
+```
+
+## Quick Start
+
+```python
+from ml4t.backtest import Engine, Strategy, BacktestConfig
+
+class SimpleMovingAverage(Strategy):
+    def __init__(self, fast=10, slow=30):
+        self.fast = fast
+        self.slow = slow
+        
+    def on_bar(self, bar):
+        fast_ma = bar.close_ma(self.fast)
+        slow_ma = bar.close_ma(self.slow)
+        
+        if fast_ma > slow_ma and self.position == 0:
+            self.buy(size=100)
+        elif fast_ma < slow_ma and self.position > 0:
+            self.close()
+
+config = BacktestConfig(
+    initial_cash=100_000,
+    commission=0.001,
+)
+
+engine = Engine(data, SimpleMovingAverage(), config)
+result = engine.run()
+
+print(f"Total Return: {result.total_return:.2%}")
+print(f"Sharpe Ratio: {result.metrics['sharpe']:.2f}")
+```
+
+## Documentation
+
+- **[AGENT.md](AGENT.md)**: Comprehensive API reference for agents and developers
+- **[api.yaml](api.yaml)**: Machine-readable API specification
+
+## Part of ML4T
+
+This library is part of the ML4T quantitative trading toolkit:
+
+- **ml4t-data**: Market data acquisition and storage
+- **ml4t-engineer**: Feature engineering and indicators
+- **ml4t-diagnostic**: Statistical validation and evaluation
+- **ml4t-backtest**: Event-driven backtesting (this library)
+- **ml4t-live**: Live trading platform
+
+## License
+
+MIT License - see LICENSE for details.

ml4t_backtest-0.1.0a2/README.md

@@ -0,0 +1,68 @@
+# ml4t-backtest
+
+Event-driven backtesting engine for ML4T quantitative trading strategies.
+
+## Features
+
+- **Event-Driven Architecture**: Point-in-time correctness with no look-ahead bias
+- **Exit-First Processing**: Matches real broker order execution behavior
+- **VectorBT Validation**: Results validated against VectorBT Pro
+- **Account Policies**: Cash and margin account support
+- **Minimal Core**: ~2,800 lines of focused, maintainable code
+- **100k+ events/sec**: High-performance event processing
+
+## Installation
+
+```bash
+pip install ml4t-backtest
+```
+
+## Quick Start
+
+```python
+from ml4t.backtest import Engine, Strategy, BacktestConfig
+
+class SimpleMovingAverage(Strategy):
+    def __init__(self, fast=10, slow=30):
+        self.fast = fast
+        self.slow = slow
+        
+    def on_bar(self, bar):
+        fast_ma = bar.close_ma(self.fast)
+        slow_ma = bar.close_ma(self.slow)
+        
+        if fast_ma > slow_ma and self.position == 0:
+            self.buy(size=100)
+        elif fast_ma < slow_ma and self.position > 0:
+            self.close()
+
+config = BacktestConfig(
+    initial_cash=100_000,
+    commission=0.001,
+)
+
+engine = Engine(data, SimpleMovingAverage(), config)
+result = engine.run()
+
+print(f"Total Return: {result.total_return:.2%}")
+print(f"Sharpe Ratio: {result.metrics['sharpe']:.2f}")
+```
+
+## Documentation
+
+- **[AGENT.md](AGENT.md)**: Comprehensive API reference for agents and developers
+- **[api.yaml](api.yaml)**: Machine-readable API specification
+
+## Part of ML4T
+
+This library is part of the ML4T quantitative trading toolkit:
+
+- **ml4t-data**: Market data acquisition and storage
+- **ml4t-engineer**: Feature engineering and indicators
+- **ml4t-diagnostic**: Statistical validation and evaluation
+- **ml4t-backtest**: Event-driven backtesting (this library)
+- **ml4t-live**: Live trading platform
+
+## License
+
+MIT License - see LICENSE for details.

ml4t_backtest-0.1.0a2/pyproject.toml

@@ -0,0 +1,244 @@
+# ml4t.backtest - Event-driven backtesting with institutional-grade correctness guarantees
+# Independent package configuration for standalone distribution
+
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.build.hooks.vcs]
+version-file = "src/ml4t/backtest/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ml4t"]
+namespaces = true
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src",
+    "/tests",
+    "/README.md",
+    "/LICENSE",
+    "/CHANGELOG.md",
+]
+
+[project]
+name = "ml4t-backtest"
+dynamic = ["version"]
+description = "State-of-the-art event-driven backtesting engine for quantitative trading"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+    { name = "QuantLab Team", email = "info@quantlab.io" },
+]
+maintainers = [
+    { name = "QuantLab Contributors", email = "dev@quantlab.io" },
+]
+keywords = [
+    "finance",
+    "backtesting",
+    "trading",
+    "simulation",
+    "event-driven",
+    "quantitative-finance",
+    "algorithmic-trading",
+    "portfolio",
+    "risk-management",
+    "execution",
+    "polars",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Financial and Insurance Industry",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Office/Business :: Financial :: Investment",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+    "Typing :: Typed",
+]
+requires-python = ">=3.11"
+
+# Core dependencies
+dependencies = [
+    # Data processing
+    "polars>=0.20.0",
+    "pandas>=2.0.0",
+    "numpy>=1.24.0",
+    "pyarrow>=14.0.0",
+    "tables>=3.8.0",  # PyTables for HDF5 support
+    # Event system
+    "sortedcontainers>=2.4.0", # Efficient priority queue
+    # Performance optimization
+    "numba>=0.57.0",
+    # Configuration and validation
+    "pydantic>=1.10.0,<3.0.0",  # Configuration schema and validation
+    "PyYAML>=6.0.0",  # YAML configuration support
+    # Utilities
+    "structlog>=23.0.0",
+    "python-dateutil>=2.8.0",
+    # Market calendars (needed for clock module)
+    "pandas-market-calendars>=4.0.0",
+]
+
+[project.optional-dependencies]
+# Visualization and reporting
+viz = [
+    "plotly>=5.15.0",
+    "matplotlib>=3.7.0",
+    "dash>=2.11.0",  # Interactive dashboards
+]
+
+# Advanced execution models
+advanced = [
+    "networkx>=3.0",  # Order routing graphs
+    "cvxpy>=1.3.0",  # Portfolio optimization
+]
+
+# Comparison libraries (for benchmarking)
+comparison = [
+    "vectorbt>=0.24.0",
+    "backtrader>=1.9.0",
+    "zipline-reloaded>=2.4.0",
+]
+
+# Development dependencies
+dev = [
+    "pytest>=7.4.0",
+    "pytest-cov>=4.1.0",
+    "pytest-xdist>=3.3.0",
+    "pytest-timeout>=2.1.0",
+    "pytest-benchmark>=4.0.0",
+    "pytest-asyncio>=0.21.0",
+    "hypothesis>=6.80.0",
+    "ruff>=0.1.0",
+    "mypy>=1.5.0",
+    "ipython>=8.14.0",
+    "ipdb>=0.13.0",
+    "pre-commit>=3.3.0",
+]
+
+# Documentation dependencies
+docs = [
+    "sphinx>=7.0.0",
+    "sphinx-rtd-theme>=1.3.0",
+    "sphinx-autodoc-typehints>=1.24.0",
+    "myst-parser>=2.0.0",
+    "nbsphinx>=0.9.0",
+]
+
+# All optional dependencies
+all = [
+    "ml4t-backtest[viz,advanced,dev,docs]",
+]
+
+[project.urls]
+Homepage = "https://github.com/ml4t/ml4t-backtest"
+Documentation = "https://ml4t-backtest.readthedocs.io"
+Repository = "https://github.com/ml4t/ml4t-backtest"
+Issues = "https://github.com/ml4t/ml4t-backtest/issues"
+Changelog = "https://github.com/ml4t/ml4t-backtest/blob/main/CHANGELOG.md"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = [
+    "-ra",
+    "--strict-markers",
+    "--ignore=tests/private",  # Exclude private/commercial dependency tests
+    "--ignore=tests/validation",  # Exclude optional cross-framework validation tests
+    "--cov=ml4t.backtest",
+    "--cov-report=term-missing",
+    "--cov-report=html",
+]
+markers = [
+    "slow: marks tests as slow (deselect with '-m \"not slow\"')",
+    "integration: marks tests as integration tests",
+    "benchmark: marks benchmark tests",
+    "unit: marks unit tests",
+    "private: requires commercial dependencies (vectorbtpro) - excluded by default",
+    "requires_comparison: requires optional comparison frameworks (vectorbt, backtrader, zipline)",
+]
+filterwarnings = [
+    "ignore::DeprecationWarning",
+    "ignore::PendingDeprecationWarning",
+    "ignore::UserWarning:vectorbt",  # VectorBT accessor registration warnings
+    "ignore::tables.NaturalNameWarning",  # PyTables naming warnings
+    "ignore::FutureWarning:zipline",  # Zipline compatibility warnings
+    "ignore::pytest.PytestReturnNotNoneWarning",  # Some tests return values for direct execution
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+fix = true
+exclude = [
+    "validation/*",  # Standalone scripts run in isolated venvs
+    "docs/*",        # Documentation artifacts
+    ".claude/*",     # Claude workspace files
+    ".serena/*",     # Serena workspace files
+]
+
+[tool.ruff.lint]
+select = [
+    "E",    # pycodestyle errors
+    "W",    # pycodestyle warnings
+    "F",    # pyflakes
+    "I",    # isort
+    "B",    # flake8-bugbear
+    "C4",   # flake8-comprehensions
+    "UP",   # pyupgrade
+    "ARG",  # flake8-unused-arguments
+    "SIM",  # flake8-simplify
+]
+ignore = [
+    "E501",  # line too long (handled by formatter)
+    "B008",  # do not perform function calls in argument defaults
+    "B905",  # zip without explicit strict parameter
+    "ARG002",  # unused method arguments (intentional in strategy callbacks)
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["ARG001", "ARG002"]  # Test functions often have unused fixtures
+
+[tool.mypy]
+python_version = "3.11"
+strict = false
+warn_return_any = false  # numpy/pandas return Any, too many false positives
+warn_unused_ignores = true
+disallow_untyped_defs = false
+disallow_any_unimported = false
+no_implicit_optional = true
+check_untyped_defs = true
+show_error_codes = true
+warn_redundant_casts = true
+ignore_missing_imports = true
+
+[tool.coverage.run]
+source = ["src/ml4t/backtest"]
+omit = [
+    "*/tests/*",
+    "*/__init__.py",
+]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "if self.debug:",
+    "if __name__ == .__main__.:",
+    "raise NotImplementedError",
+    "pass",
+    "except ImportError:",
+    "@abstractmethod",
+]

ml4t_backtest-0.1.0a2/src/ml4t/backtest/__init__.py

@@ -0,0 +1,67 @@
+"""ML4T Backtest - Event-driven backtesting engine.
+
+A minimal, event-driven backtesting engine with:
+- Point-in-time correctness
+- Exit-first order processing
+- Cash and margin account policies
+- VectorBT-validated results
+
+Example:
+    >>> from ml4t.backtest import Engine, Strategy, BacktestConfig
+    >>> 
+    >>> class MyStrategy(Strategy):
+    ...     def on_bar(self, bar):
+    ...         if self.position == 0:
+    ...             self.buy(size=100)
+    >>> 
+    >>> result = Engine(data, MyStrategy()).run()
+    >>> print(result.metrics)
+"""
+
+from ml4t.backtest.types import (
+    Order,
+    OrderType,
+    OrderSide,
+    Fill,
+    Position,
+    Trade,
+)
+from ml4t.backtest.config import BacktestConfig
+from ml4t.backtest.strategy import Strategy
+from ml4t.backtest.engine import Engine
+from ml4t.backtest.broker import Broker
+from ml4t.backtest.datafeed import DataFeed
+from ml4t.backtest.result import BacktestResult
+
+try:
+    from ml4t.backtest._version import __version__
+except ImportError:
+    __version__ = "0.0.0.dev0"
+
+__all__ = [
+    # Core types
+    "Order",
+    "OrderType",
+    "OrderSide",
+    "Fill",
+    "Position",
+    "Trade",
+    # Main classes
+    "BacktestConfig",
+    "Strategy",
+    "Engine",
+    "Broker",
+    "DataFeed",
+    "BacktestResult",
+]
+
+
+def list_order_types() -> list[str]:
+    """List available order types."""
+    return [t.name for t in OrderType]
+
+
+def list_presets() -> list[str]:
+    """List available configuration presets."""
+    from ml4t.backtest import presets
+    return [name for name in dir(presets) if not name.startswith('_')]

ml4t_backtest-0.1.0a2/src/ml4t/backtest/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '0.1.0a2'
+__version_tuple__ = version_tuple = (0, 1, 0, 'a2')
+
+__commit_id__ = commit_id = None

ml4t_backtest-0.1.0a2/src/ml4t/backtest/accounting/__init__.py

@@ -0,0 +1,27 @@
+"""Accounting module for backtesting engine.
+
+Provides proper accounting constraints for both cash accounts (no leverage, no shorts)
+and margin accounts (leverage enabled, shorts allowed).
+
+Key Components:
+- Position: Unified position tracking (from types module)
+- AccountPolicy: Interface for account type constraints
+- CashAccountPolicy: Cash account constraints (cash >= 0, no shorts)
+- MarginAccountPolicy: Margin account constraints (NLV/BP/MM calculations)
+- AccountState: Account state management and position tracking
+- Gatekeeper: Order validation before execution
+"""
+
+from ..types import Position
+from .account import AccountState
+from .gatekeeper import Gatekeeper
+from .policy import AccountPolicy, CashAccountPolicy, MarginAccountPolicy
+
+__all__ = [
+    "Position",
+    "AccountPolicy",
+    "CashAccountPolicy",
+    "MarginAccountPolicy",
+    "AccountState",
+    "Gatekeeper",
+]