fix: coerce compound LLM source strings to prevent BriefOutput validation failures

The synthesis model was echoing compound source placeholders like '10-Q, transcript'
from the prompt template, causing Pydantic to reject the entire brief with up to 14
validation errors. Adds a _normalize_source() before-validator on all four source-
bearing models (SourcedFact, CategorizedRisk, ManagementCommentaryTopic, GuidancePoint)
that resolves compound strings to a single canonical value using filing > transcript >
news precedence. Also tightens ManagementCommentaryTopic.source to exclude 'news'
(matching prompt docs) and removes the five compound placeholders from the prompt
template that caused the model to emit the bad values in the first place.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

agent/prompts.py

@@ -186,8 +186,8 @@ Required JSON structure:
       "bullish_reading": "What the optimistic surface reading says.",
       "bearish_reading": "What cross-referencing the data reveals as a concern or caveat.",
       "weight": "material or watch or minor",
-      "bullish_evidence": { "text": "...", "source": "10-K, 10-Q, transcript, or news", "reliability": "HIGH or MEDIUM or LOW", "impact": "HIGH or MEDIUM or LOW", "evidence_snippet": "verbatim quote <=30 words" },
-      "bearish_evidence": { "text": "...", "source": "10-K, 10-Q, transcript, or news", "reliability": "HIGH or MEDIUM or LOW", "impact": "HIGH or MEDIUM or LOW", "evidence_snippet": "verbatim quote <=30 words" }
+      "bullish_evidence": { "text": "...", "source": "10-Q", "reliability": "HIGH or MEDIUM or LOW", "impact": "HIGH or MEDIUM or LOW", "evidence_snippet": "verbatim quote <=30 words" },
+      "bearish_evidence": { "text": "...", "source": "10-Q", "reliability": "HIGH or MEDIUM or LOW", "impact": "HIGH or MEDIUM or LOW", "evidence_snippet": "verbatim quote <=30 words" }
     }
   ],
 
@@ -196,7 +196,7 @@ Required JSON structure:
       "dimension": "consensus_beat_mix or guidance_dynamics or narrative_vs_numbers or segment_mix or capital_allocation",
       "assessment": "positive or neutral or concerning",
       "rationale": "One sentence grounded in retrieved evidence.",
-      "evidence": { "text": "...", "source": "10-K, 10-Q, transcript, or news", "reliability": "HIGH or MEDIUM or LOW", "impact": "HIGH or MEDIUM or LOW", "evidence_snippet": "verbatim quote <=30 words" }
+      "evidence": { "text": "...", "source": "10-Q", "reliability": "HIGH or MEDIUM or LOW", "impact": "HIGH or MEDIUM or LOW", "evidence_snippet": "verbatim quote <=30 words" }
     }
   ],
 
@@ -254,7 +254,7 @@ Required JSON structure:
     "language_shift": "1-2 sentences: how has management language changed vs prior periods? More confident, more cautious, more defensive? Reference specific wording changes if available.",
     "key_quote": {
       "text": "The single most revealing management statement this period.",
-      "source": "10-Q, 10-K, or transcript",
+      "source": "10-Q",
       "reliability": "HIGH or MEDIUM",
       "impact": "HIGH or MEDIUM or LOW",
       "evidence_snippet": "The verbatim quote <=30 words"
@@ -287,7 +287,7 @@ Required JSON structure:
     {
       "period": "Q2 2025",
       "text": "The guidance statement, 1-2 sentences.",
-      "source": "10-Q, 10-K, or transcript",
+      "source": "10-Q",
       "reliability": "HIGH or MEDIUM",
       "impact": "HIGH or MEDIUM or LOW",
       "metric_focus": "Revenue or EPS or Operating margin or Capex or null",

agent/schemas.py

@@ -7,6 +7,35 @@ _CANONICAL_CATEGORIES = {
     "Regulatory", "Operational", "Competitive", "Financial", "Macro", "Demand", "Geopolitical"
 }
 
+def _normalize_source(v: object) -> object:
+    """Coerce a compound/dirty LLM source string to a single canonical value.
+
+    The LLM occasionally emits combined sources like '10-Q, transcript' (often echoing
+    the prompt's placeholder). Resolve to one value using the documented precedence
+    'filing beats transcript beats news' (see prompts.py: 'always set source to the
+    filing'). Between two filings, keep whichever appears first in the string.
+    Unknown strings pass through unchanged so the Literal still rejects them.
+    """
+    if not isinstance(v, str):
+        return v
+    s = v.strip()
+    if s in ("10-K", "10-Q", "transcript", "news"):
+        return s
+    low = s.lower()
+    if "10-k" in low or "10-q" in low:
+        k, q = low.find("10-k"), low.find("10-q")
+        if k == -1:
+            return "10-Q"
+        if q == -1:
+            return "10-K"
+        return "10-K" if k < q else "10-Q"
+    if "transcript" in low:
+        return "transcript"
+    if "news" in low:
+        return "news"
+    return v  # let Literal validation reject genuinely-invalid sources
+
+
 _CATEGORY_ALIASES: dict[str, str] = {
     "Legal": "Regulatory",
     "Compliance": "Regulatory",
@@ -54,6 +83,11 @@ class SourcedFact(BaseModel):
         description="A literal quote (≤30 words) from the cited source that directly supports the claim. Must appear verbatim in retrieved tool output."
     )
 
+    @field_validator("source", mode="before")
+    @classmethod
+    def _coerce_source(cls, v: object) -> object:
+        return _normalize_source(v)
+
     @field_validator('evidence_snippet')
     @classmethod
     def validate_snippet_length(cls, v: str) -> str:
@@ -111,6 +145,11 @@ class CategorizedRisk(BaseModel):
         description="True if this risk appears new or materially escalated vs prior filing."
     )
 
+    @field_validator("source", mode="before")
+    @classmethod
+    def _coerce_source(cls, v: object) -> object:
+        return _normalize_source(v)
+
     @field_validator("category", mode="before")
     @classmethod
     def _normalize_category(cls, v: object) -> str:
@@ -128,8 +167,8 @@ class ManagementCommentaryTopic(BaseModel):
 
     topic: str = Field(description="Topic label, 2-5 words (e.g. 'iPhone demand', 'AI capex', 'margin guidance').")
     summary: str = Field(description="1-2 sentence summary of what management said about this topic.")
-    source: Literal["10-K", "10-Q", "transcript", "news"] = Field(
-        description="Source document for this commentary item."
+    source: Literal["10-K", "10-Q", "transcript"] = Field(
+        description="Source document for this commentary item. Management commentary must come from filings or transcripts, not news."
     )
     reliability: Literal["HIGH", "MEDIUM", "LOW"] = Field(
         description="HIGH for SEC filings, MEDIUM for transcripts."
@@ -140,6 +179,11 @@ class ManagementCommentaryTopic(BaseModel):
     )
     evidence_snippet: str = Field(description="Verbatim quote ≤30 words supporting this topic.")
 
+    @field_validator("source", mode="before")
+    @classmethod
+    def _coerce_source(cls, v: object) -> object:
+        return _normalize_source(v)
+
     @field_validator('evidence_snippet')
     @classmethod
     def _trim(cls, v: str) -> str:
@@ -155,6 +199,12 @@ class GuidancePoint(BaseModel):
     source: Literal["10-K", "10-Q", "transcript", "news"] = Field(
         description="Document type where this guidance appeared."
     )
+
+    @field_validator("source", mode="before")
+    @classmethod
+    def _coerce_source(cls, v: object) -> object:
+        return _normalize_source(v)
+
     reliability: Optional[Literal["HIGH", "MEDIUM", "LOW"]] = Field(
         default=None,
         description="HIGH for SEC filings, MEDIUM for transcripts."

tests/test_schemas.py

@@ -208,3 +208,105 @@ def test_brief_output_validates_with_geopolitical_risk():
         )]
     )
     assert brief.risks_categorized[0].category == "Geopolitical"
+
+
+# ── _normalize_source — SourcedFact ─────────────────────────────────────────
+
+def _sf(source: str) -> SourcedFact:
+    return SourcedFact(text="x", source=source, reliability="HIGH", evidence_snippet="x")
+
+
+def test_sourced_fact_coerces_compound_10q_transcript():
+    assert _sf("10-Q, transcript").source == "10-Q"
+
+
+def test_sourced_fact_coerces_compound_transcript_10q():
+    # filing takes precedence regardless of order
+    assert _sf("transcript, 10-Q").source == "10-Q"
+
+
+def test_sourced_fact_coerces_compound_10k_transcript():
+    assert _sf("10-K, transcript").source == "10-K"
+
+
+def test_sourced_fact_coerces_compound_10q_news():
+    assert _sf("10-Q, news").source == "10-Q"
+
+
+def test_sourced_fact_coerces_compound_10q_10k_first_wins():
+    # '10-Q' appears before '10-K' in this string → 10-Q
+    assert _sf("10-Q, 10-K").source == "10-Q"
+
+
+def test_sourced_fact_coerces_compound_10k_10q_first_wins():
+    # '10-K' appears before '10-Q' in this string → 10-K
+    assert _sf("10-K, 10-Q").source == "10-K"
+
+
+def test_sourced_fact_coerces_compound_transcript_news():
+    assert _sf("transcript, news").source == "transcript"
+
+
+def test_sourced_fact_coerces_lowercase_10q():
+    # case-folding: "10-q" → "10-Q"
+    assert _sf("10-q").source == "10-Q"
+
+
+def test_sourced_fact_regression_invalid_source_still_rejected():
+    # _normalize_source passes unknown strings through → Literal still rejects them
+    with pytest.raises(ValidationError):
+        _sf("bloomberg")
+
+
+# ── _normalize_source — other models ────────────────────────────────────────
+
+def test_categorized_risk_coerces_compound_source():
+    r = CategorizedRisk(
+        category="Macro", text="Macro risk.", source="10-Q, 10-K",
+        reliability="HIGH", is_new_this_filing=False,
+    )
+    assert r.source == "10-Q"
+
+
+def test_management_commentary_coerces_compound_source():
+    t = ManagementCommentaryTopic(
+        topic="AI capex", summary="Capex rising.", source="transcript, 10-Q",
+        reliability="HIGH", evidence_snippet="Capex rising.",
+    )
+    assert t.source == "10-Q"
+
+
+def test_guidance_point_coerces_compound_source():
+    g = GuidancePoint(period="Q3 2025", text="Revenue guided flat.", source="10-K, transcript")
+    assert g.source == "10-K"
+
+
+# ── BriefOutput end-to-end: reproduces the original NVDA failure ─────────────
+
+def test_brief_output_tolerates_compound_source_in_analytical_tension():
+    """Reproduce the NVDA 14-error failure: compound source inside a nested SourcedFact."""
+    from agent.schemas import AnalyticalTension
+    tension = AnalyticalTension(
+        headline="Data center growth strong but sequential deceleration notable.",
+        bullish_reading="Revenue beat consensus by 4%.",
+        bearish_reading="Sequential growth slowing despite beat.",
+        weight="watch",
+        bullish_evidence=SourcedFact(
+            text="Revenue grew 78% YoY.",
+            source="10-Q, transcript",  # ← the form that caused the original failure
+            reliability="HIGH",
+            evidence_snippet="Revenue grew 78% YoY driven by data center.",
+        ),
+        bearish_evidence=SourcedFact(
+            text="Sequential growth decelerated.",
+            source="10-Q, news",
+            reliability="HIGH",
+            evidence_snippet="Sequential revenue growth slowed to 8%.",
+        ),
+    )
+    assert tension.bullish_evidence.source == "10-Q"
+    assert tension.bearish_evidence.source == "10-Q"
+
+    brief = _minimal_brief(analytical_tensions=[tension])
+    assert brief.analytical_tensions[0].bullish_evidence.source == "10-Q"
+    assert brief.analytical_tensions[0].bearish_evidence.source == "10-Q"