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

openai_sdk_helpers/agent/coordinator.py

@@ -16,7 +16,6 @@ from ..utils import ensure_directory, log
 from .base import AgentBase
 from .configuration import AgentConfiguration
 
-
 PromptFn = Callable[[str], PromptStructure]
 BuildPlanFn = Callable[[str], PlanStructure]
 ExecutePlanFn = Callable[[PlanStructure], List[str]]
@@ -42,10 +41,10 @@ class CoordinatorAgent(AgentBase):
         Name of the parent module for data organization.
     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.
-    default_model : str or None, default=None
-        Optional fallback model identifier.
+    template_path : Path or None, default=None
+        Optional template file path for prompt rendering.
+    model : str or None, default=None
+        Model identifier to use for coordinator operations.
 
     Methods
     -------
@@ -85,8 +84,8 @@ class CoordinatorAgent(AgentBase):
         module_data_path: Path,
         name: str,
         configuration: Optional[AgentConfiguration] = None,
-        prompt_dir: Optional[Path] = None,
-        default_model: Optional[str] = None,
+        template_path: Optional[Path] = None,
+        model: Optional[str] = None,
     ) -> None:
         """Initialize the project manager with injected workflow helpers.
 
@@ -106,10 +105,10 @@ class CoordinatorAgent(AgentBase):
             Name of the parent module for data organization.
         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.
-        default_model : str or None, default=None
-            Optional fallback model identifier.
+        template_path : Path or None, default=None
+            Optional template file path for prompt rendering.
+        model : str or None, default=None
+            Model identifier to use for coordinator operations.
 
         Raises
         ------
@@ -129,15 +128,13 @@ class CoordinatorAgent(AgentBase):
         """
         if configuration is None:
             configuration = AgentConfiguration(
-                name="coordinator_agent",
+                name=__class__.__name__,
                 instructions="Coordinate agents for planning and summarization.",
                 description="Coordinates agents for planning and summarization.",
+                template_path=template_path,
+                model=model,
             )
-        super().__init__(
-            configuration=configuration,
-            prompt_dir=prompt_dir,
-            default_model=default_model,
-        )
+        super().__init__(configuration=configuration)
         self._prompt_fn = prompt_fn
         self._build_plan_fn = build_plan_fn
         self._execute_plan_fn = execute_plan_fn

openai_sdk_helpers/agent/runner.py

@@ -2,14 +2,14 @@
 
 These helpers provide a consistent interface around the lower-level functions in
 the ``agent.base`` module, allowing callers to execute agents with consistent
-signatures whether they need asynchronous, synchronous, or streamed results.
+signatures whether they need asynchronous or synchronous results.
 """
 
 from __future__ import annotations
 
 from typing import Any, Dict, Optional
 
-from agents import Agent, RunResult, RunResultStreaming, Runner, Session
+from agents import Agent, RunResult, Runner, Session
 
 from openai_sdk_helpers.utils.async_utils import run_coroutine_with_fallback
 from ..structure.base import StructureBase
@@ -109,46 +109,4 @@ def run_sync(
     return result
 
 
-def run_streamed(
-    agent: Agent,
-    input: str,
-    *,
-    context: Optional[Dict[str, Any]] = None,
-    output_structure: Optional[type[StructureBase]] = None,
-    session: Optional[Session] = None,
-) -> RunResultStreaming | StructureBase:
-    """Stream agent execution results.
-
-    Parameters
-    ----------
-    agent : Agent
-        Configured agent to execute.
-    input : str
-        Prompt or query string for the agent.
-    context : dict or None, default=None
-        Optional context dictionary passed to the agent.
-    output_structure : type[StructureBase] or None, default=None
-        Optional type used to cast the final output.
-    session : Session or None, default=None
-        Optional session for maintaining conversation history.
-
-    Returns
-    -------
-    RunResultStreaming
-        Streaming output wrapper from the agent execution.
-
-    Examples
-    --------
-    >>> from agents import Agent
-    >>> agent = Agent(name="test", instructions="test", model="gpt-4o-mini")
-    >>> result = run_streamed(agent, "Explain AI")  # doctest: +SKIP
-    >>> for chunk in result.stream_text():  # doctest: +SKIP
-    ...     print(chunk, end="")
-    """
-    result = Runner.run_streamed(agent, input, context=context, session=session)
-    if output_structure is not None:
-        return result.final_output_as(output_structure)
-    return result
-
-
-__all__ = ["run_sync", "run_async", "run_streamed"]
+__all__ = ["run_sync", "run_async"]

openai_sdk_helpers/agent/search/base.py

@@ -10,7 +10,7 @@ from __future__ import annotations
 import asyncio
 from abc import ABC, abstractmethod
 from pathlib import Path
-from typing import Generic, List, Optional, TypeVar, Union
+from typing import Any, Generic, List, Optional, TypeVar, Union
 
 from ..base import AgentBase
 from ..configuration import AgentConfiguration
@@ -33,10 +33,10 @@ class SearchPlanner(AgentBase, Generic[PlanType]):
 
     Parameters
     ----------
-    prompt_dir : Path, optional
-        Directory containing prompt templates.
-    default_model : str, optional
-        Default model identifier to use when not defined in configuration.
+    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
     -------
@@ -48,35 +48,39 @@ class SearchPlanner(AgentBase, Generic[PlanType]):
     Raises
     ------
     ValueError
-        If the default model is not provided.
+        If the configuration omits a model identifier.
 
     Examples
     --------
     >>> class MyPlanner(SearchPlanner):
-    ...     def _configure_agent(self):
+    ...     def _configure_agent(self, template_path=None, model=None):
     ...         return AgentConfiguration(
     ...             name="my_planner",
     ...             description="Plans searches",
     ...             output_structure=WebSearchPlanStructure,
     ...         )
-    >>> planner = MyPlanner(default_model="gpt-4o-mini")
+    >>> planner = MyPlanner(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,
+        **kwargs: Any,
     ) -> None:
         """Initialize the planner agent."""
-        configuration = self._configure_agent()
-        super().__init__(
-            configuration=configuration,
-            prompt_dir=prompt_dir,
-            default_model=default_model,
+        configuration = self._configure_agent(
+            template_path=template_path, model=model, **kwargs
         )
+        super().__init__(configuration=configuration)
 
     @abstractmethod
-    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 this planner.
 
         Returns
@@ -124,10 +128,10 @@ class SearchToolAgent(AgentBase, Generic[ItemType, ResultType, PlanType]):
 
     Parameters
     ----------
-    prompt_dir : Path, optional
-        Directory containing prompt templates.
-    default_model : str, optional
-        Default model identifier to use when not defined in configuration.
+    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.
     max_concurrent_searches : int, default=10
         Maximum number of concurrent search operations.
 
@@ -143,12 +147,12 @@ class SearchToolAgent(AgentBase, Generic[ItemType, ResultType, PlanType]):
     Raises
     ------
     ValueError
-        If the default model is not provided.
+        If the configuration omits a model identifier.
 
     Examples
     --------
     >>> class MyTool(SearchToolAgent):
-    ...     def _configure_agent(self):
+    ...     def _configure_agent(self, *, template_path: Path | str | None = None, model: str | None = None):
     ...         return AgentConfiguration(
     ...             name="my_tool",
     ...             description="Executes searches",
@@ -156,27 +160,34 @@ class SearchToolAgent(AgentBase, Generic[ItemType, ResultType, PlanType]):
     ...         )
     ...     async def run_search(self, item):
     ...         return "result"
-    >>> tool = MyTool(default_model="gpt-4o-mini")
+    >>> tool = MyTool(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,
         max_concurrent_searches: int = 10,
+        **kwargs: Any,
     ) -> None:
         """Initialize the search tool agent."""
         self._max_concurrent_searches = max_concurrent_searches
-        configuration = self._configure_agent()
-        super().__init__(
-            configuration=configuration,
-            prompt_dir=prompt_dir,
-            default_model=default_model,
+        configuration = self._configure_agent(
+            template_path=template_path,
+            model=model,
+            **kwargs,
         )
+        super().__init__(configuration=configuration)
 
     @abstractmethod
-    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 this tool agent.
 
         Returns
@@ -247,10 +258,10 @@ class SearchWriter(AgentBase, Generic[ReportType]):
 
     Parameters
     ----------
-    prompt_dir : Path, optional
-        Directory containing prompt templates.
-    default_model : str, optional
-        Default model identifier to use when not defined in configuration.
+    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
     -------
@@ -262,53 +273,20 @@ class SearchWriter(AgentBase, Generic[ReportType]):
     Raises
     ------
     ValueError
-        If the default model is not provided.
+        If the configuration omits a model identifier.
 
     Examples
     --------
     >>> class MyWriter(SearchWriter):
-    ...     def _configure_agent(self):
+    ...     def _configure_agent(self, template_path=None, model=None):
     ...         return AgentConfiguration(
     ...             name="my_writer",
     ...             description="Writes reports",
     ...             output_structure=WebSearchReportStructure,
     ...         )
-    >>> writer = MyWriter(default_model="gpt-4o-mini")
+    >>> writer = MyWriter(model="gpt-4o-mini")
     """
 
-    def __init__(
-        self,
-        prompt_dir: Optional[Path] = None,
-        default_model: Optional[str] = None,
-    ) -> None:
-        """Initialize the writer agent."""
-        configuration = self._configure_agent()
-        super().__init__(
-            configuration=configuration,
-            prompt_dir=prompt_dir,
-            default_model=default_model,
-        )
-
-    @abstractmethod
-    def _configure_agent(self) -> AgentConfiguration:
-        """Return configuration for this writer.
-
-        Returns
-        -------
-        AgentConfiguration
-            Configuration with name, description, and output_structure set.
-
-        Examples
-        --------
-        >>> configuration = AgentConfiguration(
-        ...     name="web_writer",
-        ...     description="Write web search report",
-        ...     output_structure=WebSearchReportStructure,
-        ... )
-        >>> return configuration
-        """
-        pass
-
     async def run_agent(
         self,
         query: str,

openai_sdk_helpers/agent/search/vector.py

@@ -3,13 +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 ...environment import DEFAULT_PROMPT_DIR
-from ...structure.prompt import PromptStructure
 from ...structure.vector_search import (
     VectorSearchItemStructure,
     VectorSearchItemResultStructure,
@@ -18,11 +17,11 @@ from ...structure.vector_search import (
     VectorSearchPlanStructure,
     VectorSearchReportStructure,
 )
-from ...tools import tool_handler_factory
 from ...vector_storage import VectorStorage
 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
 
@@ -32,11 +31,10 @@ class VectorAgentPlanner(SearchPlanner[VectorSearchPlanStructure]):
 
     Parameters
     ----------
-    prompt_dir : Path or None, default=None
-        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 configuration.
+    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
     -------
@@ -46,21 +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."""
-        prompt_directory = prompt_dir or DEFAULT_PROMPT_DIR
-        super().__init__(prompt_dir=prompt_directory, 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
@@ -74,6 +70,8 @@ class VectorAgentPlanner(SearchPlanner[VectorSearchPlanStructure]):
             description="Plan vector searches based on a user query.",
             output_structure=VectorSearchPlanStructure,
             model_settings=ModelSettings(tool_choice="none"),
+            template_path=template_path,
+            model=model,
         )
 
 
@@ -88,12 +86,11 @@ class VectorSearchTool(
 
     Parameters
     ----------
-    prompt_dir : Path or None, default=None
-        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 configuration.
-    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.
@@ -113,37 +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."""
-        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_directory,
-            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
@@ -151,6 +131,8 @@ 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",
@@ -158,6 +140,28 @@ class VectorSearchTool(
             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:
@@ -209,11 +213,10 @@ class VectorSearchWriter(SearchWriter[VectorSearchReportStructure]):
 
     Parameters
     ----------
-    prompt_dir : Path or None, default=None
-        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 configuration.
+    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
     -------
@@ -223,21 +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."""
-        prompt_directory = prompt_dir or DEFAULT_PROMPT_DIR
-        super().__init__(prompt_dir=prompt_directory, 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
@@ -251,10 +265,12 @@ class VectorSearchWriter(SearchWriter[VectorSearchReportStructure]):
             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
@@ -316,7 +332,7 @@ class VectorAgentSearch:
     Raises
     ------
     ValueError
-        If the default model is not provided.
+        If the model identifier is not provided.
     """
 
     def __init__(
@@ -353,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)
@@ -399,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",