alphaforged 0.3.8

Institutional-grade AI market intelligence and quantitative trading platform scaffold

α 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 / .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