Stock Sentiment Graph API

Graph Project

FastAPI service that loads stock price data, social tweets, and AI-generated sentiment scores into a Neo4j knowledge graph for analysis. The API exposes endpoints to import tweets, sync historical OHLC data, and analyze sentiment using Hugging Face (FinBERT).

Graph Model

The schema is dynamic based on your dataset richness.

Core Schema (Always created)

Standard financial and social graph structure.

• Stock { ticker }
• TradingDay { date }
• Tweet { id, text, date, sentiment (float), confidence (float) }
• HashTag { tag }
• (:Stock)-[:PRICE_ON { close, volume, daily_change, volatility }]->(:TradingDay)
• (:Tweet)-[:DISCUSSES]->(:Stock)
• (:Tweet)-[:ON_DATE]->(:TradingDay)
• (:Tweet)-[:TAGGED_WITH]->(:HashTag)

Extended Schema (Optional)

If your dataset includes User, Topic, or EventId columns, the pipeline automatically upgrades the graph:

• User { user_id } linked via [:POSTED_BY]
• Topic { name } linked via [:MENTIONS]
• NewsEvent { event_id } linked via [:REFERENCES]

Project Structure

graph_project/
├── app/
│   ├── main.py                # FastAPI entrypoint
│   ├── config.py              # Env vars
│   ├── routers/
│   │   ├── pipeline.py        # UNIFIED INGESTION (Dataset -> Graph)
│   │   ├── analytics.py       # Graph Algos (Communities, Influence)
│   │   ├── sentiment.py       # On-demand Sentiment (Hugging Face)
│   │   └── quantitative.py    # Quant analysis (Correlations, Volatility)
│   └── services/
│       ├── neo4j_service.py   # Neo4j Driver
│       └── huggingface_service.py
├── data/                      # CSV Datasets
├── docker-compose.yml         # Neo4j Container
├── Makefile                   # Automation
└── tests/                     # Pytest Suite

Setup & Run (using Makefile)

We have a Makefile to simplify all common tasks.

1. Installation

Creates a virtual environment (graph_env) and installs dependencies.

make install

2. Environment Variables

Create a .env file for your credentials:

NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=password
# HF_TOKEN=hf_... (Required for the sentiment engine)

3. Start Neo4j (Docker)

make up

Wait a few seconds for the database to start.

4. Run API Server

make run

Access docs at: http://localhost:8000/docs

Testing & Quality

The project reached a professional state of robustness with 92% total code coverage and a 10.00/10 Pylint score.

1. Quality Stats

• Unit Tests: 58 passing tests
• Test Coverage: 92% (Analytics/Neo4j at 100%, Workflow at 98%)
• Code Quality: 10.00/10 Pylint
• Observability: Centralized structured logging for all services.

2. Unified Quality Check (Recommended)

Run the entire pipeline (Unit + Integration + Coverage + Linting) in one command:

./scripts/verify_quality.sh

3. Makefile Commands

make test           # Unit tests (Mocked)
make docker-test    # Everything inside Docker (Tests + Pylint)
make verify         # Run ./scripts/verify_quality.sh
make lint           # Check code quality (Pylint 10.00/10)
make format         # Run black code formatter
make ingest-demo    # Load sample Tesla data to the unified pipeline

Architecture & I/O

• Pydantic Models: All endpoints use centralized Pydantic models for strict I/O validation and clear OpenAPI documentation.
• Service Layer: Decoupled Neo4j and HuggingFace services with robust mocking for testing.
• Resilient Pipeline: Smart dates parsing and batch processing with individual fallbacks.

Ingestion (One-Shot)

Run the full ingestion pipeline (stocks + tweets) for a specific ticker:

curl -X POST "http://localhost:8000/api/pipeline/dataset_to_graph" \
  -H "Content-Type: application/json" \
  -d '{
    "stock": "TSLA",
    "start_date": "2021-09-30",
    "end_date": "2022-09-30"
  }'

Quantitative Features

• Correlation: GET /api/correlation/sentiment-price/{stock} (Pearson r)
• Trending: GET /api/trending/stocks (Volume + Sentiment score)
• Influencers: GET /api/influencers/{stock} (Network impact)
• Prediction: GET /api/prediction/sentiment-based/{stock} (Bull/Bear based on sentiment trends)
• Volatility: GET /api/volatility/social-driven (Sentiment variance)