StockSense-AI / README.md
PROSTLE's picture
fix: align HuggingFace metadata port (8000 -> 7860) to resolve launch timeout
19a0482
|
Raw History Blame Contribute Delete
5.08 kB
---
title: StockSense AI
emoji: πŸ“ˆ
colorFrom: indigo
colorTo: purple
sdk: docker
app_port: 7860
short_description: AI trading engine for Indian markets (NSE/BSE)
---
# πŸ“ˆ StockSense-AI β€” Enterprise-Grade Trading Engine
> **StockSense-AI** is a multi-factor hybrid intelligence platform that blends Deep Learning, Intraday ML, and LLM reasoning to provide high-precision stock signals for the Indian market (NSE/BSE).
---
## 🌟 Vision & Pitch
*"StockSense AI doesn't just predict prices; it understands market context. By fusing **LSTM-based daily forecasting** with **XGBoost intraday signals**, **FinBERT sentiment analysis**, and **Gemini LLM reasoning**, we've built a decision engine that adapts to market regimes in real-time. Whether you're tracking 5-day trends or hunting for intraday breakouts, StockSense AI provides the confidence score and risk-mitigation strategy you need."*
---
## πŸš€ Key Features
### 🧠 **The Hybrid Command Engine**
- **LSTM Neural Network**: 2-layer Deep Learning model trained on 2 years of daily data for 5-day price forecasting.
- **XGBoost Intraday Pipeline**: High-velocity ML model trained on 1-minute bars to capture micro-trends.
- **FinBERT Sentiment Analysis**: Advanced NLP scoring of real-time financial news and social sentiment.
- **Gemini LLM Reasoning**: Human-readable trade justifications and "why" analysis for every signal.
- **Factor Blending**: 5-factor weighted scoring (Technicals + Sentiment + LSTM + XGBoost + Market Context).
### 🏦 **Paper Trading & Wallet Simulation**
- **Virtual Portfolio Management**: Track open positions, realized/unrealized P&L, and win rates.
- **Integrated Wallet**: Deposit and withdraw (Razorpay-style simulation) with full transaction history.
- **Account Performance Charting**: Visual snapshots of your portfolio growth over time.
### πŸ›‘οΈ **Advanced Risk Management**
- **Dynamic ATR-based Levels**: Stop-Loss and Take-Profit targets that adjust automatically to ticker volatility.
- **Adaptive Market Regimes**: System switches behavior across 4 states: *Bull Low-Vol, Bull High-Vol, Bear High-Vol, and Sideways*.
- **Risk-Based Position Sizing**: Automatic share calculation based on your "capital-at-risk" percentage.
- **Trailing Stop-Loss**: Intelligent profit-locking mechanism that follows the price as it rises.
### πŸ’Ž **Glassmorphic Interactive UI**
- **Premium Aesthetics**: High-end translucent design system with vibrant neon accents.
- **Multi-Tab Dashboard**: Switch between **Charts**, **Unified Dashboard**, **Auto-Trade Engine**, and **Trading Portfolio**.
- **Real-Time Price Banner**: Live tracking of tickers with market-depth indicators.
- **High-Potential Scanner**: Real-time scanner for "Strong Buy" signals across Top 50 NSE stocks.
---
## πŸ—οΈ Architecture & Stack
```mermaid
graph LR
User((User)) -- "Ticker" --> API[FastAPI Gateway]
subgraph "Engine Layer"
API --> LSTM[Deep Learning: Daily Trends]
API --> XGB[XGBoost: Intraday Signals]
API --> NLP[FinBERT: News Sentiment]
API --> Gemini[LLM: Market Reasoning]
end
subgraph "Decision AI"
LSTM & XGB & NLP & Gemini --> Blender[Weighted Composite Blender]
Blender --> Regime[Regime/Volatility Filter]
end
subgraph "Execution Layer"
Regime --> Risk[ATR Risk Engine: SL/TP/Sizing]
Risk --> Sim[[Paper Trading Simulator]]
end
```
### **Tech Stack**
- **Backend**: Python 3.10+, FastAPI, Uvicorn, SQLAlchemy (SQLite).
- **ML/Science**: PyTorch (LSTM), XGBoost, Transformers (FinBERT), Scikit-learn, Pandas, yfinance.
- **Frontend**: Vanilla HTML5/JS (ES6+), Chart.js for visualization, Glassmorphic CSS Engine.
- **Reasoning**: Google Gemini 2.0 API.
---
## πŸ”§ Installation & Setup
### **1. Backend (The Brain)**
```bash
cd backend
python -m venv venv
# Windows
.\venv\Scripts\activate
# Linux/Mac
source venv/bin/activate
pip install -r requirements.txt
# Create a .env file with your GEMINI_API_KEY
uvicorn app:app --port 8000
```
### **2. Frontend (The Interface)**
Simply host the `frontend` directory using any local server:
```bash
cd frontend
python -m http.server 5500
```
Visit `http://localhost:5500`.
---
## πŸ“‹ ML Pipeline Details
| Stage | Logic |
| :--- | :--- |
| **Data** | 1-min & Daily OHLCV via Yahoo Finance API. |
| **LSTM** | 60-bar lookback window, recursive 5-day out-of-sample forecast. |
| **XGBoost** | Feature-rich ensemble (RSI, MACD, BB, VWAP, Supertrend) for next-5-bar returns. |
| **Regime** | 4-state classification using India VIX and Sector Strength. |
| **Scoring** | Normal: 45% LSTM, 45% XGB, 10% Sent \| Volatile: 48.5% LSTM, 48.5% XGB, 3% Sent. |
---
## ⚠️ Disclaimer
StockSense AI is for **educational and simulation purposes only**. This is a paper-trading platform. Algorithms can fail, and market data can be delayed. **Never use this tool for actual financial investments without consulting a certified advisor.**
---
## πŸ“œ License
Distributed under the **MIT License**. See `LICENSE` for more information.