Stock Analysis — Gemma 4 Edition

Refactored from the original FinBERT + BART notebook into a small Python package that runs Gemma 4 through either HuggingFace Transformers on a single Google Colab GPU or a local Ollama server, with multi-agent Bull-vs-Bear reasoning and a backtest that uses the same deterministic signal as the live pipeline.

Status: Phase 1 complete · 84 tests passing · all Critical and Major review findings resolved (see CODE_REVIEW.md).

Phase 1 features — "Make it credible"

Feature	Module	Why it matters
🗣️ Multi-agent Bull vs Bear debate	`src/agents.py`	Two Gemma calls argue opposite sides; a third judges. Surfaces both upside and downside, reduces overconfidence.
⏮️ Backtesting framework	`src/backtest.py`	Replays the pipeline over the past ~21 trading days and reports hit rate / Sharpe / max drawdown — you can finally measure the system.
🌐 Gradio web UI	`webapp.py`	One command (`python webapp.py`) → public `*.gradio.live` link valid 72 h. Tabs for live analysis + backtesting.
⚖️ Deterministic aggregation	`src/preprocessing.py`	A single `aggregate_polarity()` function is used by both live and backtest paths so the two are numerically consistent.
🧪 Mock-based integration tests	`tests/`	84 tests, no GPU / Ollama server / API keys required — runs offline.

Pipeline

INPUT (symbol, horizon)
   │
   ├─► Stage 1  Data collection         (yfinance daily + intraday + News API)
   ├─► Stage 2  Pre-processing          (clean • TF-IDF dedup • time-decay
   │                                     • price features on DAILY series:
   │                                     SMA/EMA/RSI/ATR/pct_1d/pct_5d/pct_30d)
   ├─► Stage 3  Per-news scoring        (Gemma 4 → "scores" array, index-aligned)
   ├─►          Aggregation             (preprocessing.aggregate_polarity
   │                                     — single source of truth)
   ├─► Stage 4  Synthesis & advice
   │   │
   │   ├─► (default) src/agents.py      Bull → Bear → Judge debate
   │   └─► (--no-debate)  src/stages.py single-call synthesize
   │
   └─► Stage 5  Presentation            (stdout • Plotly • Gradio)

Every stage talks to the LLM through one small abstraction layer (src/llm/), so the engine is a config switch — no pipeline or UI code changes:

LLM_BACKEND=hf — a local open-weight model (Gemma 4 / Phi-4 / Qwen / …) via HuggingFace transformers, 4-bit, single GPU. Loaded once per session via functools.lru_cache.
LLM_BACKEND=ollama — a local model served by Ollama and called through http://localhost:11434/api/chat. The Ollama daemon owns model loading and quantization, so the Python process does not import PyTorch.

See LLM backends below.

Project layout

.
├── main.py                  ← CLI: `analyze` and `backtest` subcommands
├── webapp.py                ← Gradio app (analyze + backtest tabs)
├── demo_ui.py               ← Mock-data Plotly preview (no GPU / no keys needed)
├── config.py                ← env-driven settings
├── pytest.ini
├── requirements.txt
├── requirements-dev.txt
├── .env.example
├── .gitignore
├── README.md                ← this file
├── CODE_REVIEW.md           ← Phase 1 review (all Critical/Major resolved)
├── src/
│   ├── apis.py              ← Stage 1: yfinance (daily + intraday) + News API
│   ├── preprocessing.py     ← Stage 2: cleaning, dedup, time-decay, features,
│   │                          aggregate_polarity, stance_from_polarity
│   ├── llm/                 ← LLM abstraction (pluggable backends)
│   │   ├── __init__.py      ←   generate / generate_json dispatcher + JSON repair
│   │   ├── hf_local.py      ←   local model (Gemma/Phi/Qwen, 4-bit) loader
│   │   └── ollama_local.py  ←   local Ollama REST API adapter
│   ├── stages.py            ← Stage 3 + (alt) single-call Stage 4
│   ├── agents.py            ← (default) Bull / Bear / Judge debate
│   ├── backtest.py          ← Replays the pipeline on past data
│   ├── pipeline.py          ← Orchestrator → AnalysisResult
│   └── display.py           ← Text / Plotly / ipywidgets renderers
└── tests/
    ├── conftest.py          ← Mocks for yfinance + NewsAPI + LLM
    ├── test_apis.py         ← yfinance schema normalisation + wrapper contracts
    ├── test_preprocessing.py
    ├── test_llm.py          ← JSON extractor + generate_json retry
    ├── test_ollama_backend.py ← Ollama HTTP adapter + dispatcher
    ├── test_stages.py         ← structured score contract + title restoration
    ├── test_pipeline.py
    ├── test_backtest.py
    └── test_webapp.py

Setup (Google Colab via VSCode extension)

Open the project in VSCode and connect to a Colab runtime. Pick Runtime → Change runtime type → GPU (T4 / L4 / A100).
Install requirements on the Colab runtime:
```
pip install -q -r requirements.txt
```
Create .env next to main.py (copy from .env.example):
```
cp .env.example .env
```
Fill in:
- NEWS_API_KEY
- LLM_BACKEND (hf for Transformers on a CUDA GPU, ollama for a local Ollama server — see LLM backends)
- HF_TOKEN (when LLM_BACKEND=hf; also accept the model licence on Hugging Face for gated models like Gemma)
- MODEL_ID (optional override, e.g. google/gemma-4-4b-it, microsoft/phi-4)
- GEMMA_ATTN_IMPL (optional, default eager)

Usage

CLI

# Live analysis with Bull vs Bear debate (default)
python main.py analyze AAPL

# Same but force single-call synthesis (faster, less depth)
python main.py analyze AAPL --no-debate

# Open the Plotly candlestick after analysis
python main.py analyze TSLA --show-chart

# Machine-readable output
python main.py analyze NVDA --json

# Backtest the last 21 trading days (capped at 22 by the News API free tier)
python main.py backtest AAPL --days 21 --show-chart

# Backtest with JSON output (for piping into another script)
python main.py backtest NVDA --json > nvda_backtest.json

Web UI (Gradio)

python webapp.py

This prints a *.gradio.live link (valid 72 h) you can open on any device. The UI has two tabs:

Analyze — symbol, horizon, debate on/off → stance + Bull case + Bear case + per-news table + Plotly candlestick.
Backtest — symbol + days slider (7–22) → metrics table + equity curve
- per-day decision log.

A concurrency queue (max_size=8) is enabled so a second user clicking "Analyze" while Gemma is busy gets queued instead of timing out.

Inside a Colab notebook cell

from src.display import launch_widget_ui
launch_widget_ui()         # ipywidgets form: symbol + horizon + debate toggle

…or programmatically:

from src.pipeline import analyze
from src.backtest import backtest
from src.display import render_advice_text, render_backtest_text

result = analyze("AAPL", horizon="1w")
print(render_advice_text(result))

bt = backtest("AAPL", backtest_days=21)
print(render_backtest_text(bt))

Local preview without a GPU (Mac/Windows/Linux)

demo_ui.py ships a self-contained Plotly preview with mock data so you can inspect the look-and-feel of the dashboard without a GPU or API keys:

pip install plotly pandas numpy
python demo_ui.py AAPL          # opens demo_preview.html in your browser

LLM backends (Hugging Face vs Ollama)

The pipeline is engine-agnostic. Pick the backend with LLM_BACKEND; the CLI, Gradio UI, Plotly charts, and backtest all behave identically either way — only the reasoning quality and where it runs change.

`LLM_BACKEND=hf` — local open-weight model (default)

Runs any instruction-tuned causal LM with a chat template on a single GPU (4-bit). Set the repo with MODEL_ID:

LLM_BACKEND=hf MODEL_ID=google/gemma-4-12b-it python main.py analyze AAPL
LLM_BACKEND=hf MODEL_ID=microsoft/phi-4        python main.py analyze AAPL

Needs HF_TOKEN for gated models (e.g. Gemma) and a CUDA GPU (Colab T4/L4/A100). GEMMA_MODEL_ID is still honoured as a fallback for MODEL_ID.

`LLM_BACKEND=ollama` — local Ollama server

Calls Ollama's non-streaming /api/chat endpoint. Ollama owns model loading, quantization, and device placement; the Python application only sends prompts over HTTP. requests is already included in requirements.txt, so no extra Python SDK is needed.

# Recommended local setup (Python 3.10+):
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements-ollama.txt

# Start the Ollama app or daemon, then download the model once.
ollama serve
ollama pull gemma4:12b

LLM_BACKEND=ollama OLLAMA_MODEL=gemma4:12b \
  python main.py analyze AAPL

Available settings:

OLLAMA_BASE_URL — default http://localhost:11434
OLLAMA_MODEL — default gemma4:12b
OLLAMA_TIMEOUT — default 600 seconds
OLLAMA_NUM_CTX — default 8192; larger values consume more memory
OLLAMA_KEEP_ALIVE — default 10m
OLLAMA_THINK — default false; enable only after measuring quality/latency

Caveats

Keep Ollama bound to localhost unless the remote endpoint is protected by appropriate network controls and authentication.
Stop a resident Ollama model before loading a large HuggingFace model on the same machine if RAM/VRAM is constrained: ollama stop gemma4:12b.
Keep a backtest run on one backend so its metrics stay comparable.

Tests

# Install dev dependencies (pytest + everything in requirements.txt)
pip install -r requirements-dev.txt

# Run the whole suite
pytest

# Run a single file or filter by name
pytest tests/test_preprocessing.py -v
pytest -k "aggregate_polarity"

The suite uses monkeypatch fixtures (autouse=True in tests/conftest.py) to stub yfinance, News API, and both LLM backends — every test runs offline with no GPU, Ollama server, or API keys.

Backtest interpretation

Metric	Meaning
`hit_rate`	Of days where the pipeline took a position (BUY or SELL), what fraction matched the next-day direction.
`cumulative_return`	What 1 unit of capital would have grown to over the period if you followed every signal (long on BUY, short on SELL, flat on HOLD).
`annualised_sharpe`	Daily mean / daily std × √252. >1 is decent, >2 is rare.
`max_drawdown`	Worst peak-to-trough loss along the equity curve.

Caveats:

The free News API tier only exposes ~30 days of history. --days is hard-capped at 22 trading days (= 30 − 7 lookback − 1 next-day). Passing a larger value prints a warning and silently caps.
No transaction costs are modelled. Real trading would subtract spread + fees.
Sample size is small — treat as a sanity check, not statistical proof.
Same aggregation as live. backtest and analyze both call preprocessing.aggregate_polarity(), so a number you see in the backtest is exactly what the live system would compute on the same news.

Configuration knobs

All thresholds, weights, and window sizes are exposed in config.py under PipelineConfig:

Knob	Default	Purpose
`stance_threshold`	0.15	min `
`impact_weights`	`{low:0.5, medium:1.0, high:1.5}`	per-news weighting
`time_decay_half_life_days`	3.5	sentiment half-life
`news_top_k`	10	max news fed to Gemma
`news_dedup_threshold`	0.85	TF-IDF cosine for dedup
`yfinance_daily_period`	`"6mo"`	daily OHLCV window for features/backtest
`yfinance_intraday_period`	`"5d"`	recent intraday history window
`yfinance_intraday_interval`	`"5m"`	intraday candle interval
`min_rsi_samples`	15	strict RSI window
`max_backtest_days`	22	News API free-tier safe cap

VRAM expectations (`LLM_BACKEND=hf`, 4-bit NF4)

Model	≈ VRAM	Fits on Colab
Gemma 4 · 4B	2.5 GB	T4 ✅
Gemma 4 · 12B (default)	7 GB	T4 ✅
Gemma 4 · 27B	15 GB	A100 ✅ (L4 marginal)
Phi-4 · 14B	9 GB	T4 ✅

Override the default via env var:

export MODEL_ID=google/gemma-4-4b-it     # or microsoft/phi-4, Qwen/Qwen2.5-14B-Instruct, ...

⚠️ Verify the exact Hugging Face id on the model card and update MODEL_ID (or config.py) accordingly. For Ollama, use its model tag instead, for example OLLAMA_MODEL=gemma4:12b.

What was removed from the original

Removed	Why
FinBERT (`yiyanghkust/finbert-tone`)	Gemma 4 covers per-news polarity + nuance
BART (`facebook/bart-large-cnn`)	Gemma 4 handles summary + advice
Sentence-BERT embeddings (`get_embeddings`)	Was dead code; dedup now via TF-IDF
Fine-tuning on IMDB	Domain mismatch + Colab Pro not suited
Two parallel UI handlers (before/after)	Collapsed into one
`Model explanation/` (28 .md)	Coverage already lives in module docstrings
Tutorial PNG screenshots	Out-of-date with the new UI

Roadmap

Phase 1 — "Make it credible" ← complete

Multi-agent Bull vs Bear debate
Backtesting framework
Gradio web UI
Unified live/backtest aggregation
Mock-based integration tests
All Critical + Major review findings resolved

Phase 2 — "Make it smarter" ← next

RAG over historical news + past predictions (BGE-M3 + FAISS)
Time-series forecast (Chronos / TimesFM)
Reddit + WSB sentiment (PRAW)
SEC filings ingest (EDGAR)

Phase 3 — "Make it production"

Watchlist + scheduled Telegram alerts
PDF report export
Earnings call audio (Whisper)
Portfolio optimiser (PyPortfolioOpt)

Navigation Menu

Repository files navigation

Stock Analysis — Gemma 4 Edition

Phase 1 features — "Make it credible"

Pipeline

Project layout

Setup (Google Colab via VSCode extension)

Usage

CLI

Web UI (Gradio)

Inside a Colab notebook cell

Local preview without a GPU (Mac/Windows/Linux)

LLM backends (Hugging Face vs Ollama)

`LLM_BACKEND=hf` — local open-weight model (default)

`LLM_BACKEND=ollama` — local Ollama server

Tests

Backtest interpretation

Configuration knobs

VRAM expectations (`LLM_BACKEND=hf`, 4-bit NF4)

What was removed from the original

Roadmap

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 182 Commits
src		src
tests		tests
.env.example		.env.example
.gitignore		.gitignore
CODE_REVIEW.md		CODE_REVIEW.md
LICENSE.txt		LICENSE.txt
README.md		README.md
config.py		config.py
demo_ui.py		demo_ui.py
main.py		main.py
pytest.ini		pytest.ini
requirements-dev.txt		requirements-dev.txt
requirements-ollama.txt		requirements-ollama.txt
requirements.txt		requirements.txt
webapp.py		webapp.py

Folders and files

Latest commit

History

Repository files navigation

Stock Analysis — Gemma 4 Edition

Phase 1 features — "Make it credible"

Pipeline

Project layout

Setup (Google Colab via VSCode extension)

Usage

CLI

Web UI (Gradio)

Inside a Colab notebook cell

Local preview without a GPU (Mac/Windows/Linux)

LLM backends (Hugging Face vs Ollama)

LLM_BACKEND=hf — local open-weight model (default)

LLM_BACKEND=ollama — local Ollama server

Tests

Backtest interpretation

Configuration knobs

VRAM expectations (LLM_BACKEND=hf, 4-bit NF4)

What was removed from the original

Roadmap

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`LLM_BACKEND=hf` — local open-weight model (default)

`LLM_BACKEND=ollama` — local Ollama server

VRAM expectations (`LLM_BACKEND=hf`, 4-bit NF4)