openai-sdk-helpers 0.6.1__tar.gz → 0.6.2__tar.gz

{openai_sdk_helpers-0.6.1 → openai_sdk_helpers-0.6.2}/PKG-INFO

@@ -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 → openai_sdk_helpers-0.6.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "openai-sdk-helpers"
-version = "0.6.1"
+version = "0.6.2"
 requires-python = ">=3.10"
 readme = "README.md"
 description = "Composable helpers for OpenAI SDK agents, prompts, and storage"

{openai_sdk_helpers-0.6.1 → openai_sdk_helpers-0.6.2}/src/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-0.6.1 → openai_sdk_helpers-0.6.2}/src/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-0.6.1 → openai_sdk_helpers-0.6.2}/src/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-0.6.1 → openai_sdk_helpers-0.6.2}/src/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.