equitysearch/README.md

equitysearch

Thorough, agent-written evaluation of individual NYSE / Nasdaq equities: valuation and over/undervalued reasoning, macro factors, entry/exit points, and stop-loss levels — grounded in structured fundamentals plus live web search.

Built spec-first with OpenSpec; the change that produced v1 lives in openspec/changes/stock-deep-evaluation/.

▶ Pick up here next time — live agent test

v1 is fully built and verified except for one thing left to do live: exercise the real Claude Code CLI agent writing the thesis with web grounding. Everything else (data → evaluation → API → structured report → charts → cost/budget) is tested and confirmed end-to-end; the analysis narrative has only been checked with a stubbed agent.

To resume:

1. Ensure the claude CLI is authenticated (claude → log in).
2. npm run dev, open http://localhost:3000, search DE.
3. Confirm the written thesis renders (Thesis / Valuation / Macro / Timing / Entry-exit-stop / Bull-vs-bear / Plan sections) and that Sources are cited.
4. Toggle Deep dive to run Fable 5 and compare depth.
5. If the narrative needs shaping, tune the prompt in src/lib/agent/agent.ts (systemInstructions / userPrompt).

The OpenSpec change stock-deep-evaluation is complete but not yet archived — archive it (openspec archive stock-deep-evaluation) once the live test looks good.

Quick start

npm install
cp .env.example .env.local   # optional — the app runs with zero config
npm run dev                  # http://localhost:3000

Search a ticker (try DE). With no configuration the app uses an offline fixture provider (DE + SPY) and the Claude Code CLI agent.

How it works

ticker → resolve → market data → evaluation engine (pure) → budget guard → analysis agent → report

• Market data (src/lib/market-data) — a provider-agnostic DataProvider interface. Default is an offline fixture (DE seeded from the reference example); set MARKET_DATA_PROVIDER=fmp + MARKET_DATA_API_KEY for real Financial Modeling Prep data.
• Evaluation engine (src/lib/evaluation) — a pure function that computes the quantitative sections (standing, earnings recap, quality-of-earnings flags, segments, valuation, entry/exit/stop levels, bull/bear, plan). Instrument-aware: v1 runs the equity branch; ETFs resolve but return "not yet supported".
• Analysis agent (src/lib/agent) — turns the structured evaluation into the written thesis, grounded with live web search.
• Cost controls (src/lib/cost) — captures per-report usage/cost and enforces a monthly budget (soft warning, hard cap, deep-dive pre-emption).

Configuration (.env.local)

Var	Default	Purpose
AGENT_TRANSPORT	claude-cli	claude-cli (runs the local Claude Code CLI on your subscription — no API key, ~$0 marginal) or api (metered Anthropic API for serving external users)
ANTHROPIC_API_KEY	—	Only for AGENT_TRANSPORT=api. Server-side only
MARKET_DATA_PROVIDER	fixture	fixture (offline DE/SPY) or fmp
MARKET_DATA_API_KEY	—	FMP free-tier key
MONTHLY_BUDGET_USD	0	Monthly spend cap; 0 disables the guard

Agent transports. The default runs claude -p --output-format json --model opus|fable --allowedTools "WebSearch WebFetch" on your existing Claude auth, so an internal tool incurs near-zero marginal cost and web grounding is built in. Deep dive escalates the model to Fable 5. Requires the claude CLI installed and authenticated. Switch to api if the app is ever served to external users (subscription-backed serving is not appropriate then).

Scripts

npm run dev        # dev server
npm run build      # production build
npm run start      # run the production build
npm run typecheck  # tsc --noEmit
npm test           # vitest (31 tests)

Not investment advice

Every report ends with a disclaimer. This is analysis, not investment advice.

Roadmap (deferred changes, compose on v1)

• ETF evaluation branch — holdings, expense ratio, NAV premium/discount, weighted fundamentals (the seams are already in place).
• Screening / candidate-finder — criteria → grounded ranked shortlist that feeds this evaluator.