AI

SF-12 AI-grounded research question (PR1 dry-run substrate)

POST /api/ai/research-question — SF-12 PR1 substrate.

Request body (JSON): { "question": "<user question>", "ticker": "AAPL", "mode": "literacy"|"interpretation"|"comparative"|"transcript_compare", "dry_run": true # PR1: must be true }

PR1 behavior:

  • dry_run=True (the only allowed value): build retrieval candidates via A2 RAG, return them as Citation entries with answer="[DRY RUN — PR1 substrate]", cost_usd=0.0, model_used="dry-run". No LLM call. dry_run suppresses the LLM, not the retrieval: the question is embedded by Voyage AI (US) on this path too. See the module header.
  • dry_run=False: return 501 with {"detail": "live LLM ships in PR2"}. Explicit refusal — never silently 200 with an empty body.
  • Advisory-shaped questions (per _is_advisory() — the COUNSEL F7 BLOCKING denylist shared with /api/ai/ask) are refused with 400 before any retrieval. The refusal payload echoes the advisory-refusal contract used by the existing Ask-AI surface.
post/api/ai/research-question

Request

  • Base URL: https://www.oxfordledge.com (the document declares no server; this is the origin it was published from)
  • URL: https://www.oxfordledge.com/api/ai/research-question
  • Auth: none declared

Response

Successful Response

answerstring required

The AI-generated answer body. PR1 dry-run: '[DRY RUN — PR1 substrate]'.

tickerstring required

Uppercase ticker echo of the request param.

mode'literacy' | 'interpretation' | 'comparative' | 'transcript_compare' required

SF-12 answer-mode enum (R1 + R4 ratifications, 2026-05-27).

Four modes — three extractive (PR2, Haiku, substring+cosine verifier)

  • one delta (PR2.5, Sonnet, cross-quarter ≥2-citation + LLM-judge):

    • literacy — "What does this number mean?" (PROFESSOR financial-literacy shape; pairs with the mastery layer).
    • interpretation — "Why is X elevated/dropping?" (SF-5 conviction + cluster output shape).
    • comparative — "Compare across tickers" (pulls multiple SF-5 outputs into one answer).
    • transcript_compare — R1 headline mode: "What did management say differently vs last 3 quarters?" Cross-quarter framing delta; ships in PR2.5 only.
cost_usdnumber

LLM spend for this call in USD. PR1 dry-run: 0.0. Mode-weighted in PR4 (transcript_compare counts 4x).

model_usedstring

Model identifier (e.g. claude-3-5-haiku-20241022). PR1 dry-run: 'dry-run'.

advice_disclosure_footerstring required

Mandatory AI_RESEARCH_DISCLOSURE literal (COUNSEL F1 BLOCKING).

generated_atstring required

ISO8601 timestamp when the response was generated.

dry_runboolean required

True in PR1 (the only allowed path); PR2 flips to False on live.

Changes

No recorded changes to this operation across all 1 revision of this API.