How chocksy/qc-options-framework works
Project Type and Purpose
• The project is a hybrid trading algorithm framework built on top of QuantConnect’s Lean engine. It is designed for implementing options strategies. The framework provides multiple interchangeable components (Alpha models, Execution models, Monitor models, and PortfolioConstruction models) that allow customizing how strategies generate signals, manage positions, execute trades, and monitor risk.
• The README explains that developers need to plug in their custom models into the main engine (via main.py), and the project uses a “hybrid” system of context management (with self.context storing positions, orders, and trade data).
File Structure
• Notice the clear separation into modular folders:
• Alpha – Contains various strategy components (e.g., SPXic, FPLModel, etc.) including the Base.py that acts as the foundation for any new alpha strategy.
• Execution – Contains models to handle order execution with further submodules such as Utils for order handling (LimitOrderHandler, MarketOrderHandler).
• Monitor – Contains monitoring modules (e.g., Risk Management, StopLoss) and again a Base.py for uniformity.
• PortfolioConstruction – Contains portfolio management components.
• Strategy – Contains a dataclass for Position and possibly related order dataclasses.
• Initialization – Contains the SetupBaseStructure which attaches initial parameters and sets up the algorithm’s context.
• Data, CustomIndicators, Tools, Research – Provide auxiliary functionalities: data handling (GoogleSheetsData, DataHandler), calculation aids (charting, performance, helper modules) as well as code for research (Jupyter Notebook, Charting in Research/Charting.py).
• Order – Manages order building and order abstractions.
• Tests – Contains well-organized test suites for each of these modules.
• Other directories (.airesearch, .cursor) contain documentation, research, and protocol rules – these provide background information and detailed notes on research and code style.
Key Components
a. Main Components:
• Alpha Strategy Layer (Alpha folder): Implements trading signals using different models (e.g., SPXic, CCModel).
• Execution Layer (Execution folder): Governs the order execution using multiple handlers.
• Monitoring Layer (Monitor folder): Manages risk and monitors open positions.
• PortfolioConstruction: Builds and maintains positions based on strategies.
• Order Management: Includes the Order folder for building orders.
• Initialization: Bootstrapping of the context, variable setup, and integration with QuantConnect (handled by SetupBaseStructure.py).
• Data and Tools: Supporting modules for data ingestion (GoogleSheetsData in Data, and others in Tools) and technical functions (Charting, Logger, Performance etc.).
• Research & Documentation: Modules in .airesearch and Research folders that explain the strategy ideas and analytical components.
b. Relationships and Interactions:
• The main.py file serves as the entry point where specific Alpha, Execution, Monitor, and PortfolioConstruction models are initialized and injected into the algorithm’s context.
• The Initialization module configures the algorithm environment and sets up base structures (like self.context with allPositions, openPositions, workingOrders).
• The Alpha models generate trading insights which then feed into the PortfolioConstruction logic that builds new Positions.
• The Execution models act on those Positions by managing order submission (using their native order handlers).
• The Monitor modules continuously observe positions and risk, possibly triggering updates or adjustments in execution.
• There is heavy dependency on shared Tools for helper functions (charting, logging, performance tracking) which support Analytics and Research.
• Communication between these modules is achieved by sharing a common data structure (e.g., Strategy/Position and related dataclasses).
c. Architectural Patterns and Design Principles:
• Inheritance and Abstraction: The use of Base.py classes in each folder (Alpha, Execution, Monitor, PortfolioConstruction) encourages a plug-and-play design.
• Separation of Concerns: Despite the “hybrid” nature, the project distinctly organizes responsibilities across modules, separating concerns such as strategy generation, trade execution, monitoring, and portfolio construction.
• Extensibility: Custom indicators and research documents indicate that the system is designed to be extended and modified with new strategies, execution protocols, or risk management features.
• Testing & Continuous Integration: The thorough tests in the Tests folder and CI configurations (e.g., in .github/workflows) suggest that robust testing is part of the design.
d. Relevant Technologies, Frameworks, and Libraries:
• QuantConnect Lean Engine: The backbone for running the algorithm.
• PDM: For dependency management.
• Python: The primary language with usage of dataclasses (in Strategy/Position).
• Tools/Utilities: Custom implementations for orders, charting and performance tracking (see Tools and CustomIndicators folders).
• CI tools: GitHub workflows (tests.yml) indicate continuous integration support.