Blame for agent/graph.py

import json
import re
from concurrent.futures import ThreadPoolExecutor
from datetime import datetime, timezone
from typing import TypedDict, Annotated, Optional
from langchain_core.messages import BaseMessage, SystemMessage, HumanMessage, ToolMessage
from langgraph.graph import StateGraph, END
from langgraph.graph.message import add_messages

from agent.tools import (
    get_financial_metrics,
    search_filing,
    search_transcript,
    search_news,
    get_analyst_expectations,
)
from agent.prompts import SYSTEM_PROMPT, SYNTHESIS_STRUCTURED_PROMPT, language_directive
from agent.schemas import BriefOutput
from agent.post_synthesis import apply_reliability, attach_edge_signals, apply_continuity_threads
from agent.evidence import (
    NO_VERIFIED_SYNTHESIS_MESSAGE,
    evidence_records_from,
    evidence_envelope,
    is_usable_evidence_payload,
    parse_evidence_envelope,
)
from agent.llm import RunConfig, default_config, make_chat_model, build_system_message, ANTHROPIC_DEFAULT_MODEL
from analytics.consensus import aligned_consensus

TOOLS = [
    get_financial_metrics,
    search_filing,
    search_transcript,
    search_news,
    get_analyst_expectations,
]
MAX_TOOL_ROUNDS = 10
MODEL = ANTHROPIC_DEFAULT_MODEL  # legacy alias — prefer agent.llm.RunConfig for new code

TOOL_BY_NAME = {t.name: t for t in TOOLS}
_EXPECTED_TOOL_SOURCES = {
    "get_financial_metrics": {"metrics"},
    "search_filing": {"10-K", "10-Q"},
    "search_transcript": {"transcript"},
    "search_news": {"news"},
    "get_analyst_expectations": {"analyst"},
}


def _invoke_one(tc: dict) -> ToolMessage:
    """Invoke a single tool call and return a ToolMessage."""
    name = tc["name"]
    args = tc.get("args") or {}
    tool_call_id = tc.get("id", "")
    try:
        fn = TOOL_BY_NAME.get(name)
        if fn is None:
            raise ValueError(f"Unknown tool: {name!r}")
        result = fn.invoke(args)
        content = result if isinstance(result, str) else str(result)
    except Exception as exc:
        content = evidence_envelope(
            tool=name,
            query=args,
            status="ERROR",
            message=str(exc),
            error_code="TOOL_INVOCATION_ERROR",
        )
    return ToolMessage(tool_call_id=tool_call_id, name=name, content=content)

# Tool names that the agent must touch before synthesis can proceed.
# Without filing AND transcript evidence, the structured brief schema
# (mda_summary, risks_categorized, management_commentary, etc.) cannot
# be filled without fabrication.
REQUIRED_TOOL_NAMES = {"search_filing", "search_transcript"}


class AgentState(TypedDict):
    ticker: str
    messages: Annotated[list[BaseMessage], add_messages]
    tool_round_count: int
    nudge_fired: bool
    edge_signals: Optional[list[dict]]  # precomputed deterministic signals
    profile_payloads: Optional[list[str]]
    open_threads: Optional[list[dict]]  # currently-open continuity threads for this ticker
    language: Optional[str]             # e.g. "French" — prose fields in brief will use this language
    brief: Optional[dict]
    brief_markdown: Optional[str]
    synthesis_error: Optional[str]
    coverage: Optional[dict]
    verification_report: Optional[dict]


def _called_tool_names(messages: list[BaseMessage]) -> set[str]:
    return {m.name for m in messages if isinstance(m, ToolMessage) and getattr(m, "name", None)}


def _filing_call_count(messages: list[BaseMessage]) -> int:
    return sum(
        1 for m in messages
        if isinstance(m, ToolMessage)
        and getattr(m, "name", None) == "search_filing"
        and is_usable_evidence_payload(m)
    )


def _tool_envelopes(messages: list[BaseMessage], name: str) -> list[dict]:
    envelopes = []
    for message in messages:
        if not isinstance(message, ToolMessage) or getattr(message, "name", None) != name:
            continue
        envelope = parse_evidence_envelope(message)
        if envelope and envelope.get("tool") == name:
            envelopes.append(envelope)
    return envelopes


def _records_for_tool(envelope: dict, name: str):
    allowed = _EXPECTED_TOOL_SOURCES.get(name, set())
    return [
        record for record in evidence_records_from(envelope)
        if record.ref.source in allowed
    ]


def _coverage_report(messages: list[BaseMessage]) -> dict:
    groups = {
        "metrics": "get_financial_metrics",
        "filings": "search_filing",
        "transcripts": "search_transcript",
        "analyst": "get_analyst_expectations",
        "news": "search_news",
    }
    report: dict = {}
    for label, name in groups.items():
        envelopes = _tool_envelopes(messages, name)
        valid_counts = {id(e): len(_records_for_tool(e, name)) for e in envelopes}
        ok = [
            e for e in envelopes
            if e.get("status") == "OK" and valid_counts[id(e)] > 0
        ]
        invalid = [
            e for e in envelopes
            if e.get("status") == "OK" and valid_counts[id(e)] == 0
        ]
        if ok:
            status = "OK"
        elif any(e.get("status") == "ERROR" for e in envelopes):
            status = "ERROR"
        elif invalid:
            status = "INVALID"
        elif any(e.get("status") == "EMPTY" for e in envelopes):
            status = "EMPTY"
        else:
            status = "NOT_CALLED"
        report[label] = {
            "status": status,
            "successful_calls": len(ok),
            "evidence_count": sum(valid_counts[id(e)] for e in ok),
            "errors": [
                (e.get("error") or {}).get("message", "tool error")
                for e in envelopes if e.get("status") == "ERROR"
            ] + (["invalid evidence record"] if invalid else []),
        }
    gaps = []
    if report["metrics"]["evidence_count"] < 1:
        gaps.append("financial metrics unavailable")
    if report["filings"]["evidence_count"] < 1:
        gaps.append("filing evidence unavailable")
    elif report["filings"]["successful_calls"] < 2:
        gaps.append("only one filing search completed")
    if report["transcripts"]["evidence_count"] < 1:
        gaps.append("transcript evidence unavailable")
    report["gaps"] = gaps
    report["status"] = "COMPLETE" if not gaps else "PARTIAL"
    return report


def _can_synthesize(messages: list[BaseMessage]) -> bool:
    coverage = _coverage_report(messages)
    return (
        coverage["metrics"]["evidence_count"] >= 1
        and coverage["filings"]["evidence_count"] >= 1
    )


def _coverage_gaps(messages: list[BaseMessage]) -> list[str]:
    """Return retryable gaps; EMPTY is confirmed absence, not retryable."""
    gaps = []
    metrics = _tool_envelopes(messages, "get_financial_metrics")
    filings = _tool_envelopes(messages, "search_filing")
    transcripts = _tool_envelopes(messages, "search_transcript")
    if not any(e.get("status") == "OK" and _records_for_tool(e, "get_financial_metrics") for e in metrics):
        gaps.append("get_financial_metrics")
    filing_ok = sum(
        e.get("status") == "OK" and bool(_records_for_tool(e, "search_filing"))
        for e in filings
    )
    if filing_ok < 2 and not any(e.get("status") == "EMPTY" for e in filings):
        gaps.append(f"search_filing (need 2 successful calls; {filing_ok} so far)")
    if not any(
        e.get("status") == "EMPTY"
        or (e.get("status") == "OK" and _records_for_tool(e, "search_transcript"))
        for e in transcripts
    ):
        gaps.append("search_transcript")
    return gaps


def should_continue(state: AgentState) -> str:
    last = state["messages"][-1]
    under_cap = state["tool_round_count"] < MAX_TOOL_ROUNDS

    if getattr(last, "tool_calls", None) and under_cap:
        return "tools"

    # Agent stopped emitting tool calls. Check coverage floor before
    # routing to synthesis: require ≥2 filing calls + ≥1 transcript call.
    if not getattr(last, "tool_calls", None) and under_cap and not state.get("nudge_fired"):
        if _coverage_gaps(state["messages"]):
            return "nudge"

    return "synthesis" if _can_synthesize(state["messages"]) else "partial"


def _chunk_text(content) -> str:
    """Text carried by one streamed chunk, whatever shape the provider used.

    A plain string when the model streams text only. Models that think —
    Claude Opus 5 runs adaptive thinking by default — stream a list of typed
    blocks instead. Take the text blocks and drop the rest: thinking is
    commentary, not the brief JSON we are parsing.
    """
    if isinstance(content, str):
        return content
    if not isinstance(content, list):
        return ""
    parts = []
    for block in content:
        if isinstance(block, str):
            parts.append(block)
        elif isinstance(block, dict) and block.get("type") == "text":
            parts.append(block.get("text") or "")
    return "".join(parts)


def _extract_json(raw: str) -> str:
    """Extract the first complete JSON object from LLM output.

    Uses raw_decode so trailing content — extra commentary, a duplicate object
    (e.g. when the model was asked about multiple tickers), or a stray code
    fence — is ignored instead of triggering a json.loads 'Extra data' error.
    """
    start = raw.find("{")
    if start != -1:
        try:
            _obj, end = json.JSONDecoder().raw_decode(raw, start)
            return raw[start:end]
        except json.JSONDecodeError:
            pass
    # Last-resort fallback: original first-{ to last-} heuristic
    end = raw.rfind("}")
    if start != -1 and end != -1 and end > start:
        return raw[start:end + 1]
    return raw


def nudge_node(state: AgentState) -> dict:
    """One-shot prod when the agent tries to terminate without minimum coverage."""
    gaps = _coverage_gaps(state["messages"])
    gaps_str = " and ".join(f"`{g}`" for g in gaps)
    nudge = HumanMessage(content=(
        f"Before synthesizing, you must satisfy these coverage requirements: {gaps_str}. "
        "Filings (10-Q/10-K) are the primary source — `what_changed`, `bull_points`, "
        "`bear_points`, and `risks_categorized` must be predominantly filing-sourced. "
        "Issue the missing search call(s) now (batched where independent)."
    ))
    return {"messages": [nudge], "nudge_fired": True}


# Checked in this order, and reported in it: revenue is the metric expected
# to align (street revenue estimates track reported GAAP revenue), while eps
# is expected to be refused as basis_mismatch, because yfinance publishes
# adjusted estimates against this repo's GAAP reported figure. See
# analytics/consensus.py's module docstring.
_CONSENSUS_METRICS = ("revenue", "eps")


def _market_expectations_aligned_metrics(
    ticker: str, period: Optional[str]
) -> list[str]:
    """The metrics whose consensus passes the alignment gate, e.g. ["revenue"].

    THIS, not the boolean below, is what a consumer rendering an
    actual-versus-consensus line must check, and it must check it for the
    metric it is about to render. Normally only revenue aligns: eps is
    expected to be refused as basis_mismatch, and that refusal is the correct
    answer rather than a defect. A consumer that read the boolean and drew an
    EPS comparison would be drawing a comparison the gate explicitly refused.

    Order is stable and mirrors _CONSENSUS_METRICS.
    """
    if not period:
        return []
    aligned: list[str] = []
    try:
        for metric in _CONSENSUS_METRICS:
            snapshot, _status = aligned_consensus(ticker, period, metric)
            if snapshot is not None:
                aligned.append(metric)
    except Exception:
        # An unreadable archive must never fail a brief. Fail closed: report
        # nothing aligned rather than a partial list of unknown provenance.
        return []
    return aligned


def _market_expectations_aligned(ticker: str, period: Optional[str]) -> bool:
    """True when AT LEAST ONE metric's consensus passes the alignment gate.

    Kept for backward compatibility, and deliberately coarse. It says nothing
    about WHICH metric aligned, so it is not sufficient authority to render
    any particular comparison — use
    ``_market_expectations_aligned_metrics`` (and the
    ``market_expectations_aligned_metrics`` display-policy key it feeds) for
    that. The gate itself is unchanged and still refuses by default; what
    changed is that the archive can now supply the pre-release estimate
    timestamp it always required.
    """
    return bool(_market_expectations_aligned_metrics(ticker, period))


def _partial_brief(state: AgentState, reason: str) -> dict:
    coverage = _coverage_report(state.get("messages", []))
    company_name = state["ticker"].upper()
    filing_date = ""
    for envelope in _tool_envelopes(state.get("messages", []), "get_financial_metrics"):
        for record in envelope.get("records") or []:
            metadata = record.get("metadata") or {}
            company_name = metadata.get("company_name") or company_name
            filing_date = metadata.get("filing_date") or filing_date
            if filing_date:
                break
    if not filing_date or company_name == state["ticker"].upper():
        try:
            from storage.metrics_db import get_metrics

            metrics = get_metrics(state["ticker"])
            if isinstance(metrics, dict):
                if company_name == state["ticker"].upper():
                    company_name = metrics.get("company_name") or company_name
                if not filing_date:
                    filing_date = metrics.get("filing_date") or filing_date
        except Exception:
            pass
    generated_at = datetime.now(timezone.utc).isoformat()
    return {
        "ticker": state["ticker"].upper(),
        "company_name": company_name,
        "filing_date": filing_date,
        "status": "PARTIAL",
        "schema_version": "brief.v2",
        "generated_at": generated_at,
        "data_as_of": filing_date,
        "what_matters_most": NO_VERIFIED_SYNTHESIS_MESSAGE,
        "non_obvious_takeaway": "",
        "analytical_tensions": [],
        "between_the_lines": [],
        "earnings_quality_signals": [],
        "standout_number": None,
        "what_changed": [],
        "bull_points": [],
        "bear_points": [],
        "what_to_watch": [],
        "trends": [],
        "evidence_notes": [reason] + list(coverage.get("gaps") or []),
        "evidence_coverage": {
            "status": "INCOMPLETE", "verified": 0, "unverified": 0,
            "failed": 0, "total": 0,
        },
        "verification_report": {
            "verified": 0, "unverified": 0, "failed": 0, "removed": 0,
        },
        "coverage": coverage,
        "mda_summary": {
            "drivers": [], "headwinds": [], "language_shift": "", "key_quote": None,
        },
        "risks_categorized": [],
        "management_commentary": [],
        "guidance_history": [],
        "sentiment": None,
        "market_expectations": None,
        "quarter_deltas": state.get("edge_signals") or [],
        "display_policy": {
            "event_returns_aligned": False,
            "market_expectations_aligned": False,
            # A partial brief has no verified market data, so no metric may
            # be shown against consensus. Present-and-empty, never absent: a
            # consumer must not have to tell "nothing aligned" from "this
            # brief predates the key".
            "market_expectations_aligned_metrics": [],
            "aggregate_reliability_meaningful": False,
        },
        "language": state.get("language") or "English",
        "company_profile": None,
        "narrative": None,
        "narrative_usage": None,
    }


def _format_signals_message(signals: list[dict]) -> str:
    """Format precomputed edge signals as a compact labelled block for the agent."""
    lines = ["== PRECOMPUTED EDGE SIGNALS (deterministic, no LLM) ==\n"]
    kind_labels = {
        "risk_added":              "NEW RISK",
        "risk_removed":            "REMOVED RISK",
        "risk_reworded":           "REWORDED RISK",
        "guidance_language_shift": "GUIDANCE LANGUAGE SHIFT",
        "term_frequency":          "TERM FREQUENCY SHIFT",
        "kpi_dropped":             "DROPPED KPI",
        "tone_trend":              "MANAGEMENT TONE TREND",
        "topic_arc":               "TRANSCRIPT TOPIC ARC",
        "recurring_evasion":       "RECURRING Q&A EVASION",
        "topic_fade":              "PREPARED-REMARKS TOPIC FADE",
    }
    for i, s in enumerate(signals, 1):
        kind = s.get("kind", "")
        label = kind_labels.get(kind, kind.upper())
        sig = s.get("significance", "MEDIUM")
        term = s.get("term", "")
        term_str = f" — {term}" if term else ""
        lines.append(f"[SIG-{i}] {label}{term_str} [{sig}]")
        if s.get("before_text"):
            lines.append(f"  BEFORE ({s.get('period_from','')}): \"{s['before_text']}\"")
        if s.get("after_text"):
            lines.append(f"  AFTER  ({s.get('period_to','')}): \"{s['after_text']}\"")
        if s.get("computed_metric"):
            lines.append(f"  METRIC: {s['computed_metric']}")
        lines.append("")
    lines.append("== END PRECOMPUTED EDGE SIGNALS ==")
    return "\n".join(lines)


MAX_EDGE_SIGNALS = 12
MAX_FILING_SIGNALS = 8
MAX_TRANSCRIPT_SIGNALS = 6
# Output budget for the single-call synthesis (brief + company profile +
# one full evidence_ref per fact). 16384 was inherited from the pre-merge
# two-call split and truncated real AAPL briefs mid-JSON (stop_reason=
# max_tokens at exactly 16384 output tokens). 64000 is the claude-haiku-4-5
# output ceiling; billing only covers tokens actually generated.
SYNTHESIS_MAX_TOKENS = 64000
# Output budget for one agent-loop turn (tool calls, no prose). LangChain
# defaults to 1024, which is ample for a tool call but not for a model that
# thinks first — thinking tokens count against max_tokens, and Claude Opus 5
# runs adaptive thinking by default. Unused headroom is not billed.
AGENT_MAX_TOKENS = 8192


class SynthesisTruncatedError(RuntimeError):
    """The synthesis stream was cut off by the max_tokens limit."""


def _cap_signals(signals: list[dict], max_total: int = MAX_EDGE_SIGNALS) -> list[dict]:
    """Bound the edge-signal block: per-source caps, then a global cap.

    Sorts HIGH→MEDIUM→LOW, keeps at most MAX_FILING_SIGNALS filing-sourced and
    MAX_TRANSCRIPT_SIGNALS transcript-sourced signals, then truncates to
    max_total so neither module can flood the prompt.
    """
    order = {"HIGH": 0, "MEDIUM": 1, "LOW": 2}
    signals = sorted(signals, key=lambda s: order.get(s.get("significance", "MEDIUM"), 2))
    capped: list[dict] = []
    filing_n = transcript_n = 0
    for s in signals:
        if s.get("source") == "transcript":
            if transcript_n >= MAX_TRANSCRIPT_SIGNALS:
                continue
            transcript_n += 1
        else:
            if filing_n >= MAX_FILING_SIGNALS:
                continue
            filing_n += 1
        capped.append(s)
    return capped[:max_total]


def signals_node(state: AgentState) -> dict:
    """Run deterministic analysis modules and inject signals into conversation."""
    ticker = state["ticker"]
    raw_signals = []
    try:
        from analysis.textdiff import compute as compute_text_deltas
        raw_signals.extend(compute_text_deltas(ticker))
    except Exception as exc:
        import sys
        print(f"[signals_node] textdiff error: {exc}", file=sys.stderr)
    try:
        from analysis.tone_drift import compute as compute_tone_deltas
        raw_signals.extend(compute_tone_deltas(ticker))
    except Exception as exc:
        import sys
        print(f"[signals_node] tone_drift error: {exc}", file=sys.stderr)
    signals = _cap_signals([s.model_dump() for s in raw_signals])

    if signals:
        msg = HumanMessage(content=_format_signals_message(signals))
        return {"edge_signals": signals, "messages": [msg]}
    return {"edge_signals": [], "messages": []}


def _format_open_threads_message(threads: list[dict]) -> str:
    """Format currently-open continuity threads as a compact labelled block."""
    lines = ["== OPEN THREADS FROM PRIOR QUARTERS ==\n"]
    for t in threads:
        last_note = (t.get("history") or [{}])[-1].get("note", "")
        lines.append(
            f"[{t['thread_id']}] {t['topic']} ({t['category']}, {t['status']} "
            f"since {t.get('last_updated_period', '?')}): {last_note}"
        )
    return "\n".join(lines)


def continuity_node(state: AgentState) -> dict:
    """Load open continuity threads for this ticker and inject them as context."""
    from storage import threads_db
    try:
        open_threads = threads_db.get_open_threads(state["ticker"])
    except Exception as exc:
        import sys
        print(f"[continuity_node] failed to load open threads: {exc}", file=sys.stderr)
        return {"open_threads": [], "messages": []}
    if not open_threads:
        return {"open_threads": [], "messages": []}
    msg = HumanMessage(content=_format_open_threads_message(open_threads))
    return {"open_threads": open_threads, "messages": [msg]}


def profile_evidence_node(state: AgentState) -> dict:
    """Inject deterministic profile evidence as parseable human messages."""
    from agent.company_profile import collect_profile_evidence

    payloads = collect_profile_evidence(state["ticker"], include_metrics=False)
    if not payloads:
        return {"profile_payloads": [], "messages": []}
    messages = [
        HumanMessage(
            content=(
                "== COMPANY PROFILE EVIDENCE "
                "(deterministic retrieval, evidence.v1 envelopes follow) =="
            )
        )
    ]
    messages.extend(HumanMessage(content=payload) for payload in payloads)
    return {"profile_payloads": payloads, "messages": messages}


def _pop_company_profile(data: dict) -> dict | None:
    """Remove the separately validated profile section from synthesis output."""
    return data.pop("company_profile", None)


def _finalize_synthesis_profile(
    state: AgentState,
    profile_section: dict,
    model: str | None,
) -> dict | None:
    """Finalize and persist a synthesized profile without risking the brief."""
    try:
        from agent.company_profile import finalize_profile_from_synthesis
        from storage import company_profiles

        all_payloads = list(state.get("messages") or []) + list(
            state.get("profile_payloads") or []
        )
        profile = finalize_profile_from_synthesis(
            state["ticker"], profile_section, all_payloads, model
        )
        company_profiles.save_profile(state["ticker"], profile)
        return profile
    except Exception as exc:
        import sys

        print(
            f"[synthesis] company profile finalization failed: {exc}",
            file=sys.stderr,
        )
        return None


def create_graph(config: Optional[RunConfig] = None):
    cfg = config or default_config()
    llm = make_chat_model(cfg, max_tokens=AGENT_MAX_TOKENS)
    llm_with_tools = llm.bind_tools(TOOLS)

    def agent_node(state: AgentState) -> dict:
        system_block = build_system_message(cfg, SYSTEM_PROMPT)
        response = llm_with_tools.invoke([system_block] + state["messages"])
        return {"messages": [response]}

    def tool_node(state: AgentState) -> dict:
        last = state["messages"][-1]
        tool_calls = getattr(last, "tool_calls", None) or []
        if not tool_calls:
            return {"messages": [], "tool_round_count": state["tool_round_count"] + 1}
        with ThreadPoolExecutor(max_workers=min(8, len(tool_calls))) as ex:
            results = list(ex.map(_invoke_one, tool_calls))
        return {"messages": results, "tool_round_count": state["tool_round_count"] + 1}

    def partial_node(state: AgentState) -> dict:
        brief = _partial_brief(state, "Required evidence was unavailable or invalid.")
        return {
            "brief": brief,
            "brief_markdown": None,
            "synthesis_error": None,
            "coverage": brief["coverage"],
            "verification_report": brief["verification_report"],
        }

    def synthesis_node(state: AgentState) -> dict:
        try:
            llm_plain = make_chat_model(cfg, max_tokens=SYNTHESIS_MAX_TOKENS)
            # Main prompt — cached (ephemeral) on Anthropic. Keep this block stable
            # so the cache hit rate is preserved regardless of the chosen language.
            lang = state.get("language") or "English"
            extra_texts = [language_directive(lang)] if lang != "English" else None
            system_block = build_system_message(cfg, SYNTHESIS_STRUCTURED_PROMPT, extra_texts)
            synthesis_messages = [system_block] + state["messages"]
            # If cap was hit mid-round the last AIMessage may still carry tool_calls.
            # Anthropic rejects conversations where tool_use blocks have no matching
            # tool_result — insert stubs so the message history is valid.
            last_msg = synthesis_messages[-1]
            if getattr(last_msg, "tool_calls", None):
                stubs = [
                    ToolMessage(
                        tool_call_id=tc["id"],
                        name=tc["name"],
                        content=evidence_envelope(
                            tool=tc["name"], query=tc.get("args") or {}, status="ERROR",
                            message="Tool call interrupted at round cap.",
                            error_code="ROUND_CAP_INTERRUPTED",
                        ),
                    )
                    for tc in last_msg.tool_calls
                ]
                synthesis_messages = synthesis_messages + stubs
            if not isinstance(synthesis_messages[-1], HumanMessage):
                synthesis_messages = synthesis_messages + [
                    HumanMessage(content="Now produce the structured research brief as a JSON object.")
                ]
            chunks = []
            stop_reason = None
            for chunk in llm_plain.stream(synthesis_messages):
                metadata = getattr(chunk, "response_metadata", None) or {}
                stop_reason = (
                    metadata.get("stop_reason")
                    or metadata.get("finish_reason")
                    or stop_reason
                )
                text = _chunk_text(chunk.content)
                if text:
                    chunks.append(text)
            if stop_reason in ("max_tokens", "length"):
                raise SynthesisTruncatedError(
                    "Synthesis output was truncated by the token limit "
                    f"(max_tokens={SYNTHESIS_MAX_TOKENS}); the brief JSON was incomplete."
                )
            raw = "".join(chunks)
            clean = _extract_json(raw)
            data = json.loads(clean)
            profile_section = _pop_company_profile(data)
            brief = BriefOutput.model_validate(data)
            brief_dict = apply_reliability(
                brief.model_dump(), evidence_payloads=state.get("messages", [])
            )
            brief_dict = attach_edge_signals(brief_dict, state.get("edge_signals"))
            try:
                brief_dict["continuity_threads"] = apply_continuity_threads(
                    state["ticker"], brief_dict.get("filing_date") or "", brief_dict.get("continuity_threads") or []
                )
            except Exception as exc:
                import sys
                # Leave brief_dict["continuity_threads"] as the LLM's raw, unpersisted
                # output rather than letting a threads_db failure (e.g. "database is
                # locked" on the shared HF Space) propagate up to the blanket
                # `except Exception` below and discard an otherwise fully-synthesized,
                # good brief.
                print(f"[synthesis] continuity thread persistence failed: {exc}", file=sys.stderr)
            brief_dict["language"] = lang
            coverage = _coverage_report(state.get("messages", []))
            evidence_coverage = brief_dict.get("evidence_coverage") or {}
            if evidence_coverage.get("verified", 0) < 1:
                note = (
                    "Synthesis contained no claim that passed deterministic "
                    "evidence verification."
                )
                brief_dict["evidence_notes"] = (
                    list(brief_dict.get("evidence_notes") or []) + [note]
                )[:6]

            generated_at = datetime.now(timezone.utc).isoformat()
            evidence_dates = []
            for message in state.get("messages", []):
                envelope = parse_evidence_envelope(message)
                if not envelope or envelope.get("status") != "OK":
                    continue
                evidence_dates.extend(
                    record.get("ref", {}).get("as_of")
                    for record in envelope.get("records") or []
                    if record.get("ref", {}).get("as_of")
                )
            brief_dict["schema_version"] = "brief.v2"
            brief_dict["generated_at"] = generated_at
            brief_dict["model"] = cfg.model
            brief_dict["data_as_of"] = max(evidence_dates) if evidence_dates else brief_dict.get("filing_date", "")
            brief_dict["coverage"] = coverage
            if coverage.get("status") != "COMPLETE" or evidence_coverage.get("status") != "VERIFIED":
                brief_dict["status"] = "PARTIAL"
            market = brief_dict.get("market_expectations") or {}
            aligned_metrics = _market_expectations_aligned_metrics(
                state["ticker"], market.get("target_period")
            )
            brief_dict["display_policy"] = {
                "event_returns_aligned": (
                    market.get("event_aligned") is True
                    and market.get("event_comparison_allowed") is True
                ),
                # Coarse: "at least one metric aligned". The provider-flag
                # branch is payload-wide and names no metric at all, so it
                # can set this True while the per-metric list below is empty.
                "market_expectations_aligned": (
                    (
                        market.get("period_aligned") is True
                        and market.get("comparison_allowed") is True
                    )
                    or bool(aligned_metrics)
                ),
                # Per-metric, from the archive gate. Anything rendering an
                # actual-versus-consensus figure for a specific metric must
                # check membership here, not the boolean above.
                "market_expectations_aligned_metrics": aligned_metrics,
                "aggregate_reliability_meaningful": False,
            }
            if isinstance(profile_section, dict) and profile_section:
                brief_dict["company_profile"] = _finalize_synthesis_profile(
                    state, profile_section, cfg.model
                )
            else:
                brief_dict["company_profile"] = None

            # The press-style narrative is composed in a second call that runs
            # AFTER verification and sees only the facts that passed it, so it
            # cannot cite unverified material. It is strictly additive: any
            # failure here leaves narrative=None and the brief untouched.
            try:
                from agent.narrative import compose_narrative
                # Product and region results come from the filing's XBRL
                # segment dimensions, not from anything the agent retrieved,
                # so they are attached here rather than synthesised.
                try:
                    from analytics.segments import digest_lines
                    brief_dict["segment_lines"] = digest_lines(state["ticker"])
                except Exception as exc:
                    import sys
                    print(f"[narrative] segment lines unavailable: {exc}", file=sys.stderr)
                article, narrative_report, narrative_usage = compose_narrative(
                    brief_dict, cfg, lang
                )
                brief_dict["narrative"] = article
                # Kept whether or not the article survived: the tokens were
                # spent either way, and the run's logged cost must say so.
                brief_dict["narrative_usage"] = narrative_usage
                if article is None and narrative_report:
                    import sys
                    print(
                        "[narrative] no article: " + "; ".join(narrative_report),
                        file=sys.stderr,
                    )
            except Exception as exc:
                import sys
                brief_dict["narrative"] = None
                print(f"[narrative] skipped: {exc}", file=sys.stderr)

            return {
                "brief": brief_dict,
                "brief_markdown": None,
                "synthesis_error": None,
                "coverage": coverage,
                "verification_report": brief_dict.get("verification_report"),
            }
        except Exception as exc:
            import sys
            print(f"[synthesis error] {exc}", file=sys.stderr)
            if isinstance(exc, SynthesisTruncatedError):
                reason = str(exc)
            else:
                reason = f"Synthesis failed validation: {exc}"
            partial = _partial_brief(state, reason)
            return {
                "brief": partial,
                "brief_markdown": None,
                "synthesis_error": str(exc),
                "coverage": partial["coverage"],
                "verification_report": partial["verification_report"],
            }

    builder = StateGraph(AgentState)
    builder.add_node("signals", signals_node)
    builder.add_node("profile_evidence", profile_evidence_node)
    builder.add_node("continuity", continuity_node)
    builder.add_node("agent", agent_node)
    builder.add_node("tools", tool_node)
    builder.add_node("nudge", nudge_node)
    builder.add_node("synthesis", synthesis_node)
    builder.add_node("partial", partial_node)
    builder.set_entry_point("signals")
    builder.add_edge("signals", "profile_evidence")
    builder.add_edge("profile_evidence", "continuity")
    builder.add_edge("continuity", "agent")
    builder.add_conditional_edges(
        "agent",
        should_continue,
        {"tools": "tools", "nudge": "nudge", "synthesis": "synthesis", "partial": "partial"},
    )
    builder.add_edge("tools", "agent")
    builder.add_edge("nudge", "agent")
    builder.add_edge("synthesis", END)
    builder.add_edge("partial", END)
    return builder.compile()


def run_brief(ticker: str, language: str = "English", config: Optional[RunConfig] = None) -> Optional[dict]:
    graph = create_graph(config)
    final = graph.invoke({
        "ticker": ticker.upper(),
        "messages": [HumanMessage(content=f"Generate a research brief for {ticker.upper()}.")],
        "tool_round_count": 0,
        "nudge_fired": False,
        "edge_signals": None,
        "profile_payloads": None,
        "open_threads": None,
        "language": language,
        "brief": None,
        "brief_markdown": None,
        "synthesis_error": None,
        "coverage": None,
        "verification_report": None,
    })
    return final.get("brief")