Source code for taimoe.platform.types.agent

"""Agent data types.

Mirrors the backend ``AgentCreate`` / ``AgentResponse`` / ``BoundKBOut``
schemas in ``backend/app/api/v1/schemas/resources.py`` and
``backend/app/api/v1/endpoints/agent_knowledge_bases.py``.

Collection fields use ``tuple[str, ...]`` (not ``list[str]``) to keep
frozen Pydantic models truly immutable. Callers that need a mutable
list can do ``list(agent.tools)`` at the call site.
"""

from __future__ import annotations

from datetime import datetime
from typing import Any

from pydantic import BaseModel, ConfigDict, Field




class AgentCreatePayload(BaseModel):
    """Typed payload for creating an agent.

    Mirrors the backend ``AgentCreate`` Pydantic schema; SDK callers get
    IDE completion and typo protection instead of ``**kwargs: Any``.

    **Serialization contract** — the resources layer dumps this with
    ``model_dump(exclude_none=True)`` so optional fields left as ``None``
    aren't sent on the wire; backend defaults take over. If you set a
    field to its falsy value explicitly (e.g. ``tools=()``), it *will*
    be sent, since the value isn't ``None``.
    """
    model_config = ConfigDict(frozen=True)

    name: str
    model_alias: str
    description: str | None = None
    runtime_type: str = "google_agent_engine"
    is_active: bool = True
    instruction: str | None = None
    runtime_agent_id: str | None = None
    runtime_id: str | None = None
    tools: tuple[str, ...] | None = None
    generation_config: dict[str, Any] | None = None
    tpm_limit: int = 0
    rpm_limit: int = 0





class Agent(BaseModel):
    """Agent representation as returned by the backend."""
    model_config = ConfigDict(frozen=True)

    id: str
    name: str
    display_name: str
    model_alias: str
    runtime_type: str
    is_active: bool
    description: str | None = None
    instruction: str | None = None
    runtime_agent_id: str | None = None
    tools: tuple[str, ...] = ()
    generation_config: dict[str, Any] = Field(default_factory=dict)
    tpm_limit: int = 0
    rpm_limit: int = 0
    create_time: datetime
    update_time: datetime | None = None





class AgentBinding(BaseModel):
    """Result of binding a knowledge base to an agent."""
    model_config = ConfigDict(frozen=True)

    kb_id: str
    agent_id: str
    slug: str
    name: str
    source_type: str
    display_name: str | None = None
    grounding_source: str | None = None
    is_active: bool
    bound_at: datetime