openai-sdk-helpers 0.4.1__py3-none-any.whl → 0.4.3__py3-none-any.whl

openai_sdk_helpers/__init__.py

@@ -2,14 +2,9 @@
 
 from __future__ import annotations
 
+from .environment import get_data_path
 from .utils.async_utils import run_coroutine_thread_safe, run_coroutine_with_fallback
-from .context_manager import (
-    AsyncManagedResource,
-    ManagedResource,
-    async_context,
-    ensure_closed,
-    ensure_closed_async,
-)
+
 from .errors import (
     OpenAISDKError,
     ConfigurationError,
@@ -22,7 +17,7 @@ from .errors import (
     AsyncExecutionError,
     ResourceCleanupError,
 )
-from .retry import with_exponential_backoff
+
 from .utils.validation import (
     validate_choice,
     validate_dict_mapping,
@@ -50,7 +45,7 @@ from .structure import (
     execute_plan,
 )
 from .prompt import PromptRenderer
-from .config import OpenAISettings
+from .settings import OpenAISettings
 from .files_api import FilesAPIManager, FilePurpose
 from .vector_storage import VectorStorage, VectorStorageFileInfo, VectorStorageFileStats
 from .agent import (
@@ -61,7 +56,7 @@ from .agent import (
     SummarizerAgent,
     TranslatorAgent,
     ValidatorAgent,
-    VectorSearch,
+    VectorAgentSearch,
     WebAgentSearch,
 )
 from .response import (
@@ -82,12 +77,7 @@ from .tools import (
     ToolSpec,
     build_tool_definitions,
 )
-from .config import build_openai_settings
-from .utils.deprecation import (
-    deprecated,
-    warn_deprecated,
-    DeprecationHelper,
-)
+from .settings import build_openai_settings
 from .utils.output_validation import (
     ValidationResult,
     ValidationRule,
@@ -97,12 +87,11 @@ from .utils.output_validation import (
     OutputValidator,
     validate_output,
 )
-from .types import (
-    SupportsOpenAIClient,
-    OpenAIClient,
-)
+
 
 __all__ = [
+    # Environment utilities
+    "get_data_path",
     # Async utilities
     "run_coroutine_thread_safe",
     "run_coroutine_with_fallback",
@@ -117,14 +106,6 @@ __all__ = [
     "InputValidationError",
     "AsyncExecutionError",
     "ResourceCleanupError",
-    # Retry utilities
-    "with_exponential_backoff",
-    # Context managers
-    "ManagedResource",
-    "AsyncManagedResource",
-    "ensure_closed",
-    "ensure_closed_async",
-    "async_context",
     # Validation
     "validate_non_empty_string",
     "validate_max_length",
@@ -156,7 +137,7 @@ __all__ = [
     "SummarizerAgent",
     "TranslatorAgent",
     "ValidatorAgent",
-    "VectorSearch",
+    "VectorAgentSearch",
     "WebAgentSearch",
     "ExtendedSummaryStructure",
     "WebSearchStructure",
@@ -180,13 +161,6 @@ __all__ = [
     "create_plan",
     "execute_task",
     "execute_plan",
-    # Type definitions
-    "SupportsOpenAIClient",
-    "OpenAIClient",
-    # Deprecation utilities
-    "deprecated",
-    "warn_deprecated",
-    "DeprecationHelper",
     # Output validation
     "ValidationResult",
     "ValidationRule",

openai_sdk_helpers/agent/__init__.py

@@ -1,18 +1,17 @@
 """Shared agent helpers built on the OpenAI Agents SDK."""
 
 from __future__ import annotations
-
 from .base import AgentBase
-from .config import AgentConfiguration, AgentRegistry, get_default_registry
+from .configuration import AgentConfiguration, AgentRegistry, get_default_registry
 from ..structure.plan.enum import AgentEnum
-from .coordination import CoordinatorAgent
+from .coordinator import CoordinatorAgent
 from .runner import run_sync, run_async, run_streamed
 from .search.base import SearchPlanner, SearchToolAgent, SearchWriter
 from .summarizer import SummarizerAgent
 from .translator import TranslatorAgent
-from .validation import ValidatorAgent
+from .validator import ValidatorAgent
 from .utils import run_coroutine_agent_sync
-from .search.vector import VectorSearch
+from .search.vector import VectorAgentSearch
 from .search.web import WebAgentSearch
 
 __all__ = [
@@ -32,6 +31,6 @@ __all__ = [
     "SummarizerAgent",
     "TranslatorAgent",
     "ValidatorAgent",
-    "VectorSearch",
+    "VectorAgentSearch",
     "WebAgentSearch",
 ]

openai_sdk_helpers/agent/base.py

@@ -2,8 +2,9 @@
 
 from __future__ import annotations
 
+import json
 from pathlib import Path
-from typing import Any, Callable, Dict, Optional, Protocol, cast
+from typing import TYPE_CHECKING, Any, Callable, Dict, Optional, Protocol, cast
 import uuid
 
 from agents import (
@@ -21,14 +22,22 @@ from jinja2 import Template
 
 from ..utils.json.data_class import DataclassJSONSerializable
 from ..structure.base import StructureBase
+from ..structure.prompt import PromptStructure
+
 
 from ..utils import (
     check_filepath,
     log,
 )
 
+from ..tools import tool_handler_factory
+
 from .runner import run_async, run_streamed, run_sync
 
+if TYPE_CHECKING:
+    from ..settings import OpenAISettings
+    from ..response.base import ResponseBase, ToolHandler
+
 
 class AgentConfigurationProtocol(Protocol):
     """Protocol describing the configuration attributes for AgentBase."""
@@ -122,22 +131,22 @@ class AgentBase(DataclassJSONSerializable):
     Create a basic agent from configuration:
 
     >>> from openai_sdk_helpers.agent import AgentBase, AgentConfiguration
-    >>> config = AgentConfiguration(
+    >>> configuration = AgentConfiguration(
     ...     name="my_agent",
     ...     description="A custom agent",
     ...     model="gpt-4o-mini"
     ... )
-    >>> agent = AgentBase(config=config, default_model="gpt-4o-mini")
+    >>> agent = AgentBase(configuration=configuration, default_model="gpt-4o-mini")
     >>> result = agent.run_sync("What is 2+2?")
 
     Use absolute path to template:
 
-    >>> config = AgentConfiguration(
+    >>> configuration = AgentConfiguration(
     ...     name="my_agent",
     ...     template_path="/absolute/path/to/template.jinja",
     ...     model="gpt-4o-mini"
     ... )
-    >>> agent = AgentBase(config=config, default_model="gpt-4o-mini")
+    >>> agent = AgentBase(configuration=configuration, default_model="gpt-4o-mini")
 
     Use async execution:
 
@@ -181,6 +190,10 @@ class AgentBase(DataclassJSONSerializable):
         Return a streaming result for the agent execution.
     as_tool()
         Return the agent as a callable tool.
+    as_response_tool()
+        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.
     close()
         Clean up agent resources (can be overridden by subclasses).
     """
@@ -188,7 +201,7 @@ class AgentBase(DataclassJSONSerializable):
     def __init__(
         self,
         *,
-        config: AgentConfigurationProtocol,
+        configuration: AgentConfigurationProtocol,
         run_context_wrapper: Optional[RunContextWrapper[Dict[str, Any]]] = None,
         data_path: Path | str | None = None,
         prompt_dir: Optional[Path] = None,
@@ -198,29 +211,29 @@ class AgentBase(DataclassJSONSerializable):
 
         Parameters
         ----------
-        config : AgentConfigurationProtocol
+        configuration : AgentConfigurationProtocol
             Configuration describing this agent.
         run_context_wrapper : RunContextWrapper or None, default=None
             Optional wrapper providing runtime context for prompt rendering.
         prompt_dir : Path or None, default=None
             Optional directory holding prompt templates. Used when
-            ``config.template_path`` is not provided or is relative. If
-            ``config.template_path`` is an absolute path, this parameter is
+            ``configuration.template_path`` is not provided or is relative. If
+            ``configuration.template_path`` is an absolute path, this parameter is
             ignored.
         default_model : str or None, default=None
-            Optional fallback model identifier if the config does not supply one.
+            Optional fallback model identifier if the configuration does not supply one.
         """
-        name = config.name
-        description = config.description or ""
-        model = config.model or default_model
+        name = configuration.name
+        description = configuration.description or ""
+        model = configuration.model or default_model
         if not model:
             raise ValueError("Model is required to construct the agent.")
 
-        prompt_path = config.resolve_prompt_path(prompt_dir)
+        prompt_path = configuration.resolve_prompt_path(prompt_dir)
 
         # Build template from file or fall back to instructions
         if prompt_path is None:
-            instructions_text = config.instructions_text
+            instructions_text = configuration.instructions_text
             self._template = Template(instructions_text)
             self._instructions = instructions_text
         elif prompt_path.exists():
@@ -249,14 +262,16 @@ class AgentBase(DataclassJSONSerializable):
 
             self._data_path = get_data_path(self.__class__.__name__)
 
-        self._input_structure = config.input_structure
-        self._output_structure = config.output_structure or config.input_structure
-        self._tools = config.tools
-        self._model_settings = config.model_settings
-        self._handoffs = config.handoffs
-        self._input_guardrails = config.input_guardrails
-        self._output_guardrails = config.output_guardrails
-        self._session = config.session
+        self._input_structure = configuration.input_structure
+        self._output_structure = (
+            configuration.output_structure or configuration.input_structure
+        )
+        self._tools = configuration.tools
+        self._model_settings = configuration.model_settings
+        self._handoffs = configuration.handoffs
+        self._input_guardrails = configuration.input_guardrails
+        self._output_guardrails = configuration.output_guardrails
+        self._session = configuration.session
         self._run_context_wrapper = run_context_wrapper
 
     def _build_prompt_from_jinja(self) -> str:
@@ -462,7 +477,7 @@ class AgentBase(DataclassJSONSerializable):
             Optional type used to cast the final output.
         session : Session or None, default=None
             Optional session for maintaining conversation history across runs.
-            If not provided, uses the session from config if available.
+            If not provided, uses the session from configuration if available.
 
         Returns
         -------
@@ -471,7 +486,7 @@ class AgentBase(DataclassJSONSerializable):
         """
         if self._output_structure is not None and output_structure is None:
             output_structure = self._output_structure
-        # Use session from parameter, fall back to config session
+        # Use session from parameter, fall back to configuration session
         session_to_use = session if session is not None else self._session
         return await run_async(
             agent=self.get_agent(),
@@ -501,7 +516,7 @@ class AgentBase(DataclassJSONSerializable):
             Optional type used to cast the final output.
         session : Session or None, default=None
             Optional session for maintaining conversation history across runs.
-            If not provided, uses the session from config if available.
+            If not provided, uses the session from configuration if available.
 
         Returns
         -------
@@ -510,7 +525,7 @@ class AgentBase(DataclassJSONSerializable):
         """
         if self._output_structure is not None and output_structure is None:
             output_structure = self._output_structure
-        # Use session from parameter, fall back to config session
+        # Use session from parameter, fall back to configuration session
         session_to_use = session if session is not None else self._session
         return run_sync(
             agent=self.get_agent(),
@@ -540,14 +555,14 @@ class AgentBase(DataclassJSONSerializable):
             Optional type used to cast the final output.
         session : Session or None, default=None
             Optional session for maintaining conversation history across runs.
-            If not provided, uses the session from config if available.
+            If not provided, uses the session from configuration if available.
 
         Returns
         -------
         RunResultStreaming
             Streaming output wrapper from the agent execution.
         """
-        # Use session from parameter, fall back to config session
+        # Use session from parameter, fall back to configuration session
         session_to_use = session if session is not None else self._session
         output_structure_to_use = output_structure or self._output_structure
         result = run_streamed(
@@ -575,26 +590,156 @@ class AgentBase(DataclassJSONSerializable):
         )
         return tool_obj
 
-    def as_response_tool(self) -> tuple[dict[str, Callable[..., Any]], dict[str, Any]]:
-        """Return the agent as a callable response tool.
+    def as_response_tool(
+        self,
+        *,
+        tool_name: str | None = None,
+        tool_description: str | None = None,
+    ) -> tuple[dict[str, Callable[..., Any]], dict[str, Any]]:
+        """Return response tool handler and definition for Responses API use.
+
+        The returned handler serializes tool output as JSON using
+        ``tool_handler_factory`` so downstream response flows can rely on a
+        consistent payload format.
+
+        Parameters
+        ----------
+        tool_name : str or None, default=None
+            Optional override for the tool name. When None, uses the agent name.
+        tool_description : str or None, default=None
+            Optional override for the tool description. When None, uses the
+            agent description.
 
         Returns
         -------
-        Tool
-            Tool instance wrapping this agent for response generation.
+        tuple[dict[str, Callable[..., Any]], dict[str, Any]]
+            Tool handler mapping and tool definition for Responses API usage.
+
+        Examples
+        --------
+        >>> tool_handler, tool_definition = agent.as_response_tool()
+        >>> response = ResponseBase(
+        ...     name="agent_tool",
+        ...     instructions="Use the agent tool when needed.",
+        ...     tools=[tool_definition],
+        ...     output_structure=None,
+        ...     tool_handlers=tool_handler,
+        ...     openai_settings=settings,
+        ... )
+        >>> response.run_sync("Invoke the agent tool")  # doctest: +SKIP
         """
-        tool_handler = {self.name: self.run_sync}
+
+        def _run_agent(**kwargs: Any) -> Any:
+            prompt = kwargs.get("prompt")
+            if prompt is None:
+                if len(kwargs) == 1:
+                    prompt = next(iter(kwargs.values()))
+                else:
+                    prompt = json.dumps(kwargs)
+            return self.run_sync(str(prompt))
+
+        name = tool_name or self.name
+        description = tool_description or self.description
+        input_model = self._input_structure or PromptStructure
+        tool_handler = {name: tool_handler_factory(_run_agent, input_model=input_model)}
         tool_definition = {
             "type": "function",
-            "name": self.name,
-            "description": self.description,
+            "name": name,
+            "description": description,
             "strict": True,
             "additionalProperties": False,
+            "parameters": self._build_response_parameters(),
         }
-        if self.output_structure:
-            tool_definition["parameters"] = self.output_structure.get_schema()
         return tool_handler, tool_definition
 
+    def build_response(
+        self,
+        *,
+        openai_settings: OpenAISettings,
+        data_path: Path | str | None = None,
+        tool_handlers: dict[str, ToolHandler] | None = None,
+        system_vector_store: list[str] | None = None,
+    ) -> ResponseBase[StructureBase]:
+        """Build a ResponseBase instance from this agent configuration.
+
+        Parameters
+        ----------
+        openai_settings : OpenAISettings
+            Authentication and model settings applied to the generated response.
+        data_path : Path, str, or None, default None
+            Optional path for storing response artifacts. When None, the
+            response uses the default data directory.
+        tool_handlers : dict[str, ToolHandler] or None, default None
+            Optional mapping of tool names to handler callables.
+        system_vector_store : list[str] or None, default None
+            Optional list of vector store names to attach as system context.
+
+        Returns
+        -------
+        ResponseBase[StructureBase]
+            ResponseBase instance configured with this agent's settings.
+
+        Examples
+        --------
+        >>> from openai_sdk_helpers import OpenAISettings
+        >>> response = agent.build_response(openai_settings=OpenAISettings.from_env())
+        """
+        from ..response.base import ResponseBase, ToolHandler
+        from ..settings import OpenAISettings
+
+        if not isinstance(openai_settings, OpenAISettings):
+            raise TypeError("openai_settings must be an OpenAISettings instance")
+
+        tools = self._normalize_response_tools(self.tools)
+
+        return ResponseBase(
+            name=self.name,
+            instructions=self.instructions_text,
+            tools=tools,
+            output_structure=self.output_structure,
+            system_vector_store=system_vector_store,
+            data_path=data_path,
+            tool_handlers=tool_handlers,
+            openai_settings=openai_settings,
+        )
+
+    def _build_response_parameters(self) -> dict[str, Any]:
+        """Build the Responses API parameter schema for this agent tool.
+
+        Returns
+        -------
+        dict[str, Any]
+            JSON schema describing tool input parameters.
+        """
+        if self._input_structure is not None:
+            return self._input_structure.get_schema()
+        return {
+            "type": "object",
+            "properties": {
+                "prompt": {"type": "string", "description": "Prompt text to run."}
+            },
+            "required": ["prompt"],
+            "additionalProperties": False,
+        }
+
+    @staticmethod
+    def _normalize_response_tools(tools: Optional[list]) -> Optional[list]:
+        """Normalize tool definitions for the Responses API."""
+        if not tools:
+            return tools
+
+        normalized: list[Any] = []
+        for tool in tools:
+            if hasattr(tool, "to_dict") and callable(tool.to_dict):
+                normalized.append(tool.to_dict())
+            elif hasattr(tool, "to_openai_tool") and callable(tool.to_openai_tool):
+                normalized.append(tool.to_openai_tool())
+            elif hasattr(tool, "schema"):
+                normalized.append(tool.schema)
+            else:
+                normalized.append(tool)
+        return normalized
+
     def __enter__(self) -> AgentBase:
         """Enter the context manager for resource management.
 
@@ -628,7 +773,7 @@ class AgentBase(DataclassJSONSerializable):
 
         Examples
         --------
-        >>> agent = AgentBase(config, default_model="gpt-4o-mini")
+        >>> agent = AgentBase(configuration, default_model="gpt-4o-mini")
         >>> try:
         ...     result = agent.run_sync("query")
         ... finally: