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

openai_sdk_helpers/agent/{config.py → configuration.py}

@@ -24,12 +24,12 @@ class AgentRegistry(RegistryBase["AgentConfiguration"]):
     Examples
     --------
     >>> registry = AgentRegistry()
-    >>> config = AgentConfiguration(
+    >>> configuration = AgentConfiguration(
     ...     name="test_agent",
     ...     model="gpt-4o-mini",
     ...     instructions="Test instructions"
     ... )
-    >>> registry.register(config)
+    >>> registry.register(configuration)
     >>> retrieved = registry.get("test_agent")
     >>> retrieved.name
     'test_agent'
@@ -85,10 +85,10 @@ def get_default_registry() -> AgentRegistry:
     Examples
     --------
     >>> registry = get_default_registry()
-    >>> config = AgentConfiguration(
+    >>> configuration = AgentConfiguration(
     ...     name="test", model="gpt-4o-mini", instructions="Test instructions"
     ... )
-    >>> registry.register(config)
+    >>> registry.register(configuration)
     """
     return _default_registry
 
@@ -165,12 +165,12 @@ class AgentConfiguration(DataclassJSONSerializable):
 
     Examples
     --------
-    >>> config = AgentConfiguration(
+    >>> configuration = AgentConfiguration(
     ...     name="summarizer",
     ...     description="Summarizes text",
     ...     model="gpt-4o-mini"
     ... )
-    >>> config.name
+    >>> configuration.name
     'summarizer'
     """
 
@@ -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."""
@@ -304,7 +308,7 @@ class AgentConfiguration(DataclassJSONSerializable):
         prompt_dir : Path or None, default=None
             Optional directory holding prompt templates.
         default_model : str or None, default=None
-            Optional fallback model identifier if config doesn't specify one.
+            Optional fallback model identifier if configuration doesn't specify one.
 
         Returns
         -------
@@ -313,17 +317,17 @@ class AgentConfiguration(DataclassJSONSerializable):
 
         Examples
         --------
-        >>> config = AgentConfiguration(
+        >>> configuration = AgentConfiguration(
         ...     name="helper", model="gpt-4o-mini", instructions="Help the user"
         ... )
-        >>> agent = config.gen_agent()
+        >>> agent = configuration.gen_agent()
         >>> result = agent.run_sync("Hello!")
         """
         # Import here to avoid circular dependency
         from .base import AgentBase
 
         return AgentBase(
-            config=self,
+            configuration=self,
             run_context_wrapper=run_context_wrapper,
             prompt_dir=prompt_dir,
             default_model=default_model,
@@ -348,10 +352,10 @@ class AgentConfiguration(DataclassJSONSerializable):
 
         Examples
         --------
-        >>> config = AgentConfiguration(
+        >>> configuration = AgentConfiguration(
         ...     name="agent1", model="gpt-4o-mini", instructions="Agent instructions"
         ... )
-        >>> config2 = config.replace(name="agent2", description="Modified")
+        >>> config2 = configuration.replace(name="agent2", description="Modified")
         >>> config2.name
         'agent2'
         >>> config2.model
@@ -361,66 +365,37 @@ 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.configuration 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

openai_sdk_helpers/agent/{coordination.py → coordinator.py}

@@ -11,11 +11,11 @@ from pathlib import Path
 from typing import Any, Callable, Dict, List, Optional
 
 
-from ..structure import TaskStructure, PlanStructure, PromptStructure
-from ..utils import DataclassJSONSerializable, ensure_directory, log
+from ..structure import TaskStructure, PlanStructure, PromptStructure, AgentEnum
+from ..utils import ensure_directory, log
 from .base import AgentBase
-from .config import AgentConfiguration
-from ..structure.plan.enum import AgentEnum
+from .configuration import AgentConfiguration
+
 
 PromptFn = Callable[[str], PromptStructure]
 BuildPlanFn = Callable[[str], PlanStructure]
@@ -40,7 +40,7 @@ class CoordinatorAgent(AgentBase):
         Base path for persisting project artifacts.
     name : str
         Name of the parent module for data organization.
-    config : AgentConfiguration or None, default=None
+    configuration : AgentConfiguration or None, default=None
         Optional agent configuration describing prompts and metadata.
     prompt_dir : Path or None, default=None
         Optional directory holding prompt templates.
@@ -84,7 +84,7 @@ class CoordinatorAgent(AgentBase):
         summarize_fn: SummarizeFn,
         module_data_path: Path,
         name: str,
-        config: Optional[AgentConfiguration] = None,
+        configuration: Optional[AgentConfiguration] = None,
         prompt_dir: Optional[Path] = None,
         default_model: Optional[str] = None,
     ) -> None:
@@ -104,7 +104,7 @@ class CoordinatorAgent(AgentBase):
             Base path for persisting project artifacts.
         name : str
             Name of the parent module for data organization.
-        config : AgentConfiguration or None, default=None
+        configuration : AgentConfiguration or None, default=None
             Optional agent configuration describing prompts and metadata.
         prompt_dir : Path or None, default=None
             Optional directory holding prompt templates.
@@ -127,14 +127,16 @@ class CoordinatorAgent(AgentBase):
         ...     name="test",
         ... )
         """
-        if config is None:
-            config = AgentConfiguration(
+        if configuration is None:
+            configuration = AgentConfiguration(
                 name="coordinator_agent",
                 instructions="Coordinate agents for planning and summarization.",
                 description="Coordinates agents for planning and summarization.",
             )
         super().__init__(
-            config=config, prompt_dir=prompt_dir, default_model=default_model
+            configuration=configuration,
+            prompt_dir=prompt_dir,
+            default_model=default_model,
         )
         self._prompt_fn = prompt_fn
         self._build_plan_fn = build_plan_fn

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/agent/search/base.py

@@ -13,7 +13,7 @@ from pathlib import Path
 from typing import Generic, List, Optional, TypeVar, Union
 
 from ..base import AgentBase
-from ..config import AgentConfiguration
+from ..configuration import AgentConfiguration
 from ...structure.base import StructureBase
 
 # Type variables for search workflow components
@@ -36,7 +36,7 @@ class SearchPlanner(AgentBase, Generic[PlanType]):
     prompt_dir : Path, optional
         Directory containing prompt templates.
     default_model : str, optional
-        Default model identifier to use when not defined in config.
+        Default model identifier to use when not defined in configuration.
 
     Methods
     -------
@@ -68,9 +68,9 @@ class SearchPlanner(AgentBase, Generic[PlanType]):
         default_model: Optional[str] = None,
     ) -> None:
         """Initialize the planner agent."""
-        config = self._configure_agent()
+        configuration = self._configure_agent()
         super().__init__(
-            config=config,
+            configuration=configuration,
             prompt_dir=prompt_dir,
             default_model=default_model,
         )
@@ -86,12 +86,12 @@ class SearchPlanner(AgentBase, Generic[PlanType]):
 
         Examples
         --------
-        >>> config = AgentConfiguration(
+        >>> configuration = AgentConfiguration(
         ...     name="web_planner",
         ...     description="Plan web searches",
         ...     output_structure=WebSearchPlanStructure,
         ... )
-        >>> return config
+        >>> return configuration
         """
         pass
 
@@ -127,7 +127,7 @@ class SearchToolAgent(AgentBase, Generic[ItemType, ResultType, PlanType]):
     prompt_dir : Path, optional
         Directory containing prompt templates.
     default_model : str, optional
-        Default model identifier to use when not defined in config.
+        Default model identifier to use when not defined in configuration.
     max_concurrent_searches : int, default=10
         Maximum number of concurrent search operations.
 
@@ -168,9 +168,9 @@ class SearchToolAgent(AgentBase, Generic[ItemType, ResultType, PlanType]):
     ) -> None:
         """Initialize the search tool agent."""
         self._max_concurrent_searches = max_concurrent_searches
-        config = self._configure_agent()
+        configuration = self._configure_agent()
         super().__init__(
-            config=config,
+            configuration=configuration,
             prompt_dir=prompt_dir,
             default_model=default_model,
         )
@@ -186,13 +186,13 @@ class SearchToolAgent(AgentBase, Generic[ItemType, ResultType, PlanType]):
 
         Examples
         --------
-        >>> config = AgentConfiguration(
+        >>> configuration = AgentConfiguration(
         ...     name="web_search",
         ...     description="Perform web searches",
         ...     input_structure=WebSearchPlanStructure,
         ...     tools=[WebSearchTool()],
         ... )
-        >>> return config
+        >>> return configuration
         """
         pass
 
@@ -250,7 +250,7 @@ class SearchWriter(AgentBase, Generic[ReportType]):
     prompt_dir : Path, optional
         Directory containing prompt templates.
     default_model : str, optional
-        Default model identifier to use when not defined in config.
+        Default model identifier to use when not defined in configuration.
 
     Methods
     -------
@@ -282,9 +282,9 @@ class SearchWriter(AgentBase, Generic[ReportType]):
         default_model: Optional[str] = None,
     ) -> None:
         """Initialize the writer agent."""
-        config = self._configure_agent()
+        configuration = self._configure_agent()
         super().__init__(
-            config=config,
+            configuration=configuration,
             prompt_dir=prompt_dir,
             default_model=default_model,
         )
@@ -300,12 +300,12 @@ class SearchWriter(AgentBase, Generic[ReportType]):
 
         Examples
         --------
-        >>> config = AgentConfiguration(
+        >>> configuration = AgentConfiguration(
         ...     name="web_writer",
         ...     description="Write web search report",
         ...     output_structure=WebSearchReportStructure,
         ... )
-        >>> return config
+        >>> return configuration
         """
         pass
 

openai_sdk_helpers/agent/search/vector.py

@@ -6,7 +6,10 @@ from pathlib import Path
 from typing import Any, Callable, Dict, List, Optional
 
 from agents import custom_span, gen_trace_id, trace
+from agents.model_settings import ModelSettings
 
+from ...environment import DEFAULT_PROMPT_DIR
+from ...structure.prompt import PromptStructure
 from ...structure.vector_search import (
     VectorSearchItemStructure,
     VectorSearchItemResultStructure,
@@ -15,23 +18,25 @@ from ...structure.vector_search import (
     VectorSearchPlanStructure,
     VectorSearchReportStructure,
 )
+from ...tools import tool_handler_factory
 from ...vector_storage import VectorStorage
-from ..config import AgentConfiguration
+from ..configuration import AgentConfiguration
 from ..utils import run_coroutine_agent_sync
 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
     ----------
     prompt_dir : Path or None, default=None
-        Directory containing prompt templates.
+        Directory containing prompt templates. Defaults to the packaged
+        ``prompt`` directory when not provided.
     default_model : str or None, default=None
-        Default model identifier to use when not defined in config.
+        Default model identifier to use when not defined in configuration.
 
     Methods
     -------
@@ -52,7 +57,8 @@ class VectorSearchPlanner(SearchPlanner[VectorSearchPlanStructure]):
         self, prompt_dir: Optional[Path] = None, default_model: Optional[str] = None
     ) -> None:
         """Initialize the planner agent."""
-        super().__init__(prompt_dir=prompt_dir, default_model=default_model)
+        prompt_directory = prompt_dir or DEFAULT_PROMPT_DIR
+        super().__init__(prompt_dir=prompt_directory, default_model=default_model)
 
     def _configure_agent(self) -> AgentConfiguration:
         """Return configuration for the vector planner agent.
@@ -67,6 +73,7 @@ class VectorSearchPlanner(SearchPlanner[VectorSearchPlanStructure]):
             instructions="Agent instructions",
             description="Plan vector searches based on a user query.",
             output_structure=VectorSearchPlanStructure,
+            model_settings=ModelSettings(tool_choice="none"),
         )
 
 
@@ -82,9 +89,10 @@ class VectorSearchTool(
     Parameters
     ----------
     prompt_dir : Path or None, default=None
-        Directory containing prompt templates.
+        Directory containing prompt templates. Defaults to the packaged
+        ``prompt`` directory when not provided.
     default_model : str or None, default=None
-        Default model identifier to use when not defined in config.
+        Default model identifier to use when not defined in configuration.
     store_name : str or None, default=None
         Name of the vector store to query.
     max_concurrent_searches : int, default=MAX_CONCURRENT_SEARCHES
@@ -123,13 +131,14 @@ class VectorSearchTool(
         vector_storage_factory: Optional[Callable[[str], VectorStorage]] = None,
     ) -> None:
         """Initialize the search tool agent."""
+        prompt_directory = prompt_dir or DEFAULT_PROMPT_DIR
         self._vector_storage: Optional[VectorStorage] = None
         self._store_name = store_name or "editorial"
         self._vector_storage_factory = vector_storage_factory
         if vector_storage is not None:
             self._vector_storage = vector_storage
         super().__init__(
-            prompt_dir=prompt_dir,
+            prompt_dir=prompt_directory,
             default_model=default_model,
             max_concurrent_searches=max_concurrent_searches,
         )
@@ -148,6 +157,7 @@ class VectorSearchTool(
             description="Perform vector searches based on a search plan.",
             input_structure=VectorSearchPlanStructure,
             output_structure=VectorSearchItemResultsStructure,
+            model_settings=ModelSettings(tool_choice="none"),
         )
 
     def _get_vector_storage(self) -> VectorStorage:
@@ -200,9 +210,10 @@ class VectorSearchWriter(SearchWriter[VectorSearchReportStructure]):
     Parameters
     ----------
     prompt_dir : Path or None, default=None
-        Directory containing prompt templates.
+        Directory containing prompt templates. Defaults to the packaged
+        ``prompt`` directory when not provided.
     default_model : str or None, default=None
-        Default model identifier to use when not defined in config.
+        Default model identifier to use when not defined in configuration.
 
     Methods
     -------
@@ -223,7 +234,8 @@ class VectorSearchWriter(SearchWriter[VectorSearchReportStructure]):
         self, prompt_dir: Optional[Path] = None, default_model: Optional[str] = None
     ) -> None:
         """Initialize the writer agent."""
-        super().__init__(prompt_dir=prompt_dir, default_model=default_model)
+        prompt_directory = prompt_dir or DEFAULT_PROMPT_DIR
+        super().__init__(prompt_dir=prompt_directory, default_model=default_model)
 
     def _configure_agent(self) -> AgentConfiguration:
         """Return configuration for the vector writer agent.
@@ -238,10 +250,11 @@ class VectorSearchWriter(SearchWriter[VectorSearchReportStructure]):
             instructions="Agent instructions",
             description="Write a report based on search results.",
             output_structure=VectorSearchReportStructure,
+            model_settings=ModelSettings(tool_choice="none"),
         )
 
 
-class VectorSearch:
+class VectorAgentSearch:
     """Manage the complete vector search workflow.
 
     This high-level agent orchestrates a multi-step research process that plans
@@ -252,9 +265,10 @@ class VectorSearch:
     Parameters
     ----------
     prompt_dir : Path or None, default=None
-        Directory containing prompt templates.
+        Directory containing prompt templates. Defaults to the packaged
+        ``prompt`` directory when not provided.
     default_model : str or None, default=None
-        Default model identifier to use when not defined in config.
+        Default model identifier to use when not defined in configuration.
     vector_store_name : str or None, default=None
         Name of the vector store to query.
     max_concurrent_searches : int, default=MAX_CONCURRENT_SEARCHES
@@ -292,6 +306,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,15 +322,15 @@ 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,
     ) -> None:
         """Create the main VectorSearch agent."""
-        self._prompt_dir = prompt_dir
+        self._prompt_dir = prompt_dir or DEFAULT_PROMPT_DIR
         self._default_model = default_model
         self._vector_store_name = vector_store_name
         self._max_concurrent_searches = max_concurrent_searches
@@ -336,7 +352,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 +399,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",
 ]