openai-agents 0.1.0__py3-none-any.whl → 0.2.1__py3-none-any.whl

agents/realtime/items.py

@@ -0,0 +1,184 @@
+from __future__ import annotations
+
+from typing import Annotated, Literal, Union
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class InputText(BaseModel):
+    """Text input content for realtime messages."""
+
+    type: Literal["input_text"] = "input_text"
+    """The type identifier for text input."""
+
+    text: str | None = None
+    """The text content."""
+
+    # Allow extra data
+    model_config = ConfigDict(extra="allow")
+
+
+class InputAudio(BaseModel):
+    """Audio input content for realtime messages."""
+
+    type: Literal["input_audio"] = "input_audio"
+    """The type identifier for audio input."""
+
+    audio: str | None = None
+    """The base64-encoded audio data."""
+
+    transcript: str | None = None
+    """The transcript of the audio, if available."""
+
+    # Allow extra data
+    model_config = ConfigDict(extra="allow")
+
+
+class AssistantText(BaseModel):
+    """Text content from the assistant in realtime responses."""
+
+    type: Literal["text"] = "text"
+    """The type identifier for text content."""
+
+    text: str | None = None
+    """The text content from the assistant."""
+
+    # Allow extra data
+    model_config = ConfigDict(extra="allow")
+
+
+class AssistantAudio(BaseModel):
+    """Audio content from the assistant in realtime responses."""
+
+    type: Literal["audio"] = "audio"
+    """The type identifier for audio content."""
+
+    audio: str | None = None
+    """The base64-encoded audio data from the assistant."""
+
+    transcript: str | None = None
+    """The transcript of the audio response."""
+
+    # Allow extra data
+    model_config = ConfigDict(extra="allow")
+
+
+class SystemMessageItem(BaseModel):
+    """A system message item in realtime conversations."""
+
+    item_id: str
+    """Unique identifier for this message item."""
+
+    previous_item_id: str | None = None
+    """ID of the previous item in the conversation."""
+
+    type: Literal["message"] = "message"
+    """The type identifier for message items."""
+
+    role: Literal["system"] = "system"
+    """The role identifier for system messages."""
+
+    content: list[InputText]
+    """List of text content for the system message."""
+
+    # Allow extra data
+    model_config = ConfigDict(extra="allow")
+
+
+class UserMessageItem(BaseModel):
+    """A user message item in realtime conversations."""
+
+    item_id: str
+    """Unique identifier for this message item."""
+
+    previous_item_id: str | None = None
+    """ID of the previous item in the conversation."""
+
+    type: Literal["message"] = "message"
+    """The type identifier for message items."""
+
+    role: Literal["user"] = "user"
+    """The role identifier for user messages."""
+
+    content: list[Annotated[InputText | InputAudio, Field(discriminator="type")]]
+    """List of content items, can be text or audio."""
+
+    # Allow extra data
+    model_config = ConfigDict(extra="allow")
+
+
+class AssistantMessageItem(BaseModel):
+    """An assistant message item in realtime conversations."""
+
+    item_id: str
+    """Unique identifier for this message item."""
+
+    previous_item_id: str | None = None
+    """ID of the previous item in the conversation."""
+
+    type: Literal["message"] = "message"
+    """The type identifier for message items."""
+
+    role: Literal["assistant"] = "assistant"
+    """The role identifier for assistant messages."""
+
+    status: Literal["in_progress", "completed", "incomplete"] | None = None
+    """The status of the assistant's response."""
+
+    content: list[Annotated[AssistantText | AssistantAudio, Field(discriminator="type")]]
+    """List of content items from the assistant, can be text or audio."""
+
+    # Allow extra data
+    model_config = ConfigDict(extra="allow")
+
+
+RealtimeMessageItem = Annotated[
+    Union[SystemMessageItem, UserMessageItem, AssistantMessageItem],
+    Field(discriminator="role"),
+]
+"""A message item that can be from system, user, or assistant."""
+
+
+class RealtimeToolCallItem(BaseModel):
+    """A tool call item in realtime conversations."""
+
+    item_id: str
+    """Unique identifier for this tool call item."""
+
+    previous_item_id: str | None = None
+    """ID of the previous item in the conversation."""
+
+    call_id: str | None
+    """The call ID for this tool invocation."""
+
+    type: Literal["function_call"] = "function_call"
+    """The type identifier for function call items."""
+
+    status: Literal["in_progress", "completed"]
+    """The status of the tool call execution."""
+
+    arguments: str
+    """The JSON string arguments passed to the tool."""
+
+    name: str
+    """The name of the tool being called."""
+
+    output: str | None = None
+    """The output result from the tool execution."""
+
+    # Allow extra data
+    model_config = ConfigDict(extra="allow")
+
+
+RealtimeItem = Union[RealtimeMessageItem, RealtimeToolCallItem]
+"""A realtime item that can be a message or tool call."""
+
+
+class RealtimeResponse(BaseModel):
+    """A response from the realtime model."""
+
+    id: str
+    """Unique identifier for this response."""
+
+    output: list[RealtimeMessageItem]
+    """List of message items in the response."""

agents/realtime/model.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import abc
+from typing import Callable
+
+from typing_extensions import NotRequired, TypedDict
+
+from ..util._types import MaybeAwaitable
+from .config import (
+    RealtimeSessionModelSettings,
+)
+from .model_events import RealtimeModelEvent
+from .model_inputs import RealtimeModelSendEvent
+
+
+class RealtimeModelListener(abc.ABC):
+    """A listener for realtime transport events."""
+
+    @abc.abstractmethod
+    async def on_event(self, event: RealtimeModelEvent) -> None:
+        """Called when an event is emitted by the realtime transport."""
+        pass
+
+
+class RealtimeModelConfig(TypedDict):
+    """Options for connecting to a realtime model."""
+
+    api_key: NotRequired[str | Callable[[], MaybeAwaitable[str]]]
+    """The API key (or function that returns a key) to use when connecting. If unset, the model will
+    try to use a sane default. For example, the OpenAI Realtime model will try to use the
+    `OPENAI_API_KEY`  environment variable.
+    """
+
+    url: NotRequired[str]
+    """The URL to use when connecting. If unset, the model will use a sane default. For example,
+    the OpenAI Realtime model will use the default OpenAI WebSocket URL.
+    """
+
+    initial_model_settings: NotRequired[RealtimeSessionModelSettings]
+    """The initial model settings to use when connecting."""
+
+
+class RealtimeModel(abc.ABC):
+    """Interface for connecting to a realtime model and sending/receiving events."""
+
+    @abc.abstractmethod
+    async def connect(self, options: RealtimeModelConfig) -> None:
+        """Establish a connection to the model and keep it alive."""
+        pass
+
+    @abc.abstractmethod
+    def add_listener(self, listener: RealtimeModelListener) -> None:
+        """Add a listener to the model."""
+        pass
+
+    @abc.abstractmethod
+    def remove_listener(self, listener: RealtimeModelListener) -> None:
+        """Remove a listener from the model."""
+        pass
+
+    @abc.abstractmethod
+    async def send_event(self, event: RealtimeModelSendEvent) -> None:
+        """Send an event to the model."""
+        pass
+
+    @abc.abstractmethod
+    async def close(self) -> None:
+        """Close the session."""
+        pass

agents/realtime/model_events.py

@@ -0,0 +1,159 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Literal, Union
+
+from typing_extensions import TypeAlias
+
+from .items import RealtimeItem
+
+RealtimeConnectionStatus: TypeAlias = Literal["connecting", "connected", "disconnected"]
+
+
+@dataclass
+class RealtimeModelErrorEvent:
+    """Represents a transport‑layer error."""
+
+    error: Any
+
+    type: Literal["error"] = "error"
+
+
+@dataclass
+class RealtimeModelToolCallEvent:
+    """Model attempted a tool/function call."""
+
+    name: str
+    call_id: str
+    arguments: str
+
+    id: str | None = None
+    previous_item_id: str | None = None
+
+    type: Literal["function_call"] = "function_call"
+
+
+@dataclass
+class RealtimeModelAudioEvent:
+    """Raw audio bytes emitted by the model."""
+
+    data: bytes
+    response_id: str
+
+    type: Literal["audio"] = "audio"
+
+
+@dataclass
+class RealtimeModelAudioInterruptedEvent:
+    """Audio interrupted."""
+
+    type: Literal["audio_interrupted"] = "audio_interrupted"
+
+
+@dataclass
+class RealtimeModelAudioDoneEvent:
+    """Audio done."""
+
+    type: Literal["audio_done"] = "audio_done"
+
+
+@dataclass
+class RealtimeModelInputAudioTranscriptionCompletedEvent:
+    """Input audio transcription completed."""
+
+    item_id: str
+    transcript: str
+
+    type: Literal["input_audio_transcription_completed"] = "input_audio_transcription_completed"
+
+
+@dataclass
+class RealtimeModelTranscriptDeltaEvent:
+    """Partial transcript update."""
+
+    item_id: str
+    delta: str
+    response_id: str
+
+    type: Literal["transcript_delta"] = "transcript_delta"
+
+
+@dataclass
+class RealtimeModelItemUpdatedEvent:
+    """Item added to the history or updated."""
+
+    item: RealtimeItem
+
+    type: Literal["item_updated"] = "item_updated"
+
+
+@dataclass
+class RealtimeModelItemDeletedEvent:
+    """Item deleted from the history."""
+
+    item_id: str
+
+    type: Literal["item_deleted"] = "item_deleted"
+
+
+@dataclass
+class RealtimeModelConnectionStatusEvent:
+    """Connection status changed."""
+
+    status: RealtimeConnectionStatus
+
+    type: Literal["connection_status"] = "connection_status"
+
+
+@dataclass
+class RealtimeModelTurnStartedEvent:
+    """Triggered when the model starts generating a response for a turn."""
+
+    type: Literal["turn_started"] = "turn_started"
+
+
+@dataclass
+class RealtimeModelTurnEndedEvent:
+    """Triggered when the model finishes generating a response for a turn."""
+
+    type: Literal["turn_ended"] = "turn_ended"
+
+
+@dataclass
+class RealtimeModelOtherEvent:
+    """Used as a catchall for vendor-specific events."""
+
+    data: Any
+
+    type: Literal["other"] = "other"
+
+
+@dataclass
+class RealtimeModelExceptionEvent:
+    """Exception occurred during model operation."""
+
+    exception: Exception
+    context: str | None = None
+
+    type: Literal["exception"] = "exception"
+
+
+# TODO (rm) Add usage events
+
+
+RealtimeModelEvent: TypeAlias = Union[
+    RealtimeModelErrorEvent,
+    RealtimeModelToolCallEvent,
+    RealtimeModelAudioEvent,
+    RealtimeModelAudioInterruptedEvent,
+    RealtimeModelAudioDoneEvent,
+    RealtimeModelInputAudioTranscriptionCompletedEvent,
+    RealtimeModelTranscriptDeltaEvent,
+    RealtimeModelItemUpdatedEvent,
+    RealtimeModelItemDeletedEvent,
+    RealtimeModelConnectionStatusEvent,
+    RealtimeModelTurnStartedEvent,
+    RealtimeModelTurnEndedEvent,
+    RealtimeModelOtherEvent,
+    RealtimeModelExceptionEvent,
+]

agents/realtime/model_inputs.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Literal, Union
+
+from typing_extensions import NotRequired, TypeAlias, TypedDict
+
+from .config import RealtimeSessionModelSettings
+from .model_events import RealtimeModelToolCallEvent
+
+
+class RealtimeModelRawClientMessage(TypedDict):
+    """A raw message to be sent to the model."""
+
+    type: str  # explicitly required
+    other_data: NotRequired[dict[str, Any]]
+    """Merged into the message body."""
+
+
+class RealtimeModelInputTextContent(TypedDict):
+    """A piece of text to be sent to the model."""
+
+    type: Literal["input_text"]
+    text: str
+
+
+class RealtimeModelUserInputMessage(TypedDict):
+    """A message to be sent to the model."""
+
+    type: Literal["message"]
+    role: Literal["user"]
+    content: list[RealtimeModelInputTextContent]
+
+
+RealtimeModelUserInput: TypeAlias = Union[str, RealtimeModelUserInputMessage]
+"""A user input to be sent to the model."""
+
+
+# Model messages
+
+
+@dataclass
+class RealtimeModelSendRawMessage:
+    """Send a raw message to the model."""
+
+    message: RealtimeModelRawClientMessage
+    """The message to send."""
+
+
+@dataclass
+class RealtimeModelSendUserInput:
+    """Send a user input to the model."""
+
+    user_input: RealtimeModelUserInput
+    """The user input to send."""
+
+
+@dataclass
+class RealtimeModelSendAudio:
+    """Send audio to the model."""
+
+    audio: bytes
+    commit: bool = False
+
+
+@dataclass
+class RealtimeModelSendToolOutput:
+    """Send tool output to the model."""
+
+    tool_call: RealtimeModelToolCallEvent
+    """The tool call to send."""
+
+    output: str
+    """The output to send."""
+
+    start_response: bool
+    """Whether to start a response."""
+
+
+@dataclass
+class RealtimeModelSendInterrupt:
+    """Send an interrupt to the model."""
+
+
+@dataclass
+class RealtimeModelSendSessionUpdate:
+    """Send a session update to the model."""
+
+    session_settings: RealtimeSessionModelSettings
+    """The updated session settings to send."""
+
+
+RealtimeModelSendEvent: TypeAlias = Union[
+    RealtimeModelSendRawMessage,
+    RealtimeModelSendUserInput,
+    RealtimeModelSendAudio,
+    RealtimeModelSendToolOutput,
+    RealtimeModelSendInterrupt,
+    RealtimeModelSendSessionUpdate,
+]