# 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`