README.md

---
title: Alpha Predict
emoji: 🚀
colorFrom: red
colorTo: red
sdk: docker
app_port: 8501
tags:
- financial-analysis
- nlp
- sentiment-analysis
- finbert
- streamlit
pinned: false
short_description: Market Sentiment & Volatility Prediction using FinBERT
---

# 🚀 Alpha Predict: Market Sentiment Engine

Alpha Predict is an AI-driven financial analysis tool that leverages **FinBERT** (Financial BERT) to quantify market sentiment from real-time and historical headlines. It correlates sentiment with **S&P 500 (SPY)** performance and the **VIX (Fear Index)** to provide a holistic view of market psychology.

## 🧠 Core Features
* **NLP Sentiment Analysis:** Uses `ProsusAI/finbert` to perform high-fidelity sentiment classification on thousands of market headlines.
* **Hybrid Data Fetching:** Integrated with **Finnhub API** for live market news and price action, with a **robust CSV fallback** mechanism for maximum uptime.
* **Predictive Indicators:** Analyzes "Panic Interaction" (Sentiment x Volatility) to detect market dislocations.
* **Interactive Analytics:** Visualizes the relationship between news sentiment trends and price movements via Streamlit.

## 🛠️ Technical Stack
* **UI Framework:** Streamlit
* **Model:** FinBERT (Hugging Face Transformers)
* **Data Providers:** Finnhub API, Yahoo Finance (via backup)
* **Deployment:** Docker / Hugging Face Spaces

## 📂 Project Structure
* `app.py`: Main entry point for the Streamlit dashboard.
* `src/data_fetcher.py`: Handles API interactions and data resilience.
* `src/processor.py`: Feature engineering and sentiment batch processing.
* `data/`: Secure storage for historical backup data to ensure 100% availability.

## 🚦 Getting Started
1.  **API Keys:** Ensure your `FINNHUB_API_KEY` is set in the Hugging Face Space Secrets.
2.  **Processing:** Upon launch, the app will fetch the last 45-60 days of data.
3.  **Inference:** FinBERT runs batch inference on the latest headlines to calculate the `Sent_Mean` index.

---
**Note:** *This project was developed for academic purposes to demonstrate the application of Transformer-based models in quantitative finance.*