equitysearch/openspec/changes/stock-deep-evaluation/design.md

## Context

This is a greenfield Next.js + TypeScript web app that turns a single NYSE/Nasdaq
ticker into a thorough, agent-written evaluation (valuation, macro, entry/exit,
stop-loss). The target output shape is captured concretely in
`examples/de-reentry-2026-08-21.md` and encoded as requirements in the four spec
files. Constraints: bring-your-own API keys, free-tier market data by default,
rate limits, and no persistence in v1. The design must keep data-provider and
model-provider choices swappable so cost/quality decisions don't ripple into the
evaluation or UI code.

## Goals / Non-Goals

**Goals:**
- One typed pipeline: `resolve ticker → fetch data → compute evaluation → agent narrative`.
- Provider-agnostic boundaries: `DataProvider` and `AnalysisAgent` interfaces are
  the only seams consumers see.
- Deterministic, testable evaluation math separated from the non-deterministic
  agent prose. The structured evaluation must stand on its own even with no agent key.
- Secrets stay server-side only.

**Non-Goals:**
- Persistence, accounts, watchlists, alerts, real-time streaming, backtesting.
- Multi-ticker dashboards. (Deferred to later changes.)
- Trade execution or brokerage integration.

## Decisions

### D1 — App structure: Next.js App Router, server-side data/agent calls
Route handlers (or server actions) under `app/api/*` run the pipeline server-side;
the client is a thin report view. Rationale: keeps API keys off the browser
(satisfies the app-config spec), and lets data + agent calls share one request.
Alternative considered: client-side fetching — rejected because it would leak keys
and duplicate rate-limit handling.

### D2 — `DataProvider` interface with a free default
A single interface returns normalized models: `CompanyProfile`, `Fundamentals`
(TTM + per-FY, optional segments), `PriceHistory`, `TechnicalContext` (computed),
`AnalystCoverage`, `Estimates`. Default implementation targets a free tier
(candidate: Financial Modeling Prep or Finnhub; final pick during tasks). Each
model carries an `asOf` timestamp and `delayed|realtime` flag. Alternative:
code directly against one vendor — rejected for lock-in and testability.

### D3 — Technical indicators computed in-house, not taken from the provider
Moving averages (20/50/200), swing highs/lows, 52-week distance, volume multiple,
and realized volatility are computed from OHLCV in a pure `technicals` module.
Rationale: providers expose these inconsistently; in-house math is deterministic
and unit-testable, and it is the same input the entry/exit/stop logic needs.

### D4 — Evaluation engine is pure and provider-free
`evaluate(inputs) → Evaluation` is a pure function over normalized data. It emits
a typed `Evaluation` object (one field per spec section) with explicit
`unavailable` markers — never fabricated or zero-filled values. All entry/exit/
stop levels, implied multiples at each level, and valuation reasoning are computed
here. Rationale: the spec requires the structured object to be consumable without
the agent, and pure functions make the many numeric requirements testable.

### D5 — `AnalysisAgent` interface; Claude Code CLI default, API alternate
The agent takes the `Evaluation` object and returns narrative sections. Consumers
depend only on the interface, so the transport is swappable. **Default transport:
the local Claude Code CLI in headless mode** — `claude -p --output-format json`,
running on the operator's existing Claude auth (subscription), so an internal
two-person tool incurs ~no metered cost. **Alternate transport:** the Anthropic API
via `@anthropic-ai/sdk`, selected by config, for when the app is served to external
users (subscription-backed serving is not appropriate then). Default model is
**Opus 4.8** (CLI alias `opus`); a per-request deep-dive flag escalates to
**Fable 5** (CLI alias `fable`) — model is a per-request parameter, not a build-time
constant. Structured narrative is requested via the CLI `--json-schema` option (or
the API alternate's structured-output). The agent is instructed to use the supplied
figures plus attributed web-sourced facts, preserve flagged caveats, and include
the disclaimer. When no agent is available the pipeline returns the `Evaluation`
with `narrative: unavailable`.

CLI invocation shape (verified against `claude --help`): `claude -p "<prompt>"
--model <opus|fable> --output-format json --json-schema '<narrative schema>'
--append-system-prompt "<instructions>" --allowedTools "WebSearch WebFetch"
--permission-mode dontAsk`. The JSON result carries the structured output plus
`total_cost_usd` and token usage (consumed by cost-controls). API-alternate notes
(from the SDK reference): Opus 4.8 and Fable 5 take `thinking: {type: "adaptive"}`,
reject `budget_tokens`/sampling params; Fable 5 has thinking always-on and can
return `stop_reason: "refusal"` (enable a server-side fallback to Opus 4.8); stream
long outputs.

### D8 — Live web grounding via the agent's web tools
The agent grounds macro/news facts through its web search + fetch capability —
Claude Code's `WebSearch`/`WebFetch` tools on the default transport, or Anthropic's
server-side web tools on the API alternate — scoped to the ticker, with sources
attributed in the output. Rationale: the reference DE evaluation's credibility came
from live, cited facts (analyst target changes, tariff figures, peer read-throughs,
catalyst dates) that don't exist in model weights or a fundamentals feed — this is
the layer that closes the gap to a search-augmented tool like Perplexity. A bonus of
the CLI default: this grounding harness is built in, so there is nothing to wire up.
Grounding degrades gracefully: on tool error the agent still writes from the
structured evaluation and notes that live grounding was unavailable.

### D6 — Typed results end-to-end; errors are values
Data, evaluation, and agent layers return typed results/errors (not thrown
exceptions across boundaries). A data failure, rate-limit, or agent failure each
degrade to a partial result the UI can render. Rationale: the specs require honest
partial states and readable errors.

### D7 — Caching and rate limiting at the provider boundary
An in-memory (v1) cache keyed by ticker+dataset with short TTLs sits inside the
provider layer, with retry/backoff for transient/rate-limit errors. Rationale:
free tiers are tightly limited; caching one evaluation's repeated reads avoids
burning quota. Persistence-backed cache is a later change.

### D9 — Cost controls: capture real usage, price from a table, guard the budget
Every agent call's `usage` (input/output/cache tokens) and web-search count are
captured from the API response — never estimated — and priced via a configurable
table (per-model token prices + per-search price) so provider price changes are
config, not code. Month-to-date spend is kept in lightweight local storage (a JSON
file/`localStorage`-class store, not a database — consistent with the no-persistence
scope) and checked before each evaluation against a configurable monthly budget:
soft threshold warns, cap blocks. The pipeline evaluates the guard *before*
dispatching the agent (and pre-empts a deep-dive whose projected cost exceeds the
remaining budget), so a runaway loop can't blow the cap. Rationale: cost is the one
resource a user can't see mid-run; real per-report numbers replace the design-time
estimate and let the user tune the Opus/Fable mix. Alternative: rely on
Anthropic-console billing after the fact — rejected because it's not in-app, not
per-ticker, and offers no pre-emptive block.

### D10 — Instrument-type-aware from the start; equity branch only in v1
The resolved profile and the `Evaluation` object carry an `instrumentType`
discriminant (`equity` | `etf`). Instrument-agnostic sections (current standing,
technicals, timing, entry/exit, stop-loss, macro) are shared; the
fundamentals/valuation sections live under a per-type branch. v1 implements only
the equity branch and returns an unsupported-type result for anything else.
Rationale: an ETF is ~half the same (all technicals/timing) and ~half different
(no EPS/earnings/segments; instead holdings, expense ratio, NAV premium/discount,
weighted fundamentals). Baking the discriminant and branch seam in now is nearly
free and avoids a refactor when the ETF branch is added as a fast-follow change.
Alternative: equities-only with no seam — rejected as false economy given ETFs are
an explicit near-term goal.

### Roadmap (deferred, compose on this change)
- **ETF evaluation branch** — fills the `etf` branch (holdings, expense ratio, NAV
  premium/discount, sector/geo weights, weighted fundamentals) and an ETF agent
  prompt variant; reuses everything instrument-agnostic here.
- **Screening / candidate-finder** — a `screening` capability: criteria/thesis →
  grounded, ranked shortlist (fundamental screener filter + web verification) where
  each candidate links into this evaluator. Deliberately built *after* the
  evaluator exists, so every surfaced idea has a rigorous place to be checked
  rather than being trusted as an oracle.

## Risks / Trade-offs

- [Free-tier data is delayed/incomplete — segments, estimates, or history may be
  missing] → Normalized models mark fields unavailable; evaluation and UI render
  honestly; provider is swappable for a paid tier without consumer changes.
- [Agent may hallucinate numbers] → Agent receives only the structured object,
  is instructed to cite nothing outside it, and prose is rendered alongside the
  computed tables so drift is visible; consider a post-check that every cited
  figure exists in the input.
- [Rate limits during development/demo] → Caching + backoff; a fixture/mock
  provider for tests and offline work.
- [Numeric correctness of valuation/technical math] → Pure modules with unit tests
  seeded from the DE example's known figures.
- [Not financial advice / liability] → Mandatory disclaimer enforced in both the
  evaluation object and the agent narrative.

## Migration Plan

Greenfield — no data migration. Deployment: run locally (`localhost:3000`) with
`.env.local` holding the market-data and Anthropic keys. Rollout is incremental by
capability (see tasks): scaffold → data layer + technicals → evaluation engine →
agent → UI. Rollback is trivial (no persisted state). Keys are provided via env;
absence degrades gracefully rather than failing the build.

## Open Questions

- Which free market-data provider is the default (coverage of segments + forward
  estimates varies materially)? Resolve early in tasks by spiking 2 providers on `DE`.
- Source of options-implied expected move and forward consensus EPS on free tiers —
  may need a secondary source or graceful omission.
- Preferred charting library (Recharts vs. lightweight-charts) for overlaying
  entry/exit/stop markers on price history.
- Whether to add an automated "every cited figure exists in inputs" guard on agent
  output in v1 or defer to a later hardening change.