alphaforged 0.3.2__tar.gz

alphaforged-0.3.2/PKG-INFO

@@ -0,0 +1,496 @@
+Metadata-Version: 2.4
+Name: alphaforged
+Version: 0.3.2
+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](assets/s%20look.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](assets/f%20look.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>
+
+<div align="center">
+
+> 📸 **Want to add more screenshots?** Place images in the `assets/` folder and reference them above.
+>
+> Supported formats: `.png`, `.jpg`, `.gif`, `.webp`
+
+</div>
+
+---
+
+## 🚀 Installation
+
+### Prerequisites
+
+| Requirement | Version |
+|-------------|---------|
+| **Python** | 3.11+ |
+
+### Quick Install (PyPI)
+
+```powershell
+pip install alphaforge
+```
+
+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>