feat(report): POST /api/report/<id>/signal — extract structured miro_signal from simulation

[LoryGlory]

Problem

MiroFish produces rich simulation reports but no machine-readable output contract. External pipelines that want to consume a prediction probability (e.g. prediction-market bots, calibration trackers) have to parse unstructured markdown — or receive a JSON block that doesn't match any stable schema. This was reported in #277.

Solution

A new POST /api/report/<report_id>/signal endpoint that distils a completed report into a canonical probability signal with a stable schema.

Changes

backend/app/services/signal_extractor.py (new)

SignalExtractor.extract() takes the report's markdown_content and simulation_requirement and uses chat_json() to extract a structured thesis:

• 3 retry attempts, temperature 0.1 with 0.05 backoff — deterministic extraction
• _trim_report() keeps the tail of long reports (conclusions matter most for signal extraction)
• All fields validated and normalised server-side:
  • p_yes clamped to [0.01, 0.99]
  • confidence enforced to high | medium | low, falls back to medium
  • action enforced to buy_yes | buy_no | hold, recomputed from p_yes if invalid
  • regime defaults to uncertain if missing
• _salvage() is wired as fallback_parser: if the LLM returns near-valid output, a regex scan extracts any float probability and constructs a minimal signal rather than failing

backend/app/api/report.py

New route POST /api/report/<report_id>/signal:

• 404 — report not found
• 400 — report not yet completed, or empty content
• 422 — LLM failed after all retry attempts (surfaced as ValueError)
• 200 — returns canonical signal

backend/tests/services/test_signal_extractor.py (new)

27 tests, LLMClient fully mocked:

• Happy path: field values, metadata, to_dict() structure, LLM call parameters
• Validation: p_yes clamping, invalid confidence/action fallbacks, missing regime
• Report trimming: short reports unchanged, long reports trimmed keeping tail
• _salvage: probability extraction, action derivation, confidence detection
• LLM failure: ValueError propagates correctly

Canonical signal schema (v1.1)

{
  "signal_id": "<uuid>",
  "schema_version": "1.1",
  "report_id": "report_xxxx",
  "simulation_id": "sim_xxxx",
  "generated_at": "2026-...",
  "thesis": {
    "p_yes": 0.73,
    "confidence": "high",
    "action": "buy_yes",
    "regime": "consensus_forming",
    "summary": "Strong agent consensus supports a YES outcome.",
    "drivers": ["70%+ agent agreement", "positive social momentum"],
    "invalidators": ["marginal counter-narrative", "low information diversity"]
  }
}

Dependency

This PR is built on top of #318 (feat/llm-structured-output-reliability) and uses its retry and JSON repair infrastructure in chat_json(). It can be merged independently if #318 lands first, or merged together with it.

Fixes

Closes #277

Testing

cd backend && uv run pytest tests/ -v
# 57 passed in 0.23s