feat: structured output for Social Media Analyst (#796)

[HrushiYadav]

Fixes #796.

social_media_analyst outputs vary wildly between runs - some include a numeric score, some only a band, some neither. Downstream agents and dashboards either degrade silently or maintain growing piles of fallback regexes.

Added SentimentReport schema (score, band, confidence, narrative) and render_sentiment_report to schemas.py, following the same pattern used for the Trader, Portfolio Manager, and Research Manager in #434. Since the analyst uses tool calls for its research phase, structured output is applied in a separate extraction call after the tool loop finishes rather than on the tool-calling chain directly. Falls back to free-text if the provider does not support structured output.

8 new unit tests covering schema validation, render output, structured path, and fallback. All 19 tests pass.

[gemini-code-assist]

Code Review

This pull request introduces structured sentiment reporting for the Social Media Analyst, including new Pydantic schemas, rendering utilities, and comprehensive unit tests. The analyst now performs a secondary extraction step to pin deterministic fields like sentiment score and confidence while preserving the full research narrative. Feedback focuses on removing redundant type checks in the analyst node, clarifying overlapping numeric ranges and enum distinctions in the schema descriptions, and improving Markdown formatting in the rendered output.

[gemini-code-assist]

The check for hasattr(report, "content") and the accompanying comment are redundant. The invoke_structured_or_freetext utility function (defined in tradingagents/agents/utils/structured.py) is already typed to return a str and explicitly returns the .content attribute when falling back to the plain LLM. Thus, report will always be a string at this point, and the comment about it returning an AIMessage is incorrect.

Suggested change

	# invoke_structured_or_freetext falls back to plain llm.invoke when
	# structured output fails; in that case it returns an AIMessage, not a str.
	if hasattr(report, "content"):
	report = report.content
	# invoke_structured_or_freetext already returns the string content
	# from either the rendered structured output or the fallback response.

[HrushiYadav]

Fixed in 1ec8997 - removed the redundant check and comment.

[gemini-code-assist]

The description for overall_band contains overlapping numeric ranges (e.g., 7.0 is in both Bullish and Mildly Bullish) and groups Neutral/Mixed together even though they are separate members in the SentimentBand enum. Providing non-overlapping ranges and a clear distinction between 'Neutral' and 'Mixed' will help the LLM select the correct enum value more reliably.

'Neutral' typically implies a lack of strong signal or a flat outlook, while 'Mixed' implies high-volume but conflicting signals.

    overall_band: SentimentBand = Field(
        description=(
            "Categorical sentiment label. Pick the band that best matches the "
            "overall_score: Bullish (7.1-10), Mildly Bullish (5.6-7.0), Neutral "
            "(4.5-5.5, flat outlook), Mixed (4.5-5.5, conflicting signals), "
            "Mildly Bearish (3.0-4.4), Bearish (0-2.9)."
        ),
    )

[HrushiYadav]

Fixed in 1ec8997 - non-overlapping ranges applied and Neutral vs Mixed distinction clarified.

[gemini-code-assist]

The current implementation of render_sentiment_report results in only a single newline between the structured header and the narrative text. In Markdown, a blank line (two newlines) is standard for separating blocks of text. Adding an additional empty string to the join list will ensure proper spacing for downstream display.

Suggested change

	header = "\n".join([
	f"**Overall Sentiment:** **{report.overall_band.value}** "
	f"(Score: {report.overall_score:.1f}/10, Confidence: {report.confidence})",
	"",
	])
	header = "\n".join([
	f"**Overall Sentiment:** **{report.overall_band.value}** "
	f"(Score: {report.overall_score:.1f}/10, Confidence: {report.confidence})",
	"",
	"",
	])

[HrushiYadav]

Fixed in 1ec8997 - added the extra blank line for proper markdown block separation.