"""Template for a Sentinel endpoint structured-I/O model.

Upload this file (edited) in the Sentinel web UI under Endpoints → Structured I/O.
Sentinel scans it for `pydantic.BaseModel` subclasses and lets you pick:

  - an OUTPUT model — the agent's answer is coerced into this shape and returned as
    structured JSON (via the model's `with_structured_output`), and/or
  - an INPUT model — the incoming request body is validated against it, and you can
    reference its fields in the endpoint's prompt template as %field_name%.

Rules:
  - Define plain pydantic v2 `BaseModel` subclasses. No LLM or client code is needed —
    Sentinel wires the model to the endpoint's agent for you (delete the example if
    you paste one in).
  - Give every field a type and a `Field(description=...)`. The description is what
    guides the model when it produces structured output, so make it specific.
  - Nested models, `Literal[...]` enums, `list[...]`, and defaults are all supported.
"""
from __future__ import annotations

from typing import Literal

from pydantic import BaseModel, Field


class RequestInput(BaseModel):
    """INPUT model — validates + shapes the endpoint's incoming request.

    Reference these fields in the endpoint's prompt template as %topic%, %tone%,
    %max_points%."""

    topic: str = Field(description="What the request is about")
    tone: Literal["formal", "casual"] = Field(
        default="casual", description="Desired tone of the response"
    )
    max_points: int = Field(default=5, description="How many key points to return")


class KeyPoint(BaseModel):
    """A single structured item in the response (nested-model example)."""

    title: str = Field(description="Short label for the point")
    detail: str = Field(description="One or two sentences explaining it")


class StructuredAnswer(BaseModel):
    """OUTPUT model — the agent's answer is coerced into this shape."""

    summary: str = Field(description="A one-paragraph summary of the answer")
    points: list[KeyPoint] = Field(
        default_factory=list, description="The key points, most important first"
    )
    confidence: int = Field(
        description="The model's confidence in the answer, from 1 (low) to 10 (high)"
    )