Skip to main content

α AlphaForge

AI-Powered Market Intelligence & Quantitative Trading Platform

Python 3.11+ Pydantic v2 License Status

Institutional-grade scaffold for cross-asset prediction, risk-aware signal generation, continual learning, and human-readable decision support.


🎯 What is AlphaForge?

AlphaForge is an institutional-grade scaffold for an AI-powered market intelligence and quantitative trading platform. It is designed as a research-to-production operating system for:

  • Cross-asset prediction — Equities, crypto, futures, and derivatives
  • Risk-aware signal generation — Volatility-adjusted sizing, drawdown protection
  • Continual learning — Adaptive regime detection, model retraining pipelines
  • Human-readable decision support — Explainable signals, not black boxes

Built for traders who want to understand why a signal fires, not just that it fires.


🖼️ Screenshots

📊 Full Dashboard View

Dashboard Screenshot

Real-time market data, watchlist, macro indicators, and stock analysis in one unified view


🔍 Detailed Stock Analysis

Stock Analysis Screenshot

Deep dive into individual stocks with risk assessment, insider trading, and earnings data


🎨 UI Highlights

Feature Preview
API Quota Monitor Hover over API section
Smart Watchlist Add/remove with optimistic UI
Stock Screener Multi-factor filtering
Alert System Real-time notifications

🚀 Installation

Prerequisites

Requirement Version
Python 3.11+

Quick Install (PyPI)

pip install alphaforged

That's it. One command installs:

  • Core package (pydantic models, risk engine, backtesting, research tournament)
  • Operator console web app (FastAPI + static HTML/JS/CSS)
  • CLI entry point

Launch

# Start the operator console
alphaforge serve

# Custom port
alphaforge serve --port 9000

# Run demo pipeline
alphaforge demo

Open http://localhost:8765 in your browser.

First-Time Setup

Create a .env file in your working directory:

ALPHA_VANTAGE_API_KEY=your_key_here
FRED_API_KEY=your_key_here
FINNHUB_API_KEY=optional

Get free keys:

Install with All Dependencies

# Full install (ML, data, API, UI, ops)
pip install "alphaforge[all]"

# Or specific groups
pip install "alphaforge[ml]"      # PyTorch, scikit-learn, XGBoost
pip install "alphaforge[data]"    # Pandas, Polars, DuckDB
pip install "alphaforge[api]"     # FastAPI, Uvicorn

Development Install (from source)

# Clone the repo
git clone https://github.com/Soodkrish03/alphaforge.git
cd alphaforge

# uv reads .python-version + uv.lock → exact same Python + deps
uv sync --all-extras

uv automatically installs Python 3.13.4 (pinned in .python-version) and all dependencies from uv.lock. No version mismatches, no "works on my machine."


⚙️ Configuration

Environment Variables (.env)

Variable Required Description
ALPHA_VANTAGE_API_KEY ✅ Stock data, fundamentals, news sentiment
FRED_API_KEY ✅ Macroeconomic indicators
FINNHUB_API_KEY ❌ Near-realtime US stock quotes

Platform Config (configs/platform.toml)

[risk]
max_gross_exposure = 2.5
max_drawdown_pct = 12.0
volatility_target_pct = 14.0

[research]
walk_forward_windows = 12
stress_paths = 5000
tournament_size = 128

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                           OPERATOR CONSOLE GUI                              │
│   Real-time Dashboard │ Watchlist │ Screener │ Alerts │ Portfolio │ Macros  │
├─────────────────────────────────────────────────────────────────────────────┤
│                              API LAYER                                      │
│   FastAPI REST │ WebSocket Streams │ gRPC (planned) │ Kafka Events         │
├─────────────────────────────────────────────────────────────────────────────┤
│                         ORCHESTRATION ENGINE                                │
│   Async Control Plane │ Regime Detection │ Model Retraining │ Alert Routing │
├─────────────────────────────────────────────────────────────────────────────┤
│                          RESEARCH TOURNAMENT                                │
│   Alpha Factor Ranking │ Walk-Forward Validation │ Model Comparison         │
├─────────────────────────────────────────────────────────────────────────────┤
│                          RISK ENGINE                                        │
│   Volatility Sizing │ Drawdown Brakes │ Kelly Scaling │ Position Limits     │
├─────────────────────────────────────────────────────────────────────────────┤
│                           ML PIPELINE                                       │
│   LSTM │ Transformer │ XGBoost │ Ensemble │ Regime Classifier              │
├─────────────────────────────────────────────────────────────────────────────┤
│                         FEATURE STORE                                       │
│   Feast Integration │ Time-Series Features │ Cross-Asset Signals            │
├─────────────────────────────────────────────────────────────────────────────┤
│                          DATA LAYER                                         │
│   yfinance │ Alpha Vantage │ FRED │ Finnhub │ Google News RSS │ Binance    │
└─────────────────────────────────────────────────────────────────────────────┘

✨ Features

📊 Operator Console (Live)

Feature Description
Real-Time Dashboard Live market data, charts, and portfolio overview
Smart Watchlist Add/remove symbols with optimistic UI updates
Stock Screener Multi-factor screening with sector/industry filters
Alert System Volatility, sentiment, regime, and liquidity alerts
API Quota Monitor Live tracking of Finnhub (60 req/min) and Alpha Vantage (25 req/day)
Market Movers Top gainers, losers, most active stocks
Macro Panel Fed funds rate, unemployment, yield curve, consumer sentiment
Insider Trading Real-time insider transactions from SEC filings
Earnings Calendar Upcoming earnings dates and estimates
Crypto Dashboard Fear & Greed Index, funding rates, on-chain metrics

🧠 Core Engine

Module Purpose
alphaforge.domain Pure data structures (TradePlan, RiskSnapshot, ModelPrediction)
alphaforge.models ML abstractions (BaseModel ABC, RegimeClassifier, EnsembleModel)
alphaforge.features Feast feature store wrapper with time-series support
alphaforge.execution RiskEngine, AlertEvent generation, position sizing
alphaforge.backtesting Deterministic simulation from TradePlan signals
alphaforge.research Experiment runner → IntelligenceReport with factor ranking
alphaforge.orchestration Async ControlPlane scheduling risk/model updates
alphaforge.runtime Demo entry point, UniverseMonitorService, FreeTierReportService

🛡️ Risk Management

# Automatic risk checks before every trade
RiskEngine.evaluate(
    trade_plan=plan,
    portfolio=portfolio,
    market_regime=current_regime,
)
# → Returns approved/rejected with explanation
  • Volatility-aware sizing — Position size inversely proportional to IV
  • Drawdown protection — Automatic halting at configurable thresholds
  • Kelly criterion scaling — Optimal bet sizing based on edge/volatility
  • Regime-adaptive limits — Tighter constraints in bear markets

📁 Project Structure

C:\VScode\ALGO
│
├── 📱 apps\operator_console\              # Live web dashboard
│   ├── index.html                         # Main UI (single-page app)
│   ├── app.js                             # All UI logic, charts, API calls
│   ├── styles.css                         # Professional dark theme
│   └── server.py                          # FastAPI server with REST endpoints
│
├── 🖼️ assets\                             # Screenshots, images, demo files
│   ├── s look.png                         # Dashboard screenshot
│   └── f look.png                         # Stock analysis screenshot
│
├── 🧠 src\alphaforge\                     # Core platform package
│   ├── domain\models.py                   # Typed data structures
│   ├── models\                            # ML model abstractions
│   ├── features\                          # Feature store wrapper
│   ├── execution\risk_engine.py           # Risk evaluation & sizing
│   ├── execution\alerts.py                # Alert generation
│   ├── backtesting\engine.py              # Deterministic simulation
│   ├── research\                          # Experiment runner
│   ├── orchestration\control_plane.py     # Async orchestrator
│   ├── data\free_market_data.py           # Free API connectors
│   └── runtime\                           # Services & demo entry
│
├── 📊 configs\platform.toml               # Platform defaults
├── 📈 data\universes\                     # Symbol universes (CSV)
├── 🧪 tests\                             # Deterministic unit tests
└── 📚 docs\                              # Architecture & wireframes

🔌 Data Sources

Free Tier (No API Key Required)

Provider Data Rate Limit
yfinance Prices, fundamentals, insider transactions, earnings Unlimited*
Google News RSS News sentiment for stocks Unlimited
alternative.me Crypto Fear & Greed Index Unlimited
Binance Crypto perpetual funding rates Unlimited
blockchain.com BTC on-chain metrics (hashrate, mempool) Unlimited

*yfinance uses unofficial Yahoo Finance endpoints — may be rate-limited during high traffic.

Free Tier (API Key Required)

Provider Data Rate Limit
Alpha Vantage Daily prices, fundamentals, news sentiment, market movers 25 requests/day
FRED Macro indicators (Fed funds, unemployment, yields, consumer sentiment) Unlimited
Finnhub Near-realtime US stock quotes 60 requests/min

Indian Market Support

AlphaForge is optimized for Indian equities:

  • Automatic .NS / .BO suffix handling for NSE / BSE symbols
  • INR currency detection and display
  • Reliance, TCS, Infosys, HDFC — all work out of the box
  • Macro panel includes USD/INR exchange rate

🧪 Testing

alphaforge demo

🗺️ Roadmap

Phase 1: Core Platform ✅

  • Typed domain model (Pydantic v2)
  • Free-tier data connectors (yfinance, Alpha Vantage, FRED, Finnhub)
  • Risk engine with volatility sizing and drawdown protection
  • Operator console with live dashboard
  • Smart watchlist with optimistic UI updates
  • Market screener with multi-factor filtering

Phase 2: ML Pipeline 🚧

  • LSTM/Transformer price prediction models
  • Sentiment analysis with FinBERT
  • Regime detection with Hidden Markov Models
  • Ensemble model with dynamic weighting
  • Walk-forward validation framework

Phase 3: Production Systems 📋

  • FastAPI REST + WebSocket server
  • Kafka event streaming
  • PostgreSQL feature store
  • Redis caching layer
  • Docker/Kubernetes deployment

Phase 4: Advanced Features 📋

  • Multi-broker execution (Zerodha, IBKR, Alpaca)
  • Options pricing (Black-Scholes, binomial)
  • Crypto perpetual futures trading
  • Portfolio optimization (Markowitz, Black-Litterman)
  • Regulatory compliance (SEBI, SEC)

🚀 Deployment: Publish to PyPI

1. Update Version

Edit pyproject.toml:

version = "0.2.0"

2. Build & Upload

pip install build twine
python -m build
twine upload dist/*

3. Tag Release

git tag -a v0.2.0 -m "Release v0.2.0"
git push origin v0.2.0

📚 Documentation

Document Description
docs/architecture.md Deep architecture dossier
docs/gui_wireframes.md UI wireframes and design specs
CLAUDE.md Claude Code integration guide

🤝 Contributing

AlphaForge is currently in private development. For inquiries:

  • Open an issue for bugs or feature requests
  • Submit PRs for improvements (will be reviewed)

📄 License

Proprietary — All rights reserved.


🙏 Acknowledgments

Built with:

  • Pydantic v2 — Data validation and settings management
  • yfinance — Free market data (Yahoo Finance)
  • Alpha Vantage — Free stock data API
  • FRED — Federal Reserve Economic Data
  • Finnhub — Real-time stock quotes

🐛 Troubleshooting

Issue Solution
FileNotFoundError: .env Create .env file from .env.example with your API keys
ConnectionError when fetching data Check internet connection; yfinance requires stable connection
RateLimitError from Alpha Vantage You've exceeded 25 requests/day; wait 24h or upgrade plan
Server won't start on port 8765 Another process is using the port; try --port 9000

AlphaForge — Where quantitative research meets production trading.i think

GitHub Python Pydantic

Metadata

Release files for alphaforged 0.3.12

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for alphaforged 0.3.12
File Size Uploaded Provenance Actions
alphaforged-0.3.12.tar.gz 685.5 kB Without provenance Details for alphaforged-0.3.12.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for alphaforged 0.3.12
File Interpreter ABI Platform Actions
alphaforged-0.3.12-py3-none-any.whl Python 3 none any Details for alphaforged-0.3.12-py3-none-any.whl

Total release size: 1.4 MB

Release files / alphaforged-0.3.12.tar.gz

Download URL alphaforged-0.3.12.tar.gz
Size 685.5 kB
Tags Source
SHA-256 checksum
How to use checksums
238e219f89e77cc24bb83589f936c8b9b4f35c17f84a073d9d3ff9042f8938d8
BLAKE2b-256 checksum
How to use checksums
b6075a9cb58ad79a1a7cab947fb36d42eb5963e42212e44365763d8d09682255
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.4

Release files / alphaforged-0.3.12-py3-none-any.whl

Download URL alphaforged-0.3.12-py3-none-any.whl
Size 715.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b99631250d2da885b818241b6881269249a734ce6274abe0bcdef17d1a10462f
BLAKE2b-256 checksum
How to use checksums
425bf62ef803def49b7645ec45398cacdb7a26fa664c3406f3a74dc4b33b1844
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.4

Security for alphaforged 0.3.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page