AlphaFlow

AlphaFlow is a Python-based, event-driven backtesting framework designed for professional-grade trading research and strategy development. Built on a robust pub-sub architecture, AlphaFlow provides a flexible, high-performance environment for quantitative analysts and algorithmic traders.

Vision: Offer a "batteries included" backtesting experience leveraging the simplicity of Python, while also enabling unlimited customization and optimization using an event-driven architecture that can support components written in any language.

Table of Contents

1. Key Features
2. Why AlphaFlow?
3. High-Level Architecture
   • EventBus (Pub-Sub)
   • DataFeed
   • Strategy
   • Broker (Execution Engine)
   • Portfolio
   • Analytics
4. Getting Started
5. Contributing
6. License

Key Features

• Event-Driven Core
  Uses a publish-subscribe (pub-sub) architecture to simulate market data, order placements, and trade executions in a realistic, decoupled manner.

• Commission Tracking
  Built-in commission handling for realistic transaction costs.

• Multi-Asset Support
  Initially focused on stocks & ETFs with daily or intraday data, but built to extend to futures, forex, cryptocurrencies, and options in future releases.

• Performance-Oriented
  Planned message queue integration which will enable optimization of speed-critical components (like indicator calculations on large datasets).

• Extendable & Modular

  • Swap out data sources (CSV, APIs, real-time feeds).
  • Plugin-style architecture for custom brokers, strategies, analytics, and risk management.
  • Components are planned to be made language agnostic in a future release (v1).
  • A solid foundation for live trading integration in a future version (v1).

• Professional-Grade Analytics

  • Built-in performance metrics (Sharpe, Sortino, drawdown, annualized returns).
  • Ongoing support for event-based analytics and reporting modules.

Why AlphaFlow?

1. Maintainable & Modern
   Many legacy libraries are no longer actively maintained or don’t follow best practices. AlphaFlow focuses on code quality, modular design, and clear APIs.

2. Powerful & Future-Proof
   By embracing an event-driven architecture, you get fine-grained control over every aspect of your trading simulation. The transition to real-time or live trading is also more natural compared to purely vectorized solutions.

3. Commission-Aware Backtesting
   Built-in commission tracking ensures realistic transaction costs are accounted for in your strategy performance.

4. Performance Upgrades
   Future Rust integration will offload compute-heavy tasks, enabling large-scale backtests without major slowdowns or memory bottlenecks.

5. Community & Extensibility
   Built to be plugin-friendly, allowing the community to add new data feeds, brokers, analytics modules, and advanced features without modifying the core.

High-Level Architecture

1. EventBus (Pub-Sub)

• The heart of AlphaFlow.
• Components (DataFeed, Strategy, Broker, Portfolio, Analytics) subscribe to and publish events.
• Ensures a loose coupling: each module only needs to know how to react to specific event types.

2. DataFeed

• Responsible for providing market data (historical or real-time).
• Publishes MarketDataEvents (price bars, ticks, earnings, news, etc.) to the EventBus.
• Can support multiple timeframes (daily, intraday, tick data in v2).

3. Strategy

• Subscribes to MarketDataEvents from the DataFeed.
• Generates trading signals and publishes OrderEvents to the Broker.
• Can also subscribe to Portfolio updates if needed (to track position sizing, risk limits, etc.).

4. Broker (Execution Engine)

• Subscribes to OrderEvents from the Strategy.
• Simulates fills (partial or full) and slippage, calculates commissions, and publishes FillEvents.
• Centralizes order handling logic, making it easy to swap in a real-time broker later.

5. Portfolio

• Subscribes to FillEvents to track positions, cash balances, and profit/loss.
• Optionally publishes portfolio updates (like margin calls, risk alerts) to other modules.

6. Analytics

• Subscribes to relevant events (MarketData, FillEvents, or PortfolioUpdates) to compile performance metrics, visualize PnL curves, or generate custom reports.
• Encourages real-time or post-backtest reporting, ideal for quick iteration.

Getting Started

1. Install AlphaFlow

   pip install alphaflow
   

2. Basic Example

   from datetime import datetime
   
   from alphaflow import AlphaFlow
   from alphaflow.brokers import SimpleBroker
   from alphaflow.data_feeds import PolarsDataFeed
   from alphaflow.strategies import BuyAndHoldStrategy
   
   # 1. Initialize AlphaFlow
   flow = AlphaFlow()
   flow.set_cash(100000)
   flow.set_backtest_start_timestamp(datetime(1990, 2, 10))
   flow.set_backtest_end_timestamp(datetime(2025, 1, 5))
   
   # 2. Create DataFeed (e.g., CSV-based daily bars)
   flow.set_data_feed(
       PolarsDataFeed(
           df_or_file_path="historical_data.csv",
       )
   )
   
   # 3. Set Equity Universe
   flow.add_equity("BND")
   flow.add_equity("SPY")
   
   # 4. Initialize Strategy
   flow.add_strategy(
       BuyAndHoldStrategy(
           symbol="SPY",
           target_weight=0.9
       )
   )
   flow.add_strategy(
       BuyAndHoldStrategy(
           symbol="BND",
           target_weight=0.1
       )
   )
   
   # 5. Create Broker
   flow.set_broker(SimpleBroker())
   
   # 6. Run the backtest
   flow.run()
   

3. Monitor Results

   • Use built-in analytics or your own custom module to generate metrics and charts.
   • Check logs to see partial fills, order details, and event flows.

Contributing

We welcome contributions from the community! To get started:

1. Fork the repository and create a new branch.
2. Implement or fix a feature.
3. Submit a pull request describing your changes.

License

AlphaFlow is released under the MIT License. See LICENSE for details.

Contact & Community

• GitHub: github.com/brandonschabell/alphaflow

Thank you for choosing AlphaFlow! We’re excited to see what you’ll build.