api/models/responses.py

"""Response models for KGraph-MCP API."""

from datetime import datetime

from pydantic import BaseModel, Field


class HealthResponse(BaseModel):
    """Health check response model."""

    status: str = Field(description="Service status")
    version: str = Field(description="Application version")
    environment: str = Field(description="Environment name")
    timestamp: datetime = Field(description="Health check timestamp")


class TaskResponse(BaseModel):
    """Task response model."""

    id: int = Field(description="Task ID")
    title: str = Field(description="Task title")
    description: str = Field(description="Task description")
    status: str = Field(description="Task status")
    dependencies: list[int] = Field(description="Task dependencies")


class ToolSuggestionResponse(BaseModel):
    """Tool suggestion response model."""

    tool_id: str = Field(description="Tool identifier")
    name: str = Field(description="Tool name")
    description: str = Field(description="Tool description")
    tags: list[str] = Field(description="Tool tags")
    invocation_command_stub: str = Field(description="Tool invocation command")


class PromptInfo(BaseModel):
    """Prompt information within a planned step."""

    prompt_id: str = Field(description="Prompt identifier")
    name: str = Field(description="Prompt name")
    description: str = Field(description="Prompt description")
    template_string: str = Field(description="Prompt template with variables")
    difficulty_level: str = Field(description="Prompt difficulty level")
    input_variables: list[str] = Field(description="Required input variables")


class PlannedStepResponse(BaseModel):
    """Planned step response model combining tool and prompt."""

    tool: ToolSuggestionResponse = Field(description="Selected tool information")
    prompt: PromptInfo = Field(description="Selected prompt information")
    relevance_score: float | None = Field(
        description="Relevance score for this combination"
    )
    summary: str = Field(description="Human-readable summary of this planned step")


class PlanResponse(BaseModel):
    """Plan generation response model."""

    query: str = Field(description="Original user query")
    planned_steps: list[PlannedStepResponse] = Field(
        description="List of planned steps"
    )
    total_steps: int = Field(description="Total number of planned steps")


class ErrorResponse(BaseModel):
    """Error response model."""

    error: str = Field(description="Error message")
    detail: str | None = Field(default=None, description="Error details")
    error_code: str | None = Field(default=None, description="Error code")