equitysearch/openspec/changes/stock-deep-evaluation/specs/cost-controls/spec.md at main

Files

T

paulandClaude Opus 4.8 902758ce67 Build stock-deep-evaluation v1: single-stock equity evaluation app

Next.js 15 + TypeScript app implementing the fully-specced first change.
Pipeline: resolve -> market data -> pure evaluation engine -> budget guard
-> analysis agent -> report.

- market-data: DataProvider interface, offline FixtureProvider (DE/SPY seeded
  from the reference example), FmpProvider (FMP free tier), TTL cache + retry.
- technicals: pure MA/volatility/swing/52-week math.
- evaluation: instrument-aware pure engine; equity branch built, ETF gated to
  "not yet supported". Reproduces the DE example (P/E 34.5, fwd 29.3, $167.6B).
- agent: AnalysisAgent interface; default Claude Code CLI transport (headless,
  subscription-backed, web-grounded), Anthropic API alternate via config.
- cost-controls: price table, spend store, monthly budget guard.
- UI: ticker search + deep-dive toggle, report view, price chart with marked
  entry/exit/stop levels, cost/budget display, ETF/not-found states.

31 vitest tests, typecheck, production build, and lint all pass. Verified
end-to-end via the API for DE, SPY, and an unknown ticker. Live Claude CLI
agent test is the documented pick-up point (see README).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-08-21 17:03:04 -04:00

4.0 KiB

Raw Permalink Blame History

ADDED Requirements

Requirement: Per-report usage capture

The system SHALL capture the actual usage of every evaluation that calls the analysis agent from the agent's own reported usage — the Claude Code CLI JSON output (total_cost_usd plus token usage) for the default transport, or the API response usage for the alternate — not from estimates. Captured fields SHALL include, where the transport reports them, token counts, model used, and a reported cost. When the transport runs on a subscription rather than metered billing, the reported marginal cost MAY be zero or near-zero; the system SHALL record what the transport reports.

Scenario: Usage recorded for a completed report

WHEN an evaluation completes an agent call
THEN the system records the report's token counts, web-search count, model, ticker, and timestamp

Scenario: Usage captured on partial results

WHEN an agent call fails after consuming tokens (e.g. a mid-stream error)
THEN the usage consumed up to that point is still recorded

Requirement: Cost computation from a configurable price table

The system SHALL compute each report's cost from captured usage and a configurable price table (per-model input/output/cache token prices and per-search price). Prices SHALL be editable via configuration so provider price changes require no code changes.

Scenario: Report cost computed

WHEN a report's usage is captured
THEN the system computes its cost using the configured price table and stores the cost alongside the usage

Scenario: Unknown model priced safely

WHEN a report uses a model absent from the price table
THEN the system flags the cost as unpriced rather than recording zero

Requirement: Spend aggregation

The system SHALL maintain a running month-to-date total spend and SHALL expose per-report cost history. The spend record MAY use lightweight local storage; a full database is out of scope for this change.

Scenario: Month-to-date total available

WHEN a new report's cost is recorded
THEN the month-to-date total reflects the new report
AND the per-report history includes the new entry

Scenario: Month boundary resets the running total

WHEN the calendar month changes
THEN the month-to-date total starts from zero for the new month
AND prior months' totals remain available in history

Requirement: Monthly budget guard

The system SHALL enforce a configurable monthly budget. When month-to-date spend crosses a configurable soft threshold (default 80% of budget) the system SHALL warn but still allow evaluations. When spend reaches the budget cap the system SHALL block new evaluations and return a clear message rather than silently proceeding. A disabled/zero budget SHALL mean no enforcement.

Scenario: Soft-threshold warning

WHEN month-to-date spend crosses the soft threshold but is below the cap
THEN the system allows the evaluation and surfaces a budget warning with the current spend and remaining budget

Scenario: Hard-cap block

WHEN month-to-date spend has reached the configured cap
THEN the system blocks new evaluations and returns a message stating the cap was reached and how to raise or disable it

Scenario: Deep-dive gated at the cap

WHEN a deep-dive (Fable 5) evaluation is requested and the projected cost would exceed the remaining budget
THEN the system blocks it and explains the remaining budget

Scenario: Guard disabled

WHEN the monthly budget is set to zero or disabled
THEN evaluations proceed without budget enforcement

Requirement: Cost visibility in the UI

The system SHALL display each report's cost in the report view and SHALL surface month-to-date spend against the configured budget in the app.

Scenario: Report cost shown

WHEN a report renders
THEN its computed cost is shown in the report view

Scenario: Budget status shown

WHEN the app is in use
THEN month-to-date spend and remaining budget are visible

4.0 KiB Raw Permalink Blame History