openai-sdk-helpers 0.0.5__py3-none-any.whl → 0.0.7__py3-none-any.whl

openai_sdk_helpers/response/messages.py

@@ -0,0 +1,211 @@
+"""Message containers for shared OpenAI responses."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Dict, List, Union, cast
+
+from openai.types.responses.response_function_tool_call import ResponseFunctionToolCall
+from openai.types.responses.response_function_tool_call_param import (
+    ResponseFunctionToolCallParam,
+)
+from openai.types.responses.response_input_message_content_list_param import (
+    ResponseInputMessageContentListParam,
+)
+from openai.types.responses.response_input_param import (
+    FunctionCallOutput,
+    ResponseInputItemParam,
+)
+from openai.types.responses.response_output_message import ResponseOutputMessage
+
+from ..utils import JSONSerializable
+from .tool_call import ResponseToolCall
+
+
+@dataclass
+class ResponseMessage(JSONSerializable):
+    """Single message exchanged with the OpenAI client.
+
+    Methods
+    -------
+    to_openai_format()
+        Return the payload in the format expected by the OpenAI client.
+    """
+
+    role: str  # "user", "assistant", "tool", etc.
+    content: (
+        ResponseInputItemParam
+        | ResponseOutputMessage
+        | ResponseFunctionToolCallParam
+        | FunctionCallOutput
+        | ResponseInputMessageContentListParam
+    )
+    timestamp: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+    metadata: Dict[str, Union[str, float, bool]] = field(default_factory=dict)
+
+    def to_openai_format(
+        self,
+    ) -> (
+        ResponseInputItemParam
+        | ResponseOutputMessage
+        | ResponseFunctionToolCallParam
+        | FunctionCallOutput
+        | ResponseInputMessageContentListParam
+    ):
+        """Return the message in the format expected by the OpenAI client.
+
+        Returns
+        -------
+        ResponseInputItemParam | ResponseOutputMessage | ResponseFunctionToolCallParam | FunctionCallOutput | ResponseInputMessageContentListParam
+            Stored message content in OpenAI format.
+        """
+        return self.content
+
+
+@dataclass
+class ResponseMessages(JSONSerializable):
+    """Represent a collection of messages in a response.
+
+    This dataclass encapsulates user inputs and assistant outputs during an
+    OpenAI API interaction.
+
+    Methods
+    -------
+    add_system_message(content, **metadata)
+        Append a system message to the conversation.
+    add_user_message(input_content, **metadata)
+        Append a user message to the conversation.
+    add_assistant_message(content, metadata)
+        Append an assistant message to the conversation.
+    add_tool_message(content, output, **metadata)
+        Record a tool call and its output.
+    to_openai_payload()
+        Convert stored messages to the OpenAI input payload.
+    """
+
+    messages: List[ResponseMessage] = field(default_factory=list)
+
+    def add_system_message(
+        self, content: ResponseInputMessageContentListParam, **metadata
+    ) -> None:
+        """Append a system message to the conversation.
+
+        Parameters
+        ----------
+        content : ResponseInputMessageContentListParam
+            System message content in OpenAI format.
+        **metadata
+            Optional metadata to store with the message.
+
+        Returns
+        -------
+        None
+        """
+        response_input = cast(
+            ResponseInputItemParam, {"role": "system", "content": content}
+        )
+        self.messages.append(
+            ResponseMessage(role="system", content=response_input, metadata=metadata)
+        )
+
+    def add_user_message(
+        self, input_content: ResponseInputItemParam, **metadata
+    ) -> None:
+        """Append a user message to the conversation.
+
+        Parameters
+        ----------
+        input_content : ResponseInputItemParam
+            Message payload supplied by the user.
+        **metadata
+            Optional metadata to store with the message.
+
+        Returns
+        -------
+        None
+        """
+        self.messages.append(
+            ResponseMessage(role="user", content=input_content, metadata=metadata)
+        )
+
+    def add_assistant_message(
+        self,
+        content: ResponseOutputMessage,
+        metadata: Dict[str, Union[str, float, bool]],
+    ) -> None:
+        """Append an assistant message to the conversation.
+
+        Parameters
+        ----------
+        content : ResponseOutputMessage
+            Assistant response message.
+        metadata : dict[str, Union[str, float, bool]]
+            Optional metadata to store with the message.
+
+        Returns
+        -------
+        None
+        """
+        self.messages.append(
+            ResponseMessage(role="assistant", content=content, metadata=metadata)
+        )
+
+    def add_tool_message(
+        self, content: ResponseFunctionToolCall, output: str, **metadata
+    ) -> None:
+        """Record a tool call and its output in the conversation history.
+
+        Parameters
+        ----------
+        content : ResponseFunctionToolCall
+            Tool call received from OpenAI.
+        output : str
+            JSON string returned by the executed tool.
+        **metadata
+            Optional metadata to store with the message.
+
+        Returns
+        -------
+        None
+        """
+        tool_call = ResponseToolCall(
+            call_id=content.call_id,
+            name=content.name,
+            arguments=content.arguments,
+            output=output,
+        )
+        function_call, function_call_output = tool_call.to_response_input_item_param()
+        self.messages.append(
+            ResponseMessage(role="tool", content=function_call, metadata=metadata)
+        )
+        self.messages.append(
+            ResponseMessage(
+                role="tool", content=function_call_output, metadata=metadata
+            )
+        )
+
+    def to_openai_payload(
+        self,
+    ) -> List[
+        ResponseInputItemParam
+        | ResponseOutputMessage
+        | ResponseFunctionToolCallParam
+        | FunctionCallOutput
+        | ResponseInputMessageContentListParam
+    ]:
+        """Convert stored messages to the input payload expected by OpenAI.
+
+        Notes
+        -----
+        Assistant messages are model outputs and are not included in the
+        next request's input payload.
+
+        Returns
+        -------
+        list
+            List of message payloads excluding assistant outputs.
+        """
+        return [
+            msg.to_openai_format() for msg in self.messages if msg.role != "assistant"
+        ]

openai_sdk_helpers/response/runner.py

@@ -0,0 +1,104 @@
+"""Convenience runners for response workflows."""
+
+from __future__ import annotations
+
+import asyncio
+
+from typing import Any, Optional, Type, TypeVar
+
+from .base import ResponseBase
+
+
+R = TypeVar("R", bound=ResponseBase[Any])
+
+
+def run_sync(
+    response_cls: Type[R],
+    *,
+    content: str,
+    response_kwargs: Optional[dict[str, Any]] = None,
+) -> Any:
+    """Run a response workflow synchronously and close resources.
+
+    Parameters
+    ----------
+    response_cls
+        Response class to instantiate.
+    content
+        Prompt text to send to the OpenAI API.
+    response_kwargs
+        Keyword arguments forwarded to ``response_cls``. Default ``None``.
+
+    Returns
+    -------
+    Any
+        Parsed response from :meth:`ResponseBase.run_response`.
+    """
+    response = response_cls(**(response_kwargs or {}))
+    try:
+        return response.run_sync(content=content)
+    finally:
+        response.close()
+
+
+async def run_async(
+    response_cls: Type[R],
+    *,
+    content: str,
+    response_kwargs: Optional[dict[str, Any]] = None,
+) -> Any:
+    """Run a response workflow asynchronously and close resources.
+
+    Parameters
+    ----------
+    response_cls
+        Response class to instantiate.
+    content
+        Prompt text to send to the OpenAI API.
+    response_kwargs
+        Keyword arguments forwarded to ``response_cls``. Default ``None``.
+
+    Returns
+    -------
+    Any
+        Parsed response from :meth:`ResponseBase.run_response_async`.
+    """
+    response = response_cls(**(response_kwargs or {}))
+    try:
+        return await response.run_async(content=content)
+    finally:
+        response.close()
+
+
+def run_streamed(
+    response_cls: Type[R],
+    *,
+    content: str,
+    response_kwargs: Optional[dict[str, Any]] = None,
+) -> Any:
+    """Run a response workflow and return the asynchronous result.
+
+    This mirrors the agent API for discoverability. Streaming responses are not
+    currently supported by :class:`ResponseBase`, so this returns the same value
+    as :func:`run_async`.
+
+    Parameters
+    ----------
+    response_cls
+        Response class to instantiate.
+    content
+        Prompt text to send to the OpenAI API.
+    response_kwargs
+        Keyword arguments forwarded to ``response_cls``. Default ``None``.
+
+    Returns
+    -------
+    Any
+        Parsed response returned from :func:`run_async`.
+    """
+    return asyncio.run(
+        run_async(response_cls, content=content, response_kwargs=response_kwargs)
+    )
+
+
+__all__ = ["run_sync", "run_async", "run_streamed"]

openai_sdk_helpers/response/tool_call.py

@@ -0,0 +1,70 @@
+"""Tool call representation for shared responses."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Tuple
+
+from openai.types.responses.response_function_tool_call_param import (
+    ResponseFunctionToolCallParam,
+)
+from openai.types.responses.response_input_param import FunctionCallOutput
+
+
+@dataclass
+class ResponseToolCall:
+    """Container for tool call data used in a conversation.
+
+    Attributes
+    ----------
+    call_id : str
+        Identifier of the tool call.
+    name : str
+        Name of the tool invoked.
+    arguments : str
+        JSON string with the arguments passed to the tool.
+    output : str
+        JSON string representing the result produced by the tool.
+
+    Methods
+    -------
+    to_response_input_item_param()
+        Convert stored data into OpenAI tool call objects.
+    """
+
+    call_id: str
+    name: str
+    arguments: str
+    output: str
+
+    def to_response_input_item_param(
+        self,
+    ) -> Tuple[ResponseFunctionToolCallParam, FunctionCallOutput]:
+        """Convert stored data into OpenAI tool call objects.
+
+        Returns
+        -------
+        tuple[ResponseFunctionToolCallParam, FunctionCallOutput]
+            The function call object and the corresponding output object
+            suitable for inclusion in an OpenAI request.
+        """
+        from typing import cast
+
+        function_call = cast(
+            ResponseFunctionToolCallParam,
+            {
+                "arguments": self.arguments,
+                "call_id": self.call_id,
+                "name": self.name,
+                "type": "function_call",
+            },
+        )
+        function_call_output = cast(
+            FunctionCallOutput,
+            {
+                "call_id": self.call_id,
+                "output": self.output,
+                "type": "function_call_output",
+            },
+        )
+        return function_call, function_call_output

openai_sdk_helpers/response/vector_store.py

@@ -0,0 +1,84 @@
+"""Helpers for attaching vector stores to responses."""
+
+from __future__ import annotations
+
+from typing import Any, Optional, Sequence
+
+from openai import OpenAI
+
+from ..utils import ensure_list
+from .base import ResponseBase
+
+
+def attach_vector_store(
+    response: ResponseBase[Any],
+    vector_stores: str | Sequence[str],
+    api_key: Optional[str] = None,
+) -> list[str]:
+    """Attach vector stores to a response ``file_search`` tool.
+
+    Parameters
+    ----------
+    response
+        Response instance whose tool configuration is updated.
+    vector_stores
+        Single vector store name or a sequence of names to attach.
+    api_key : str, optional
+        API key used when the response does not already have a client. Default
+        ``None``.
+
+    Returns
+    -------
+    list[str]
+        Ordered list of vector store IDs applied to the ``file_search`` tool.
+
+    Raises
+    ------
+    ValueError
+        If a vector store cannot be resolved or no API key is available when
+        required.
+    """
+    requested_stores = ensure_list(vector_stores)
+
+    client = getattr(response, "_client", None)
+    if client is None:
+        if api_key is None:
+            raise ValueError(
+                "OpenAI API key is required to resolve vector store names."
+            )
+        client = OpenAI(api_key=api_key)
+
+    available_stores = client.vector_stores.list().data
+    resolved_ids: list[str] = []
+
+    for store in requested_stores:
+        match = next(
+            (vs.id for vs in available_stores if vs.name == store),
+            None,
+        )
+        if match is None:
+            raise ValueError(f"Vector store '{store}' not found.")
+        if match not in resolved_ids:
+            resolved_ids.append(match)
+
+    file_search_tool = next(
+        (tool for tool in response._tools if tool.get("type") == "file_search"),
+        None,
+    )
+
+    if file_search_tool is None:
+        response._tools.append(
+            {"type": "file_search", "vector_store_ids": resolved_ids}
+        )
+        return resolved_ids
+
+    existing_ids = ensure_list(file_search_tool.get("vector_store_ids", []))
+    combined_ids = existing_ids.copy()
+    for vector_store_id in resolved_ids:
+        if vector_store_id not in combined_ids:
+            combined_ids.append(vector_store_id)
+    file_search_tool["vector_store_ids"] = combined_ids
+    return combined_ids
+
+
+__all__ = ["attach_vector_store"]

openai_sdk_helpers/structure/__init__.py

@@ -0,0 +1,43 @@
+"""Shared structured output models and base helpers."""
+
+from __future__ import annotations
+
+from .agent_blueprint import AgentBlueprint
+from .plan import *
+from .base import *
+from .prompt import PromptStructure
+from .responses import *
+from .summary import *
+from .vector_search import *
+from .validation import ValidationResultStructure
+from .web_search import *
+
+__all__ = [
+    "BaseStructure",
+    "SchemaOptions",
+    "spec_field",
+    "AgentBlueprint",
+    "AgentEnum",
+    "TaskStructure",
+    "PlanStructure",
+    "PromptStructure",
+    "SummaryTopic",
+    "SummaryStructure",
+    "ExtendedSummaryStructure",
+    "WebSearchStructure",
+    "WebSearchPlanStructure",
+    "WebSearchItemStructure",
+    "WebSearchItemResultStructure",
+    "WebSearchReportStructure",
+    "VectorSearchReportStructure",
+    "VectorSearchItemStructure",
+    "VectorSearchItemResultStructure",
+    "VectorSearchItemResultsStructure",
+    "VectorSearchPlanStructure",
+    "VectorSearchStructure",
+    "ValidationResultStructure",
+    "assistant_tool_definition",
+    "assistant_format",
+    "response_tool_definition",
+    "response_format",
+]