openai-sdk-helpers 0.2.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

openai_sdk_helpers/agent/runner.py

@@ -9,9 +9,10 @@ from __future__ import annotations
 
 from typing import Any, Dict, Optional
 
-from agents import Agent, RunResult, RunResultStreaming, Runner
+from agents import Agent, RunResult, RunResultStreaming, Runner, Session
 
 from openai_sdk_helpers.utils.async_utils import run_coroutine_with_fallback
+from ..structure.base import StructureBase
 
 
 async def run_async(
@@ -19,7 +20,8 @@ async def run_async(
     input: str,
     *,
     context: Optional[Dict[str, Any]] = None,
-    output_type: Optional[Any] = None,
+    output_structure: Optional[type[StructureBase]] = None,
+    session: Optional[Session] = None,
 ) -> Any:
     """Run an Agent asynchronously.
 
@@ -31,13 +33,15 @@ async def run_async(
         Prompt or query string for the agent.
     context : dict or None, default=None
         Optional context dictionary passed to the agent.
-    output_type : type or None, default=None
+    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
     -------
     Any
-        Agent response, optionally converted to ``output_type``.
+        Agent response, optionally converted to ``output_structure``.
 
     Examples
     --------
@@ -49,9 +53,9 @@ async def run_async(
     ...     return result
     >>> asyncio.run(example())  # doctest: +SKIP
     """
-    result = await Runner.run(agent, input, context=context)
-    if output_type is not None:
-        return result.final_output_as(output_type)
+    result = await Runner.run(agent, input, context=context, session=session)
+    if output_structure is not None:
+        return result.final_output_as(output_structure)
     return result
 
 
@@ -60,7 +64,8 @@ def run_sync(
     input: str,
     *,
     context: Optional[Dict[str, Any]] = None,
-    output_type: Optional[Any] = None,
+    output_structure: Optional[type[StructureBase]] = None,
+    session: Optional[Session] = None,
 ) -> Any:
     """Run an Agent synchronously.
 
@@ -76,13 +81,15 @@ def run_sync(
         Prompt or query string for the agent.
     context : dict or None, default=None
         Optional context dictionary passed to the agent.
-    output_type : type or None, default=None
+    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
     -------
     Any
-        Agent response, optionally converted to ``output_type``.
+        Agent response, optionally converted to ``output_structure``.
 
     Raises
     ------
@@ -95,10 +102,10 @@ def run_sync(
     >>> agent = Agent(name="test", instructions="test", model="gpt-4o-mini")
     >>> result = run_sync(agent, "What is 2+2?")  # doctest: +SKIP
     """
-    coro = Runner.run(agent, input, context=context)
+    coro = Runner.run(agent, input, context=context, session=session)
     result: RunResult = run_coroutine_with_fallback(coro)
-    if output_type is not None:
-        return result.final_output_as(output_type)
+    if output_structure is not None:
+        return result.final_output_as(output_structure)
     return result
 
 
@@ -107,8 +114,9 @@ def run_streamed(
     input: str,
     *,
     context: Optional[Dict[str, Any]] = None,
-    output_type: Optional[Any] = None,
-) -> RunResultStreaming:
+    output_structure: Optional[type[StructureBase]] = None,
+    session: Optional[Session] = None,
+) -> RunResultStreaming | StructureBase:
     """Stream agent execution results.
 
     Parameters
@@ -119,8 +127,10 @@ def run_streamed(
         Prompt or query string for the agent.
     context : dict or None, default=None
         Optional context dictionary passed to the agent.
-    output_type : type or None, default=None
+    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
     -------
@@ -135,9 +145,9 @@ def run_streamed(
     >>> for chunk in result.stream_text():  # doctest: +SKIP
     ...     print(chunk, end="")
     """
-    result = Runner.run_streamed(agent, input, context=context)
-    if output_type is not None:
-        return result.final_output_as(output_type)
+    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
 
 

openai_sdk_helpers/agent/search/base.py

@@ -13,14 +13,16 @@ from pathlib import Path
 from typing import Generic, List, Optional, TypeVar, Union
 
 from ..base import AgentBase
-from ..config import AgentConfig
+from ..config import AgentConfiguration
+from ...structure.base import StructureBase
 
 # Type variables for search workflow components
-ItemType = TypeVar("ItemType")  # Search item structure (e.g., WebSearchItemStructure)
+ItemType = TypeVar(
+    "ItemType", bound=StructureBase
+)  # Search item structure (e.g., WebSearchItemStructure)
 ResultType = TypeVar("ResultType")  # Individual search result
-PlanType = TypeVar("PlanType")  # Complete search plan structure
-ReportType = TypeVar("ReportType")  # Final report structure
-OutputType = TypeVar("OutputType")  # Generic output type
+PlanType = TypeVar("PlanType", bound=StructureBase)  # Complete search plan structure
+ReportType = TypeVar("ReportType", bound=StructureBase)  # Final report structure
 
 
 class SearchPlanner(AgentBase, Generic[PlanType]):
@@ -29,12 +31,35 @@ class SearchPlanner(AgentBase, Generic[PlanType]):
     Subclasses implement specific planner logic by overriding the
     `_configure_agent` method and specifying the output type.
 
+    Parameters
+    ----------
+    prompt_dir : Path, optional
+        Directory containing prompt templates.
+    default_model : str, optional
+        Default model identifier to use when not defined in config.
+
     Methods
     -------
     run_agent(query)
         Generate a search plan for the provided query.
     _configure_agent()
-        Return AgentConfig for this planner instance.
+        Return AgentConfiguration for this planner instance.
+
+    Raises
+    ------
+    ValueError
+        If the default model is not provided.
+
+    Examples
+    --------
+    >>> class MyPlanner(SearchPlanner):
+    ...     def _configure_agent(self):
+    ...         return AgentConfiguration(
+    ...             name="my_planner",
+    ...             description="Plans searches",
+    ...             output_structure=WebSearchPlanStructure,
+    ...         )
+    >>> planner = MyPlanner(default_model="gpt-4o-mini")
     """
 
     def __init__(
@@ -42,15 +67,7 @@ class SearchPlanner(AgentBase, Generic[PlanType]):
         prompt_dir: Optional[Path] = None,
         default_model: Optional[str] = None,
     ) -> None:
-        """Initialize the planner agent.
-
-        Parameters
-        ----------
-        prompt_dir : Path, optional
-            Directory containing prompt templates.
-        default_model : str, optional
-            Default model identifier to use when not defined in config.
-        """
+        """Initialize the planner agent."""
         config = self._configure_agent()
         super().__init__(
             config=config,
@@ -59,20 +76,20 @@ class SearchPlanner(AgentBase, Generic[PlanType]):
         )
 
     @abstractmethod
-    def _configure_agent(self) -> AgentConfig:
+    def _configure_agent(self) -> AgentConfiguration:
         """Return configuration for this planner.
 
         Returns
         -------
-        AgentConfig
-            Configuration with name, description, and output_type set.
+        AgentConfiguration
+            Configuration with name, description, and output_structure set.
 
         Examples
         --------
-        >>> config = AgentConfig(
+        >>> config = AgentConfiguration(
         ...     name="web_planner",
         ...     description="Plan web searches",
-        ...     output_type=WebSearchPlanStructure,
+        ...     output_structure=WebSearchPlanStructure,
         ... )
         >>> return config
         """
@@ -93,7 +110,7 @@ class SearchPlanner(AgentBase, Generic[PlanType]):
         """
         result: PlanType = await self.run_async(
             input=query,
-            output_type=self._output_type,
+            output_structure=self._output_structure,
         )
         return result
 
@@ -105,6 +122,15 @@ class SearchToolAgent(AgentBase, Generic[ItemType, ResultType, PlanType]):
     Subclasses implement search execution logic by overriding the
     `_configure_agent` and `run_search` methods.
 
+    Parameters
+    ----------
+    prompt_dir : Path, optional
+        Directory containing prompt templates.
+    default_model : str, optional
+        Default model identifier to use when not defined in config.
+    max_concurrent_searches : int, default=10
+        Maximum number of concurrent search operations.
+
     Methods
     -------
     run_agent(search_plan)
@@ -112,7 +138,25 @@ class SearchToolAgent(AgentBase, Generic[ItemType, ResultType, PlanType]):
     run_search(item)
         Execute a single search item.
     _configure_agent()
-        Return AgentConfig for this tool agent.
+        Return AgentConfiguration for this tool agent.
+
+    Raises
+    ------
+    ValueError
+        If the default model is not provided.
+
+    Examples
+    --------
+    >>> class MyTool(SearchToolAgent):
+    ...     def _configure_agent(self):
+    ...         return AgentConfiguration(
+    ...             name="my_tool",
+    ...             description="Executes searches",
+    ...             input_structure=WebSearchPlanStructure,
+    ...         )
+    ...     async def run_search(self, item):
+    ...         return "result"
+    >>> tool = MyTool(default_model="gpt-4o-mini")
     """
 
     def __init__(
@@ -122,17 +166,7 @@ class SearchToolAgent(AgentBase, Generic[ItemType, ResultType, PlanType]):
         default_model: Optional[str] = None,
         max_concurrent_searches: int = 10,
     ) -> None:
-        """Initialize the search tool agent.
-
-        Parameters
-        ----------
-        prompt_dir : Path, optional
-            Directory containing prompt templates.
-        default_model : str, optional
-            Default model identifier to use when not defined in config.
-        max_concurrent_searches : int, default=10
-            Maximum number of concurrent search operations.
-        """
+        """Initialize the search tool agent."""
         self._max_concurrent_searches = max_concurrent_searches
         config = self._configure_agent()
         super().__init__(
@@ -142,20 +176,20 @@ class SearchToolAgent(AgentBase, Generic[ItemType, ResultType, PlanType]):
         )
 
     @abstractmethod
-    def _configure_agent(self) -> AgentConfig:
+    def _configure_agent(self) -> AgentConfiguration:
         """Return configuration for this tool agent.
 
         Returns
         -------
-        AgentConfig
-            Configuration with name, description, input_type, and tools set.
+        AgentConfiguration
+            Configuration with name, description, input_structure, and tools set.
 
         Examples
         --------
-        >>> config = AgentConfig(
+        >>> config = AgentConfiguration(
         ...     name="web_search",
         ...     description="Perform web searches",
-        ...     input_type=WebSearchPlanStructure,
+        ...     input_structure=WebSearchPlanStructure,
         ...     tools=[WebSearchTool()],
         ... )
         >>> return config
@@ -211,12 +245,35 @@ class SearchWriter(AgentBase, Generic[ReportType]):
     Synthesizes search results into a final report. Subclasses implement
     specific report generation logic by overriding the `_configure_agent` method.
 
+    Parameters
+    ----------
+    prompt_dir : Path, optional
+        Directory containing prompt templates.
+    default_model : str, optional
+        Default model identifier to use when not defined in config.
+
     Methods
     -------
     run_agent(query, search_results)
         Generate a report from search results.
     _configure_agent()
-        Return AgentConfig for this writer instance.
+        Return AgentConfiguration for this writer instance.
+
+    Raises
+    ------
+    ValueError
+        If the default model is not provided.
+
+    Examples
+    --------
+    >>> class MyWriter(SearchWriter):
+    ...     def _configure_agent(self):
+    ...         return AgentConfiguration(
+    ...             name="my_writer",
+    ...             description="Writes reports",
+    ...             output_structure=WebSearchReportStructure,
+    ...         )
+    >>> writer = MyWriter(default_model="gpt-4o-mini")
     """
 
     def __init__(
@@ -224,15 +281,7 @@ class SearchWriter(AgentBase, Generic[ReportType]):
         prompt_dir: Optional[Path] = None,
         default_model: Optional[str] = None,
     ) -> None:
-        """Initialize the writer agent.
-
-        Parameters
-        ----------
-        prompt_dir : Path, optional
-            Directory containing prompt templates.
-        default_model : str, optional
-            Default model identifier to use when not defined in config.
-        """
+        """Initialize the writer agent."""
         config = self._configure_agent()
         super().__init__(
             config=config,
@@ -241,20 +290,20 @@ class SearchWriter(AgentBase, Generic[ReportType]):
         )
 
     @abstractmethod
-    def _configure_agent(self) -> AgentConfig:
+    def _configure_agent(self) -> AgentConfiguration:
         """Return configuration for this writer.
 
         Returns
         -------
-        AgentConfig
-            Configuration with name, description, and output_type set.
+        AgentConfiguration
+            Configuration with name, description, and output_structure set.
 
         Examples
         --------
-        >>> config = AgentConfig(
+        >>> config = AgentConfiguration(
         ...     name="web_writer",
         ...     description="Write web search report",
-        ...     output_type=WebSearchReportStructure,
+        ...     output_structure=WebSearchReportStructure,
         ... )
         >>> return config
         """
@@ -286,7 +335,7 @@ class SearchWriter(AgentBase, Generic[ReportType]):
         result: ReportType = await self.run_async(
             input=query,
             context=template_context,
-            output_type=self._output_type,
+            output_structure=self._output_structure,
         )
         return result
 

openai_sdk_helpers/agent/search/vector.py

@@ -16,7 +16,7 @@ from ...structure.vector_search import (
     VectorSearchReportStructure,
 )
 from ...vector_storage import VectorStorage
-from ..config import AgentConfig
+from ..config import AgentConfiguration
 from ..utils import run_coroutine_agent_sync
 from .base import SearchPlanner, SearchToolAgent, SearchWriter
 
@@ -26,38 +26,47 @@ MAX_CONCURRENT_SEARCHES = 10
 class VectorSearchPlanner(SearchPlanner[VectorSearchPlanStructure]):
     """Plan vector searches to satisfy a user query.
 
+    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.
+
     Methods
     -------
     run_agent(query)
         Generate a vector search plan for the provided query.
+
+    Raises
+    ------
+    ValueError
+        If the default model is not provided.
+
+    Examples
+    --------
+    >>> planner = VectorSearchPlanner(default_model="gpt-4o-mini")
     """
 
     def __init__(
         self, prompt_dir: Optional[Path] = None, default_model: Optional[str] = None
     ) -> None:
-        """Initialize the planner agent.
-
-        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.
-        """
+        """Initialize the planner agent."""
         super().__init__(prompt_dir=prompt_dir, default_model=default_model)
 
-    def _configure_agent(self) -> AgentConfig:
+    def _configure_agent(self) -> AgentConfiguration:
         """Return configuration for the vector planner agent.
 
         Returns
         -------
-        AgentConfig
+        AgentConfiguration
             Configuration with name, description, and output type.
         """
-        return AgentConfig(
+        return AgentConfiguration(
             name="vector_planner",
+            instructions="Agent instructions",
             description="Plan vector searches based on a user query.",
-            output_type=VectorSearchPlanStructure,
+            output_structure=VectorSearchPlanStructure,
         )
 
 
@@ -70,12 +79,37 @@ class VectorSearchTool(
 ):
     """Execute vector searches defined in a search plan.
 
+    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
+        Name of the vector store to query.
+    max_concurrent_searches : int, default=MAX_CONCURRENT_SEARCHES
+        Maximum number of concurrent vector search tasks to run.
+    vector_storage : VectorStorage or None, default=None
+        Optional preconfigured vector storage instance to reuse.
+    vector_storage_factory : Callable or None, default=None
+        Factory for constructing a VectorStorage when one is not provided.
+        Receives ``store_name`` as an argument.
+
     Methods
     -------
     run_agent(search_plan)
         Execute searches described by the plan.
     run_search(item)
         Perform a single vector search and summarise the result.
+
+    Raises
+    ------
+    ValueError
+        If the default model is not provided.
+
+    Examples
+    --------
+    >>> tool = VectorSearchTool(default_model="gpt-4o-mini", store_name="my_store")
     """
 
     def __init__(
@@ -88,24 +122,7 @@ class VectorSearchTool(
         vector_storage: Optional[VectorStorage] = None,
         vector_storage_factory: Optional[Callable[[str], VectorStorage]] = None,
     ) -> None:
-        """Initialize the search tool agent.
-
-        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
-            Name of the vector store to query.
-        max_concurrent_searches : int, default=MAX_CONCURRENT_SEARCHES
-            Maximum number of concurrent vector search tasks to run.
-        vector_storage : VectorStorage or None, default=None
-            Optional preconfigured vector storage instance to reuse.
-        vector_storage_factory : Callable or None, default=None
-            Factory for constructing a VectorStorage when one is not provided.
-            Receives ``store_name`` as an argument.
-        """
+        """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
@@ -117,19 +134,20 @@ class VectorSearchTool(
             max_concurrent_searches=max_concurrent_searches,
         )
 
-    def _configure_agent(self) -> AgentConfig:
+    def _configure_agent(self) -> AgentConfiguration:
         """Return configuration for the vector search tool agent.
 
         Returns
         -------
-        AgentConfig
+        AgentConfiguration
             Configuration with name, description, and input type.
         """
-        return AgentConfig(
+        return AgentConfiguration(
             name="vector_search",
+            instructions="Agent instructions",
             description="Perform vector searches based on a search plan.",
-            input_type=VectorSearchPlanStructure,
-            output_type=VectorSearchItemResultsStructure,
+            input_structure=VectorSearchPlanStructure,
+            output_structure=VectorSearchItemResultsStructure,
         )
 
     def _get_vector_storage(self) -> VectorStorage:
@@ -179,38 +197,47 @@ class VectorSearchTool(
 class VectorSearchWriter(SearchWriter[VectorSearchReportStructure]):
     """Generate reports summarizing vector search results.
 
+    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.
+
     Methods
     -------
     run_agent(query, search_results)
         Compile a final report from search results.
+
+    Raises
+    ------
+    ValueError
+        If the default model is not provided.
+
+    Examples
+    --------
+    >>> writer = VectorSearchWriter(default_model="gpt-4o-mini")
     """
 
     def __init__(
         self, prompt_dir: Optional[Path] = None, default_model: Optional[str] = None
     ) -> None:
-        """Initialize the writer agent.
-
-        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.
-        """
+        """Initialize the writer agent."""
         super().__init__(prompt_dir=prompt_dir, default_model=default_model)
 
-    def _configure_agent(self) -> AgentConfig:
+    def _configure_agent(self) -> AgentConfiguration:
         """Return configuration for the vector writer agent.
 
         Returns
         -------
-        AgentConfig
+        AgentConfiguration
             Configuration with name, description, and output type.
         """
-        return AgentConfig(
+        return AgentConfiguration(
             name="vector_writer",
+            instructions="Agent instructions",
             description="Write a report based on search results.",
-            output_type=VectorSearchReportStructure,
+            output_structure=VectorSearchReportStructure,
         )
 
 
@@ -222,6 +249,22 @@ class VectorSearch:
     comprehensive reports. It combines ``VectorSearchPlanner``,
     ``VectorSearchTool``, and ``VectorSearchWriter`` into a single 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.
+    vector_store_name : str or None, default=None
+        Name of the vector store to query.
+    max_concurrent_searches : int, default=MAX_CONCURRENT_SEARCHES
+        Maximum number of concurrent search tasks to run.
+    vector_storage : VectorStorage or None, default=None
+        Optional preconfigured vector storage instance to reuse.
+    vector_storage_factory : callable, default=None
+        Factory used to construct a VectorStorage when one is not provided.
+        Receives ``vector_store_name`` as an argument.
+
     Examples
     --------
     Basic vector search:
@@ -253,6 +296,11 @@ class VectorSearch:
         Convenience asynchronous entry point for the workflow.
     run_vector_agent_sync(search_query)
         Convenience synchronous entry point for the workflow.
+
+    Raises
+    ------
+    ValueError
+        If the default model is not provided.
     """
 
     def __init__(
@@ -265,24 +313,7 @@ class VectorSearch:
         vector_storage: Optional[VectorStorage] = None,
         vector_storage_factory: Optional[Callable[[str], VectorStorage]] = None,
     ) -> None:
-        """Create the main VectorSearch agent.
-
-        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.
-        vector_store_name : str or None, default=None
-            Name of the vector store to query.
-        max_concurrent_searches : int, default=MAX_CONCURRENT_SEARCHES
-            Maximum number of concurrent search tasks to run.
-        vector_storage : VectorStorage or None, default=None
-            Optional preconfigured vector storage instance to reuse.
-        vector_storage_factory : callable, default=None
-            Factory used to construct a VectorStorage when one is not provided.
-            Receives ``vector_store_name`` as an argument.
-        """
+        """Create the main VectorSearch agent."""
         self._prompt_dir = prompt_dir
         self._default_model = default_model
         self._vector_store_name = vector_store_name