Source code for reminix.runtime.types

"""
Reminix Runtime Types

Type definitions for building agents that conform to the Reminix API contract.
"""

from typing import (
    Any,
    AsyncGenerator,
    Callable,
    Literal,
    TypedDict,
    Union,
)


# =============================================================================
# Chat Message Types (OpenAI-compatible)
# =============================================================================


class ToolCallFunction(TypedDict):
    """Function details within a tool call."""

    name: str
    arguments: str  # JSON string


class ToolCall(TypedDict):
    """Tool call made by the assistant."""

    id: str
    type: Literal["function"]
    function: ToolCallFunction




class ChatMessage(TypedDict, total=False):
    """
    Chat message in OpenAI-compatible format.

    Supports system, user, assistant, and tool roles.
    """

    role: Literal["system", "user", "assistant", "tool"]
    content: Union[str, list[Any], dict[str, Any], None]
    name: str  # Optional: tool name (required when role is "tool")
    tool_call_id: str  # Optional: for tool role





class AssistantMessage(TypedDict, total=False):
    """Assistant message response."""

    role: Literal["assistant"]
    content: Union[str, list[Any], None]
    tool_calls: list[ToolCall]



# =============================================================================
# Request Types
# =============================================================================


class InvokeRequest(TypedDict):
    """Request body for invoke endpoint."""

    input: dict[str, Any]
    stream: bool


class ChatRequest(TypedDict):
    """Request body for chat endpoint."""

    messages: list[ChatMessage]
    stream: bool


# =============================================================================
# Response Types
# =============================================================================


class InvokeResponse(TypedDict):
    """Response for non-streaming invoke."""

    output: Any


class ChatResponse(TypedDict):
    """Response for non-streaming chat."""

    message: AssistantMessage


class StreamChunk(TypedDict):
    """Single chunk in a streaming response."""

    chunk: str


# =============================================================================
# Context Types
# =============================================================================




class Context(TypedDict, total=False):
    """
    Request context passed to handlers.

    Contains information about the current request, conversation, and user.
    """

    conversation_id: str | None
    user_id: str | None
    custom: dict[str, Any]



# =============================================================================
# Handler Types
# =============================================================================

# Type for invoke handler return value
InvokeResult = Union[InvokeResponse, AsyncGenerator[StreamChunk, None]]

# Type for chat handler return value
ChatResult = Union[ChatResponse, AsyncGenerator[StreamChunk, None]]

# Type for invoke handler function (with optional context)
InvokeHandler = Callable[..., InvokeResult]

# Type for chat handler function (with optional context)
ChatHandler = Callable[..., ChatResult]


# =============================================================================
# Health Check Types
# =============================================================================


class AgentHealth(TypedDict):
    """Health status for a single agent."""

    name: str
    invoke: bool
    chat: bool


class HealthResponse(TypedDict):
    """Response for health check endpoint."""

    status: Literal["healthy"]
    agents: list[str]


# =============================================================================
# Discovery Types
# =============================================================================


class AgentInfo(TypedDict):
    """Agent information for discovery endpoint."""

    name: str
    invoke: bool
    chat: bool
    metadata: dict[str, Any]


class RuntimeInfo(TypedDict):
    """Runtime information for discovery endpoint."""

    version: str
    language: Literal["python"]
    framework: Literal["fastapi"]


class DiscoverResponse(TypedDict):
    """Response for /_discover endpoint."""

    runtime: RuntimeInfo
    agents: list[AgentInfo]