StockAnalyzer

📊 StockAnalyzer

Multi‑agent, local‑first market‑sentiment platform with LangGraph + FinBERT + Llama 3, dual MCP servers, vector search, and Streamlit dashboard

---

✨ Features

Layer	Details
Agents	NewsCollector → PreCleaner → EntityExtractor → SentimentAnalyzer → TrendAggregator → Reporter
LLMs / Models	• ProsusAI/finbert for finance‑tuned sentiment • Local Llama‑3 8B (quantised via Ollama) for reporting
Pipelines	1. LangGraph standalone runner (main.py) 2. MCP‑FastAPI server (mcp/) exposed as REST & CLI 3. Anthropic MCP (fastmcp) server (mcp2/) discoverable by Claude Desktop
Storage	• SQLite (data/raw_news.db) ‑ raw articles / summaries • ChromaDB (data/embeddings/) ‑ MiniLM vectors
UI / Clients	• Streamlit dashboard (dashboard.py) • fastmcp CLI pipes • Claude Desktop (via MCP)
Local‑first	Runs entirely on CPU; no OpenAI / cloud costs

---

🗂️ Repo Structure

StockAnalyzer/
├─ agents/                  # core agent logic
├─ models/finbert/          # local FinBERT weights
├─ data/
│  ├─ raw\_news.db           # SQLite DB
│  └─ embeddings/           # Chroma vector store
├─ mcp/                     # FastAPI + LangGraph MCP server (REST)
├─ mcp2/                    # Anthropic "fastmcp" server (stdio / Claude)
│  ├─ tools/                # thin wrappers that expose agents as tools
│  └─ utils/                # db helpers reused from mcp
├─ dashboard.py             # Streamlit dashboard
├─ main.py                  # LangGraph runner (no DB)
└─ README.md

---

🚀 Quick‑start

git clone https://github.com/<you>/StockAnalyzer.git
cd StockAnalyzer
python -m venv venv && source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

Create .env for NewsAPI key & others:

NEWSAPI_KEY=xxxxxxxxxxxxxxxx

1. LangGraph (one‑shot)

python main.py

2. FastAPI MCP server (REST)

uvicorn mcp.server:app --reload
# Swagger UI: http://127.0.0.1:8000/docs

3. Anthropic fastmcp server (Claude Desktop / CLI)

python mcp2/server.py            # runs on stdio
fastmcp list mcp2/server.py      # see tools
fastmcp call mcp2/server.py collect_news --json '{"tickers":["AAPL"]}' --pretty

(Claude Desktop → click 🔌 → select stock_analyzer_mcp and instruct it in natural language.)

4. Streamlit Dashboard

streamlit run dashboard.py

---

📐 Agent Details

Agent	Role / Libs
NewsCollector	Hits NewsAPI (RSS, GNews ready) with exponential back‑off.
PreCleaner	readability-lxml, sim‑hash duplicate removal.
EntityExtractor	spaCy en_core_web_lg + simple ORG filter → potential tickers.
SentimentAnalyzer	HF pipeline with local FinBERT (ProsusAI/finbert).
TrendAggregator	pandas, numpy; z‑score, per‑ticker aggregates.
Reporter	Markdown report + Llama‑3 summary via Ollama HTTP API.

---

💾 Data Persistence

• SQLite articles table – title, url, content, entities, sentiment, JSON blob.
• SQLite summaries table – markdown report + llama summary (+ ISO date).
• ChromaDB – MiniLM embeddings keyed by article URL for semantic lookup / RAG.

---

🔗 Using the Tools from CLI (pipes)

fastmcp call mcp2/server.py collect_news      --json '{"tickers":["AAPL","MSFT"]}' |
fastmcp call mcp2/server.py clean_articles    --stdin |
fastmcp call mcp2/server.py extract_entities  --stdin |
fastmcp call mcp2/server.py analyze_sentiment --stdin |
fastmcp call mcp2/server.py aggregate_trends  --stdin |
fastmcp call mcp2/server.py generate_report   --stdin --pretty

---

📈 Dashboard Preview

Section	What it shows
Markdown Report	Daily ticker breakdown (counts, avg score).
Llama Summary	200‑word prose summary.
Sentiment Chart	Matplotlib bar of positive / negative / neutral.
Download	Saves report_YYYY‑MM‑DD.md.

---

🛠️ Development Notes

• Python 3.11, no Conda.
• Tested on Windows 11 + WSL, Ubuntu 22, macOS 14 (Apple Silicon).
• FinBERT and Llama 3 are loaded once and cached.
• Vector search optional; turn off by commenting mcp/vector_utils.py calls.

---

🏆 Impact

• End‑to‑end pipeline generates actionable sentiment brief in < 30 s on laptop CPU.
• Zero cloud costs (all local models).
• MCP integration lets Claude or any tool‑calling LLM orchestrate analysis autonomously.
• Modular design—drop‑in new agents (e.g., price scraper) or swap models easily.

---

📜 License

MIT — use, fork, star ⭐, enjoy!

> Save the block above as **`README.md`** at repo root.  
> Feel free to tweak badges, add screenshots, or redact keys before publishing.