"""Tool-related schema types for Fluxibly.

Defines ToolCall, ToolResult, and Citation models used across
LLM responses and agent tool execution.
"""

from __future__ import annotations

from typing import Any

from pydantic import BaseModel, Field


class ToolCall(BaseModel):
    """A tool/function call from the LLM."""

    id: str = Field(..., description="Unique call ID")
    name: str = Field(..., description="Function/tool name")
    arguments: dict[str, Any] | str = Field(
        ..., description="Arguments (dict if parsed, str if raw JSON)"
    )
    type: str = Field(
        default="function",
        description="Tool type: 'function', 'mcp', 'web_search', etc.",
    )


class ToolResult(BaseModel):
    """Result from a tool execution."""

    tool_call_id: str = Field(..., description="References ToolCall.id")
    content: str | dict[str, Any] = Field(..., description="Tool output")
    is_error: bool = Field(
        default=False, description="Whether the result is an error"
    )


class Citation(BaseModel):
    """A citation or annotation in the output."""

    type: str = Field(
        ..., description="Citation type: 'url', 'file', 'document', etc."
    )
    text: str | None = Field(default=None, description="Cited text")
    url: str | None = Field(default=None, description="Source URL")
    title: str | None = Field(default=None, description="Source title")
    start_index: int | None = Field(
        default=None, description="Start position in output_text"
    )
    end_index: int | None = Field(
        default=None, description="End position in output_text"
    )
