openai-sdk-helpers 0.4.0__tar.gz → 0.4.2__tar.gz

{openai_sdk_helpers-0.4.0 → openai_sdk_helpers-0.4.2}/PKG-INFO

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

{openai_sdk_helpers-0.4.0 → openai_sdk_helpers-0.4.2}/pyproject.toml

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

{openai_sdk_helpers-0.4.0 → openai_sdk_helpers-0.4.2}/src/openai_sdk_helpers/__init__.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+from .environment import get_data_path, get_model
 from .utils.async_utils import run_coroutine_thread_safe, run_coroutine_with_fallback
 from .context_manager import (
     AsyncManagedResource,
@@ -61,7 +62,7 @@ from .agent import (
     SummarizerAgent,
     TranslatorAgent,
     ValidatorAgent,
-    VectorSearch,
+    VectorAgentSearch,
     WebAgentSearch,
 )
 from .response import (
@@ -103,6 +104,9 @@ from .types import (
 )
 
 __all__ = [
+    # Environment utilities
+    "get_data_path",
+    "get_model",
     # Async utilities
     "run_coroutine_thread_safe",
     "run_coroutine_with_fallback",
@@ -156,7 +160,7 @@ __all__ = [
     "SummarizerAgent",
     "TranslatorAgent",
     "ValidatorAgent",
-    "VectorSearch",
+    "VectorAgentSearch",
     "WebAgentSearch",
     "ExtendedSummaryStructure",
     "WebSearchStructure",

{openai_sdk_helpers-0.4.0 → openai_sdk_helpers-0.4.2}/src/openai_sdk_helpers/agent/__init__.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from .base import AgentBase
-from .config import AgentConfiguration, AgentConfigurationRegistry, get_default_registry
+from .config import AgentConfiguration, AgentRegistry, get_default_registry
 from ..structure.plan.enum import AgentEnum
 from .coordination import CoordinatorAgent
 from .runner import run_sync, run_async, run_streamed
@@ -12,13 +12,13 @@ from .summarizer import SummarizerAgent
 from .translator import TranslatorAgent
 from .validation 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__ = [
     "AgentBase",
     "AgentConfiguration",
-    "AgentConfigurationRegistry",
+    "AgentRegistry",
     "get_default_registry",
     "AgentEnum",
     "CoordinatorAgent",
@@ -32,6 +32,6 @@ __all__ = [
     "SummarizerAgent",
     "TranslatorAgent",
     "ValidatorAgent",
-    "VectorSearch",
+    "VectorAgentSearch",
     "WebAgentSearch",
 ]

{openai_sdk_helpers-0.4.0 → openai_sdk_helpers-0.4.2}/src/openai_sdk_helpers/agent/base.py

@@ -2,8 +2,9 @@
 
 from __future__ import annotations
 
+import json
 from pathlib import Path
-from typing import Any, Dict, Optional, Protocol, cast
+from typing import TYPE_CHECKING, Any, Callable, Dict, Optional, Protocol, cast
 import uuid
 
 from agents import (
@@ -21,16 +22,23 @@ 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 ..config import OpenAISettings
+    from ..response.base import ResponseBase, ToolHandler
+
 
-class AgentConfigurationLike(Protocol):
+class AgentConfigurationProtocol(Protocol):
     """Protocol describing the configuration attributes for AgentBase."""
 
     @property
@@ -181,6 +189,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 +200,7 @@ class AgentBase(DataclassJSONSerializable):
     def __init__(
         self,
         *,
-        config: AgentConfigurationLike,
+        config: AgentConfigurationProtocol,
         run_context_wrapper: Optional[RunContextWrapper[Dict[str, Any]]] = None,
         data_path: Path | str | None = None,
         prompt_dir: Optional[Path] = None,
@@ -198,7 +210,7 @@ class AgentBase(DataclassJSONSerializable):
 
         Parameters
         ----------
-        config : AgentConfigurationLike
+        config : AgentConfigurationProtocol
             Configuration describing this agent.
         run_context_wrapper : RunContextWrapper or None, default=None
             Optional wrapper providing runtime context for prompt rendering.
@@ -428,7 +440,7 @@ class AgentBase(DataclassJSONSerializable):
             "model": self.model,
         }
         if self._output_structure:
-            agent_config["output_structure"] = self._output_structure
+            agent_config["output_type"] = self._output_structure
         if self._tools:
             agent_config["tools"] = self._tools
         if self._model_settings:
@@ -575,6 +587,156 @@ class AgentBase(DataclassJSONSerializable):
         )
         return tool_obj
 
+    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
+        -------
+        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
+        """
+
+        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": name,
+            "description": description,
+            "strict": True,
+            "additionalProperties": False,
+            "parameters": self._build_response_parameters(),
+        }
+        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 ..config 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.
 
@@ -651,4 +813,4 @@ class AgentBase(DataclassJSONSerializable):
         log(f"Saved messages to {target}")
 
 
-__all__ = ["AgentConfigurationLike", "AgentBase"]
+__all__ = ["AgentConfigurationProtocol", "AgentBase"]

{openai_sdk_helpers-0.4.0 → openai_sdk_helpers-0.4.2}/src/openai_sdk_helpers/agent/config.py

@@ -10,20 +10,20 @@ from agents import Agent, Handoff, InputGuardrail, OutputGuardrail, Session
 from agents.model_settings import ModelSettings
 
 from ..utils.json.data_class import DataclassJSONSerializable
-from ..utils.registry import BaseRegistry
+from ..utils.registry import RegistryBase
 from ..utils.instructions import resolve_instructions_from_path
 from ..structure.base import StructureBase
 
 
-class AgentConfigurationRegistry(BaseRegistry["AgentConfiguration"]):
+class AgentRegistry(RegistryBase["AgentConfiguration"]):
     """Registry for managing AgentConfiguration instances.
 
-    Inherits from BaseRegistry to provide centralized storage and retrieval
+    Inherits from RegistryBase to provide centralized storage and retrieval
     of agent configurations, enabling reusable agent specs across the application.
 
     Examples
     --------
-    >>> registry = AgentConfigurationRegistry()
+    >>> registry = AgentRegistry()
     >>> config = AgentConfiguration(
     ...     name="test_agent",
     ...     model="gpt-4o-mini",
@@ -65,7 +65,7 @@ class AgentConfigurationRegistry(BaseRegistry["AgentConfiguration"]):
 
         Examples
         --------
-        >>> registry = AgentConfigurationRegistry()
+        >>> registry = AgentRegistry()
         >>> count = registry.load_from_directory("./agents")
         >>> print(f"Loaded {count} configurations")
         """
@@ -74,12 +74,12 @@ class AgentConfigurationRegistry(BaseRegistry["AgentConfiguration"]):
         return super().load_from_directory(path, config_class=config_class)
 
 
-def get_default_registry() -> AgentConfigurationRegistry:
+def get_default_registry() -> AgentRegistry:
     """Return the global default registry instance.
 
     Returns
     -------
-    AgentConfigurationRegistry
+    AgentRegistry
         Singleton registry for application-wide configuration storage.
 
     Examples
@@ -187,9 +187,8 @@ class AgentConfiguration(DataclassJSONSerializable):
     input_guardrails: Optional[list[InputGuardrail]] = None
     output_guardrails: Optional[list[OutputGuardrail]] = None
     session: Optional[Session] = None
-    _instructions_cache: Optional[str] = field(
-        default=None, init=False, repr=False, compare=False
-    )
+    add_output_instructions: bool = False
+    add_web_search_tool: bool = False
 
     def __post_init__(self) -> None:
         """Validate configuration invariants after initialization.
@@ -258,11 +257,16 @@ class AgentConfiguration(DataclassJSONSerializable):
         str
             Plain-text instructions, loading template files when necessary.
         """
-        cached = self._instructions_cache
-        if cached is None:
-            cached = self._resolve_instructions()
-            object.__setattr__(self, "_instructions_cache", cached)
-        return cached
+        resolved_instructions: str = resolve_instructions_from_path(self.instructions)
+        output_instructions = ""
+        if self.output_structure is not None and self.add_output_instructions:
+            output_instructions = self.output_structure.get_prompt(
+                add_enum_values=False
+            )
+            if output_instructions:
+                return f"{resolved_instructions}\n{output_instructions}"
+
+        return resolved_instructions
 
     def _resolve_instructions(self) -> str:
         """Resolve instructions from string or file path."""
@@ -361,69 +365,40 @@ class AgentConfiguration(DataclassJSONSerializable):
 
         return replace(self, **changes)
 
-    def to_json(self) -> dict[str, Any]:
-        """Return a JSON-compatible dict representation.
-
-        Returns
-        -------
-        dict[str, Any]
-            Serialized configuration data without cached fields.
-        """
-        data = DataclassJSONSerializable.to_json(self)
-        data.pop("_instructions_cache", None)
-        return data
-
-    @classmethod
-    def from_json(cls, data: dict[str, Any]) -> AgentConfiguration:
-        """Create an AgentConfiguration from JSON data.
+    def to_response_config(self) -> Any:
+        """Convert this AgentConfiguration to a ResponseConfiguration.
 
-        Overrides the default JSONSerializable.from_json to properly handle
-        the instructions field, converting string paths that look like file
-        paths back to Path objects for proper file loading.
-
-        Parameters
-        ----------
-        data : dict[str, Any]
-            Dictionary containing the configuration data.
+        This is a convenience method for creating a ResponseConfiguration
+        instance using the relevant fields from this agent configuration.
 
         Returns
         -------
-        AgentConfiguration
-            New configuration instance.
-
-        Notes
-        -----
-        This method attempts to preserve the original type of the instructions
-        field. If instructions is a string that represents an existing file path,
-        it will be converted to a Path object to ensure proper file loading
-        behavior is maintained across JSON round-trips.
+        ResponseConfiguration
+            New response configuration instance.
+
+        Examples
+        --------
+        >>> agent_config = AgentConfiguration(
+        ...     name="responder",
+        ...     model="gpt-4o-mini",
+        ...     instructions="Respond to user queries"
+        ... )
+        >>> response_config = agent_config.to_response_config()
+        >>> response_config.name
+        'responder'
         """
-        # Make a copy to avoid modifying the input
-        data = data.copy()
-        data.pop("_instructions_cache", None)
-
-        # Handle instructions field: if it's a string path to an existing file,
-        # convert it back to Path for proper file loading
-        if "instructions" in data and data["instructions"] is not None:
-            instructions_value = data["instructions"]
-            if isinstance(instructions_value, str):
-                # Check if it looks like a file path and the file exists
-                # This preserves the intended behavior for file-based instructions
-                try:
-                    potential_path = Path(instructions_value)
-                    # Only convert to Path if it's an existing file
-                    # This way, plain text instructions stay as strings
-                    if potential_path.exists() and potential_path.is_file():
-                        data["instructions"] = potential_path
-                except (OSError, ValueError):
-                    # If path parsing fails, keep it as a string (likely plain text)
-                    pass
-
-        # Use the parent class method for the rest
-        return super(AgentConfiguration, cls).from_json(data)
+        from ..response.config import ResponseConfiguration
+
+        return ResponseConfiguration(
+            name=self.name,
+            instructions=self.instructions,
+            input_structure=self.input_structure,
+            output_structure=self.output_structure,
+            tools=self.tools,
+        )
 
 
 # Global default registry instance
-_default_registry = AgentConfigurationRegistry()
+_default_registry = AgentRegistry()
 
-__all__ = ["AgentConfiguration", "AgentConfigurationRegistry", "get_default_registry"]
+__all__ = ["AgentConfiguration", "AgentRegistry", "get_default_registry"]

{openai_sdk_helpers-0.4.0 → openai_sdk_helpers-0.4.2}/src/openai_sdk_helpers/agent/search/__init__.py

@@ -10,10 +10,10 @@ from .web import (
 )
 from .vector import (
     MAX_CONCURRENT_SEARCHES as VECTOR_MAX_CONCURRENT_SEARCHES,
-    VectorSearchPlanner,
+    VectorAgentPlanner,
     VectorSearchTool,
     VectorSearchWriter,
-    VectorSearch,
+    VectorAgentSearch,
 )
 
 __all__ = [
@@ -26,8 +26,8 @@ __all__ = [
     "WebAgentWriter",
     "WebAgentSearch",
     "VECTOR_MAX_CONCURRENT_SEARCHES",
-    "VectorSearchPlanner",
+    "VectorAgentPlanner",
     "VectorSearchTool",
     "VectorSearchWriter",
-    "VectorSearch",
+    "VectorAgentSearch",
 ]

{openai_sdk_helpers-0.4.0 → openai_sdk_helpers-0.4.2}/src/openai_sdk_helpers/agent/search/vector.py

@@ -7,6 +7,7 @@ from typing import Any, Callable, Dict, List, Optional
 
 from agents import custom_span, gen_trace_id, trace
 
+from ...structure.prompt import PromptStructure
 from ...structure.vector_search import (
     VectorSearchItemStructure,
     VectorSearchItemResultStructure,
@@ -15,6 +16,7 @@ from ...structure.vector_search import (
     VectorSearchPlanStructure,
     VectorSearchReportStructure,
 )
+from ...tools import tool_handler_factory
 from ...vector_storage import VectorStorage
 from ..config import AgentConfiguration
 from ..utils import run_coroutine_agent_sync
@@ -23,7 +25,7 @@ from .base import SearchPlanner, SearchToolAgent, SearchWriter
 MAX_CONCURRENT_SEARCHES = 10
 
 
-class VectorSearchPlanner(SearchPlanner[VectorSearchPlanStructure]):
+class VectorAgentPlanner(SearchPlanner[VectorSearchPlanStructure]):
     """Plan vector searches to satisfy a user query.
 
     Parameters
@@ -241,7 +243,7 @@ class VectorSearchWriter(SearchWriter[VectorSearchReportStructure]):
         )
 
 
-class VectorSearch:
+class VectorAgentSearch:
     """Manage the complete vector search workflow.
 
     This high-level agent orchestrates a multi-step research process that plans
@@ -292,6 +294,8 @@ class VectorSearch:
         Execute the research workflow asynchronously.
     run_agent_sync(search_query)
         Execute the research workflow synchronously.
+    as_response_tool(vector_store_name, tool_name, tool_description)
+        Build a Responses API tool definition and handler.
     run_vector_agent(search_query)
         Convenience asynchronous entry point for the workflow.
     run_vector_agent_sync(search_query)
@@ -306,9 +310,9 @@ class VectorSearch:
     def __init__(
         self,
         *,
+        vector_store_name: str,
         prompt_dir: Optional[Path] = None,
         default_model: Optional[str] = None,
-        vector_store_name: Optional[str] = None,
         max_concurrent_searches: int = MAX_CONCURRENT_SEARCHES,
         vector_storage: Optional[VectorStorage] = None,
         vector_storage_factory: Optional[Callable[[str], VectorStorage]] = None,
@@ -336,7 +340,7 @@ class VectorSearch:
         """
         trace_id = gen_trace_id()
         with trace("VectorSearch trace", trace_id=trace_id):
-            planner = VectorSearchPlanner(
+            planner = VectorAgentPlanner(
                 prompt_dir=self._prompt_dir, default_model=self._default_model
             )
             tool = VectorSearchTool(
@@ -383,45 +387,53 @@ class VectorSearch:
         """
         return run_coroutine_agent_sync(self.run_agent(search_query))
 
-    @staticmethod
-    async def run_vector_agent(search_query: str) -> VectorSearchStructure:
-        """Return a research report for the given query using ``VectorSearch``.
+    def as_response_tool(
+        self,
+        *,
+        tool_name: str = "vector_search",
+        tool_description: str = "Run the vector search workflow.",
+    ) -> tuple[dict[str, Callable[..., Any]], dict[str, Any]]:
+        """Return a Responses API tool handler and definition.
 
         Parameters
         ----------
-        search_query : str
-            User's research query.
+        vector_store_name : str
+            Name of the vector store to use for the response tool.
+        tool_name : str, default="vector_search"
+            Name to use for the response tool.
+        tool_description : str, default="Run the vector search workflow."
+            Description for the response tool.
 
         Returns
         -------
-        VectorSearchStructure
-            Completed research output.
+        tuple[dict[str, Callable[..., Any]], dict[str, Any]]
+            Tool handler mapping and tool definition for Responses API usage.
         """
-        return await VectorSearch().run_agent(search_query=search_query)
+        search = VectorAgentSearch(
+            prompt_dir=self._prompt_dir,
+            default_model=self._default_model,
+            vector_store_name=self._vector_store_name,
+            max_concurrent_searches=self._max_concurrent_searches,
+            vector_storage=self._vector_storage,
+            vector_storage_factory=self._vector_storage_factory,
+        )
 
-    @staticmethod
-    def run_vector_agent_sync(search_query: str) -> VectorSearchStructure:
-        """Run :meth:`run_vector_agent` synchronously for ``search_query``.
+        def _run_search(prompt: str) -> VectorSearchStructure:
+            return run_coroutine_agent_sync(search.run_agent(search_query=prompt))
 
-        Parameters
-        ----------
-        search_query : str
-            User's research query.
-
-        Returns
-        -------
-        VectorSearchStructure
-            Completed research output.
-        """
-        return run_coroutine_agent_sync(
-            VectorSearch.run_vector_agent(search_query=search_query)
+        tool_handler = {
+            tool_name: tool_handler_factory(_run_search, input_model=PromptStructure)
+        }
+        tool_definition = PromptStructure.response_tool_definition(
+            tool_name, tool_description=tool_description
         )
+        return tool_handler, tool_definition
 
 
 __all__ = [
     "MAX_CONCURRENT_SEARCHES",
-    "VectorSearchPlanner",
+    "VectorAgentPlanner",
     "VectorSearchTool",
     "VectorSearchWriter",
-    "VectorSearch",
+    "VectorAgentSearch",
 ]