"""Structured output contract for a turn's response.

The live model fills these specific fields rather than writing free prose — this is what
keeps answers close to the reference script's shape (headline / next_moves / suggested
wording / citations) instead of drifting into open-ended paragraphs that are hard to compare
turn-by-turn against a fixed script.
"""
from typing import Optional

from pydantic import BaseModel, Field


class TurnResponse(BaseModel):
    headline: str = Field(
        description="One sentence summarizing the situation or decision for this turn.")
    next_moves: list[str] = Field(
        default_factory=list,
        description="Concrete next actions for the representative, as short imperative bullets.")
    suggested_wording: Optional[str] = Field(
        default=None,
        description="Exact wording the representative can say to the customer, only when "
                    "this turn calls for a direct quote (e.g. asking a sensitive question).")
    citations: list[str] = Field(
        default_factory=list,
        description="Article ids from the provided source material that this turn's "
                    "guidance is grounded in. Never cite an id that wasn't provided.")

    @classmethod
    def tool_schema(cls):
        schema = cls.model_json_schema()
        return {
            "type": "function",
            "function": {
                "name": "submit_turn_response",
                "description": "Submit this turn's structured response to the representative.",
                "parameters": schema,
            },
        }