app/models.py

"""
Pydantic models for request/response schemas.
These match the exact API specification from the assignment.
"""

from pydantic import BaseModel, Field
from typing import Optional


class Message(BaseModel):
    """A single message in the conversation history."""
    role: str = Field(..., description="Either 'user' or 'assistant'")
    content: str = Field(..., description="The message text")


class ChatRequest(BaseModel):
    """
    Incoming POST /chat request.
    Stateless: carries full conversation history every call.
    """
    messages: list[Message] = Field(
        ...,
        description="Full conversation history, alternating user/assistant",
        min_length=1,
    )


class Recommendation(BaseModel):
    """A single assessment recommendation."""
    name: str = Field(..., description="Assessment name from the SHL catalog")
    url: str = Field(..., description="Catalog URL for the assessment")
    test_type: str = Field(
        ...,
        description="Single-letter test type code(s): K, P, S, B, C, A, D, E"
    )


class ChatResponse(BaseModel):
    """
    Outgoing POST /chat response.
    Schema is non-negotiable — deviating breaks the automated evaluator.
    """
    reply: str = Field(..., description="Agent's natural language response")
    recommendations: list[Recommendation] = Field(
        default_factory=list,
        description="Empty when still gathering context or refusing. 1-10 items when recommending.",
    )
    end_of_conversation: bool = Field(
        default=False,
        description="True only when the agent considers the task complete",
    )


class HealthResponse(BaseModel):
    """GET /health response."""
    status: str = "ok"