Stock Sentiment Portfolio Analyzer

Project Overview

Stock Sentiment Portfolio Analyzer is a web-based dashboard built with Streamlit that enables users to manage a stock portfolio, track real-time prices, analyze social media sentiment from StockTwits, and visualize the interplay between market prices and public sentiment. Powered by yfinance for stock data, Hugging Face Transformers for sentiment analysis, and Plotly for interactive charts, this tool helps investors gauge market mood alongside traditional price metrics.

Key Features

• Portfolio Management: Add, view, and clear stock tickers (e.g., AAPL, GOOGL) with share counts.
• Real-Time Stock Data: Fetch historical and current prices using yfinance.
• Sentiment Analysis: Analyze StockTwits messages using a fine-tuned DistilRoBERTa model for financial news sentiment (bullish, bearish, neutral).
• Interactive Visualizations: Plotly charts showing price trends with sentiment overlays (colored markers indicate sentiment strength).
• Data Aggregation: Merge sentiment data with price history using time-based alignment for hourly insights.
• Responsive UI: Wide layout with sidebar controls, metrics, and expandable details for recent messages.

This project was developed as an advanced demonstration of integrating APIs, machine learning models, and data visualization in a user-friendly interface.

Prerequisites

• Python 3.12 or higher
• uv (Python package manager) for dependency management
• Access to Hugging Face API (free tier sufficient)
• Optional: StockTwits API access token for full sentiment data

Installation

1. Clone or Navigate to the Project Directory:

   cd '..\..\'   
   

2. Install Dependencies: The project uses uv for fast, reproducible installations. Run:

   uv sync
   

   This will create a virtual environment and install all dependencies listed in pyproject.toml (including Streamlit, yfinance, pandas, plotly, requests, and numpy).

   If you prefer pip:

   uv pip install -e .
   

3. Set Up Environment Variables: Create a .env file in the project root (or use Streamlit secrets for deployment):

   HF_TOKEN=your_huggingface_api_token_here
   ST_ACCESS_TOKEN=your_stocktwits_access_token_here  # Optional, but recommended
   

   • Hugging Face Token: Obtain from Hugging Face Settings. Required for sentiment analysis.
   • StockTwits Token: Get from StockTwits API. Without it, sentiment data will be limited or skipped.

   Alternatively, hardcode tokens in main.py (not recommended for production):

   HF_TOKEN = 'your_token'
   ST_ACCESS_TOKEN = 'your_token'

Usage

1. Run the Application: Activate the virtual environment (if using uv) and start the Streamlit server:

   streamlit run main.py
   

   The app will open in your default browser at http://localhost:8501.

2. Interact with the Dashboard:

   • Add Stocks: Use the sidebar form to enter a ticker symbol (e.g., AAPL) and number of shares, then click "Add to Portfolio".
   • View Portfolio: See your current holdings in the sidebar.
   • Analyze: Select a time period (1d, 5d, 1mo, 3mo) and refresh data if needed. The main area will display:
     • Price metrics (current price, change %).
     • Company info (name, sector).
     • Interactive chart with price line and sentiment markers.
     • Expandable section for recent StockTwits messages and their sentiment scores.
   • Clear Portfolio: Use the sidebar button to reset.

3. Customization:

   • Adjust caching TTL in code for faster/slower data refreshes.
   • For deployment (e.g., Streamlit Cloud), upload secrets via the app settings.
   • Extend by adding more tickers, custom periods, or additional data sources.

Project Structure

project/
├── main.py              # Main Streamlit application
├── pyproject.toml       # Dependencies and project metadata
├── uv.lock              # Lockfile for reproducible installs
├── plan.md              # Development plan and architecture
└── README.md            # This file

Limitations and Notes

• API Rate Limits: Hugging Face and StockTwits have usage limits; heavy use may require paid plans.
• Data Accuracy: Sentiment model is fine-tuned for financial news; results are indicative, not financial advice.
• Time Zones: All data is in UTC; adjust for local markets if needed.
• System Date Check: The app validates dates to prevent mismatches from incorrect system clocks.
• No Real Trading: This is for analysis only; integrate with brokerage APIs for actual trading.

Contributing

Feel free to fork the repo, submit issues, or pull requests for enhancements like additional APIs, ML models, or UI improvements.

License

This project is open-source under the MIT License. See LICENSE file for details (add one if needed).

Acknowledgments

• Streamlit for the UI framework.
• yfinance for stock data.
• Hugging Face for the sentiment model (mrm8488/distilroberta-finetuned-financial-news-sentiment-analysis).
• StockTwits API for social sentiment.
• Plotly for visualizations.