α AlphaForge
AI-Powered Market Intelligence & Quantitative Trading Platform
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
Real-time market data, watchlist, macro indicators, and stock analysis in one unified view
🔍 Detailed Stock Analysis
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:
- Alpha Vantage — 25 req/day
- FRED — Unlimited
- Finnhub — 60 req/min (optional)
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/.BOsuffix 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 |
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.