Metadata-Version: 2.4
Name: alphaforged
Version: 0.3.8
Summary: Institutional-grade AI market intelligence and quantitative trading platform scaffold
Author: Soodkrish
Project-URL: Homepage, https://github.com/Soodkrish03/AlphaForge
Project-URL: Repository, https://github.com/Soodkrish03/AlphaForge
Project-URL: Issues, https://github.com/Soodkrish03/AlphaForge/issues
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: pydantic<3.0,>=2.7
Requires-Dist: vaderSentiment>=3.3
Requires-Dist: yfinance>=0.2.40
Requires-Dist: fastapi>=0.112
Requires-Dist: uvicorn>=0.30
Provides-Extra: data
Requires-Dist: pandas>=2.2; extra == "data"
Requires-Dist: polars>=1.1; extra == "data"
Requires-Dist: pyarrow>=17.0; extra == "data"
Requires-Dist: duckdb>=1.1; extra == "data"
Requires-Dist: httpx>=0.27; extra == "data"
Requires-Dist: redis>=5.0; extra == "data"
Provides-Extra: ml
Requires-Dist: numpy>=1.26; extra == "ml"
Requires-Dist: scipy>=1.13; extra == "ml"
Requires-Dist: scikit-learn>=1.5; extra == "ml"
Requires-Dist: xgboost>=2.1; extra == "ml"
Requires-Dist: lightgbm>=4.5; extra == "ml"
Requires-Dist: catboost>=1.2; extra == "ml"
Requires-Dist: torch>=2.4; extra == "ml"
Requires-Dist: transformers>=4.44; extra == "ml"
Requires-Dist: optuna>=3.6; extra == "ml"
Requires-Dist: timesfm>=1.0; extra == "ml"
Requires-Dist: google-genai>=1.0; extra == "ml"
Provides-Extra: api
Requires-Dist: fastapi>=0.112; extra == "api"
Requires-Dist: uvicorn>=0.30; extra == "api"
Requires-Dist: orjson>=3.10; extra == "api"
Provides-Extra: ui
Requires-Dist: streamlit>=1.38; extra == "ui"
Requires-Dist: plotly>=5.24; extra == "ui"
Provides-Extra: ops
Requires-Dist: sqlalchemy>=2.0; extra == "ops"
Requires-Dist: alembic>=1.13; extra == "ops"
Requires-Dist: prometheus-client>=0.20; extra == "ops"
Requires-Dist: structlog>=24.4; extra == "ops"

# α AlphaForge

### AI-Powered Market Intelligence & Quantitative Trading Platform


<div align="center">

![Python 3.11+](https://img.shields.io/badge/Python-3.11+-3776AB?style=for-the-badge&logo=python&logoColor=white)
![Pydantic v2](https://img.shields.io/badge/Pydantic-v2-E91E63?style=for-the-badge&logo=pydantic&logoColor=white)
![License](https://img.shields.io/badge/License-Proprietary-FF4500?style=for-the-badge)
![Status](https://img.shields.io/badge/Status-Active%20Development-00E676?style=for-the-badge)

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

</div>

---

## 🎯 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

<div align="center">

### 📊 Full Dashboard View

> <!-- Add image link here: assets/s look.png -->
>
> ![Dashboard Screenshot](https://raw.githubusercontent.com/Soodkrish/AlphaForge/refs/heads/main/assets/s-look.png)
>
> *Real-time market data, watchlist, macro indicators, and stock analysis in one unified view*

---

### 🔍 Detailed Stock Analysis

> <!-- Add image link here: assets/f look.png -->
>
> ![Stock Analysis Screenshot](https://raw.githubusercontent.com/Soodkrish/AlphaForge/refs/heads/main/assets/f-look.png)
>
> *Deep dive into individual stocks with risk assessment, insider trading, and earnings data*

---

### 🎨 UI Highlights

| Feature | Preview |
|---------|---------|
| **API Quota Monitor** | <!-- Add GIF/screenshot here --> `Hover over API section` |
| **Smart Watchlist** | <!-- Add GIF/screenshot here --> `Add/remove with optimistic UI` |
| **Stock Screener** | <!-- Add GIF/screenshot here --> `Multi-factor filtering` |
| **Alert System** | <!-- Add GIF/screenshot here --> `Real-time notifications` |

</div>



---

## 🚀 Installation

### Prerequisites

| Requirement | Version |
|-------------|---------|
| **Python** | 3.11+ |

### Quick Install (PyPI)

```powershell
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

```powershell
# 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:

```env
ALPHA_VANTAGE_API_KEY=your_key_here
FRED_API_KEY=your_key_here
FINNHUB_API_KEY=optional
```

Get free keys:
- [Alpha Vantage](https://www.alphavantage.co/support/#api-key) — 25 req/day
- [FRED](https://fred.stlouisfed.org/docs/api/api_key.html) — Unlimited
- [Finnhub](https://finnhub.io/) — 60 req/min (optional)

### Install with All Dependencies

```powershell
# 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)

```powershell
# 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`)

```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

```python
# 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

```powershell
alphaforge demo
```

---

## 🗺️ Roadmap

### Phase 1: Core Platform ✅
- [x] Typed domain model (Pydantic v2)
- [x] Free-tier data connectors (yfinance, Alpha Vantage, FRED, Finnhub)
- [x] Risk engine with volatility sizing and drawdown protection
- [x] Operator console with live dashboard
- [x] Smart watchlist with optimistic UI updates
- [x] 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`:
```toml
version = "0.2.0"
```

### 2. Build & Upload

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

### 3. Tag Release

```powershell
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` |

---

<div align="center">

**AlphaForge** — *Where quantitative research meets production trading.i think*

[![GitHub](https://img.shields.io/badge/GitHub-Soodkrish03-181717?style=for-the-badge&logo=github&logoColor=white)](https://github.com/Soodkrish03/alphaforge)
[![Python](https://img.shields.io/badge/Python-3.11+-3776AB?style=for-the-badge&logo=python&logoColor=white)](https://python.org)
[![Pydantic](https://img.shields.io/badge/Pydantic-v2-E91E63?style=for-the-badge&logo=pydantic&logoColor=white)](https://pydantic.dev)

</div>
