equitysearch/openspec/changes/stock-deep-evaluation/specs/analysis-agent/spec.md

ADDED Requirements

Requirement: Provider-agnostic analysis-agent interface

The system SHALL define an AnalysisAgent interface that accepts a structured evaluation object and returns a written analysis. Consumers MUST depend only on this interface so the underlying model provider can change without affecting the evaluation engine or UI.

Scenario: Agent invoked through the interface

• WHEN an evaluation object is passed to the configured analysis agent
• THEN the agent returns a written analysis produced through the interface

Scenario: Alternate implementation can be registered

• WHEN a different agent implementation is configured
• THEN the system uses it without changes to evaluation or UI code

Requirement: Default agent via Claude Code CLI; API as swappable alternate

The system SHALL ship a default AnalysisAgent that invokes the local Claude Code CLI in headless mode (claude -p --output-format json), which runs on the operator's existing Claude authentication (e.g. subscription) rather than a metered API key. The system SHALL also ship an alternate implementation backed by the Anthropic API (@anthropic-ai/sdk), selectable via configuration without changes in consumers. Either way, the default model SHALL be Claude Opus 4.8 (CLI alias opus) and a per-request "deep dive" option SHALL escalate to Claude Fable 5 (CLI alias fable); the model SHALL be selectable per evaluation. Structured narrative output SHALL be requested via the CLI --json-schema option (or the equivalent structured-output mechanism on the API alternate). Any API key used by the alternate SHALL be loaded from configuration and never hard-coded or committed.

Scenario: Claude Code CLI produces the written thesis

• WHEN the CLI agent is configured and an evaluation is submitted
• THEN the system runs claude -p with model alias opus and returns the written thesis parsed from the CLI JSON output

Scenario: Deep-dive escalates to Fable 5

• WHEN an evaluation is requested with the deep-dive option enabled
• THEN the agent runs the CLI with model alias fable for that request
• AND requests without the option continue to use opus

Scenario: API alternate selected via configuration

• WHEN the agent transport is configured to the API alternate with a valid key
• THEN evaluations are served through @anthropic-ai/sdk instead of the CLI
• AND no changes to evaluation or UI code are required

Scenario: Secrets sourced from configuration

• WHEN the API alternate reads its configuration
• THEN the Anthropic API key is loaded from environment/config, not source code

Requirement: Live web grounding

The agent SHALL be able to retrieve current information via its web search and web fetch capability — the Claude Code CLI's WebSearch/WebFetch tools for the default transport, or Anthropic's server-side web tools for the API alternate — to source macro and news-driven facts the structured data layer does not provide: tariff/rate developments, analyst rating and price-target changes, management commentary, peer read-throughs, and dated catalysts. Facts drawn from the web SHALL carry their source so the output can attribute them, and grounding SHALL be scoped to the ticker under evaluation.

Scenario: Web-sourced facts are attributed

• WHEN the agent uses a web-sourced fact in the analysis (e.g. an analyst target change or a catalyst date)
• THEN the output attributes that fact to its source

Scenario: Grounding degrades gracefully

• WHEN web search or fetch is unavailable or returns an error
• THEN the agent still produces the analysis from the structured evaluation
• AND notes that live macro/news grounding was unavailable

Requirement: Grounded, structured written analysis

The agent SHALL base its narrative on the supplied evaluation data plus attributed web-sourced facts, and SHALL NOT invent figures. It SHALL produce the narrative sections reflected in the example evaluation: current standing, earnings recap and quality-of-earnings caveats, valuation with explicit over/undervalued reasoning, macro factors, timing, entry/exit/stop-loss rationale, bull-versus-bear, and an actionable plan. When a data caveat or discrepancy is present in the input, the agent SHALL preserve it.

Scenario: Narrative grounded in provided data

• WHEN the agent writes the analysis
• THEN every figure it cites is either present in the supplied evaluation object or attributed to a web source it retrieved

Scenario: Data caveats preserved

• WHEN the evaluation object flags a discrepancy or one-time item
• THEN the written analysis surfaces that caveat rather than omitting it

Scenario: Disclaimer preserved in narrative

• WHEN the agent returns its analysis
• THEN the analysis-not-advice disclaimer is present

Requirement: Graceful degradation without an available agent

The system SHALL, when no analysis agent is available (the Claude Code CLI is not installed or not authenticated, or the configured API alternate has no key), still return the full structured evaluation and clearly indicate that the written narrative is unavailable and how to enable it.

Scenario: Agent unavailable

• WHEN an evaluation is requested and no agent transport is available
• THEN the structured evaluation is returned
• AND the response indicates the written analysis is unavailable and how to enable it (authenticate the CLI, or configure an API key)

Requirement: Agent error handling

The system SHALL handle agent failures (auth errors, rate limits, timeouts) by returning a typed error and the underlying structured evaluation, without losing the data already computed.

Scenario: Agent call fails

• WHEN the agent call errors after retries
• THEN the system returns the structured evaluation plus a typed agent error
• AND the computed data is not discarded