openai-sdk-helpers 0.6.0__py3-none-any.whl → 0.6.2__py3-none-any.whl

openai_sdk_helpers/agent/__init__.py

@@ -14,6 +14,7 @@ from .validator import ValidatorAgent
 from .utils import run_coroutine_agent_sync
 from .search.vector import VectorAgentSearch
 from .search.web import WebAgentSearch
+from .files import build_agent_input_messages
 
 __all__ = [
     "AgentBase",
@@ -34,4 +35,5 @@ __all__ = [
     "ValidatorAgent",
     "VectorAgentSearch",
     "WebAgentSearch",
+    "build_agent_input_messages",
 ]

openai_sdk_helpers/agent/base.py

@@ -6,7 +6,7 @@ import logging
 import traceback
 import uuid
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, Dict, Optional, Protocol, cast
+from typing import TYPE_CHECKING, Any, Dict, Literal, Optional, Protocol, cast
 
 from agents import Agent, Handoff, InputGuardrail, OutputGuardrail, Session
 from agents.model_settings import ModelSettings
@@ -33,6 +33,7 @@ from .runner import run_async, run_sync
 if TYPE_CHECKING:
     from ..settings import OpenAISettings
     from ..response.base import ResponseBase
+    from ..files_api import FilePurpose, FilesAPIManager
 
 
 class AgentConfigurationProtocol(Protocol):
@@ -184,6 +185,8 @@ class AgentBase(DataclassJSONSerializable):
         Return response tool handler and definition for Responses API use.
     build_response(openai_settings, data_path=None, tool_handlers=None, system_vector_store=None)
         Build a ResponseBase instance based on this agent.
+    build_input_messages(content, files=None, files_manager=None, file_purpose="user_data", image_detail="auto")
+        Build Agents SDK input messages with optional file attachments.
     save_error(exc)
         Persist error details to a file named with the agent UUID.
     close()
@@ -429,9 +432,16 @@ class AgentBase(DataclassJSONSerializable):
         """
         return self._session
 
-    def get_agent(self) -> Agent:
+    def get_agent(
+        self, output_structure: Optional[type[StructureBase]] = None
+    ) -> Agent:
         """Construct and return the configured :class:`agents.Agent` instance.
 
+        Parameters
+        ----------
+        output_structure : type[StructureBase] or None, default=None
+            Optional override for the agent output schema.
+
         Returns
         -------
         Agent
@@ -442,8 +452,9 @@ class AgentBase(DataclassJSONSerializable):
             "instructions": self._configuration.instructions_text or ".",
             "model": self._model,
         }
-        if self._configuration.output_structure:
-            agent_config["output_type"] = self._configuration.output_structure
+        output_type = output_structure or self._configuration.output_structure
+        if output_type is not None:
+            agent_config["output_type"] = output_type
         if self._configuration.tools:
             agent_config["tools"] = self._configuration.tools
         if self._model_settings:
@@ -459,7 +470,7 @@ class AgentBase(DataclassJSONSerializable):
 
     async def run_async(
         self,
-        input: str,
+        input: str | list[dict[str, Any]],
         *,
         context: Optional[Dict[str, Any]] = None,
         output_structure: Optional[type[StructureBase]] = None,
@@ -469,8 +480,8 @@ class AgentBase(DataclassJSONSerializable):
 
         Parameters
         ----------
-        input : str
-            Prompt or query for the agent.
+        input : str or list[dict[str, Any]]
+            Prompt text or structured input for the agent.
         context : dict or None, default=None
             Optional dictionary passed to the agent.
         output_structure : type[StructureBase] or None, default=None
@@ -490,7 +501,7 @@ class AgentBase(DataclassJSONSerializable):
         session_to_use = session if session is not None else self._session
         try:
             return await run_async(
-                agent=self.get_agent(),
+                agent=self.get_agent(output_structure=output_structure),
                 input=input,
                 context=context,
                 output_structure=output_structure,
@@ -514,7 +525,7 @@ class AgentBase(DataclassJSONSerializable):
 
     def run_sync(
         self,
-        input: str,
+        input: str | list[dict[str, Any]],
         *,
         context: Optional[Dict[str, Any]] = None,
         output_structure: Optional[type[StructureBase]] = None,
@@ -524,8 +535,8 @@ class AgentBase(DataclassJSONSerializable):
 
         Parameters
         ----------
-        input : str
-            Prompt or query for the agent.
+        input : str or list[dict[str, Any]]
+            Prompt text or structured input for the agent.
         context : dict or None, default=None
             Optional dictionary passed to the agent.
         output_structure : type[StructureBase] or None, default=None
@@ -545,7 +556,7 @@ class AgentBase(DataclassJSONSerializable):
         session_to_use = session if session is not None else self._session
         try:
             return run_sync(
-                agent=self.get_agent(),
+                agent=self.get_agent(output_structure=output_structure),
                 input=input,
                 context=context,
                 output_structure=output_structure,
@@ -652,6 +663,71 @@ class AgentBase(DataclassJSONSerializable):
             openai_settings=openai_settings,
         )
 
+    @staticmethod
+    def build_input_messages(
+        content: str | list[str],
+        files: str | list[str] | None = None,
+        *,
+        files_manager: FilesAPIManager | None = None,
+        openai_settings: OpenAISettings | None = None,
+        file_purpose: FilePurpose = "user_data",
+        image_detail: Literal["low", "high", "auto"] = "auto",
+    ) -> list[dict[str, Any]]:
+        """Build Agents SDK input messages with file attachments.
+
+        Parameters
+        ----------
+        content : str or list[str]
+            Prompt text or list of prompt texts to send.
+        files : str, list[str], or None, default None
+            Optional file path or list of file paths. Image files are sent as
+            base64-encoded ``input_image`` entries. Document files are uploaded
+            using ``files_manager`` and sent as ``input_file`` entries.
+        files_manager : FilesAPIManager or None, default None
+            File upload helper used to create file IDs for document uploads.
+            Required when ``files`` contains non-image documents.
+        openai_settings : OpenAISettings or None, default None
+            Optional OpenAI settings used to build a FilesAPIManager when one is
+            not provided. When supplied, ``openai_settings.create_client()`` is
+            used to initialize the Files API manager.
+        file_purpose : FilePurpose, default "user_data"
+            Purpose passed to the Files API when uploading document files.
+        image_detail : {"low", "high", "auto"}, default "auto"
+            Detail hint passed along with base64-encoded image inputs.
+
+        Returns
+        -------
+        list[dict[str, Any]]
+            Agents SDK input messages that include text and optional file entries.
+
+        Raises
+        ------
+        ValueError
+            If document files are provided without a ``files_manager``.
+
+        Examples
+        --------
+        >>> from openai import OpenAI
+        >>> from openai_sdk_helpers.files_api import FilesAPIManager
+        >>> client = OpenAI()
+        >>> files_manager = FilesAPIManager(client)
+        >>> messages = AgentBase.build_input_messages(
+        ...     "Summarize this document",
+        ...     files="report.pdf",
+        ...     files_manager=files_manager,
+        ... )
+        """
+        from .files import build_agent_input_messages
+
+        return build_agent_input_messages(
+            content=content,
+            files=files,
+            files_manager=files_manager,
+            openai_settings=openai_settings,
+            file_purpose=file_purpose,
+            image_detail=image_detail,
+        )
+
     def _build_response_parameters(self) -> dict[str, Any]:
         """Build the Responses API parameter schema for this agent tool.