src/api/dto/tools.py

"""DTOs for ``/tools/*`` endpoints — the read-only registry view.

Backs the About page and the Add Book / Search advanced-models pickers.
The frontend trusts the registry's ``verified`` + ``last_updated`` flags
to render stale-pricing warnings.
"""

from __future__ import annotations

from enum import Enum

from .common import ApiModel


class ToolStatusEnum(str, Enum):
    """Whether the tool actually runs in production right now."""

    active = "active"
    stubbed = "stubbed"
    planned = "planned"


class ToolCategoryEnum(str, Enum):
    """High-level grouping for the registry picker."""

    llm = "llm"
    embedding = "embedding"
    reranker = "reranker"
    vector_db = "vector_db"
    ocr = "ocr"
    pdf = "pdf"
    ui = "ui"
    misc = "misc"


class ToolPricingDTO(ApiModel):
    """Pricing block as it lives in ``tools_registry.yaml``.

    ``verified`` is hand-flipped after a maintainer confirmed the
    numbers against the provider's billing page. ``last_updated`` drives
    the stale-pricing chip on the dashboard (>90 days → stale).
    """

    input_per_million_usd: float | None = None
    output_per_million_usd: float | None = None
    image_input_tokens_per_image: int | None = None
    per_request_usd: float | None = None
    last_updated: str | None = None
    verified: bool


class ToolDTO(ApiModel):
    """One tool from ``tools_registry.yaml``."""

    name: str
    category: ToolCategoryEnum
    status: ToolStatusEnum
    used_by: list[str]
    compatible_with: list[str]
    source_file: str | None = None
    provider: str | None = None
    pricing: ToolPricingDTO | None = None
    notes: str
    # Task A1b: for llm tools, whether the provider's API key is resolvable
    # (store or env) so the model is actually callable. ``None`` for non-llm
    # tools or llm tools whose provider isn't one of the 5 managed providers.
    # The FE picker uses this to disable unconfigured-provider models. Never
    # exposes the key value — only a boolean.
    active: bool | None = None