openai-sdk-helpers 0.4.2__py3-none-any.whl → 0.5.0__py3-none-any.whl

openai_sdk_helpers/agent/search/vector.py

@@ -3,11 +3,12 @@
 from __future__ import annotations
 
 from pathlib import Path
-from typing import Any, Callable, Dict, List, Optional
+from typing import Any, Callable, List, Optional
 
 from agents import custom_span, gen_trace_id, trace
+from agents.model_settings import ModelSettings
 
-from ...structure.prompt import PromptStructure
+from ...environment import DEFAULT_PROMPT_DIR
 from ...structure.vector_search import (
     VectorSearchItemStructure,
     VectorSearchItemResultStructure,
@@ -16,11 +17,11 @@ 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
+from ..base import AgentBase
 
 MAX_CONCURRENT_SEARCHES = 10
 
@@ -30,10 +31,10 @@ class VectorAgentPlanner(SearchPlanner[VectorSearchPlanStructure]):
 
     Parameters
     ----------
-    prompt_dir : Path or None, default=None
-        Directory containing prompt templates.
-    default_model : str or None, default=None
-        Default model identifier to use when not defined in config.
+    template_path : Path | str | None, optional
+        Template file path for prompt rendering.
+    model : str | None, optional
+        Model identifier to use when not defined in configuration.
 
     Methods
     -------
@@ -43,20 +44,19 @@ class VectorAgentPlanner(SearchPlanner[VectorSearchPlanStructure]):
     Raises
     ------
     ValueError
-        If the default model is not provided.
+        If the configuration omits a model identifier.
 
     Examples
     --------
-    >>> planner = VectorSearchPlanner(default_model="gpt-4o-mini")
+    >>> planner = VectorSearchPlanner(model="gpt-4o-mini")
     """
 
-    def __init__(
-        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)
-
-    def _configure_agent(self) -> AgentConfiguration:
+    def _configure_agent(
+        self,
+        template_path: Path | str | None = None,
+        model: str | None = None,
+        **kwargs: Any,
+    ) -> AgentConfiguration:
         """Return configuration for the vector planner agent.
 
         Returns
@@ -69,6 +69,9 @@ class VectorAgentPlanner(SearchPlanner[VectorSearchPlanStructure]):
             instructions="Agent instructions",
             description="Plan vector searches based on a user query.",
             output_structure=VectorSearchPlanStructure,
+            model_settings=ModelSettings(tool_choice="none"),
+            template_path=template_path,
+            model=model,
         )
 
 
@@ -83,11 +86,11 @@ class VectorSearchTool(
 
     Parameters
     ----------
-    prompt_dir : Path or None, default=None
-        Directory containing prompt templates.
-    default_model : str or None, default=None
-        Default model identifier to use when not defined in config.
-    store_name : str or None, default=None
+    template_path : Path | str | None, optional
+        Template file path for prompt rendering.
+    model : str | None, optional
+        Model identifier to use when not defined in configuration.
+    store_name : str
         Name of the vector store to query.
     max_concurrent_searches : int, default=MAX_CONCURRENT_SEARCHES
         Maximum number of concurrent vector search tasks to run.
@@ -107,36 +110,20 @@ class VectorSearchTool(
     Raises
     ------
     ValueError
-        If the default model is not provided.
+        If the configuration omits a model identifier.
 
     Examples
     --------
-    >>> tool = VectorSearchTool(default_model="gpt-4o-mini", store_name="my_store")
+    >>> tool = VectorSearchTool(model="gpt-4o-mini", store_name="my_store")
     """
 
-    def __init__(
+    def _configure_agent(
         self,
         *,
-        prompt_dir: Optional[Path] = None,
-        default_model: Optional[str] = None,
-        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:
-        """Initialize the search tool agent."""
-        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,
-            default_model=default_model,
-            max_concurrent_searches=max_concurrent_searches,
-        )
-
-    def _configure_agent(self) -> AgentConfiguration:
+        template_path: Path | str | None = None,
+        model: str | None = None,
+        **kwargs: Any,
+    ) -> AgentConfiguration:
         """Return configuration for the vector search tool agent.
 
         Returns
@@ -144,12 +131,37 @@ class VectorSearchTool(
         AgentConfiguration
             Configuration with name, description, and input type.
         """
+        if self._store_name is None:
+            raise ValueError("store_name must be provided to configure the agent.")
         return AgentConfiguration(
             name="vector_search",
             instructions="Agent instructions",
             description="Perform vector searches based on a search plan.",
             input_structure=VectorSearchPlanStructure,
             output_structure=VectorSearchItemResultsStructure,
+            model_settings=ModelSettings(tool_choice="none"),
+            template_path=template_path,
+            model=model,
+        )
+
+    def __init__(
+        self,
+        *,
+        store_name: str,
+        template_path: Path | str | None = None,
+        model: str | None = None,
+        max_concurrent_searches: int = MAX_CONCURRENT_SEARCHES,
+        vector_storage: Optional[VectorStorage] = None,
+        vector_storage_factory: Optional[Callable[[str], VectorStorage]] = None,
+    ) -> None:
+        """Initialize the vector search tool agent."""
+        self._vector_storage = vector_storage
+        self._vector_storage_factory = vector_storage_factory
+        self._store_name = store_name
+        super().__init__(
+            template_path=template_path,
+            model=model,
+            max_concurrent_searches=max_concurrent_searches,
         )
 
     def _get_vector_storage(self) -> VectorStorage:
@@ -201,10 +213,10 @@ class VectorSearchWriter(SearchWriter[VectorSearchReportStructure]):
 
     Parameters
     ----------
-    prompt_dir : Path or None, default=None
-        Directory containing prompt templates.
-    default_model : str or None, default=None
-        Default model identifier to use when not defined in config.
+    template_path : Path | str | None, optional
+        Template file path for prompt rendering.
+    model : str | None, optional
+        Model identifier to use when not defined in configuration.
 
     Methods
     -------
@@ -214,20 +226,32 @@ class VectorSearchWriter(SearchWriter[VectorSearchReportStructure]):
     Raises
     ------
     ValueError
-        If the default model is not provided.
+        If the configuration omits a model identifier.
 
     Examples
     --------
-    >>> writer = VectorSearchWriter(default_model="gpt-4o-mini")
+    >>> writer = VectorSearchWriter(model="gpt-4o-mini")
     """
 
     def __init__(
-        self, prompt_dir: Optional[Path] = None, default_model: Optional[str] = None
+        self,
+        template_path: Path | str | None = None,
+        model: str | None = None,
+        **kwargs: Any,
     ) -> None:
         """Initialize the writer agent."""
-        super().__init__(prompt_dir=prompt_dir, default_model=default_model)
+        configuration = self._configure_agent(
+            template_path=template_path, model=model, **kwargs
+        )
+        super().__init__(configuration=configuration)
 
-    def _configure_agent(self) -> AgentConfiguration:
+    def _configure_agent(
+        self,
+        *,
+        template_path: Path | str | None = None,
+        model: str | None = None,
+        **kwargs: Any,
+    ) -> AgentConfiguration:
         """Return configuration for the vector writer agent.
 
         Returns
@@ -240,10 +264,13 @@ class VectorSearchWriter(SearchWriter[VectorSearchReportStructure]):
             instructions="Agent instructions",
             description="Write a report based on search results.",
             output_structure=VectorSearchReportStructure,
+            model_settings=ModelSettings(tool_choice="none"),
+            template_path=template_path,
+            model=model,
         )
 
 
-class VectorAgentSearch:
+class VectorAgentSearch(AgentBase):
     """Manage the complete vector search workflow.
 
     This high-level agent orchestrates a multi-step research process that plans
@@ -254,9 +281,10 @@ class VectorAgentSearch:
     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
@@ -304,7 +332,7 @@ class VectorAgentSearch:
     Raises
     ------
     ValueError
-        If the default model is not provided.
+        If the model identifier is not provided.
     """
 
     def __init__(
@@ -318,7 +346,7 @@ class VectorAgentSearch:
         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
@@ -341,18 +369,16 @@ class VectorAgentSearch:
         trace_id = gen_trace_id()
         with trace("VectorSearch trace", trace_id=trace_id):
             planner = VectorAgentPlanner(
-                prompt_dir=self._prompt_dir, default_model=self._default_model
+                template_path=self._prompt_dir, model=self._default_model
             )
             tool = VectorSearchTool(
-                prompt_dir=self._prompt_dir,
-                default_model=self._default_model,
-                store_name=self._vector_store_name,
+                template_path=self._prompt_dir,
+                model=self._default_model,
                 max_concurrent_searches=self._max_concurrent_searches,
-                vector_storage=self._vector_storage,
-                vector_storage_factory=self._vector_storage_factory,
+                store_name=self._vector_store_name,
             )
             writer = VectorSearchWriter(
-                prompt_dir=self._prompt_dir, default_model=self._default_model
+                template_path=self._prompt_dir, model=self._default_model
             )
             with custom_span("vector_search.plan"):
                 search_plan = await planner.run_agent(query=search_query)
@@ -387,48 +413,6 @@ class VectorAgentSearch:
         """
         return run_coroutine_agent_sync(self.run_agent(search_query))
 
-    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
-        ----------
-        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
-        -------
-        tuple[dict[str, Callable[..., Any]], dict[str, Any]]
-            Tool handler mapping and tool definition for Responses API usage.
-        """
-        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,
-        )
-
-        def _run_search(prompt: str) -> VectorSearchStructure:
-            return run_coroutine_agent_sync(search.run_agent(search_query=prompt))
-
-        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",

openai_sdk_helpers/agent/search/web.py

@@ -3,13 +3,14 @@
 from __future__ import annotations
 
 from pathlib import Path
-from typing import Any, Callable, Dict, List, Optional, Union
+from typing import Any, Dict, Optional, Union
 
 from agents import custom_span, gen_trace_id, trace
 from agents.model_settings import ModelSettings
 from agents.tool import WebSearchTool
 
 from ...structure.prompt import PromptStructure
+from ..base import AgentBase
 from ...structure.web_search import (
     WebSearchItemStructure,
     WebSearchItemResultStructure,
@@ -17,10 +18,10 @@ from ...structure.web_search import (
     WebSearchPlanStructure,
     WebSearchReportStructure,
 )
-from ...tools import tool_handler_factory
-from ..config import AgentConfiguration
+from ..configuration import AgentConfiguration
 from ..utils import run_coroutine_agent_sync
 from .base import SearchPlanner, SearchToolAgent, SearchWriter
+from ...tools import ToolSpec, ToolHandlerRegistration
 
 MAX_CONCURRENT_SEARCHES = 10
 
@@ -30,10 +31,10 @@ class WebAgentPlanner(SearchPlanner[WebSearchPlanStructure]):
 
     Parameters
     ----------
-    prompt_dir : Path or None, default=None
-        Directory containing prompt templates.
-    default_model : str or None, default=None
-        Default model identifier to use when not defined in config.
+    template_path : Path | str | None, default=None
+        Template file path for prompt rendering.
+    model : str | None, default=None
+        Model identifier to use when not defined in configuration.
 
     Methods
     -------
@@ -43,20 +44,19 @@ class WebAgentPlanner(SearchPlanner[WebSearchPlanStructure]):
     Raises
     ------
     ValueError
-        If the default model is not provided.
+        If the configuration omits a model identifier.
 
     Examples
     --------
-    >>> planner = WebAgentPlanner(default_model="gpt-4o-mini")
+    >>> planner = WebAgentPlanner(model="gpt-4o-mini")
     """
 
-    def __init__(
-        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)
-
-    def _configure_agent(self) -> AgentConfiguration:
+    def _configure_agent(
+        self,
+        template_path: Path | str | None = None,
+        model: str | None = None,
+        **kwargs: Any,
+    ) -> AgentConfiguration:
         """Return configuration for the web planner agent.
 
         Returns
@@ -68,6 +68,8 @@ class WebAgentPlanner(SearchPlanner[WebSearchPlanStructure]):
             name="web_planner",
             instructions="Agent instructions",
             description="Agent that plans web searches based on a user query.",
+            template_path=template_path,
+            model=model,
             output_structure=WebSearchPlanStructure,
         )
 
@@ -81,10 +83,10 @@ class WebSearchToolAgent(
 
     Parameters
     ----------
-    prompt_dir : Path or None, default=None
-        Directory containing prompt templates.
-    default_model : str or None, default=None
-        Default model identifier to use when not defined in config.
+    template_path : Path | str | None, default=None
+        Template file path for prompt rendering.
+    model : str or None, default=None
+        Model identifier to use when not defined in configuration.
 
     Methods
     -------
@@ -96,24 +98,20 @@ class WebSearchToolAgent(
     Raises
     ------
     ValueError
-        If the default model is not provided.
+        If the model is not provided.
 
     Examples
     --------
-    >>> tool = WebSearchToolAgent(default_model="gpt-4o-mini")
+    >>> tool = WebSearchToolAgent(model="gpt-4o-mini")
     """
 
-    def __init__(
-        self, prompt_dir: Optional[Path] = None, default_model: Optional[str] = None
-    ) -> None:
-        """Initialize the search tool agent."""
-        super().__init__(
-            prompt_dir=prompt_dir,
-            default_model=default_model,
-            max_concurrent_searches=MAX_CONCURRENT_SEARCHES,
-        )
-
-    def _configure_agent(self) -> AgentConfiguration:
+    def _configure_agent(
+        self,
+        *,
+        template_path: Path | str | None = None,
+        model: str | None = None,
+        **kwargs: Any,
+    ) -> AgentConfiguration:
         """Return configuration for the web search tool agent.
 
         Returns
@@ -125,6 +123,8 @@ class WebSearchToolAgent(
             name="web_search",
             instructions="Agent instructions",
             description="Agent that performs web searches and summarizes results.",
+            template_path=template_path,
+            model=model,
             input_structure=WebSearchPlanStructure,
             tools=[WebSearchTool()],
             model_settings=ModelSettings(tool_choice="required"),
@@ -186,10 +186,10 @@ class WebAgentWriter(SearchWriter[WebSearchReportStructure]):
 
     Parameters
     ----------
-    prompt_dir : Path or None, default=None
-        Directory containing prompt templates.
-    default_model : str or None, default=None
-        Default model identifier to use when not defined in config.
+    template_path : Path | str | None, default=None
+        Template file path for prompt rendering.
+    model : str | None, default=None
+        Model identifier to use when not defined in configuration.
 
     Methods
     -------
@@ -199,20 +199,31 @@ class WebAgentWriter(SearchWriter[WebSearchReportStructure]):
     Raises
     ------
     ValueError
-        If the default model is not provided.
+        If the configuration omits a model identifier.
 
     Examples
     --------
-    >>> writer = WebAgentWriter(default_model="gpt-4o-mini")
+    >>> writer = WebAgentWriter(model="gpt-4o-mini")
     """
 
     def __init__(
-        self, prompt_dir: Optional[Path] = None, default_model: Optional[str] = None
+        self,
+        template_path: Path | str | None = None,
+        model: str | None = None,
+        **kwargs: Any,
     ) -> None:
         """Initialize the writer agent."""
-        super().__init__(prompt_dir=prompt_dir, default_model=default_model)
+        configuration = self._configure_agent(
+            template_path=template_path, model=model, **kwargs
+        )
+        super().__init__(configuration=configuration)
 
-    def _configure_agent(self) -> AgentConfiguration:
+    def _configure_agent(
+        self,
+        template_path: Path | str | None = None,
+        model: str | None = None,
+        **kwargs: Any,
+    ) -> AgentConfiguration:
         """Return configuration for the web writer agent.
 
         Returns
@@ -224,19 +235,21 @@ class WebAgentWriter(SearchWriter[WebSearchReportStructure]):
             name="web_writer",
             instructions="Agent instructions",
             description="Agent that writes a report based on web search results.",
+            template_path=template_path,
+            model=model,
             output_structure=WebSearchReportStructure,
         )
 
 
-class WebAgentSearch:
+class WebAgentSearch(AgentBase):
     """Manage the complete web search workflow.
 
     Parameters
     ----------
-    prompt_dir : Path or None, default=None
-        Directory containing prompt templates.
-    default_model : str or None, default=None
-        Default model identifier to use when not defined in config.
+    template_path : Path | str | None, default=None
+        Template file path for prompt rendering.
+    model : str | None, default=None
+        Model identifier to use when not defined in configuration.
 
     Methods
     -------
@@ -254,21 +267,36 @@ class WebAgentSearch:
     Raises
     ------
     ValueError
-        If the default model is not provided.
+        If the model identifier is not provided.
 
     Examples
     --------
-    >>> search = WebAgentSearch(default_model="gpt-4o-mini")
+    >>> search = WebAgentSearch(model="gpt-4o-mini")
     """
 
     def __init__(
         self,
-        prompt_dir: Optional[Path] = None,
-        default_model: Optional[str] = None,
+        *,
+        template_path: Path | str | None = None,
+        model: str | None = None,
     ) -> None:
-        """Create the main web search agent."""
-        self._prompt_dir = prompt_dir
-        self._default_model = default_model
+        """Initialize the web search orchestration agent.
+
+        Parameters
+        ----------
+        template_path : Path | str | None, default=None
+            Optional template file path for prompt rendering.
+        model : str | None, default=None
+            Model identifier to use when not defined in configuration.
+        """
+        configuration = AgentConfiguration(
+            name="web_agent_search",
+            instructions="Agent instructions",
+            description="Run a multi-step web search workflow.",
+            template_path=template_path,
+            model=model,
+        )
+        super().__init__(configuration=configuration)
 
     async def run_agent_async(self, search_query: str) -> WebSearchStructure:
         """Execute the entire research workflow for ``search_query``.
@@ -286,14 +314,12 @@ class WebAgentSearch:
         trace_id = gen_trace_id()
         with trace("WebAgentSearch trace", trace_id=trace_id):
             planner = WebAgentPlanner(
-                prompt_dir=self._prompt_dir, default_model=self._default_model
+                template_path=self._template_path, model=self.model
             )
             tool = WebSearchToolAgent(
-                prompt_dir=self._prompt_dir, default_model=self._default_model
-            )
-            writer = WebAgentWriter(
-                prompt_dir=self._prompt_dir, default_model=self._default_model
+                template_path=self._template_path, model=self.model
             )
+            writer = WebAgentWriter(template_path=self._template_path, model=self.model)
             search_plan = await planner.run_agent(query=search_query)
             search_results = await tool.run_agent(search_plan=search_plan)
             search_report = await writer.run_agent(search_query, search_results)
@@ -320,37 +346,33 @@ class WebAgentSearch:
         """
         return run_coroutine_agent_sync(self.run_agent_async(search_query))
 
-    def as_response_tool(
-        self,
-        *,
-        tool_name: str = "web_search",
-        tool_description: str = "Run the web search workflow.",
-    ) -> tuple[dict[str, Callable[..., Any]], dict[str, Any]]:
-        """Return a Responses API tool handler and definition.
+    def as_tool_registration(
+        self, tool_name: str, tool_description: str
+    ) -> ToolHandlerRegistration:
+        """Build a Responses API tool definition and handler for the web search agent.
 
         Parameters
         ----------
-        tool_name : str, default="web_search"
-            Name to use for the response tool.
-        tool_description : str, default="Run the web search workflow."
-            Description for the response tool.
+        tool_name : str
+            Name of the tool.
+        tool_description : str
+            Description of the tool.
 
         Returns
         -------
-        tuple[dict[str, Callable[..., Any]], dict[str, Any]]
-            Tool handler mapping and tool definition for Responses API usage.
+        ToolHandlerRegistration
+            Tool definition and handler for the Responses API.
         """
-
-        def _run_search(prompt: str) -> WebSearchStructure:
-            return run_coroutine_agent_sync(self.run_agent_async(search_query=prompt))
-
-        tool_handler = {
-            tool_name: tool_handler_factory(_run_search, input_model=PromptStructure)
-        }
-        tool_definition = PromptStructure.response_tool_definition(
-            tool_name, tool_description=tool_description
+        tool_spec = ToolSpec(
+            input_structure=PromptStructure,
+            tool_name=tool_name,
+            tool_description=tool_description,
+            output_structure=WebSearchStructure,
+        )
+        return ToolHandlerRegistration(
+            handler=self.run_agent_sync,
+            tool_spec=tool_spec,
         )
-        return tool_handler, tool_definition
 
 
 __all__ = [