🌋 AlphaForge

AlphaForge is an enterprise-grade, local-first algorithmic trading backtesting platform designed to execute and compare quantitative strategies side-by-side using the industrial-strength QuantConnect LEAN engine. It handles the entire lifecycle of a strategy—from raw Python logic to containerized sandbox execution, real-time metrics parsing, and beautiful dual-strategy dashboard comparative analytics.

By utilizing local container execution, AlphaForge bypasses cloud-based paywalls, subscriptions, and restrictive APIs. Your intellectual property (strategy code) and data remain 100% on your machine, executing with real institutional backtesting fidelity.

---

🔍 Key Highlights & Features

• ⚡ Zero-Dependency Interactive Dashboard: An integrated, ultra-fast single-page interface with a responsive Dark-Dimmed theme. Features customized native HTML5 canvas charts for overlaid portfolio equity curves and metric breakdowns without external rendering framework dependencies.
• 🛡️ Hardened Sandbox Isolation: Every strategy runs within its own secure, isolated container built on quantconnect/lean:latest. Resources are strictly limited (--cpus 2.0 --memory 2g --network none) to prevent malicious activity or system resource exhaustion.
• 🔄 Live Pipeline Streaming: Strategy execution states and backtest progress are streamed in real time to the browser via WebSockets over five pipeline stages: HYPOTHESIS ➔ DATA_HUB ➔ SIGNAL_DETECTION ➔ PORTFOLIO_AND_RISK ➔ EVALUATION.
• 📊 Autonomous Alternative Data Hub: Integrated with yfinance to automatically pull, downsample (daily vs. minute), feature-engineer, and cache alternative OHLCV datasets enriched with deterministic momentum, sentiment, and signal strength indicators.
• 🧬 Heuristic Code Transpilation: Converts high-level, human-readable trading code into enterprise-grade QuantConnect boilerplate using custom AST and Regex-based code mappings.

---

🏗️ Architecture Design

AlphaForge is designed with an event-driven, micro-services oriented topology where the FastAPI gateway orchestrates ephemeral container work-loops.

                  ┌────────────────────────────────────────┐
                  │          Client (Browser UI)           │
                  └────────────▲──────────────────────┬────┘
                    WebSocket  │                      │
                  /ws/compare  │                      │ Submit Strategies
                               │                      ▼
                  ┌────────────┴───────────────────────────┐
                  │            FastAPI Server              │
                  ├────────────────────────────────────────┤
                  │  • Code Transpiler (AST/Regex Engine)  │
                  │  • Data Hub Fetcher & Momentum Engine  │
                  │  • Asynchronous Container Orchestrator │
                  └────────────┬──────────────────────┬────┘
                               │                      │
              Mount Data (Ro)  │                      │ Mount Workspaces (Rw)
                               ▼                      ▼
                  ┌────────────────────────┐     ┌────────────────────────┐
                  │     Local Data Hub     │     │ Ephemeral Workspaces   │
                  │  data/custom_sources/  │     │ projects/{strategy_id} │
                  └────────────┬───────────┘     └────────────┬───────────┘
                               │                              │
                               └──────────────┬───────────────┘
                                              │ Spawn Ephemeral Sandbox
                                              ▼
                               ┌──────────────────────────────┐
                               │     Docker Engine API        │
                               │   quantconnect/lean:latest   │
                               ├──────────────────────────────┤
                               │  - CPU: 2.0  - Memory: 2G    │
                               │  - Network: None             │
                               └──────────────┬───────────────┘
                                              │
                                              │ writes results/<id>/output.json
                                              ▼
                               ┌──────────────────────────────┐
                               │  Metrics Parser Engine       │
                               │  (Extracts CAGR, Sharpe,     │
                               │   Sortino, Drawdown, Equity) │
                               └──────────────────────────────┘

Components Breakdown:

1. FastAPI Gateway: Exposes async WebSocket and Static routes. Manages concurrent client sessions and schedules execution tasks using asyncio.gather.
2. Transpiler Engine: Automatically rewrites simple assignments and calls (e.g., positions['SPY'] = 1 or buy()) into a complete subclass of LEAN's QCAlgorithm with zero manual boilerplate.
3. Local Data Hub: Slices, caches, and indexes historical stock price series. Infers minute-bar resolutions for ranges under 5 weeks and daily-bar resolutions for longer ranges to match LEAN's expectations.
4. Orchestrator Engine: Interacts with the Docker socket daemon to start/stop the official quantconnect/lean container, monitors progress using live log parsing, and cleans up artifacts upon execution end.
5. Metrics Parser Engine: Transforms deep, multi-megabyte JSON output structures generated by LEAN's backtester into high-fidelity flat metrics (Sharpe, Drawdown, Win Rate, CAGR, and an equity curve vector).

---

⏳ The Five-Stage Pipeline Lifecycle

Each strategy submission triggers a robust, asynchronous linear pipeline:

1. HYPOTHESIS: Performs abstract syntax tree (AST) validation to verify Python code validity. Transpiles user logic, constructs the config.json launch blueprint, and scaffolds the ephemeral workspaces inside ./projects/{strategy_id}/.
2. DATA_HUB: Verifies if target market data is cached. If absent, downloads historical bars from yfinance, calculates technical features (SentimentScore and SignalStrength based on momentum-derived variables), and writes standard CSV files under data/custom_sources/ as read-only.
3. SIGNAL_DETECTION: Spawns the Docker sandbox container, maps dependencies, hooks the container standard output stream, initializes indicator warmup loops inside the LEAN engine, and begins step-by-step engine execution.
4. PORTFOLIO_AND_RISK: Runs the algorithm backtesting loop. Simulates order matching queues, fills, brokerage commissions, margin accounts, tracking constraints, and records continuous performance metrics.
5. EVALUATION: Stops the container, deletes intermediate project artifacts, parses the LEAN raw results, extracts core statistics, evaluates them against configuration limits (such as maximum drawdowns), and streams the final payload to the client.

---

🛡️ Sandbox & Security Constraints

To guarantee system stability, AlphaForge enforces absolute sandbox isolation on spawned containers:

• Resource Caps: Hard limits of --cpus 2.0 and --memory 2g prevent memory exhaustion (OOM crashes) or full-core locks on the host.
• Zero Network Access: Spawning with --network none guarantees that user strategies cannot transmit intellectual property, secrets, or perform unauthorized internet connectivity.
• Strict Access Modes: Sourced data caches are mounted as Read-Only (ro) to prevent running strategies from altering historical prices. Only temporary configuration and results output folders are mounted as Read-Write (rw).
• Docker Optimization: Custom options are written to /etc/docker/daemon.json to optimize container disk performance (overlay2 storage driver) and stream parallel workloads without bottlenecks.

---

🛠️ Installation & One-Shot Setup

Follow these streamlined instructions to configure and deploy AlphaForge on your Linux host.

Prerequisites

• Operating System: Linux (systemd-managed distributions such as Ubuntu, Debian, Arch Linux, or Fedora).
• Docker Engine: Installed and running (Docker daemon started).
• Python Runtime: Python 3.10 or 3.11 with pip and virtual environment support (python3-venv).
• Disk Capacity: Minimum ~13 GB of free disk space is required to store the official quantconnect/lean:latest engine image.
• And patience

1. Clone & Set Up Directory

git clone https://github.com/Pulkitsheoran/AlphaForge.git
cd AlphaForge

# Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate

# Install backend dependencies
pip install -r requirements.txt

# Initialize configuration
cp .env.example .env

2. Execute Automated Provisioning

Run the automated setup script to set up Docker permissions, fetch the LEAN image, and merge Docker configuration settings:

# Requires sudo access to configure Docker and append group memberships
bash setup.sh

The script will:

• Enable and start the Docker service.
• Append your current user to the docker security group.
• Apply high-performance settings inside /etc/docker/daemon.json.
• Download and extract the quantconnect/lean:latest base image.

3. Reload Shell Group Membership

Since your user's group configuration has changed, reload your terminal session for Docker group changes to take effect:

newgrp docker

---

🚀 Running the Platform

To start the AlphaForge backend daemon, execute:

./start.sh

This launches the FastAPI server detached inside a new process group. All server events and outputs are automatically written to server.log.

To monitor the backend server log stream:

tail -f server.log

Once running, navigate to:

http://localhost:8000

to access the visual Comparison Dashboard.

---

✍️ Strategy Authoring Guide

Algorithms in AlphaForge are written as pure decision-making logic blocks. No class boilerplate or indicator definitions are required.

Supported Environment Fields

The following variables are dynamically mapped and available within your strategy runtime:

• price: The current close price of the active symbol.
• sentiment: A momentum-derived alternate sentiment score bounded roughly between -1.0 (bearish) and +1.0 (bullish).
• signal_strength: A technical trend metric representing relative indicators, bounded between 0.0 (no trend) and 1.0 (strong trend).
• positions['<SYMBOL>']: Set to 1 to allocate full capital (equivalent to SetHoldings) or set to 0 to exit position (equivalent to Liquidate).

High-level Code Translative Mapping

Under the hood, AlphaForge translates your high-level syntax into explicit QuantConnect commands:

User Code Syntax	Transpiled LEAN Output
buy()	self.SetHoldings(self.custom_symbol, 1.0)
sell()	self.Liquidate(self.custom_symbol)
positions['SPY'] = 1	self.SetHoldings(self.custom_symbol, 1.0)
positions['SPY'] = 0	self.Liquidate(self.custom_symbol)
SetHoldings('SPY', 0.5)	self.SetHoldings(self.custom_symbol, 0.5)
Liquidate('SPY')	self.Liquidate(self.custom_symbol)

Practical Code Examples

1. Sentiment Momentum Strategy

Executes trade positions based on momentum-derived alternative sentiment scores:

if sentiment > 0.80 and signal_strength > 0.4:
    positions['SPY'] = 1
elif sentiment < 0.20 or signal_strength > 0.8:
    positions['SPY'] = 0

2. Mean Reversion Logic

Takes advantage of localized price pullbacks:

if sentiment < -0.60:
    buy()
elif sentiment > 0.60:
    sell()

---

📡 API & WebSocket Contract (/ws/compare)

Integrate custom clients or external bots with the platform using our standard WebSocket schema.

1. Ingestion Request (Client ➔ Server)

Submit a payload containing multiple strategy definitions to trigger parallel execution:

{
  "action": "START_COMPARISON",
  "strategies": [
    {
      "id": "momentum_v1",
      "name": "Sentiment Momentum V1",
      "code": "if sentiment > 0.85: buy()",
      "initial_capital": 100000.0,
      "benchmark": "SPY",
      "symbol": "SPY",
      "start_date": "2024-01-01",
      "end_date": "2025-12-31"
    },
    {
      "id": "reversion_v1",
      "name": "Mean Reversion V1",
      "code": "if sentiment < 0.15: buy()\\nelif sentiment > 0.80: sell()",
      "initial_capital": 100000.0,
      "benchmark": "SPY",
      "symbol": "SPY",
      "start_date": "2024-01-01",
      "end_date": "2025-12-31"
    }
  ]
}

2. Streaming Progress State (Server ➔ Client)

During the backtest run-loop, states are continuously broadcast to update UI loading gauges:

{
  "strategy_id": "momentum_v1",
  "stage": "PORTFOLIO_AND_RISK",
  "status": "RUNNING",
  "progress_pct": 42.5,
  "message": "Processing slice timestamp: 2024-08-15 11:30:00"
}

3. Final Evaluation Response (Server ➔ Client)

Once execution completes, normalized portfolio vectors and statistics are published:

{
  "strategy_id": "momentum_v1",
  "stage": "EVALUATION",
  "status": "SUCCESS",
  "metrics": {
    "initial_capital": 100000.0,
    "final_equity": 124890.50,
    "cagr_pct": 11.75,
    "sharpe_ratio": 1.42,
    "sortino_ratio": 1.68,
    "max_drawdown_pct": 7.35,
    "total_trades": 86,
    "win_rate_pct": 54.65
  },
  "equity_curve": [
    { "timestamp": "2024-01-01T00:00:00Z", "equity": 100000.0 },
    { "timestamp": "2024-01-02T00:00:00Z", "equity": 100150.0 }
  ]
}

---

📁 File Structure Reference

AlphaForge/
├── app/
│   ├── main.py                  # FastAPI server startup & WebSocket endpoints
│   ├── engine/
│   │   ├── transpiler.py        # Abstract Code Transpilation & boilerplates
│   │   ├── data_hub.py          # Real market-data downloader & indicator feature-engineering
│   │   ├── orchestrator.py      # EPHEMERAL Docker workspace launcher & progress tracker
│   │   └── metrics_parser.py    # Raw LEAN backtest JSON parser
│   ├── models/
│   │   └── schemas.py           # Pydantic schemas for data-validation
│   └── static/
│       └── index.html           # Single-page client dashboard (Vanilla HTML/CSS/Canvas/JS)
├── config/
│   └── daemon.json              # Optimized Docker Daemon properties
├── data/
│   └── custom_sources/          # Cached historical market data (.csv files)
├── projects/                    # Ephemeral, git-ignored strategy workspace folders
├── results/                     # Ephemeral, git-ignored strategy output folders
├── .env.example                 # Template for custom environment properties
├── pyrightconfig.json           # Python language server typing layout
├── setup.sh                     # System configuration and Docker provisioning shell script
├── SPEC.md                      # Detailed system engineering specification
└── start.sh                     # Daemonized FastAPI server launcher script

---

⚙️ Configuration (.env)

The following parameters can be fine-tuned inside your local .env configuration file:

• LEAN_PROJECT_NAME: Defines the root strategy project identifier.
• LEAN_WORKSPACE_DIR: Points to the local workspace folder.
• RESULTS_ROOT_DIR: Path where backtest evaluation files are temporally structured.
• SHARPE_DEGRADATION_THRESHOLD: Standard warning threshold when strategy Sharpe ratios dip below target values.
• MAX_DRAWDOWN_LIMIT: Security policy trigger when absolute drawdown exceeds the acceptable ceiling (e.g. 0.25 for 25%).

---

⚠️ Platform Limitations

• Indicator Proxying: Currently, SentimentScore and SignalStrength are generated using deterministic momentum formulas based on raw OHLCV series. They serve as placeholder indicators and should be replaced with live sentiment api feeds for true quantitative validation.
• Intraday Resolutions: Intraday minute-bar accuracy provided by yfinance is restricted to recent trading periods (typically up to 30 days). Backtests requested for historical ranges beyond this range will automatically fallback to daily resolution bars.
• Ratios Initialization: Calculating Sharpe and Sortino ratios requires a sufficiently robust transaction frequency and timeline length. Extremely short backtests (e.g., under 15 trading days) may yield mathematical zeros (0.0).

---

📄 License

AlphaForge is open-source software licensed under the MIT License. Feel free to adapt, build upon, or integrate this engine into your proprietary trading desks.