Uris001/equity-research-platform

<div align="center">

<br>

<img src="https://readme-typing-svg.demolab.com?font=Fira+Code&weight=700&size=27&pause=1000&color=60A5FA&center=true&vCenter=true&width=760&lines=%E2%9A%A1+AI-Powered+Equity+Research+Platform;Score+any+public+ticker+in+seconds;Live+Quant+%2B+OOS+Stat-Arb+%2B+Volatility+Cones" alt="Typing SVG" />

<br><br>

      [](LICENSE) [](https://huggingface.co/spaces/Uris001/equity-research-platform)

<br>

Type any ticker — S&P 500, Nasdaq, or global — and get a full quant deep-dive in seconds: a transparent 0–100 scorecard, an AI-written analyst note, two peer-discovery engines, a look-ahead-free pairs stat-arb backtest, and a 21-day volatility cone — all from live market data.

<br>

Built around one principle: every number on screen is either real, validated, or explicitly labelled as neither.

<br>

</div>

🎯 The Problem & The Solution

A junior equity analyst spends hours per stock pulling prices, computing technical indicators, reading fundamentals, scanning sentiment, writing up a note, and finding comparable companies. That workflow is repetitive, slow, and inconsistent across analysts.

This project automates the entire loop with a data-science pipeline that spans every stage of the course — synthetic data generation, EDA, embedding-based recommendation, LLM text generation, a trained sentiment classifier, and a live application — tied together into one coherent product:

What makes this version different: the platform is engineered to be defensible, not just impressive. The pairs backtest is look-ahead-free by construction and unit-tested for it; the return-prediction experiment that scored negative out-of-sample R² is disclosed on the card instead of dressed up as a forecast; and every tab carries a data-provenance badge (📡 LIVE · 🧪 SYNTHETIC · 🤖 MODEL) so no synthetic number can masquerade as a real one.

📋 Table of Contents

🗺 End-to-End Workflow

flowchart TD
    A["🧪 PART 1 — Synthetic Data Generation<br/>Qwen2.5-1.5B-Instruct · 200 tickers × 10 sectors<br/>× event/technique mix · leakage-controlled = 10,000 notes"] --> B
    B["📊 PART 2 — Exploratory Data Analysis<br/>Quality audit · IQR outliers · 7 research questions<br/>feature engineering · text-vs-quant separability"] --> C
    C["🧹 Quality Gate<br/>drop short / low-diversity / failed generations<br/>→ clean modeling corpus"] --> D
    C --> T
    D["🧠 PART 3 — Embedding Benchmark<br/>MiniLM-L6-v2 · MPNet-base-v2 · BGE-small-en-v1.5<br/>(+ Tabular-PCA quant baseline) · intra-sim / silhouette / Davies-Bouldin"] --> E
    E["🏆 Winner: BAAI/bge-small-en-v1.5<br/>recorded in winner.json · FAISS IndexFlatIP (cosine)<br/>ticker & natural-language recommendation"] --> F
    T["🔢 Quant feature matrix<br/>synthetic fundamentals → winsorized z-scores<br/>SECTOR-NEUTRAL Value/Quality/Momentum factors"] --> H
    F["✍️ PART 4 — Analyst-Note Generation<br/>Mistral-7B-Instruct-v0.2 · few-shot prompting<br/>ROUGE-L · BERTScore · Flesch · semantic sim · hallucination proxy"] --> H
    P["🔮 PART 6 — Return-Model Evaluation<br/>real yfinance features · temporal split<br/>VERDICT: OOS R² < 0 → ship the VOLATILITY CONE instead"] --> H
    Q["📈 Pairs Stat-Arb Engine<br/>formation/trading split · Engle–Granger screen<br/>causal rolling z · next-bar execution · bootstrap CI"] --> H
    H["🚀 PART 5 — HuggingFace Space (Gradio 6)<br/>modular architecture · 26 unit tests · provenance badges<br/>6 tabs · zero runtime training · dark quant UI"]

    style A fill:#e0e7ff,stroke:#4338ca,color:#1e1b4b
    style B fill:#dcfce7,stroke:#16a34a,color:#052e16
    style C fill:#fef3c7,stroke:#d97706,color:#451a03
    style T fill:#fff7ed,stroke:#ea580c,color:#431407
    style D fill:#e0f2fe,stroke:#0284c7,color:#0c4a6e
    style E fill:#fce7f3,stroke:#db2777,color:#500724
    style F fill:#f3e8ff,stroke:#9333ea,color:#2e1065
    style P fill:#dbeafe,stroke:#2563eb,color:#0c1d57
    style Q fill:#cffafe,stroke:#0891b2,color:#083344
    style H fill:#e0f2fe,stroke:#0369a1,color:#0c4a6e

Two AI engines, one platform. A recommendation engine (embeddings + FAISS) finds similar stocks; a generation engine (Mistral-7B) writes the analyst note. Both are wrapped by a deterministic, finance-aware scorecard, extended by a look-ahead-free stat-arb backtester and an empirical volatility cone — and everything that touches synthetic data says so on screen.

🔗 How the Parts Connect

Nothing is an isolated exercise; every part is a dependency of the next.

1. 1.Part 1 → Part 2. The synthetic generator produces ~10,000 notes across 200 tickers. Because the generator is a small instruction model, raw outputs need auditing — so Part 2 (EDA) is the gate that measures quality and removes noise before modeling.

1. 1.Part 2 → Part 3. The EDA defines the quality filters and engineers the tabular financial features that feed the factor model and the trained sentiment classifier.

1. 1.Part 3 → Part 4 → App. Part 3 benchmarks three text-embedding models (MiniLM, MPNet, BGE-small) against a quant-PCA baseline, crowns BGE-small-en-v1.5 the measured winner — recorded in winner.json, which the app reads at startup so the deployed encoder can never drift from the declared winner — and builds the FAISS index the app reuses for narrative peer discovery. Part 4 validates the few-shot prompting strategy for Mistral-7B that the app reuses to write notes. Parts 3–4 are the R&D; the app is the production deployment of their findings.

1. 1.Honesty as an architectural rule. Two return-prediction experiments were run — one on synthetic fundamentals (Part 3 §11), one on real market data (Part 6). Both scored out-of-sample R² ≈ 0 or below, and both are shelved, with the negative results documented in the app itself. The forward-looking views the platform does ship are the ones that survive scrutiny: the factor ranking (transparent methodology), the OOS pairs backtest (look-ahead-free), and the volatility cone (measured uncertainty).

Part 1 (generate) ─▶ Part 2 (clean + engineer features)
                          │                          │
                          ▼                          ▼
                  text notes (≈10k)         tabular features
                          │                          │
                          ▼                ┌──────────┴───────────────┐
                 Part 3 (BGE + FAISS)    ▼                          ▼
                          │       Value/Quality/Momentum     sentiment classifier
                          │       (sector-neutral z-scores)  (the trained deliverable)
                          │                │                          │
                          │                │     §11 + Part 6 return predictors
                          │                │     → BOTH SHELVED (OOS R² ≤ 0),
                          │                │       disclosed in-app
                          └────────┬───────┴──────────┬───────────────┘
                                   ▼                  ▼
        Part 4 (Mistral few-shot)  +  pairs stat-arb engine  +  volatility cone
                                   ▼
                  Part 5 — Gradio App (this Space, 6 tabs, 26 unit tests)

📦 Upstream — the Dataset (Parts 1 & 2)

This app is built on `Uris001/equity-research-dataset` — ~10,000 analyst notes across 200 tickers and 10 sectors, generated with an instruction-tuned LLM under a leakage-controlled design, then audited and cleaned via a full EDA (quality, outliers, 7 research questions). The generation process and the EDA are documented in the [dataset card](https://huggingface.co/datasets/Uris001/equity-research-dataset).

One rule follows from this everywhere in the app: the corpus fundamentals are synthetic, so any panel built on them carries a 🧪 SYNTHETIC provenance badge, and no synthetic quantity is ever blended into a live-data number.

🧠 Part 3 — Recommendation, Embeddings & the Quant Layer

📓 Notebook: 03_embeddings_recommendation.ipynb

The goal: turn each stock into a vector, so "find me similar stocks" becomes a geometry problem — then extend the same feature work into a systematic factor model and a trained classifier.

3.1 — Three-model embedding benchmark

Full-document coverage via chunk + mean-pool (naïve encode() silently truncates at ~250 words), and a composite quality metric (intra-sector cosine + silhouette + inverted Davies-Bouldin):

🏆 `BAAI/bge-small-en-v1.5` wins the measured composite (intra-sector cosine + silhouette + inverted Davies-Bouldin) and is recorded in winner.json — the app reads that file at startup. Winning vectors are L2-normalised and indexed with FAISS `IndexFlatIP` (inner product = cosine on unit vectors) for sub-millisecond search.

3.1b — Does the recommender actually recommend? (measured, not asserted)

The deployed index was validated two ways — the sector label is never an input (the engine sees only note text), so recovering sector structure is genuine validation, not circularity:

Domain spot checks (pre-stated expectations, then inspected output):

Universe-wide metric — querying every one of the 200 tickers and scoring its top-5 neighbours:

Sector precision@5 = 0.62 vs a ≈ 0.14 random-sector prior — a same-sector peer is ~4.4× more likely than chance. Strongest where the language is distinctive (Energy 0.90, Healthcare 0.72, Technology 0.72); weakest for Materials (0.07) and Communication Services (0.03) — both have only 6 names in the universe (few same-sector candidates exist), and their notes read like adjacent sectors (GOOGL/META are labelled Communication Services but discussed as tech). That failure mode is the embedding faithfully reflecting the notes' language colliding with a rigid sector taxonomy — disclosed here rather than hidden. KMeans + DBSCAN independently recover the sector taxonomy and flag the pre-profit Space/Quantum names as density outliers — an unsupervised confirmation of the EDA.

3.2 — Cross-Sectional Factor Model (the Universe Screener)

Every ticker is scored on three classic factors (Fama-French / AQR lineage) via winsorised (1/99%), sign-adjusted, cross-sectional z-scores:

New in this version — sector-neutral scoring (default). Global z-scores make the Value factor a hidden sector bet (short tech, long energy). The screener now standardizes each input within its sector (with a global fallback for tiny groups), so "cheap" means cheap versus its own sector. The effect is unit-tested: on a synthetic universe with deliberately different sector valuation levels, sector-mean Value spread drops from >0.5σ to <0.15σ.

3.3 — Return predictor on synthetic fundamentals (§11 — shelved)

Pre-registered ship rule: deploy only if OOS R² ≥ 0.05. Verdict: shelved — synthetic fundamentals carry no real forward signal (OOS R² ≈ 0 or below). In this version the shelving is complete: no synthetic-data return model is loaded anywhere in the app — no hidden "ML estimate" panels.

3.4 — Sentiment classifier (§12 — the trained deliverable)

A multimodal bake-off (TF-IDF + SVD text channel ⊕ engineered features ⊕ standardized fundamentals) across four model families under one shared CV split, scored on macro-F1:

🏆 Winner: Logistic Regression — test macro-F1 = 0.618 (chance = 0.333), beating the tree ensembles and single-channel baselines. It runs live in the Document Research tab with its provenance disclosed on-screen: it was trained on this project's synthetic corpus, so agreement with FinBERT is a consistency check between models, not independent validation on real market text.

✍️ Part 4 — Analyst-Note Generation

📓 Notebook: 04_generation.ipynb

Benchmarks the app's runtime generator — `mistralai/Mistral-7B-Instruct-v0.2` — across zero-shot / one-shot / few-shot prompting on a stratified test set, with a five-metric evaluation suite:

Few-shot wins the composite, and that exact strategy ships in the app. In production the model is served via the HF Inference API (no 7B weights in the Space) behind a two-tier fallback: Mistral-7B → deterministic template (Mistral is the only LLM) — the note box is never empty, even without an HF_TOKEN, on a rate limit, or during a cold start — and every note is labelled with the tier that actually wrote it, so a template can never masquerade as an LLM.

🎯 The Heuristic Scorecard

Every ticker gets a transparent 0–100 score. It is deliberately presented as what it is — a documented rule-based rubric, not a fitted or validated predictive model — and its bands are named accordingly (no implied trading calls):

Composite = 0.40 · Technical  +  0.40 · Fundamental  +  0.20 · Market Signal

  Technical     = 0.30·RSI + 0.30·MACD + 0.15·BB%B + 0.15·Momentum + 0.10·Volume
  Fundamental   ┌ profitable : 0.30·ROE + 0.25·NetMargin + 0.25·RevGrowth + 0.20·P/E
                └ pre-profit : 0.55·RevGrowth + 0.30·P/S + 0.15·MarketCap
  Market Signal = analyst target-price premium + recommendation mean
                  (3-month momentum ONLY as a disclosed fallback when there is
                   no analyst coverage — it is already inside Technical, so
                   blending it unconditionally would double-count it)

Pre-profit awareness is the key design choice — loss-making Space/Quantum names have structurally NaN profitability metrics, so pushing them through a P/E-based rubric would be nonsense. The platform routes them through a revenue-growth + price-to-sales + market-cap track instead. Both tracks are unit-tested to stay within [0, 100] even on all-NaN input.

🖥 Part 5 — The Live Application

📄 Entry point: app.py — this Hugging Face Space (modular architecture, see Engineering & Tests)

A six-tab Gradio app with a dark quant UI, reading the dataset and models directly from the Hub at runtime. Every tab carries a provenance badge.

Each tab ships one-click Quick Starters (e.g. AAPL, TSLA, IONQ).

📈 Pairs Trading — a Look-Ahead-Free Backtest

The single most common flaw in amateur stat-arb backtests is look-ahead bias: computing the z-score from full-sample statistics, so the entry signal at time t "knows" the future mean it will revert to. This platform's backtest is engineered — and unit-tested — to be free of it:

      ├────────────── FORMATION (60%) ──────────────┤├───────── TRADING (40%) ─────────┤
      pair selection (Engle–Granger ADF on spread)     the ONLY window that is reported
      hedge ratio β (OLS on log prices)                trailing 60-day z-score, shifted
      OU half-life                                     one bar → strictly causal
                                                       positions execute NEXT bar
                                                       P&L net of costs (10 bps/side)

• —Selection without peeking — the hedge leg is chosen among FAISS-suggested peers by formation-window correlation + cointegration only. A test proves that corrupting the trading window cannot change any formation metric.
• —Causal signals — z_t uses the mean/std of the previous 60 bars (window shifted by one). A test proves that perturbing future prices cannot change past z-scores, and that a signal formed on the final bar earns exactly zero (next-bar execution).
• —Honest statistics — OOS Sharpe ships with a bootstrap 90% confidence interval; pairs that fail the Engle–Granger 5% critical value (−3.34) are labelled NO TRADE and their stats greyed out; low trade counts and weak correlations trigger explicit low-confidence banners.
• —Validated math — the pure-numpy ADF t-statistic matches statsmodels.adfuller to 1e-6 in tests.

Example of the honesty working as designed: on a recent KO/PEP run the formation ADF was −2.31 (fails the −3.34 bar) → the app shows NO TRADE, and the OOS Sharpe's CI of [−0.68, +3.07] straddles zero — which is exactly what an unvalidated pair should look like.

🔮 Part 6 — From Return Model to Volatility Cone

📓 Notebook: price_predictor.ipynb · Artifact: price_scenario_model.joblib

Part 6 asks: can a model predict the 21-day forward return from real market data? A 186-ticker, ~27k-row weekly panel of strictly-trailing technical features + fundamentals, a temporal split (train ≤ 12 months ago, test = last 12 months, no shuffle), three regressors, and a pre-registered ship rule (deploy if OOS R² ≥ 0.05):

⚖️ Verdict: no model clears the bar — so no point forecast ships. Publishing bull/bear price targets from a negative-R² model would be decorative complexity. Instead, the 🔮 tab shows the defensible object:

The volatility cone. The ticker's own realized daily volatility (trailing 252d), scaled by √t under a zero-drift lognormal model:

upper_t = P₀ · exp(+1.5·σ·√t)        21-day band ≈ ±11% for a defensive name (KO)
lower_t = P₀ · exp(−1.5·σ·√t)                     ≈ ±19% for a high-beta name (TSLA)

The card states plainly why there is no expected-return line — "a Ridge regression was evaluated for this horizon and scored OOS R² = −0.03" — turning a negative result into demonstrated methodology. Knowing what doesn't predict is part of the analysis.

🧪 Engineering & Tests

The app is a modular package (one concern per module) rather than a single-file script:

What the tests pin down (tests/test_logic.py):

Robustness & degraded modes: no HF_TOKEN → deterministic template (note box never empty) · Yahoo blocked → Finnhub → history-derived cards · FAISS artifacts missing → narrative peers disabled gracefully · long documents → token-window chunking + a sentence cap with an on-screen notice · the ~40-fetch live peer index builds in a background thread at startup so the first click is fast. Secrets are read from the environment only and never logged. No GPU anywhere — free CPU tier.

🚀 How to Use the App

Live Space: **huggingface.co/spaces/Uris001/equity-research-platform**

Tab 1 — 📊 Analyze Any Stock

Type a ticker (AAPL, NVDA, IONQ, …) → Analyze → scorecard + band, technical/fundamental breakdown, price chart, AI note, and the two peer tables.

Tab 2 — 🌍 Universe & Factor Screener

Drag the Value / Quality / Momentum sliders (updates live), toggle sector-neutral, filter sectors, then 🔬 Deep-Dive #1 Pick to pull a full live dossier on the top name.

Tab 3 — 📑 Analyst Terminal

Type a ticker → Pull Full Dossier → ~60 metrics + chart + live news on one screen.

Tab 4 — 🧠 Document Research

Paste text or upload a .txt/.pdf → Analyze Document → dual-model sentiment with agreement read, summary, key figures & event signals, sentence-level evidence, AI research brief.

Tab 5 — 📈 Pairs Trading

Enter a ticker (optionally a hedge leg) → Run Stat-Arb → cointegration screen, causal signal, and the out-of-sample backtest with its bootstrap CI. Try KO/PEP, GS/MS, XOM/CVX.

Tab 6 — 🔮 Price Scenarios

Type a ticker → Project Cone → the 21-day √t volatility cone, terminal band levels, and the disclosed return-model evaluation.

Tip: generation needs an HF_TOKEN Space secret to call Mistral. Without it the app still runs end-to-end (deterministic template note, clearly labelled).

🛠 Tech Stack

⚠️ Limitations & Disclaimer

• —Not financial advice. This is an educational data-science project. Do not trade on its output.
• —The scorecard is a heuristic. Its weights and thresholds are documented rules, not fitted parameters — it is labelled on-screen as "not a validated predictive signal," and its bands deliberately avoid buy/sell language.
• —The factor screener's inputs are synthetic (the project corpus), disclosed on the tab. The ranking methodology — winsorized, sector-neutral cross-sectional z-scores — is the deliverable; the deep-dive pulls real live data.
• —The pairs backtest is honest but still simplified — no slippage or borrow costs, IID bootstrap (ignores autocorrelation), single fixed formation split. All stated in the UI caveats.
• —Near-term return prediction failed our ship rule twice (synthetic §11 and real-data Part 6, both OOS R² ≤ 0) — which is why the app shows uncertainty cones, factor ranks and cointegration screens instead of price forecasts.
• —ETFs & non-equities lack per-company fundamentals — their fundamental sub-score falls back to neutral defaults and is indicative only.

👤 Author

<table> <tr> <td> <b>Uri Sivan</b><br> Introduction to Data Science · Reichman University<br> Final Project — Synthetic Data · EDA · Embeddings · Generation · Classifier · Stat-Arb · HuggingFace Spaces<br><br> <a href="https://huggingface.co/Uris001">🤗 HuggingFace</a> &nbsp;·&nbsp; <a href="https://huggingface.co/spaces/Uris001/equity-research-platform">🚀 Live Space</a> &nbsp;·&nbsp; <a href="https://huggingface.co/datasets/Uris001/equity-research-dataset">📦 Dataset</a> </td> </tr> </table>

<div align="center">

<br>

If you found this useful, consider leaving a ⭐ on the Space!

<br>

Built with ❤️ using

🤗 HuggingFace &nbsp;·&nbsp; 📈 yfinance &nbsp;·&nbsp; 🧠 BGE-small &nbsp;·&nbsp; 🤖 Mistral-7B &nbsp;·&nbsp; 🔎 FAISS &nbsp;·&nbsp; 🟩 Gradio

<br>

<br>

</div>