openai-sdk-helpers 0.6.1__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()
@@ -467,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,
@@ -477,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
@@ -522,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,
@@ -532,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
@@ -660,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.
 

openai_sdk_helpers/agent/classifier.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import asyncio
+import threading
 import re
 from dataclasses import dataclass, field
 from enum import Enum
@@ -16,6 +17,7 @@ from ..structure import (
     StructureBase,
     TaxonomyNode,
 )
+from ..utils import ensure_list
 from .base import AgentBase
 from .configuration import AgentConfiguration
 
@@ -32,8 +34,12 @@ class TaxonomyClassifierAgent(AgentBase):
 
     Methods
     -------
-    run_agent(text, taxonomy, context, max_depth)
+    run_agent(text, taxonomy, context, max_depth, session)
         Classify text by recursively walking the taxonomy tree.
+    run_async(input, context, max_depth, confidence_threshold, single_class)
+        Classify text asynchronously using taxonomy traversal.
+    run_sync(input, context, max_depth, confidence_threshold, single_class)
+        Classify text synchronously using taxonomy traversal.
 
     Examples
     --------
@@ -93,9 +99,11 @@ class TaxonomyClassifierAgent(AgentBase):
         text: str,
         *,
         context: Optional[Dict[str, Any]] = None,
+        file_ids: str | Sequence[str] | None = None,
         max_depth: Optional[int] = None,
         confidence_threshold: float | None = None,
         single_class: bool = False,
+        session: Optional[Any] = None,
     ) -> ClassificationResult:
         """Classify ``text`` by recursively walking taxonomy levels.
 
@@ -105,12 +113,16 @@ class TaxonomyClassifierAgent(AgentBase):
             Source text to classify.
         context : dict or None, default=None
             Additional context values to merge into the prompt.
+        file_ids : str or Sequence[str] or None, default=None
+            Optional file IDs to attach to each classification step.
         max_depth : int or None, default=None
             Maximum depth to traverse before stopping.
         confidence_threshold : float or None, default=None
             Minimum confidence required to accept a classification step.
         single_class : bool, default=False
             Whether to keep only the highest-priority selection per step.
+        session : Session or None, default=None
+            Optional session for maintaining conversation history across runs.
 
         Returns
         -------
@@ -125,15 +137,18 @@ class TaxonomyClassifierAgent(AgentBase):
         True
         """
         state = _TraversalState()
+        input_payload = _build_input_payload(text, file_ids)
         await self._classify_nodes(
-            text=text,
+            input_payload=input_payload,
             nodes=list(self._root_nodes),
             depth=0,
             parent_path=[],
             context=context,
+            file_ids=file_ids,
             max_depth=max_depth,
             confidence_threshold=confidence_threshold,
             single_class=single_class,
+            session=session,
             state=state,
         )
 
@@ -149,37 +164,210 @@ class TaxonomyClassifierAgent(AgentBase):
             path_nodes=state.path_nodes,
         )
 
+    async def run_async(
+        self,
+        input: str | list[dict[str, Any]],
+        *,
+        context: Optional[Dict[str, Any]] = None,
+        output_structure: Optional[type[StructureBase]] = None,
+        session: Optional[Any] = None,
+        file_ids: str | Sequence[str] | None = None,
+        max_depth: Optional[int] = None,
+        confidence_threshold: float | None = None,
+        single_class: bool = False,
+    ) -> ClassificationResult:
+        """Classify ``input`` asynchronously with taxonomy traversal.
+
+        Parameters
+        ----------
+        input : str or list[dict[str, Any]]
+            Source text to classify.
+        context : dict or None, default=None
+            Additional context values to merge into the prompt.
+        output_structure : type[StructureBase] or None, default=None
+            Unused in taxonomy traversal. Present for API compatibility.
+        session : Session or None, default=None
+            Optional session for maintaining conversation history across runs.
+        file_ids : str or Sequence[str] or None, default=None
+            Optional file IDs to attach to each classification step.
+        max_depth : int or None, default=None
+            Maximum depth to traverse before stopping.
+        confidence_threshold : float or None, default=None
+            Minimum confidence required to accept a classification step.
+        single_class : bool, default=False
+            Whether to keep only the highest-priority selection per step.
+
+        Returns
+        -------
+        ClassificationResult
+            Structured classification result describing the traversal.
+        """
+        _ = output_structure
+        if not isinstance(input, str):
+            msg = "TaxonomyClassifierAgent run_async requires text input."
+            raise TypeError(msg)
+        kwargs: Dict[str, Any] = {
+            "context": context,
+            "file_ids": file_ids,
+            "max_depth": max_depth,
+            "confidence_threshold": confidence_threshold,
+            "single_class": single_class,
+        }
+        if session is not None:
+            kwargs["session"] = session
+        return await self.run_agent(input, **kwargs)
+
+    def run_sync(
+        self,
+        input: str | list[dict[str, Any]],
+        *,
+        context: Optional[Dict[str, Any]] = None,
+        output_structure: Optional[type[StructureBase]] = None,
+        session: Optional[Any] = None,
+        file_ids: str | Sequence[str] | None = None,
+        max_depth: Optional[int] = None,
+        confidence_threshold: float | None = None,
+        single_class: bool = False,
+    ) -> ClassificationResult:
+        """Classify ``input`` synchronously with taxonomy traversal.
+
+        Parameters
+        ----------
+        input : str or list[dict[str, Any]]
+            Source text to classify.
+        context : dict or None, default=None
+            Additional context values to merge into the prompt.
+        output_structure : type[StructureBase] or None, default=None
+            Unused in taxonomy traversal. Present for API compatibility.
+        session : Session or None, default=None
+            Optional session for maintaining conversation history across runs.
+        file_ids : str or Sequence[str] or None, default=None
+            Optional file IDs to attach to each classification step.
+        max_depth : int or None, default=None
+            Maximum depth to traverse before stopping.
+        confidence_threshold : float or None, default=None
+            Minimum confidence required to accept a classification step.
+        single_class : bool, default=False
+            Whether to keep only the highest-priority selection per step.
+
+        Returns
+        -------
+        ClassificationResult
+            Structured classification result describing the traversal.
+        """
+        _ = output_structure
+        if not isinstance(input, str):
+            msg = "TaxonomyClassifierAgent run_sync requires text input."
+            raise TypeError(msg)
+        kwargs: Dict[str, Any] = {
+            "context": context,
+            "file_ids": file_ids,
+            "max_depth": max_depth,
+            "confidence_threshold": confidence_threshold,
+            "single_class": single_class,
+        }
+        if session is not None:
+            kwargs["session"] = session
+
+        async def runner() -> ClassificationResult:
+            return await self.run_agent(input, **kwargs)
+
+        try:
+            asyncio.get_running_loop()
+        except RuntimeError:
+            return asyncio.run(runner())
+
+        result: ClassificationResult | None = None
+        error: Exception | None = None
+
+        def _thread_func() -> None:
+            nonlocal error, result
+            try:
+                result = asyncio.run(runner())
+            except Exception as exc:
+                error = exc
+
+        thread = threading.Thread(target=_thread_func)
+        thread.start()
+        thread.join()
+
+        if error is not None:
+            raise error
+        if result is None:
+            msg = "Classification did not return a result"
+            raise RuntimeError(msg)
+        return result
+
+    async def _run_step_async(
+        self,
+        *,
+        input: str | list[dict[str, Any]],
+        context: Optional[Dict[str, Any]] = None,
+        output_structure: Optional[type[StructureBase]] = None,
+        session: Optional[Any] = None,
+    ) -> StructureBase:
+        """Execute a single classification step asynchronously.
+
+        Parameters
+        ----------
+        input : str or list[dict[str, Any]]
+            Prompt 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
+            Optional type used to cast the final output.
+        session : Session or None, default=None
+            Optional session for maintaining conversation history across runs.
+
+        Returns
+        -------
+        StructureBase
+            Parsed result for the classification step.
+        """
+        return await super().run_async(
+            input=input,
+            context=context,
+            output_structure=output_structure,
+            session=session,
+        )
+
     async def _classify_nodes(
         self,
         *,
-        text: str,
+        input_payload: str | list[dict[str, Any]],
         nodes: list[TaxonomyNode],
         depth: int,
         parent_path: list[str],
         context: Optional[Dict[str, Any]],
+        file_ids: str | Sequence[str] | None,
         max_depth: Optional[int],
         confidence_threshold: float | None,
         single_class: bool,
+        session: Optional[Any],
         state: "_TraversalState",
     ) -> None:
         """Classify a taxonomy level and recursively traverse children.
 
         Parameters
         ----------
-        text : str
-            Source text to classify.
+        input_payload : str or list[dict[str, Any]]
+            Input payload used to prompt the agent.
         nodes : list[TaxonomyNode]
             Candidate taxonomy nodes for the current level.
         depth : int
             Current traversal depth.
         context : dict or None
             Additional context values to merge into the prompt.
+        file_ids : str or Sequence[str] or None
+            Optional file IDs attached to each classification step.
         max_depth : int or None
             Maximum traversal depth before stopping.
         confidence_threshold : float or None
             Minimum confidence required to accept a classification step.
         single_class : bool
             Whether to keep only the highest-priority selection per step.
+        session : Session or None
+            Optional session for maintaining conversation history across runs.
         state : _TraversalState
             Aggregated traversal state.
         """
@@ -197,10 +385,11 @@ class TaxonomyClassifierAgent(AgentBase):
             context=context,
         )
         step_structure = _build_step_structure(list(node_paths.keys()))
-        raw_step = await self.run_async(
-            input=text,
+        raw_step = await self._run_step_async(
+            input=input_payload,
             context=template_context,
             output_structure=step_structure,
+            session=session,
         )
         step = _normalize_step_output(raw_step, step_structure)
         state.path.append(step)
@@ -242,14 +431,16 @@ class TaxonomyClassifierAgent(AgentBase):
                     (
                         self._classify_subtree(
                             sub_agent=sub_agent,
-                            text=text,
+                            input_payload=input_payload,
                             nodes=list(node.children),
                             depth=depth + 1,
                             parent_path=[*parent_path, node.label],
                             context=context,
+                            file_ids=file_ids,
                             max_depth=max_depth,
                             confidence_threshold=confidence_threshold,
                             single_class=single_class,
+                            session=session,
                             state=sub_state,
                         ),
                         base_final_nodes_len,
@@ -325,21 +516,23 @@ class TaxonomyClassifierAgent(AgentBase):
             model=self._model,
             taxonomy=list(nodes),
         )
-        sub_agent.run_async = self.run_async
+        sub_agent._run_step_async = self._run_step_async
         return sub_agent
 
     async def _classify_subtree(
         self,
         *,
         sub_agent: "TaxonomyClassifierAgent",
-        text: str,
+        input_payload: str | list[dict[str, Any]],
         nodes: list[TaxonomyNode],
         depth: int,
         parent_path: list[str],
         context: Optional[Dict[str, Any]],
+        file_ids: str | Sequence[str] | None,
         max_depth: Optional[int],
         confidence_threshold: float | None,
         single_class: bool,
+        session: Optional[Any],
         state: "_TraversalState",
     ) -> "_TraversalState":
         """Classify a taxonomy subtree and return the traversal state.
@@ -348,8 +541,8 @@ class TaxonomyClassifierAgent(AgentBase):
         ----------
         sub_agent : TaxonomyClassifierAgent
             Sub-agent configured for the subtree traversal.
-        text : str
-            Source text to classify.
+        input_payload : str or list[dict[str, Any]]
+            Input payload used to prompt the agent.
         nodes : list[TaxonomyNode]
             Candidate taxonomy nodes for the subtree.
         depth : int
@@ -358,12 +551,16 @@ class TaxonomyClassifierAgent(AgentBase):
             Path segments leading to the current subtree.
         context : dict or None
             Additional context values to merge into the prompt.
+        file_ids : str or Sequence[str] or None
+            Optional file IDs attached to each classification step.
         max_depth : int or None
             Maximum traversal depth before stopping.
         confidence_threshold : float or None
             Minimum confidence required to accept a classification step.
         single_class : bool
             Whether to keep only the highest-priority selection per step.
+        session : Session or None
+            Optional session for maintaining conversation history across runs.
         state : _TraversalState
             Traversal state to populate for the subtree.
 
@@ -373,14 +570,16 @@ class TaxonomyClassifierAgent(AgentBase):
             Populated traversal state for the subtree.
         """
         await sub_agent._classify_nodes(
-            text=text,
+            input_payload=input_payload,
             nodes=nodes,
             depth=depth,
             parent_path=parent_path,
             context=context,
+            file_ids=file_ids,
             max_depth=max_depth,
             confidence_threshold=confidence_threshold,
             single_class=single_class,
+            session=session,
             state=state,
         )
         return state
@@ -716,6 +915,38 @@ def _normalize_step_output(
     return ClassificationStep.from_json(payload)
 
 
+def _build_input_payload(
+    text: str,
+    file_ids: str | Sequence[str] | None,
+) -> str | list[dict[str, Any]]:
+    """Build input payloads with optional file attachments.
+
+    Parameters
+    ----------
+    text : str
+        Prompt text to send to the agent.
+    file_ids : str or Sequence[str] or None
+        Optional file IDs to include as ``input_file`` attachments.
+
+    Returns
+    -------
+    str or list[dict[str, Any]]
+        Input payload suitable for the Agents SDK.
+    """
+    normalized_file_ids = [file_id for file_id in ensure_list(file_ids) if file_id]
+    if not normalized_file_ids:
+        return text
+    attachments = [
+        {"type": "input_file", "file_id": file_id} for file_id in normalized_file_ids
+    ]
+    return [
+        {
+            "role": "user",
+            "content": [{"type": "input_text", "text": text}, *attachments],
+        }
+    ]
+
+
 def _extract_enum_fields(
     step_structure: type[StructureBase],
 ) -> dict[str, type[Enum]]:

openai_sdk_helpers/agent/configuration.py

@@ -13,6 +13,7 @@ from ..utils.json.data_class import DataclassJSONSerializable
 from ..utils.registry import RegistryBase
 from ..utils.instructions import resolve_instructions_from_path
 from ..structure.base import StructureBase
+from ..settings import OpenAISettings
 
 
 class AgentRegistry(RegistryBase["AgentConfiguration"]):
@@ -152,6 +153,8 @@ class AgentConfiguration(DataclassJSONSerializable):
         Resolve the prompt template path for this configuration.
     gen_agent(run_context_wrapper)
         Create a AgentBase instance from this configuration.
+    to_openai_settings(dotenv_path=None, **overrides)
+        Build OpenAISettings using this configuration as defaults.
     replace(**changes)
         Create a new AgentConfiguration with specified fields replaced.
     to_json()
@@ -272,6 +275,45 @@ class AgentConfiguration(DataclassJSONSerializable):
         """Resolve instructions from string or file path."""
         return resolve_instructions_from_path(self.instructions)
 
+    def to_openai_settings(
+        self, *, dotenv_path: Path | None = None, **overrides: Any
+    ) -> OpenAISettings:
+        """Build OpenAI settings using this configuration as defaults.
+
+        Parameters
+        ----------
+        dotenv_path : Path or None, optional
+            Optional dotenv file path for loading environment variables.
+        overrides : Any
+            Keyword overrides applied on top of environment values. Use this
+            to supply API credentials and override defaults.
+
+        Returns
+        -------
+        OpenAISettings
+            OpenAI settings instance with defaults derived from this
+            configuration.
+
+        Raises
+        ------
+        ValueError
+            If no API key is supplied via overrides or environment variables.
+
+        Examples
+        --------
+        >>> configuration = AgentConfiguration(
+        ...     name="summarizer",
+        ...     instructions="Summarize text",
+        ...     model="gpt-4o-mini",
+        ... )
+        >>> settings = configuration.to_openai_settings(api_key="sk-...")
+        >>> # Or rely on environment variables like OPENAI_API_KEY
+        >>> settings = configuration.to_openai_settings()
+        """
+        if self.model and "default_model" not in overrides:
+            overrides["default_model"] = self.model
+        return OpenAISettings.from_env(dotenv_path=dotenv_path, **overrides)
+
     def resolve_prompt_path(self, prompt_dir: Path | None = None) -> Path | None:
         """Resolve the prompt template path for this configuration.
 

openai_sdk_helpers/agent/files.py

@@ -0,0 +1,120 @@
+"""File attachment helpers for the Agents SDK."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from ..files_api import FilePurpose, FilesAPIManager
+from ..settings import OpenAISettings
+from ..utils import create_image_data_url, ensure_list, is_image_file
+
+
+def build_agent_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
+    >>> from openai_sdk_helpers.agent.files import build_agent_input_messages
+    >>> client = OpenAI()
+    >>> files_manager = FilesAPIManager(client)
+    >>> messages = build_agent_input_messages(
+    ...     "Summarize this document",
+    ...     files="report.pdf",
+    ...     files_manager=files_manager,
+    ... )
+    """
+    contents = ensure_list(content)
+    all_files = ensure_list(files)
+
+    image_files: list[str] = []
+    document_files: list[str] = []
+    for file_path in all_files:
+        if is_image_file(file_path):
+            image_files.append(file_path)
+        else:
+            document_files.append(file_path)
+
+    attachments: list[dict[str, Any]] = []
+
+    if document_files:
+        if files_manager is None and openai_settings is not None:
+            files_manager = FilesAPIManager(openai_settings.create_client())
+        if files_manager is None:
+            raise ValueError(
+                "files_manager is required to upload document files for agent input."
+            )
+        expires_after = 86400 if file_purpose == "user_data" else None
+        if hasattr(files_manager, "batch_upload"):
+            uploaded_files = files_manager.batch_upload(
+                document_files,
+                purpose=file_purpose,
+                expires_after=expires_after,
+            )
+        else:
+            uploaded_files = [
+                files_manager.create(
+                    file_path, purpose=file_purpose, expires_after=expires_after
+                )
+                for file_path in document_files
+            ]
+        for uploaded_file in uploaded_files:
+            attachments.append({"type": "input_file", "file_id": uploaded_file.id})
+
+    for image_path in image_files:
+        image_url, detail = create_image_data_url(image_path, detail=image_detail)
+        attachments.append(
+            {"type": "input_image", "image_url": image_url, "detail": detail}
+        )
+
+    messages: list[dict[str, Any]] = []
+    for index, raw_content in enumerate(contents):
+        text = raw_content.strip()
+        content_items: list[dict[str, Any]] = [{"type": "input_text", "text": text}]
+        if index == 0:
+            content_items.extend(attachments)
+        messages.append({"role": "user", "content": content_items})
+
+    return messages
+
+
+__all__ = ["build_agent_input_messages"]

openai_sdk_helpers/agent/runner.py

@@ -7,7 +7,7 @@ signatures whether they need asynchronous or synchronous results.
 
 from __future__ import annotations
 
-from typing import Any, Dict, Optional
+from typing import Any, Dict, Optional, cast
 
 from agents import Agent, RunResult, Runner, Session
 
@@ -17,7 +17,7 @@ from ..structure.base import StructureBase
 
 async def run_async(
     agent: Agent,
-    input: str,
+    input: str | list[dict[str, Any]],
     *,
     context: Optional[Dict[str, Any]] = None,
     output_structure: Optional[type[StructureBase]] = None,
@@ -29,8 +29,8 @@ async def run_async(
     ----------
     agent : Agent
         Configured agent instance to execute.
-    input : str
-        Prompt or query string 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 context dictionary passed to the agent.
     output_structure : type[StructureBase] or None, default=None
@@ -53,7 +53,7 @@ async def run_async(
     ...     return result
     >>> asyncio.run(example())  # doctest: +SKIP
     """
-    result = await Runner.run(agent, input, context=context, session=session)
+    result = await Runner.run(agent, cast(Any, input), context=context, session=session)
     if output_structure is not None:
         return result.final_output_as(output_structure)
     return result
@@ -61,7 +61,7 @@ async def run_async(
 
 def run_sync(
     agent: Agent,
-    input: str,
+    input: str | list[dict[str, Any]],
     *,
     context: Optional[Dict[str, Any]] = None,
     output_structure: Optional[type[StructureBase]] = None,
@@ -77,8 +77,8 @@ def run_sync(
     ----------
     agent : Agent
         Configured agent instance to execute.
-    input : str
-        Prompt or query string 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 context dictionary passed to the agent.
     output_structure : type[StructureBase] or None, default=None
@@ -102,7 +102,7 @@ def run_sync(
     >>> agent = Agent(name="test", instructions="test", model="gpt-4o-mini")
     >>> result = run_sync(agent, "What is 2+2?")  # doctest: +SKIP
     """
-    coro = Runner.run(agent, input, context=context, session=session)
+    coro = Runner.run(agent, cast(Any, input), context=context, session=session)
     result: RunResult = run_coroutine_with_fallback(coro)
     if output_structure is not None:
         return result.final_output_as(output_structure)

openai_sdk_helpers/agent/translator.py

@@ -138,7 +138,7 @@ class TranslatorAgent(AgentBase):
 
     def run_sync(
         self,
-        input: str,
+        input: str | list[dict[str, Any]],
         *,
         context: Optional[Dict[str, Any]] = None,
         output_structure: Optional[type[StructureBase]] = None,
@@ -149,7 +149,7 @@ class TranslatorAgent(AgentBase):
 
         Parameters
         ----------
-        input : str
+        input : str or list[dict[str, Any]]
             Source content to translate.
         context : dict or None, default=None
             Additional context values to merge into the prompt.

openai_sdk_helpers/files_api.py

@@ -12,7 +12,7 @@ from __future__ import annotations
 
 import logging
 from pathlib import Path
-from typing import Any, BinaryIO, Literal, cast
+from typing import Any, BinaryIO, Literal, Sequence, cast
 
 from openai import OpenAI, NOT_GIVEN
 from openai.types import FileDeleted, FileObject
@@ -62,6 +62,8 @@ class FilesAPIManager:
         Delete a specific file.
     retrieve_content(file_id)
         Download file content.
+    batch_upload(files, purpose, track, expires_after)
+        Upload multiple files to the Files API.
     cleanup()
         Delete all tracked files.
 
@@ -350,6 +352,49 @@ class FilesAPIManager:
         """
         return self._client.files.content(file_id).read()
 
+    def batch_upload(
+        self,
+        files: Sequence[BinaryIO | Path | str],
+        purpose: FilePurpose,
+        track: bool | None = None,
+        expires_after: int | None = None,
+    ) -> list[FileObject]:
+        """Upload multiple files to the OpenAI Files API.
+
+        Parameters
+        ----------
+        files : Sequence[BinaryIO | Path | str]
+            File-like objects or file paths to upload.
+        purpose : FilePurpose
+            The intended purpose of the uploaded files.
+        track : bool or None, default None
+            Override auto_track for these uploads. If None, uses instance setting.
+        expires_after : int or None, default None
+            Number of seconds after which files expire. See ``create`` for details.
+
+        Returns
+        -------
+        list[FileObject]
+            Uploaded file objects in the same order as ``files``.
+
+        Examples
+        --------
+        >>> files = ["doc1.pdf", "doc2.pdf"]
+        >>> uploaded = manager.batch_upload(files, purpose="user_data")
+        >>> [file.id for file in uploaded]
+        """
+        if not files:
+            return []
+        return [
+            self.create(
+                file_path,
+                purpose=purpose,
+                track=track,
+                expires_after=expires_after,
+            )
+            for file_path in files
+        ]
+
     def cleanup(self) -> dict[str, bool]:
         """Delete all tracked files.
 

openai_sdk_helpers/prompt/classifier.jinja

@@ -5,12 +5,28 @@ Instructions:
 - Populate selected_nodes as a list of taxonomy node ids for multi-class matches.
 - Use selected_node when a single best match is appropriate.
 - Provide a confidence score between 0 and 1 for the selections; higher means more certain.
+- Interpret confidence as:
+  - 0.90–1.00: explicit lexical match.
+  - 0.70–0.89: strong semantic alignment.
+  - 0.40–0.69: weak or ambiguous alignment.
+  - <0.40: low-confidence inference.
 - Use only taxonomy identifiers from the candidate list for any selections.
 - Use the stop_reason enum values only: "continue", "stop", "no_match", "max_depth", "no_children".
-- If a child level should be explored, set stop_reason to "continue".
-- If no appropriate node exists, set stop_reason to "no_match" and leave selections empty.
-- If you are confident this is the final level, set stop_reason to "stop".
-- Provide a concise rationale in one or two sentences.
+- Stop reason semantics:
+  - continue: valid match exists and deeper traversal is required.
+  - stop: low confidence, terminate to avoid false precision.
+  - no_match: no semantic fit in candidates.
+  - max_depth: taxonomy depth limit reached.
+  - no_children: matched node has no children.
+- Decision mapping:
+  - High or medium confidence with children available: continue.
+  - High confidence with terminal node: no_children.
+  - Low confidence match: stop.
+  - No semantic alignment: no_match.
+  - Depth limit reached: max_depth.
+- Provide a concise rationale in one sentence.
+- Keep rationale evidence-based and avoid restating taxonomy labels.
+- Avoid verbosity, speculation, stylistic language, narrative explanation, redundancy, or creativity.
 
 Current depth: {{ depth }}
 

openai_sdk_helpers/structure/__init__.py

@@ -80,8 +80,10 @@ from .classification import (
     ClassificationResult,
     ClassificationStep,
     ClassificationStopReason,
+    Taxonomy,
     TaxonomyNode,
     flatten_taxonomy,
+    taxonomy_enum_path,
 )
 from .extraction import (
     AnnotatedDocumentStructure,
@@ -108,8 +110,10 @@ __all__ = [
     "ClassificationResult",
     "ClassificationStep",
     "ClassificationStopReason",
+    "Taxonomy",
     "TaxonomyNode",
     "flatten_taxonomy",
+    "taxonomy_enum_path",
     "TaskStructure",
     "PlanStructure",
     "create_plan",

openai_sdk_helpers/structure/classification.py

@@ -115,6 +115,48 @@ class TaxonomyNode(StructureBase):
         )
 
 
+class Taxonomy(StructureBase):
+    """Represent a taxonomy with metadata and root nodes.
+
+    Attributes
+    ----------
+    name : str
+        Human-readable taxonomy name.
+    description : str | None
+        Optional description of the taxonomy.
+    nodes : list[TaxonomyNode]
+        Root taxonomy nodes.
+
+    Methods
+    -------
+    flattened_nodes
+        Return a flattened list of all taxonomy nodes.
+    """
+
+    name: str = spec_field("name", description="Human-readable taxonomy name.")
+    description: str | None = spec_field(
+        "description",
+        description="Optional description of the taxonomy.",
+        default=None,
+    )
+    nodes: list[TaxonomyNode] = spec_field(
+        "nodes",
+        description="Root taxonomy nodes.",
+        default_factory=list,
+    )
+
+    @property
+    def flattened_nodes(self) -> list[TaxonomyNode]:
+        """Return a flattened list of all taxonomy nodes.
+
+        Returns
+        -------
+        list[TaxonomyNode]
+            Depth-first list of taxonomy nodes.
+        """
+        return flatten_taxonomy(self.nodes)
+
+
 def _split_path_identifier(path: str) -> list[str]:
     """Split a path identifier into label segments.
 
@@ -444,10 +486,42 @@ def flatten_taxonomy(nodes: Iterable[TaxonomyNode]) -> list[TaxonomyNode]:
     return flattened
 
 
+def taxonomy_enum_path(value: Enum | str | None) -> list[str]:
+    """Return the taxonomy path segments for an enum value.
+
+    Parameters
+    ----------
+    value : Enum or str or None
+        Enum member or path identifier string to split. If None, return an
+        empty list.
+
+    Returns
+    -------
+    list[str]
+        Path segments extracted from the taxonomy identifier.
+
+    Examples
+    --------
+    >>> StepEnum = Enum("StepEnum", {"ROOT_LEAF": "Root > Leaf"})
+    >>> taxonomy_enum_path(StepEnum.ROOT_LEAF)
+    ['Root', 'Leaf']
+    """
+    if value is None:
+        return []
+    normalized_value = _normalize_enum_value(value)
+    if not normalized_value:
+        return []
+    if not isinstance(normalized_value, str):
+        normalized_value = str(normalized_value)
+    return _split_path_identifier(normalized_value)
+
+
 __all__ = [
     "ClassificationResult",
     "ClassificationStep",
     "ClassificationStopReason",
+    "Taxonomy",
     "TaxonomyNode",
     "flatten_taxonomy",
+    "taxonomy_enum_path",
 ]

{openai_sdk_helpers-0.6.1.dist-info → openai_sdk_helpers-0.6.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openai-sdk-helpers
-Version: 0.6.1
+Version: 0.6.2
 Summary: Composable helpers for OpenAI SDK agents, prompts, and storage
 Author: openai-sdk-helpers maintainers
 License: MIT

{openai_sdk_helpers-0.6.1.dist-info → openai_sdk_helpers-0.6.2.dist-info}/RECORD

@@ -2,20 +2,21 @@ openai_sdk_helpers/__init__.py,sha256=8I469KuzrbAjhNX2A5UnYt_kSmjXqQbfHectTeUx7T
 openai_sdk_helpers/cli.py,sha256=BDc08NqWVfL4GBekxMfN5IPPB4pmN1Od9sVpKtIJRZk,8025
 openai_sdk_helpers/environment.py,sha256=mNoswzIdv37tTRhFwA2B6_Onxsm7vhfjPArfwhYuL7g,1825
 openai_sdk_helpers/errors.py,sha256=ZclLp94o08fSsFNjFn_yrX9yTjw1RE0v7A5T1hBChUc,2925
-openai_sdk_helpers/files_api.py,sha256=Sg-k4YDsrzggvICYA7h4Ua6_vGhMpZmAeS5JtQVE2hU,12598
+openai_sdk_helpers/files_api.py,sha256=kn-A2pwiNkxMd035PkWDLi_EWzccuEnGyMpLQcY-aVY,14086
 openai_sdk_helpers/logging.py,sha256=djtMo_R_88JjxJeUGU_hSlYCTRv3ffoSu1ocOKrUBIw,1153
 openai_sdk_helpers/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 openai_sdk_helpers/settings.py,sha256=9qTdEIWuvQfQEQI8MU6STUDvbOk-I9FdmAEDjb2Zwx8,13316
 openai_sdk_helpers/tools.py,sha256=8hhcytpmDfoXV16UQbDmDVV0rhLOn8c_VjXO8XaTFLQ,19000
 openai_sdk_helpers/types.py,sha256=ejCG0rYqJhjOQvKLoNnzq-TzcKCFt69GVfi7y805NkU,1451
-openai_sdk_helpers/agent/__init__.py,sha256=Nyvm8MJB-FhxhOfXD6ohDveSEUDR4KK76ffASCtgNIk,1119
-openai_sdk_helpers/agent/base.py,sha256=vEsAZ6FkaQx1vAEJkCArL-ygplOEw4546f36jA2R6Ws,26488
-openai_sdk_helpers/agent/classifier.py,sha256=6RjWhCz-hAWdHooShdUUFn0FkSWH4QZZogkRKML0S3k,25864
-openai_sdk_helpers/agent/configuration.py,sha256=FU3xnb8-8qoezLW47WwxZg7z2AxNXRW1Svl0FMsk8kc,14244
+openai_sdk_helpers/agent/__init__.py,sha256=qyzKzPhD8KsEl6d79XERK32AK5It_BZNOqChOpBdmhg,1199
+openai_sdk_helpers/agent/base.py,sha256=vLs0oALhxsd_Xy5dGjSZTUFTug-YwZkF1LabQ2ruLxk,29508
+openai_sdk_helpers/agent/classifier.py,sha256=GWgjQxkh1QbZhKlcDCkj-aNgpa8seJWxTfbtXyQSkSg,34889
+openai_sdk_helpers/agent/configuration.py,sha256=ZeH4ErgVe-BZamjUeNONbQi60ViolgYAWh-c8hNAQTw,15810
 openai_sdk_helpers/agent/coordinator.py,sha256=lVjA0yI-GhGKlqbNR_k9GOCrUjFoZ0QoqRaafHckyME,18052
-openai_sdk_helpers/agent/runner.py,sha256=l2NPS9VA9d4RISuBfanFfKxXNYSHQ7MTjRsuzx4APls,3473
+openai_sdk_helpers/agent/files.py,sha256=H7UfSZSjFUbv1cjRvNld9kZwIjc5wPq4vynqU8HgGJE,4478
+openai_sdk_helpers/agent/runner.py,sha256=uNf8FiLIlZsbSvE-CopYhv5sPAyxU2te0OaBBxO9RWY,3613
 openai_sdk_helpers/agent/summarizer.py,sha256=-yVm-KdTvGRXGj1MlEikTAFYVlPoovLNIL3Tc_WYIzs,3653
-openai_sdk_helpers/agent/translator.py,sha256=6Gj1cqT-W5j32F14sY9kOCFQenq_odceu2fi8hud_Z0,5970
+openai_sdk_helpers/agent/translator.py,sha256=Skke5wyZTpo_9gMcwHRyoBQl00zTBeXnIUujUIr2ZDE,6017
 openai_sdk_helpers/agent/utils.py,sha256=DTD5foCqGYfXf13F2bZMYIQROl7SbDSy5GDPGi0Zl-0,1089
 openai_sdk_helpers/agent/validator.py,sha256=krktzjaHhEprn76F7hD4cH6H2CwucmFN1KWJ_vjl01g,4774
 openai_sdk_helpers/agent/search/__init__.py,sha256=LXXzEcX2MU7_htHRdRCGPw0hsr9CrZn0ESii7GZJMBw,806
@@ -29,7 +30,7 @@ openai_sdk_helpers/extract/extractor.py,sha256=vmRJyhKDEYAVfRk0KMgLH5hTqUfDAUyWB
 openai_sdk_helpers/extract/generator.py,sha256=K9Euq0IaWs82oe5aRm73_18DelLKYyuH8VhfZ1_ZCEU,14695
 openai_sdk_helpers/prompt/__init__.py,sha256=MOqgKwG9KLqKudoKRlUfLxiSmdOi2aD6hNrWDFqLHkk,418
 openai_sdk_helpers/prompt/base.py,sha256=6X0zeopEvO0ba8207O8Nnj1QvFZEZier7kNNh4qkcmE,7782
-openai_sdk_helpers/prompt/classifier.jinja,sha256=PgJ8tvnuOcEa4DGbOqIrEyrG0GJ26bBpTZ7FlRZoL-s,1239
+openai_sdk_helpers/prompt/classifier.jinja,sha256=6od2DyyEUUrT0AmeJfJ57gJxJ6gdbPc11vff-VNywNk,1895
 openai_sdk_helpers/prompt/extractor_config_agent_instructions.jinja,sha256=vCrsoUnsgHWSr7OS_ojMUjmPtHfbyv9bzKfaMaCJ99E,329
 openai_sdk_helpers/prompt/extractor_config_generator.jinja,sha256=9rZ1PZdoQtnxDxFUlKRb0SooIEfNw4_Em99n9xvFyyU,960
 openai_sdk_helpers/prompt/extractor_config_generator_instructions.jinja,sha256=GqV3DrGObyER_Fa-GMGGqhWBrQIH9FFlyKdgTjidyzg,534
@@ -54,10 +55,10 @@ openai_sdk_helpers/response/vector_store.py,sha256=HClp6O_g20uklQTY7trC4age3rtDm
 openai_sdk_helpers/streamlit_app/__init__.py,sha256=3yAkl6qV71cqtT5YFZuC9Bkqit0NtffDV6jmMWpT1k4,812
 openai_sdk_helpers/streamlit_app/app.py,sha256=kkjtdCKVwrJ9nZWuBArm3dhvcjMESX0TMqAiF61_JLM,17402
 openai_sdk_helpers/streamlit_app/configuration.py,sha256=0KeJ4HqCNFthBHsedV6ptqHluAcTPBb5_TujFOGkIUU,16685
-openai_sdk_helpers/structure/__init__.py,sha256=-_bEFvvKhg99bgsMnimpxx7RpLQpQyReSMquOc-2Ts8,4173
+openai_sdk_helpers/structure/__init__.py,sha256=ErtNlTADV4cc7s27i_CbQATd2PD9xcJd8_D273QmyOI,4253
 openai_sdk_helpers/structure/agent_blueprint.py,sha256=VyJWkgPNzAYKRDMeR1M4kE6qqQURnwqtrrEn0TRJf0g,9698
 openai_sdk_helpers/structure/base.py,sha256=UrnNNU9qQ9mEES8MB9y6QESbDgPXH47XW8LVWSxYUYM,25280
-openai_sdk_helpers/structure/classification.py,sha256=q7d9x2Ya7ICBr6rk5SOSrQrW5lDLat345wHQisKZO7Y,13351
+openai_sdk_helpers/structure/classification.py,sha256=Vk7LGG3pty5T0Eh94Pao7kWY8_Wcuw37ywdPDcnElrg,15316
 openai_sdk_helpers/structure/extraction.py,sha256=wODP0iLAhhsdQkMWRYPYTiLUMU8bFMKiBjPl3PKUleg,37335
 openai_sdk_helpers/structure/prompt.py,sha256=ZfsaHdA0hj5zmZDrOdpXjCsC8U-jjzwFG4JBsWYiaH4,1535
 openai_sdk_helpers/structure/responses.py,sha256=WUwh0DhXj24pkvgqH1FMkdx5V2ArdvdtrDN_fuMBtDU,4882
@@ -91,8 +92,8 @@ openai_sdk_helpers/vector_storage/__init__.py,sha256=L5LxO09puh9_yBB9IDTvc1CvVkA
 openai_sdk_helpers/vector_storage/cleanup.py,sha256=sZ4ZSTlnjF52o9Cc8A9dTX37ZYXXDxS_fdIpoOBWvrg,3666
 openai_sdk_helpers/vector_storage/storage.py,sha256=t_ukacaXRa9EXE4-3BxsrB4Rjhu6nTu7NA9IjCJBIpQ,24259
 openai_sdk_helpers/vector_storage/types.py,sha256=jTCcOYMeOpZWvcse0z4T3MVs-RBOPC-fqWTBeQrgafU,1639
-openai_sdk_helpers-0.6.1.dist-info/METADATA,sha256=S0KXq5lr2GHbi8uYDac-sn7W4ug5WlIjMqNXjXXHBj0,24622
-openai_sdk_helpers-0.6.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-openai_sdk_helpers-0.6.1.dist-info/entry_points.txt,sha256=gEOD1ZeXe8d2OP-KzUlG-b_9D9yUZTCt-GFW3EDbIIY,63
-openai_sdk_helpers-0.6.1.dist-info/licenses/LICENSE,sha256=CUhc1NrE50bs45tcXF7OcTQBKEvkUuLqeOHgrWQ5jaA,1067
-openai_sdk_helpers-0.6.1.dist-info/RECORD,,
+openai_sdk_helpers-0.6.2.dist-info/METADATA,sha256=TGZjA_nQ2FDm9KeEjun4MrIAUl-zAxB-Xi5UCUkn8nY,24622
+openai_sdk_helpers-0.6.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+openai_sdk_helpers-0.6.2.dist-info/entry_points.txt,sha256=gEOD1ZeXe8d2OP-KzUlG-b_9D9yUZTCt-GFW3EDbIIY,63
+openai_sdk_helpers-0.6.2.dist-info/licenses/LICENSE,sha256=CUhc1NrE50bs45tcXF7OcTQBKEvkUuLqeOHgrWQ5jaA,1067
+openai_sdk_helpers-0.6.2.dist-info/RECORD,,