CLAUDE.md

Amplegest — Claude Code Context

What this project is

A Streamlit web app for retail investors. User enters a ticker → receives a structured research brief covering: what changed in the latest results, what matters most, bull points, bear points, what to watch next.

MVP scope: 5–10 S&P 500 large-cap companies, manually curated.

Architecture

Two layers:

Offline ingestion (python ingest.py TICKER) — fetches SEC EDGAR filings + earnings transcripts, chunks and embeds text into Chroma, extracts structured financial metrics into SQLite. Run manually after each earnings release.

Runtime (streamlit run app.py) — LangGraph tool-calling agent retrieves from Chroma + SQLite + Tavily (live news), synthesizes into a structured brief. LangSmith traces every run.

Key constraints

• Public data only. No Bloomberg, Refinitiv, or paid market data APIs.
• No buy/sell recommendations, no price targets — ever.
• Every output fact must carry a source tag (10-K, 10-Q, transcript, news) and reliability level (HIGH, MEDIUM, LOW).
• what_matters_most is the only AI-interpretation field — all others are sourced facts.
• LangGraph agent is capped at 10 tool rounds per run (a round may contain multiple parallel tool calls) to bound token spend.

LLM

Model: claude-haiku-4-5-20251001 (Anthropic SDK). Used for both agent loop and synthesis node.

Tech stack

• Python 3.11+
• langgraph, langsmith, anthropic
• chromadb — vector store (two collections: filings, transcripts)
• sqlite3 — structured financial metrics
• tavily-python — live news search (runtime only)
• streamlit — frontend
• yfinance — analyst estimates, price reaction, EDGAR XBRL fallback
• sentence-transformers — cross-encoder reranker (BAAI/bge-reranker-base) for RAG chunks
• alpha_vantage — quarterly EPS surprise / earnings tracker

Environment variables (.env)

ANTHROPIC_API_KEY=
TAVILY_API_KEY=
LANGCHAIN_TRACING_V2=true
LANGCHAIN_API_KEY=
LANGCHAIN_PROJECT=amplegest

Data directory

data/ is gitignored. Contains chroma/ (vector DB files) and metrics.db (SQLite).

Full design spec

docs/superpowers/specs/2026-05-04-ticker-brief-design.md