AlphaSuite

AlphaSuite is an open-source quantitative analysis platform that gives you the power to build, test, and deploy professional-grade trading strategies. It's designed for traders and analysts who want to move beyond simple backtests and develop a genuine, data-driven edge in the financial markets.

✨ Key Features

• Modular Strategy Engine: A powerful, pybroker-based engine for rigorous backtesting.
  • Walk-Forward Analysis: Test strategies on out-of-sample data to prevent overfitting and ensure robustness.
  • Bayesian Optimization: Automatically tune strategy parameters to find the most optimal settings.
  • ML Integration: Seamlessly integrate machine learning models (like LightGBM) into your strategies.
  • Extensible SDK: Add new, complex trading strategies by creating a single Python file.
• Powerful Market Scanning: A fully customizable scanner to find trading opportunities across global markets.
  • Generic Screener: A rich UI to build custom screens using dozens of fundamental and technical filters without writing code.
  • Custom Scanner SDK: An extensible framework to create scanners for any pattern imaginable, from RSI divergences to complex Wyckoff setups.
  • 20+ Pre-Built Scanners: Comes with a rich library of ready-to-use scanners for common trading patterns.
• Comprehensive Data & Research Tools: An integrated suite for deep market analysis.
  • Automated Data Pipeline: Fetches and stores comprehensive data for global markets from Yahoo Finance into a PostgreSQL database.
  • AI-Powered Stock Reports: Generate in-depth fundamental and technical analysis reports for any stock using LLMs.
  • AI News Intelligence: Get AI-generated market briefings and risk analysis based on the latest financial news.

🌐 Live Demo

Check out the live dashboard application here: https://alphasuite.aitransformer.net

Note: The live demo runs on a free-tier service. To prevent high costs and long loading times, data loading and AI-powered features are disabled. For full functionality and the best performance, it's recommended to run the application locally.

🖼️ Screenshots

Here's a glimpse of what you can do with AlphaSuite.

Home Page

Backtest Performance Visualization

Analyze the out-of-sample performance of a trained and tuned strategy model.

Summary Metrics & Equity Curve:

Trade Execution Chart:

Detailed Metrics Table:

📖 Articles & Case Studies

Check out these articles to see how AlphaSuite can be used to develop and test sophisticated trading strategies from scratch:

• Stop Paying for Stock Screeners. Build Your Own for Free with Python: A comprehensive guide on using AlphaSuite's modular market scanner to build custom screens for any market, moving beyond the limitations of commercial tools.
• From Backtest to Battle-Ready: A Guide to Preparing a Trading Strategy with AlphaSuite: A practical, step-by-step walkthrough for taking a strategy from concept to live-trading readiness using our open-source quant engine.
• We Backtested a Viral Trading Strategy. The Results Will Teach You a Lesson.: An investigation into a popular trading strategy, highlighting critical lessons on overfitting, data leakage, and the importance of robust backtesting. Also available as a video narration.
• I Was Paralyzed by Uncertainty, So I Built My Own Quant Engine: The story behind AlphaSuite's creation and its mission to empower data-driven investors. Also available as a video narration.
• From Chaos Theory to a Profitable Trading Strategy: A step-by-step guide on building a rule-based strategy using concepts from chaos theory.
• Supercharging a Machine Learning Strategy with Lorenz Features: Demonstrates how to enhance an ML-based strategy with custom features and optimize it using walk-forward analysis.
• The Institutional Edge: How We Boosted a Strategy’s Return with Volume Profile: A deep dive into using Volume Profile to enhance a classic trend-following strategy, demonstrating a significant performance boost.

🛠️ Tech Stack

• Backend: Python
• Web Framework: Streamlit
• Backtesting Engine: pybroker
• Data Analysis: Pandas, NumPy, SciPy
• Financial Data: yfinance, TA-Lib
• Database: PostgreSQL with SQLAlchemy
• AI/LLM: LangChain, Google Gemini, Ollama

📂 Project Structure

The project is organized into several key directories:

• core/: Contains the core application logic, including database setup (db.py), model definitions (model.py), and logging configuration.
• pages/: Each file in this directory corresponds to a page in the Streamlit web UI.
• pybroker_trainer/: Holds the machine learning pipeline for training and tuning trading models with pybroker.
• strategies/: Contains the definitions for different trading strategies. New strategies can be added here.
• scanners/: Contains the definitions for custom market scanners. New scanners can be added here.
• tools/: Includes various utility modules for tasks like financial calculations, data scanning, and interacting with the yfinance API.
• Home.py: The main entry point for the Streamlit application.
• download_data.py: The command-line interface for all data management tasks.
• quant_engine.py: The core quantitative engine for backtesting and analysis.
• requirements.txt: A list of all the Python packages required to run the project.
• .env.example: An example file for environment variables.

🚀 Getting Started

Follow these steps to set up and run AlphaSuite on your local machine.

1. Prerequisites

• Python 3.9+
• PostgreSQL Server
• Git

2. Installation

1. Clone the repository:

   git clone https://github.com/rsandx/AlphaSuite.git
   cd AlphaSuite

2. Create and activate a virtual environment:

   # Windows
   python -m venv venv
   .\venv\Scripts\activate
   
   # macOS / Linux
   python3 -m venv venv
   source venv/bin/activate

3. Install dependencies:

   • TA-Lib: This library has a C dependency that must be installed first. Follow the official TA-Lib installation instructions for your operating system.
   • Install the remaining Python packages:

     pip install -r requirements.txt

4. Set up the Database:

   • Ensure your PostgreSQL server is running.
   • Create a new database (e.g., alphasuite).
   • The application will create the necessary tables on its first run.

5. Configure Environment Variables:

   • Copy the example environment file:

     cp .env.example .env

   • Open the .env file and edit the variables:
     • DATABASE_URL: Set this to your PostgreSQL connection string.
     • LLM_PROVIDER: Set to gemini or ollama to choose your provider.
     • GEMINI_API_KEY: Required if LLM_PROVIDER is gemini.
     • OLLAMA_URL: The URL for your running Ollama instance (e.g., http://localhost:11434). Required for ollama.
     • OLLAMA_MODEL: The name of the model you have pulled in Ollama (e.g., llama3).

3. Usage

1. Initial Data Download: Before running the app, you need to populate the database with market data. Run the download script from your terminal. This may take a long time for the initial run.

   • For the very first run to populate your database:

     python download_data.py download 

   # For subsequent daily updates, run the pipeline:
   python download_data.py pipeline

2. Run the Streamlit Web Application:

   streamlit run Home.py

   Open your web browser to the local URL provided by Streamlit (usually http://localhost:8501).

3. Follow the In-App Workflow:

   1. Populate Data: Go to the Data Management page and run the "Daily Pipeline" or a "Full Download".
   2. Scan for Setups: Go to the Market Scanner page. Use the "Signal Scanner" to find setups from your trained ML models, or use the "Generic Scanner" to find stocks matching fundamental or technical criteria with custom scanners.
   3. Tune & Train: To build custom models, navigate to the Model Training & Tuning page.
   4. Analyze & Backtest: Use the Portfolio Analysis page to validate your strategies.
   5. Deep Research: Use the Stock Report page for in-depth analysis of specific stocks.

🧠 Adding a New Trading Strategy

The quantitative engine is designed to be modular, allowing new trading strategies to be developed and integrated by simply adding a single, self-contained Python file to the strategies/ directory. The system automatically discovers and loads any valid strategy file at runtime.

How It Works

The system scans the strategies/ directory for Python files. Inside each file, it looks for a class that inherits from pybroker_trainer.strategy_sdk.BaseStrategy. This class encapsulates all the logic and parameters for a single strategy. Two sample strategy files are included in the repository: ma_crossover.py is a non-ML, rule-based strategy; donchian_breakout.py is a ML-based strategy. You can use them as a reference for building your own.

Step-by-Step Guide

1. Create a New File: Create a new Python file in the strategies/ directory. The filename should be descriptive and use snake_case (e.g., my_awesome_strategy.py).
2. Define the Strategy Class: Inside the new file, define a class that inherits from BaseStrategy. The class name should be descriptive and use CamelCase (e.g., MyAwesomeStrategy).
3. Implement Required Methods: Implement the four required methods within your class: define_parameters, get_feature_list, add_strategy_specific_features, and get_setup_mask.

Strategy Class Breakdown

Each strategy class must implement the following methods, which define its behavior, data requirements, and entry logic.

1. define_parameters()

This static method defines all the parameters the strategy uses, their default values, and their tuning ranges for optimization. This is critical for backtesting and hyperparameter tuning.

• Returns: A dictionary where each key is a parameter name. The value is another dictionary specifying its type, default value, and a tuning_range tuple.

Example from DonchianBreakoutStrategy:

@staticmethod
def define_parameters():
    """Defines parameters, their types, defaults, and tuning ranges."""
    return {
        'donchian_period': {'type': 'int', 'default': 20, 'tuning_range': (15, 50)},
        'atr_period': {'type': 'int', 'default': 14, 'tuning_range': (10, 30)},
        # ... other parameters
    }

2. get_feature_list()

This method returns a list of all the feature (column) names that the strategy's machine learning model requires as input. The training engine uses this list to prepare the data correctly.

• Returns: A list of strings.

Example from DonchianBreakoutStrategy:

def get_feature_list(self) -> list[str]:
    """Returns the list of feature column names required by the model."""
    return [
        'roc', 'rsi', 'mom', 'ppo', 'cci',
        # ... other features
    ]

3. add_strategy_specific_features()

This is where you calculate any indicators or features that are unique to your strategy and are not part of the common features provided by the system.

• Arguments: A pandas DataFrame containing the price data and common indicators.
• Returns: The modified pandas DataFrame with your new feature columns added.

Example from DonchianBreakoutStrategy:

def add_strategy_specific_features(self, data: pd.DataFrame) -> pd.DataFrame:
    """Calculates and adds features unique to this specific strategy."""
    donchian_period = self.params.get('donchian_period', 20)
    data['donchian_upper'] = data['high'].rolling(window=donchian_period).max()
    data['donchian_lower'] = data['low'].rolling(window=donchian_period).min()
    data['donchian_middle'] = (data['donchian_upper'] + data['donchian_lower']) / 2
    return data

4. get_setup_mask()

This is the core of your strategy's entry logic. This method must return a boolean pandas Series that is True on the bars where a potential trade setup occurs and False otherwise.

• Arguments: A pandas DataFrame containing all required features (both common and strategy-specific).
• Returns: A pandas Series of boolean values, with the same index as the input DataFrame.

Example from DonchianBreakoutStrategy:

def get_setup_mask(self, data: pd.DataFrame) -> pd.Series:
    """Returns a boolean Series indicating the bars where a trade setup occurs."""
    is_uptrend = data['trend_bullish'] == 1
    is_breakout = data['high'] > data['donchian_upper'].shift(1)
    raw_setup_mask = is_uptrend & is_breakout
    # Ensure we only signal on the first bar of a new setup
    return raw_setup_mask & ~raw_setup_mask.shift(1).fillna(False)

By following this structure, you can create new, complex strategies that seamlessly integrate with the project's backtesting, tuning, and training infrastructure.

🧠 Adding a New Scanner

AlphaSuite comes with over 20 pre-built custom scanners that are ready to use out of the box. These scanners cover a wide range of technical and fundamental patterns, from classic RSI divergences to complex Wyckoff accumulation setups. They not only provide powerful screening capabilities but also serve as excellent, practical examples for developers looking to build their own custom scanners.

The Market Scanner is also designed to be modular, allowing you to create and integrate custom scanners with minimal effort. By adding a self-contained Python file to the scanners/ directory, the system will automatically discover and load it into the Streamlit UI.

How It Works

The system scans the scanners/ directory for Python files. Inside each file, it looks for a class that inherits from scanners.scanner_sdk.BaseScanner. This class encapsulates all the logic and parameters for a single scanner. The generic_screener.py is a special, built-in scanner, but any other file you add will be treated as a custom scanner.

Step-by-Step Guide

1. Create a New File: Create a new Python file in the scanners/ directory. The filename should be descriptive and use snake_case (e.g., my_custom_scanner.py). The filename will be used as the scanner's unique identifier.
2. Define the Scanner Class: Inside the new file, define a class that inherits from BaseScanner. The class name should be descriptive and use CamelCase (e.g., MyCustomScanner).
3. Implement Required Methods: Implement the required methods within your class to define its parameters, display columns, and scanning logic.

Scanner Class Breakdown

Each scanner class should implement the following methods to define its behavior.

1. define_parameters()

This static method defines the parameters that will appear in the UI for your scanner. It allows users to customize the scan without changing the code.

• Returns: A list of dictionaries, where each dictionary defines a parameter's name, type (int, float, select), default value, and label.

Example from BullishDipBounceScanner:

@staticmethod
def define_parameters():
    return [
        {"name": "min_avg_volume", "type": "int", "default": 250000, "label": "Min. Avg. Volume"},
        {"name": "rsi_period", "type": "int", "default": 7, "label": "RSI Period"},
        {"name": "divergence_lookback", "type": "int", "default": 30, "label": "Divergence Lookback"},
    ]

2. get_leading_columns()

This static method returns a list of column names that should be displayed first in the results table, ensuring the most important information is easily visible.

• Returns: A list of strings.

Example from BullishDipBounceScanner:

@staticmethod
def get_leading_columns():
    return ['symbol', 'rsi', 'divergence_date', 'longname', 'marketcap']

3. get_sort_info()

This static method defines the default sorting order for the results table.

• Returns: A dict specifying the column(s) to sort by and the ascending order.

Example from BullishDipBounceScanner:

@staticmethod
def get_sort_info():
    return {'by': 'marketcap', 'ascending': False}

4. scan_company()

This is the core logic of your scanner. The base framework handles filtering stocks by market, volume, and market cap, then calls this method for each remaining company. Your job is to analyze the provided data and determine if the company is a match.

• Arguments:
  • group: A pandas DataFrame containing the company's historical price data.
  • company_info: A dict containing basic company information from the database.
• Returns: The company_info dictionary if the stock matches the criteria (you can add new keys to it, like divergence_date), or None if it does not.

Example from BullishDipBounceScanner:

def scan_company(self, group: pd.DataFrame, company_info: dict) -> dict | None:
    # ... (calculation logic for RSI, SMA, and divergence) ...

    if is_uptrend and is_lower_low_price and is_higher_rsi:
        company_info['rsi'] = float(rsi.iloc[-i])
        company_info['divergence_date'] = group['date'].iloc[-i].strftime('%Y-%m-%d')
        return company_info
    
    return None

For scanners with more complex requirements that don't fit the per-company iteration model (like the StrongestIndustriesScanner, which groups by industry first), you can override the run_scan() method to implement your own custom data fetching and processing logic.

⚖️ License

This project is licensed under the MIT License - see the LICENSE file for details.