py-backtesting-lib 0.1.0__py3-none-any.whl

Backtesting/analysis/__init__.py

@@ -0,0 +1,11 @@
+# Backtesting/analysis/__init__.py
+
+from .result import ExperimentResult
+from .reports.console_report import ConsoleTradeReport
+from .persistence.event_sink import DuckDBEventSink
+
+__all__ = [
+    "ExperimentResult",
+    "ConsoleTradeReport",
+    "DuckDBEventSink",
+]

Backtesting/analysis/persistence/__init__.py

@@ -0,0 +1,5 @@
+# Backtesting/analysis/persistence/__init__.py
+
+from .event_sink import DuckDBEventSink
+
+__all__ = ["DuckDBEventSink"]

Backtesting/analysis/persistence/event_sink.py

@@ -0,0 +1,133 @@
+# Backtesting/analysis/persistence/event_sink.py
+# Persists events to a database
+from decimal import Decimal
+
+import duckdb
+from typing import Dict, Any
+from datetime import datetime
+import json
+from ...definition import EventType, MarketBarReceived, SignalGenerated, OrderSubmitted, OrderFilled, FillExecuted, TradeArchived, MarketBar, Signal, Order, Fill, Trade
+
+class DuckDBEventSink:
+    """
+    Subscribes to the EventBus and persists events to a DuckDB database.
+    """
+    def __init__(self, db_path: str = "backtest_events.duckdb"):
+        self.con = duckdb.connect(db_path)
+        self.experiment_id = None
+        self._create_table()
+
+    def _create_table(self):
+        create_sql = """
+        CREATE TABLE IF NOT EXISTS events (
+            experiment_id VARCHAR NOT NULL,
+            event_timestamp TIMESTAMP NOT NULL,
+            event_type VARCHAR NOT NULL,
+            event_data JSON
+        );
+        """
+        self.con.execute(create_sql)
+
+    def subscribe_to_engine(self, event_bus, experiment_id: str):
+        """
+        Subscribes to the given EventBus for all event types and tags them with the experiment_id.
+        """
+        self.experiment_id = experiment_id
+        # Subscribe to the base event type to catch all events
+        # This assumes all events have a common base class or share a common attribute like 'event_type'
+        # A more robust way might be to subscribe to each specific event type or use a wildcard if supported.
+        # For now, let's subscribe to a common parent type or a generic object type.
+        # We'll use the most general type possible in Python, `object`, but this is inefficient.
+        # A better approach is to subscribe to each specific event type dynamically if possible.
+        # Let's assume we know the types we care about for now.
+        # A more generic solution would be to have a base event class that all events inherit from.
+        # For this implementation, let's create a subscriber that catches any object and filters.
+        def event_handler(event):
+            self.persist_event(event)
+
+        # Subscribe to common event types
+        event_bus.subscribe(MarketBarReceived, event_handler)
+        event_bus.subscribe(SignalGenerated, event_handler)
+        event_bus.subscribe(OrderSubmitted, event_handler)
+        event_bus.subscribe(OrderFilled, event_handler)
+        event_bus.subscribe(FillExecuted, event_handler)
+        event_bus.subscribe(TradeArchived, event_handler)
+        # Add subscriptions for other known event types as needed
+
+    def persist_event(self, event: Any):
+        """
+        Inserts an event into the database.
+        """
+        if not self.experiment_id:
+            # Should not happen if subscribed correctly
+            print("Warning: Attempting to persist event without experiment_id set.")
+            return
+
+        event_type_name = type(event).__name__
+        event_data_serialized = json.dumps(self._serialize_event_data(event))
+
+        insert_sql = """
+        INSERT INTO events (experiment_id, event_timestamp, event_type, event_data)
+        VALUES (?, ?, ?, ?);
+        """
+        self.con.execute(insert_sql, [self.experiment_id, datetime.now(), event_type_name, event_data_serialized])
+
+    def _serialize_event_data(self, event: Any) -> Dict[str, Any]:
+        """
+        Converts an event object's attributes into a dictionary suitable for JSON serialization.
+        This is a simplified approach. A more robust solution might use a serialization library
+        that understands dataclasses, enums, and Decimals.
+        """
+        # Use dataclass `__dict__` for events defined as dataclasses
+        # Handle special cases like enums and Decimals
+        data = {}
+        for key, value in event.__dict__.items():
+            if isinstance(value, (MarketBar, Signal, Order, Fill, Trade)):
+                # Recursively serialize nested dataclass objects
+                data[key] = self._serialize_event_data(value)
+            elif isinstance(value, (int, float, str, bool, type(None))):
+                # Primitive types are fine
+                data[key] = value
+            elif hasattr(value, 'value'): # Handle enums
+                data[key] = value.value
+            elif isinstance(value, Decimal):
+                # Convert Decimal to string to preserve precision in JSON
+                data[key] = str(value)
+            elif isinstance(value, datetime):
+                # Convert datetime to ISO string
+                data[key] = value.isoformat()
+            else:
+                # Fallback for other types - might cause issues if not serializable
+                data[key] = repr(value) # Use repr as a very last resort
+        return data
+
+    def close_connection(self):
+        """
+        Closes the database connection.
+        """
+        if self.con:
+            self.con.close()
+
+    def query_events(self, experiment_id: str = None, event_type: str = None, limit: int = None) -> duckdb.DuckDBPyRelation:
+        """
+        Queries the event log. Allows filtering by experiment_id and event_type.
+        Returns a DuckDB relation object for further manipulation.
+        """
+        sql = "SELECT * FROM events WHERE 1=1" # Start with a base condition
+        params = []
+
+        if experiment_id:
+            sql += " AND experiment_id = ?"
+            params.append(experiment_id)
+
+        if event_type:
+            sql += " AND event_type = ?"
+            params.append(event_type)
+
+        sql += " ORDER BY event_timestamp ASC" # Always order chronologically
+
+        if limit:
+            sql += " LIMIT ?"
+            params.append(limit)
+
+        return self.con.execute(sql, params)

Backtesting/analysis/reports/__init__.py

@@ -0,0 +1,5 @@
+# Backtesting/analysis/reports/__init__.py
+
+from .console_report import ConsoleTradeReport
+
+__all__ = ["ConsoleTradeReport"]

Backtesting/analysis/reports/console_report.py

@@ -0,0 +1,73 @@
+# Backtesting/analysis/reports/console_report.py
+# Simple console report plugin
+
+from decimal import Decimal
+from typing import List
+from ..result import ExperimentResult
+from ...definition import Trade
+
+class ConsoleTradeReport:
+    """
+    A simple report plugin that prints a summary of the experiment results to the console.
+    """
+    def generate_report(self, result: ExperimentResult):
+        """
+        Generates and prints the report based on the ExperimentResult.
+        """
+        print("\n" + "="*50)
+        print(f"REPORT FOR EXPERIMENT: {result.experiment_name}")
+        print(f"RUN ID: {result.experiment_id}")
+        print(f"STARTED: {result.started_at.isoformat()}")
+        print(f"FINISHED: {result.finished_at.isoformat()}")
+        print("-"*50)
+
+        closed_trades: List[Trade] = result.get_closed_trades()
+        total_trades = len(closed_trades)
+        total_pnl = result.get_total_pnl()
+
+        if total_trades == 0:
+            print("No trades executed.")
+            print("="*50)
+            return
+
+        winning_trades = [t for t in closed_trades if t.realized_pnl > 0]
+        losing_trades = [t for t in closed_trades if t.realized_pnl < 0]
+
+        win_rate = (len(winning_trades) / total_trades) * 100 if total_trades > 0 else 0
+        avg_trade_pnl = total_pnl / total_trades if total_trades > 0 else Decimal('0')
+
+        # Calculate Max Drawdown (simplified)
+        # This is a basic calculation assuming equity is known at each trade close.
+        # A more robust calculation would require equity snapshots throughout the run.
+        # For now, we'll calculate drawdown based on cumulative PnL.
+        cumulative_pnl = [Decimal('0')]
+        for trade in closed_trades:
+            cumulative_pnl.append(cumulative_pnl[-1] + trade.realized_pnl)
+
+        peak = Decimal('-Infinity')
+        max_drawdown = Decimal('0')
+        for pnl in cumulative_pnl:
+            if pnl > peak:
+                peak = pnl
+            drawdown = peak - pnl
+            if drawdown > max_drawdown:
+                max_drawdown = drawdown
+
+        # Calculate Sharpe Ratio (simplified, requires risk-free rate assumption)
+        # Annualized Sharpe = (Annualized Return - Risk_Free_Rate) / Annualized Volatility
+        # For simplicity, assume daily returns and risk-free rate of 0.
+        # Annualized Return = (Final Value / Initial Value)^(252/n_days) - 1
+        # Annualized Volatility = Std Dev of Daily Returns * sqrt(252)
+        # This requires daily equity values, which we don't have here.
+        # Let's skip Sharpe for this basic report or use a placeholder.
+        sharpe_ratio_placeholder = "N/A (requires daily equity curve)"
+
+        print(f"Total Trades: {total_trades}")
+        print(f"Winning Trades: {len(winning_trades)}")
+        print(f"Losing Trades: {len(losing_trades)}")
+        print(f"Win Rate: {win_rate:.2f}%")
+        print(f"Total PnL: {total_pnl:.2f}")
+        print(f"Average Trade PnL: {avg_trade_pnl:.2f}")
+        print(f"Max Drawdown: {max_drawdown:.2f}")
+        print(f"Sharpe Ratio: {sharpe_ratio_placeholder}") # Placeholder
+        print("="*50)

Backtesting/analysis/result.py

@@ -0,0 +1,42 @@
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from decimal import Decimal
+from typing import List, Dict, Any
+from ..execution import Trade
+
+@dataclass(frozen=True)
+class ExperimentResult:
+    """
+    Immutable aggregate containing the final state and event log of an experiment run.
+    """
+    # Metadata
+    experiment_id: str # Unique identifier for this run
+    experiment_name: str
+    started_at: datetime
+    finished_at: datetime
+
+    # Final State Snapshots
+    portfolio_snapshot: Dict[str, Any] # e.g., {"cash": Decimal, "equity": Decimal, "margin_used": Decimal}
+    position_book_snapshot: Dict[str, Dict[str, Decimal]] # e.g., {"SYMBOL": {"net_size": Decimal, "avg_price": Decimal, "upl": Decimal}}
+    trade_book_snapshot: List[Dict[str, Any]] # List of serialized Trade objects
+
+    # Full Event Log (serialized)
+    event_log: List[Dict[str, Any]] # List of serialized events [{"type": str, "data": dict, "timestamp": datetime}]
+
+    def get_closed_trades(self) -> List[Trade]:
+        """
+        Helper to deserialize and return the list of closed trades.
+        """
+        # This is a simplified deserialization. In practice, you might use a dedicated serializer/deserializer.
+        # For now, assume the snapshot data matches the Trade dataclass structure.
+        return [Trade(**trade_dict) for trade_dict in self.trade_book_snapshot]
+
+    def get_total_pnl(self) -> Decimal:
+        """
+        Calculates total realized PnL from closed trades.
+        """
+        total = Decimal('0')
+        for trade in self.get_closed_trades():
+            total += trade.realized_pnl
+        return total

Backtesting/definition/__init__.py

@@ -0,0 +1,7 @@
+
+from .plugins import *
+from .configs import *
+from .core import *
+from .experiment import Experiment
+
+__all__ = ["Experiment"] + configs.__all__ + plugins.__all__ + core.__all__

Backtesting/definition/configs/__init__.py

@@ -0,0 +1,8 @@
+from .base import StrategyConfig, MarketDataConfig, MoneyManagementConfig, BrokerConfig
+
+__all__ = [
+    "MarketDataConfig",
+    "StrategyConfig",
+    "MoneyManagementConfig",
+    "BrokerConfig",
+]

Backtesting/definition/configs/base.py

@@ -0,0 +1,31 @@
+# Backtesting/definition/configs/base.py
+from pydantic import BaseModel, ConfigDict, field_validator
+
+class PluginConfig(BaseModel):
+    """
+    Base configuration model for plugins' configuration.
+    Enforces the standard structure: name and flexible params.
+    """
+    model_config = ConfigDict(frozen=True)
+    name: str
+    params: dict = {} # Defaults to empty dict if not provided
+
+    @field_validator('params', mode='before')
+    @classmethod
+    def validate_params(cls, v):
+        return {} if v is None else v
+
+    def __hash__(self):
+        return hash((type(self),) + tuple(self.__dict__.values()))
+
+class StrategyConfig(PluginConfig):
+    pass
+
+class MoneyManagementConfig(PluginConfig):
+    pass
+
+class BrokerConfig(PluginConfig):
+    pass
+
+class MarketDataConfig(PluginConfig):
+    pass

Backtesting/definition/core/__init__.py

@@ -0,0 +1,22 @@
+
+from .domain_models import *
+
+__all__ = [
+    "MarketBar",
+    "SignalType",
+    "Signal",
+    "OrderType",
+    "OrderSide",
+    "OrderStatus",
+    "Order",
+    "Fill",
+    "EventType",
+    "Trade",
+    "MarketBarReceived",
+    "SignalGenerated",
+    "OrderSubmitted",
+    "OrderFilled",
+    "OrderCancelled",
+    "FillExecuted",
+    "TradeArchived",
+]

Backtesting/definition/core/domain_models.py

@@ -0,0 +1,165 @@
+# Backtesting/definition/core/domain_models.py
+# Shared core domain models and events used by definition and execution
+
+from datetime import datetime
+from decimal import Decimal
+from dataclasses import dataclass, field
+from enum import Enum
+
+# --- Enums ---
+class EventType(Enum):
+    MARKET_BAR_RECEIVED = "market_bar_received"
+    SIGNAL_GENERATED = "signal_generated"
+    ORDER_SUBMITTED = "order_submitted"
+    ORDER_FILLED = "order_filled"
+    ORDER_CANCELLED = "order_cancelled"
+    FILL_EXECUTED = "fill_executed"
+    POSITION_OPENED = "position_opened"
+    POSITION_CLOSED = "position_closed"
+    TRADE_ARCHIVED = "trade_archived"
+    PORTFOLIO_STATE_UPDATE = "portfolio_state_update"
+
+class SignalType(Enum):
+    BUY_LONG = "buy_long"
+    SELL_SHORT = "sell_short"
+    EXIT_LONG = "exit_long"
+    EXIT_SHORT = "exit_short"
+
+class OrderType(Enum):
+    MARKET = "market"
+    LIMIT = "limit"
+    STOP = "stop"
+
+class OrderSide(Enum):
+    BUY = "buy"
+    SELL = "sell"
+
+class OrderStatus(Enum):
+    SUBMITTED = "submitted"
+    PENDING = "pending"
+    FILLED = "filled"
+    PARTIALLY_FILLED = "partially_filled"
+    CANCELLED = "cancelled"
+
+# --- Core Domain Data Structures ---
+@dataclass(frozen=True)
+class MarketBar:
+    """
+    Represents a single bar/tick of market data.
+    """
+    symbol: str
+    timestamp: datetime
+    open: Decimal
+    high: Decimal
+    low: Decimal
+    close: Decimal
+    volume: Decimal
+
+    def __repr__(self):
+        return f"MarketBar({self.symbol}, {self.timestamp}, O:{self.open}, H:{self.high}, L:{self.low}, C:{self.close}, V:{self.volume})"
+
+@dataclass(frozen=True)
+class Signal:
+    """
+    Represents a trading signal generated by a Strategy.
+    """
+    id: str # Add an ID field for better tracking
+    symbol: str
+    signal_type: SignalType
+    strength: Decimal = Decimal('1.0')
+    meta: dict = field(default_factory=dict) # Use field for mutable defaults
+
+    def __repr__(self):
+        return f"Signal({self.id}, {self.symbol}, {self.signal_type}, Strength: {self.strength})"
+
+@dataclass(frozen=True)
+class Order:
+    """
+    Represents a trading order created by a MoneyManager based on a Signal.
+    This is the *immutable* version used for events/logs.
+    """
+    order_id: str
+    signal_id: str
+    symbol: str
+    order_type: OrderType
+    side: OrderSide
+    quantity: Decimal
+    price: Decimal = None # Optional for MARKET orders
+    stop_price: Decimal = None # Optional for STOP orders
+    status: OrderStatus = OrderStatus.SUBMITTED
+    filled_quantity: Decimal = Decimal('0')
+    average_fill_price: Decimal = Decimal('0')
+    commission: Decimal = Decimal('0') # Added commission field
+
+    def __repr__(self):
+        return f"Order({self.order_id}, {self.symbol}, {self.side} {self.quantity} {self.order_type}, Status: {self.status})"
+
+@dataclass(frozen=True)
+class Fill:
+    """
+    Represents the execution details of an Order (or part of it).
+    """
+    fill_id: str
+    order_id: str
+    symbol: str
+    side: OrderSide
+    quantity: Decimal
+    fill_price: Decimal
+    fill_time: datetime
+    commission: Decimal = Decimal('0')
+
+    def __repr__(self):
+        return f"Fill({self.fill_id}, {self.order_id}, {self.side} {self.quantity} @ {self.fill_price}, Time: {self.fill_time})"
+
+@dataclass(frozen=True)
+class Trade:
+    """
+    Represents an immutable record of a closed trade.
+    """
+    symbol: str
+    entry_time: Decimal # Or datetime if available in fill
+    exit_time: Decimal  # Or datetime if available in fill
+    entry_price: Decimal
+    exit_price: Decimal
+    quantity: Decimal
+    side: str # 'LONG' or 'SHORT' based on entry side
+    realized_pnl: Decimal
+    commission: Decimal
+
+# --- Event Definitions (Immutable wrappers around core data structures) ---
+# These are the objects published by the engine and listened to by handlers.
+
+@dataclass(frozen=True)
+class MarketBarReceived:
+    bar: MarketBar
+    event_type: EventType = EventType.MARKET_BAR_RECEIVED
+
+@dataclass(frozen=True)
+class SignalGenerated:
+    signal: Signal
+    event_type: EventType = EventType.SIGNAL_GENERATED
+
+@dataclass(frozen=True)
+class OrderSubmitted:
+    order: Order
+    event_type: EventType = EventType.ORDER_SUBMITTED
+
+@dataclass(frozen=True)
+class OrderFilled:
+    order: Order
+    event_type: EventType = EventType.ORDER_FILLED
+
+@dataclass(frozen=True)
+class OrderCancelled:
+    order_id: str # Just the ID might suffice, or include the Order object if needed
+    event_type: EventType = EventType.ORDER_CANCELLED
+
+@dataclass(frozen=True)
+class FillExecuted:
+    fill: Fill
+    event_type: EventType = EventType.FILL_EXECUTED
+
+@dataclass(frozen=True)
+class TradeArchived:
+    trade: Trade
+    event_type: EventType = EventType.TRADE_ARCHIVED

Backtesting/definition/experiment.py

@@ -0,0 +1,142 @@
+from multiprocessing.connection import default_family
+
+import yaml
+from pathlib import Path
+from pydantic import BaseModel, ValidationError, ConfigDict, Field
+from .configs import (
+    StrategyConfig,
+    MoneyManagementConfig,
+    BrokerConfig,
+    MarketDataConfig,
+)
+from .plugins.plugin_registry import resolve, PluginNotFoundError
+from datetime import datetime
+
+class Experiment(BaseModel):
+    """
+    The Aggregate Root for a backtesting experiment.
+    Holds all configuration data and provides validation and serialization.
+    """
+    model_config = ConfigDict(frozen=True) # Make the entire Experiment immutable after creation
+
+    # Metadata
+    name: str
+    author: str = "Unknown" # Optional default
+    version: str = "1.0" # Optional default
+    created_at: datetime = Field(default_factory=datetime.now) # Automatically set unless provided
+
+    # Plugin configurations
+    strategy_config: StrategyConfig
+    money_management_config: MoneyManagementConfig
+    broker_config: BrokerConfig
+    market_data_config: MarketDataConfig
+
+    def validate(self):
+        """
+        Performs semantic validation by checking if all plugin names exist in the registry.
+        Raises PluginNotFoundError if any name is invalid.
+        This method should be called *after* plugins are registered.
+        """
+        plugin_names_to_check = [
+            self.strategy_config.name,
+            self.money_management_config.name,
+            self.broker_config.name,
+            self.market_data_config.name,
+        ]
+
+        for name in plugin_names_to_check:
+            try:
+                resolve(name)
+            except PluginNotFoundError:
+                # Re-raising with context about the specific config field
+                raise PluginNotFoundError(
+                    f"Experiment validation failed: Plugin '{name}' referenced in "
+                    f"configuration is not registered in the PluginRegistry."
+                )
+
+
+    @classmethod
+    def from_yaml(cls, file_path: str):
+        """
+        Loads an Experiment definition from a YAML file.
+        Performs syntactic validation via Pydantic.
+        Does NOT perform semantic validation (registry check) here.
+        Call `experiment_instance.validate()` after loading if needed.
+        """
+        path = Path(file_path)
+        if not path.exists():
+            raise FileNotFoundError(f"Experiment YAML file not found: {file_path}")
+
+        with open(path, 'r', encoding='utf-8') as file:
+            data = yaml.safe_load(file)
+
+        # Assuming the YAML structure wraps the fields under an 'experiment:' key
+        # as shown in the README example.
+        experiment_data = data.get('experiment')
+        if not experiment_data:
+             raise ValueError(f"YAML file {file_path} must contain an 'experiment:' section.")
+
+        # Remap keys from YAML format to Pydantic field names
+        config_map = {
+            "strategy": "strategy_config",
+            "money_management": "money_management_config",
+            "broker": "broker_config",
+            "market_data": "market_data_config"
+        }
+
+        remapped_data = {}
+        for yaml_key, pydantic_field in config_map.items():
+            if yaml_key in experiment_data.get('configs', {}):
+                 remapped_data[pydantic_field] = experiment_data['configs'][yaml_key]
+
+        # Add top-level metadata fields directly
+        for field in ['name', 'author', 'version']:
+            if field in experiment_data.get('metadata', {}):
+                remapped_data[field] = experiment_data['metadata'][field]
+
+        # Construct the final input for Pydantic
+        final_input = {
+            "name": experiment_data["name"],
+            "author": experiment_data.get("metadata", {}).get("author", "Unknown"),
+            "version": experiment_data.get("metadata", {}).get("version", "1.0"),
+            "strategy_config": remapped_data.get("strategy_config"),
+            "money_management_config": remapped_data.get("money_management_config"),
+            "broker_config": remapped_data.get("broker_config"),
+            "market_data_config": remapped_data.get("market_data_config"),
+        }
+
+        try:
+            return cls(**final_input)
+        except ValidationError as e:
+            # Optionally log the detailed Pydantic error
+            print(f"Pydantic validation error loading Experiment from {file_path}: {e}")
+            raise # Re-raise to fail fast
+
+    def to_yaml(self, file_path: str):
+        """
+        Serializes the Experiment definition to a YAML file.
+        """
+        path = Path(file_path)
+        # Prepare data structure matching the expected YAML input format
+        yaml_data = {
+            "experiment": {
+                "name": self.model_dump()['name'], # Access via model_dump for safety
+                "metadata": {
+                     "author": self.model_dump()['author'],
+                     "version": self.model_dump()['version'],
+                     "created_at": self.model_dump()['created_at'].isoformat(), # Convert datetime to string
+                },
+                "configs": {
+                    "strategy": self.strategy_config.model_dump(),
+                    "money_management": self.money_management_config.model_dump(),
+                    "broker": self.broker_config.model_dump(),
+                    "market_data": self.market_data_config.model_dump(),
+                }
+            }
+        }
+
+        with open(path, 'w', encoding='utf-8') as file:
+            yaml.dump(yaml_data, file, default_flow_style=False, indent=2)
+
+    def __repr__(self):
+        return f"Experiment(name='{self.name}', strategy='{self.strategy_config.name}')"

Backtesting/definition/plugins/__init__.py

@@ -0,0 +1,3 @@
+from .base_interfaces import Strategy, MoneyManager, Broker, Reporter, MarketDataProvider
+
+__all__ = ["Strategy", "MoneyManager", "Broker", "Reporter", "MarketDataProvider"]