Stock Sentiment Analyzer

A production-ready Python tool that uses FinBERT to classify financial news headlines as positive, negative, or neutral sentiment. Built with comprehensive testing, linting, and CI/CD workflows.

Features

• Real-time sentiment analysis of financial headlines using FinBERT
• FinBERT model fine-tuned specifically for financial text
• Confidence scores for each prediction
• Summary statistics across multiple headlines
• Comprehensive test suite with 88% code coverage
• Type hints and full linting support
• Organized project structure with src/ and tests/ directories
• CI/CD workflow with automated testing and linting

Quick Start

Prerequisites

• Python 3.8 or higher
• pip package manager

Installation

# Clone the repository
git clone https://github.com/MeridianAlgo/Basic-Sentiment-Analysis.git
cd Basic-Sentiment-Analysis

# Create virtual environment
python3 -m venv .venv

# Activate virtual environment
# On macOS/Linux:
source .venv/bin/activate
# On Windows:
.venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Usage

python main.py

Enter financial headlines one per line. Type done when finished:

Stock News Sentiment Analyzer
Enter headlines (one per line). Type 'done' when finished.

Headline: NVIDIA beats earnings expectations, stock surges 8%
Headline: Tesla stock plunges 12% after controversial tweet
Headline: done

Analyzing stock news sentiment:

--------------------------------------------------------------------------------
1. Headline: NVIDIA beats earnings expectations, stock surges 8%
   Sentiment: POSITIVE | Confidence: 90.8%

2. Headline: Tesla stock plunges 12% after controversial tweet
   Sentiment: NEGATIVE | Confidence: 87.3%

--------------------------------------------------------------------------------

Summary (2 headlines analyzed):
  Positive: 1 (50.0%)
  Negative: 1 (50.0%)
  Neutral:  0 (0.0%)

Development

Project Structure

stock-sentiment-analyzer/
├── src/
│   ├── __init__.py
│   └── analyzer.py          # Core sentiment analysis logic
├── tests/
│   ├── __init__.py
│   └── test_analyzer.py     # Unit tests
├── config/                  # Configuration files
├── main.py                  # Entry point
├── requirements.txt         # Python dependencies
├── pytest.ini              # Pytest configuration
├── pyproject.toml          # Black and tool configuration
├── .flake8                 # Flake8 configuration
├── README.md               # This file
├── LICENSE                 # MIT License
├── CONTRIBUTING.md         # Contribution guidelines
└── CODE_OF_CONDUCT.md      # Code of conduct

Running Tests

# Run all tests
pytest

# Run with coverage report
pytest --cov=src --cov-report=html

# Run specific test file
pytest tests/test_analyzer.py -v

Code Quality

# Format code with black
black src/ tests/ main.py

# Sort imports with isort
isort src/ tests/ main.py

# Lint with flake8
flake8 src/ tests/ main.py

# Check with ruff
ruff check src/ tests/ main.py

# Type checking with mypy
mypy src/ --ignore-missing-imports

Run All Quality Checks

# Format
black src/ tests/ main.py && isort src/ tests/ main.py

# Lint
flake8 src/ tests/ main.py && ruff check src/ tests/ main.py

# Test
pytest --cov=src --cov-report=term-missing

How It Works

1. Model Loading: Uses FinBERT, a BERT model fine-tuned on financial text
2. Headline Input: Accepts user-provided financial news headlines
3. Sentiment Analysis: Classifies each headline as positive, negative, or neutral
4. Confidence Scoring: Returns confidence percentage for each prediction
5. Summary Statistics: Aggregates and displays results across all headlines

Model Details

• Model: ProsusAI/finbert
• Task: Sentiment classification
• Labels: Positive, Negative, Neutral
• Framework: Hugging Face Transformers
• Model Size: ~500MB (downloaded on first run)

Dependencies

• transformers (>=4.30.0): Hugging Face NLP library
• torch (>=2.0.0): PyTorch deep learning framework
• pytest (>=7.4.0): Testing framework
• black (>=23.0.0): Code formatter
• flake8 (>=6.0.0): Linter
• isort (>=5.12.0): Import sorter
• ruff (>=0.1.0): Fast Python linter
• mypy (>=1.0.0): Static type checker

Troubleshooting

Model Download Issues

The first run downloads the FinBERT model (~500MB). Ensure you have:

• Stable internet connection
• Sufficient disk space (at least 1GB free)
• Proper Hugging Face cache permissions

CUDA/GPU Issues

If you encounter GPU-related errors, the model will automatically fall back to CPU processing.

Import Errors

If you get import errors, ensure you've activated the virtual environment and installed all dependencies:

source .venv/bin/activate  # or .venv\Scripts\activate on Windows
pip install -r requirements.txt

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines on:

• Setting up development environment
• Making changes
• Running tests and linting
• Submitting pull requests

Code of Conduct

This project adheres to the Contributor Covenant Code of Conduct. See CODE_OF_CONDUCT.md for details.

License

This project is licensed under the MIT License. See LICENSE file for details.

Citation

If you use this project in your research, please cite:

@software{stock_sentiment_analyzer,
  title={Stock Sentiment Analyzer},
  author=Richard Zhu,
  year={2026},
  url={https://github.com/MeridianAlgo/Basic-Sentiment-Analysis}
}

Support

For issues, questions, or suggestions, please open an issue on GitHub.

Version

Current version: v1.0.0

Last updated: January 2026

Made by: Richard Zhu https://github.com/ZelinZhu-Richard

Edited by: The MeridianAlgo Team