PaPs Mercados — AI-Powered Equity Analytics Platform
End-to-end equity research and risk platform: a multi-tab Streamlit front-end backed by a FastAPI service that combines fundamentals data, market data, options analytics, and AI-generated narratives over a strict service / adapter architecture.
Used as a production-grade equity research workflow and as a pedagogical platform for graduate finance courses (Universidad Panamericana).
🔗 Live demo: paps-mercados-app.onrender.com
What it does
A single workspace where a user can pull any U.S.-listed name and get, in one screen, the inputs an institutional analyst would assemble by hand from Bloomberg or FactSet:
- Company fundamentals — profile, market cap, key metrics, income statement, growth, revenue segmentation (by product and by geography), institutional holdings, peers and sector peer-comparison.
- Price & forecast — historical prices, peer returns, price change diagnostics, analyst price targets, consensus grades, historical grades.
- News & narrative synthesis — stock-level news feed plus on-demand LLM-generated summaries (Anthropic Claude streaming).
- Options analytics — risk-neutral densities from live option chains via Breeden–Litzenberger (served by the FastAPI backend).
Architecture
Strict layered service / adapter architecture (UI → services → adapters → domain) so the code stays easy to extend with new providers:
src/ui_streamlit/ ← Streamlit front-end (pages, components, theme)
src/services/ ← 24 domain services (quote, peers, news, market data, key metrics,
institutional holdings, income statement, revenue segmentation, ...)
src/adapters/ ← thin clients to Financial Modeling Prep, Massive (ex-Polygon), tastytrade, FinViz
src/analytics/ ← cross-cutting analytics primitives
src/domain/ ← pure domain models and RND math
backend/ ← FastAPI service: /api/rnd endpoints, auth, RND core, data providers
├─ app/main.py ← FastAPI entry point
├─ api/rnd.py ← RND endpoints
├─ rnd_core/ ← models and computation primitives
├─ data_providers/ ← Massive (stocks + options), FMP stocks
└─ config.py ← env-driven settings via python-dotenv
20+ Financial Modeling Prep adapters are governed by per-endpoint cache TTLs and 429-aware retries, so the same screen renders fast on revisit and degrades gracefully under rate-limit pressure.
Stack
- Language / runtime: Python 3.11
- Front-end: Streamlit · Plotly · Altair
- Back-end: FastAPI · Uvicorn · python-dotenv · structured logging
- Data providers: Financial Modeling Prep · Massive (ex-Polygon.io) · tastytrade · FinViz
- AI: Anthropic Claude API (streaming narratives over standardized datasets)
- Persistence (commercial backend variant): PostgreSQL · SQLAlchemy 2.x · Alembic
- Billing / auth (commercial backend variant): Stripe Checkout & billing portal · Google OAuth · JWT
- Deployment: Docker · Render
Quant methods shipped
- 30-day GBM probability fan with EWMA (RiskMetrics, λ = 0.94) and rolling-60d σ estimators, 68% / 95% bands
- Risk-neutral density extraction via Breeden–Litzenberger (PCHIP interpolation, forward-correction normalization)
- Sector and peer exposure mapping, peer-return diagnostics
- Income-statement growth and operating-profitability growth analytics
Repository layout
| Path | Purpose |
|---|---|
src/ui_streamlit/app.py |
Streamlit entry point |
src/services/*.py |
One service per analytical concern (news, peers, market data, …) |
src/adapters/ |
Provider clients (FMP, Massive, tastytrade, FinViz) |
backend/app/main.py |
FastAPI entry point |
backend/api/rnd.py |
RND HTTP endpoints |
backend/data_providers/ |
Backend-side provider clients |
docs/ |
11 internal docs: architecture, deployment, FMP contract, rate-limit/cache design, agent style |
requirements.txt |
Dependencies (pinned) |
runtime.txt |
Python version for Render |
Local development
git clone https://github.com/leoromero-quant/paps-mercados-app.git
cd paps-mercados-app
cp .env.example .env # fill FMP_API_KEY, MASSIVE_API_KEY, ANTHROPIC_API_KEY, ...
pip install -r requirements.txt
# Run front-end
streamlit run src/ui_streamlit/app.py
# (optional) run the FastAPI backend for RND endpoints
uvicorn backend.app.main:app --reload
See docs/02_Deployement.md for the Render deployment recipe and docs/04_Rate_Limit_Cache.md for the cache and 429-handling design.
Author
Leonardo Suárez Romero, PhD — Quantitative Data Analyst. leoromero.dev · LinkedIn
License
Private — all rights reserved. Demo and source available for inspection; commercial use requires permission.
