paulandClaude Opus 4.8
902758ce67
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>
94 lines
4.0 KiB
Markdown
94 lines
4.0 KiB
Markdown
## 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
|