openai-sdk-helpers 0.0.7__py3-none-any.whl → 0.0.9__py3-none-any.whl

openai_sdk_helpers/agent/runner.py

@@ -1,179 +1,101 @@
 """Convenience wrappers for running OpenAI agents.
 
-These helpers provide a narrow surface around the lower-level functions in
-``openai-sdk-helpers.agent.base`` so that callers can execute agents with consistent
+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.
 """
 
 from __future__ import annotations
 
 from typing import Any, Dict, Optional
-import asyncio
-import threading
-from agents import Agent, Runner, RunResult, RunResultStreaming
 
+from agents import Agent, RunResult, RunResultStreaming, Runner
 
-async def _run_async(
+from openai_sdk_helpers.async_utils import run_coroutine_with_fallback
+
+
+async def run_async(
     agent: Agent,
     input: str,
     context: Optional[Dict[str, Any]] = None,
     output_type: Optional[Any] = None,
 ) -> Any:
-    """Run an ``Agent`` asynchronously.
+    """Run an Agent asynchronously.
 
     Parameters
     ----------
-    agent
+    agent : Agent
         Configured agent instance to execute.
-    input
+    input : str
         Prompt or query string for the agent.
-    context
-        Optional context dictionary passed to the agent. Default ``None``.
-    output_type
-        Optional type used to cast the final output. Default ``None``.
+    context : dict or None, default=None
+        Optional context dictionary passed to the agent.
+    output_type : type or None, default=None
+        Optional type used to cast the final output.
 
     Returns
     -------
     Any
         Agent response, optionally converted to ``output_type``.
+
+    Examples
+    --------
+    >>> import asyncio
+    >>> from agents import Agent
+    >>> async def example():
+    ...     agent = Agent(name="test", instructions="test", model="gpt-4o-mini")
+    ...     result = await run_async(agent, "What is 2+2?")
+    ...     return result
+    >>> asyncio.run(example())  # doctest: +SKIP
     """
     result = await Runner.run(agent, input, context=context)
     if output_type is not None:
-        result = result.final_output_as(output_type)
-    return result
-
-
-def _run_sync(
-    agent: Agent,
-    input: str,
-    context: Optional[Dict[str, Any]] = None,
-) -> RunResult:
-    """Run an ``Agent`` synchronously.
-
-    Parameters
-    ----------
-    agent
-        Configured agent instance to execute.
-    input
-        Prompt or query string for the agent.
-    context
-        Optional context dictionary passed to the agent. Default ``None``.
-
-    Returns
-    -------
-    RunResult
-        Result from the agent execution.
-    """
-    coro = Runner.run(agent, input, context=context)
-    try:
-        loop = asyncio.get_running_loop()
-    except RuntimeError:
-        return asyncio.run(coro)
-
-    if loop.is_running():
-        result: RunResult | None = None
-
-        def _thread_runner() -> None:
-            nonlocal result
-            result = asyncio.run(coro)
-
-        thread = threading.Thread(target=_thread_runner, daemon=True)
-        thread.start()
-        thread.join()
-        if result is None:
-            raise RuntimeError("Agent execution did not return a result.")
-        return result
-
-    return loop.run_until_complete(coro)
-
-
-def _run_streamed(
-    agent: Agent,
-    input: str,
-    context: Optional[Dict[str, Any]] = None,
-) -> RunResultStreaming:
-    """Run an ``Agent`` synchronously and return a streaming result.
-
-    Parameters
-    ----------
-    agent
-        Configured agent to execute.
-    input
-        Prompt or query string for the agent.
-    context
-        Optional context dictionary passed to the agent. Default ``None``.
-
-    Returns
-    -------
-    RunResultStreaming
-        Instance for streaming outputs.
-    """
-    result = Runner.run_streamed(agent, input, context=context)
+        return result.final_output_as(output_type)
     return result
 
 
-async def run_async(
+def run_sync(
     agent: Agent,
     input: str,
     context: Optional[Dict[str, Any]] = None,
     output_type: Optional[Any] = None,
 ) -> Any:
-    """Run an ``Agent`` asynchronously.
+    """Run an Agent synchronously.
+
+    Internally uses async execution with proper event loop handling.
+    If an event loop is already running, creates a new thread to avoid
+    nested event loop errors.
 
     Parameters
     ----------
-    agent
+    agent : Agent
         Configured agent instance to execute.
-    input
+    input : str
         Prompt or query string for the agent.
-    context
-        Optional context dictionary passed to the agent. Default ``None``.
-    output_type
-        Optional type used to cast the final output. Default ``None``.
+    context : dict or None, default=None
+        Optional context dictionary passed to the agent.
+    output_type : type or None, default=None
+        Optional type used to cast the final output.
 
     Returns
     -------
     Any
         Agent response, optionally converted to ``output_type``.
-    """
-    return await _run_async(
-        agent=agent,
-        input=input,
-        context=context,
-        output_type=output_type,
-    )
-
-
-def run_sync(
-    agent: Agent,
-    input: str,
-    context: Optional[Dict[str, Any]] = None,
-    output_type: Optional[Any] = None,
-) -> Any:
-    """Run an ``Agent`` synchronously.
 
-    Parameters
-    ----------
-    agent
-        Configured agent instance to execute.
-    input
-        Prompt or query string for the agent.
-    context
-        Optional context dictionary passed to the agent. Default ``None``.
-    output_type
-        Optional type used to cast the final output. Default ``None``.
+    Raises
+    ------
+    AsyncExecutionError
+        If execution fails or times out.
 
-    Returns
-    -------
-    Any
-        Agent response, optionally converted to ``output_type``.
+    Examples
+    --------
+    >>> from agents import Agent
+    >>> agent = Agent(name="test", instructions="test", model="gpt-4o-mini")
+    >>> result = run_sync(agent, "What is 2+2?")  # doctest: +SKIP
     """
-    result: RunResult = _run_sync(
-        agent=agent,
-        input=input,
-        context=context,
-    )
-    if output_type:
+    coro = Runner.run(agent, input, context=context)
+    result: RunResult = run_coroutine_with_fallback(coro)
+    if output_type is not None:
         return result.final_output_as(output_type)
     return result
 
@@ -184,30 +106,34 @@ def run_streamed(
     context: Optional[Dict[str, Any]] = None,
     output_type: Optional[Any] = None,
 ) -> RunResultStreaming:
-    """Run an ``Agent`` and return a streaming result.
+    """Stream agent execution results.
 
     Parameters
     ----------
-    agent
-        Configured agent instance to execute.
-    input
+    agent : Agent
+        Configured agent to execute.
+    input : str
         Prompt or query string for the agent.
-    context
-        Optional context dictionary passed to the agent. Default ``None``.
-    output_type
-        Optional type used to cast the final output. Default ``None``.
+    context : dict or None, default=None
+        Optional context dictionary passed to the agent.
+    output_type : type or None, default=None
+        Optional type used to cast the final output.
 
     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 = _run_streamed(
-        agent=agent,
-        input=input,
-        context=context,
-    )
-    if output_type:
+    result = Runner.run_streamed(agent, input, context=context)
+    if output_type is not None:
         return result.final_output_as(output_type)
     return result
 

openai_sdk_helpers/agent/search/__init__.py

@@ -0,0 +1,33 @@
+"""Search-related agent workflows and helpers."""
+
+from .base import SearchPlanner, SearchToolAgent, SearchWriter
+from .web import (
+    MAX_CONCURRENT_SEARCHES as WEB_MAX_CONCURRENT_SEARCHES,
+    WebAgentPlanner,
+    WebSearchToolAgent,
+    WebAgentWriter,
+    WebAgentSearch,
+)
+from .vector import (
+    MAX_CONCURRENT_SEARCHES as VECTOR_MAX_CONCURRENT_SEARCHES,
+    VectorSearchPlanner,
+    VectorSearchTool,
+    VectorSearchWriter,
+    VectorSearch,
+)
+
+__all__ = [
+    "SearchPlanner",
+    "SearchToolAgent",
+    "SearchWriter",
+    "WEB_MAX_CONCURRENT_SEARCHES",
+    "WebAgentPlanner",
+    "WebSearchToolAgent",
+    "WebAgentWriter",
+    "WebAgentSearch",
+    "VECTOR_MAX_CONCURRENT_SEARCHES",
+    "VectorSearchPlanner",
+    "VectorSearchTool",
+    "VectorSearchWriter",
+    "VectorSearch",
+]

openai_sdk_helpers/agent/search/base.py

@@ -0,0 +1,297 @@
+"""Generic base classes for search agent workflows.
+
+This module provides abstract base classes that extract common patterns from
+web search and vector search implementations, eliminating code duplication
+and providing a consistent interface for new search types.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Generic, List, Optional, TypeVar, Union
+
+from ..base import AgentBase
+from ..config import AgentConfig
+
+# Type variables for search workflow components
+ItemType = TypeVar("ItemType")  # 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
+
+
+class SearchPlanner(AgentBase, Generic[PlanType]):
+    """Generic planner agent for search workflows.
+
+    Subclasses implement specific planner logic by overriding the
+    `_configure_agent` method and specifying the output type.
+
+    Methods
+    -------
+    run_agent(query)
+        Generate a search plan for the provided query.
+    _configure_agent()
+        Return AgentConfig for this planner instance.
+    """
+
+    def __init__(
+        self,
+        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.
+        """
+        config = self._configure_agent()
+        super().__init__(
+            config=config,
+            prompt_dir=prompt_dir,
+            default_model=default_model,
+        )
+
+    @abstractmethod
+    def _configure_agent(self) -> AgentConfig:
+        """Return configuration for this planner.
+
+        Returns
+        -------
+        AgentConfig
+            Configuration with name, description, and output_type set.
+
+        Examples
+        --------
+        >>> config = AgentConfig(
+        ...     name="web_planner",
+        ...     description="Plan web searches",
+        ...     output_type=WebSearchPlanStructure,
+        ... )
+        >>> return config
+        """
+        pass
+
+    async def run_agent(self, query: str) -> PlanType:
+        """Generate a search plan for the query.
+
+        Parameters
+        ----------
+        query : str
+            User search query.
+
+        Returns
+        -------
+        PlanType
+            Generated search plan of the configured output type.
+        """
+        result: PlanType = await self.run_async(
+            input=query,
+            output_type=self._output_type,
+        )
+        return result
+
+
+class SearchToolAgent(AgentBase, Generic[ItemType, ResultType, PlanType]):
+    """Generic tool agent for executing search workflows.
+
+    Executes individual searches in a plan with concurrency control.
+    Subclasses implement search execution logic by overriding the
+    `_configure_agent` and `run_search` methods.
+
+    Methods
+    -------
+    run_agent(search_plan)
+        Execute all searches in the plan.
+    run_search(item)
+        Execute a single search item.
+    _configure_agent()
+        Return AgentConfig for this tool agent.
+    """
+
+    def __init__(
+        self,
+        prompt_dir: Optional[Path] = None,
+        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.
+        """
+        self._max_concurrent_searches = max_concurrent_searches
+        config = self._configure_agent()
+        super().__init__(
+            config=config,
+            prompt_dir=prompt_dir,
+            default_model=default_model,
+        )
+
+    @abstractmethod
+    def _configure_agent(self) -> AgentConfig:
+        """Return configuration for this tool agent.
+
+        Returns
+        -------
+        AgentConfig
+            Configuration with name, description, input_type, and tools set.
+
+        Examples
+        --------
+        >>> config = AgentConfig(
+        ...     name="web_search",
+        ...     description="Perform web searches",
+        ...     input_type=WebSearchPlanStructure,
+        ...     tools=[WebSearchTool()],
+        ... )
+        >>> return config
+        """
+        pass
+
+    @abstractmethod
+    async def run_search(self, item: ItemType) -> ResultType:
+        """Execute a single search item.
+
+        Parameters
+        ----------
+        item : ItemType
+            Individual search item from the plan.
+
+        Returns
+        -------
+        ResultType
+            Result of executing the search item.
+        """
+        pass
+
+    async def run_agent(self, search_plan: PlanType) -> List[ResultType]:
+        """Execute all searches in the plan with concurrency control.
+
+        Parameters
+        ----------
+        search_plan : PlanType
+            Plan structure containing search items.
+
+        Returns
+        -------
+        list[ResultType]
+            Completed search results from executing the plan.
+        """
+        semaphore = asyncio.Semaphore(self._max_concurrent_searches)
+
+        async def _bounded_search(item: ItemType) -> Optional[ResultType]:
+            """Execute search within concurrency limit."""
+            async with semaphore:
+                return await self.run_search(item)
+
+        items = getattr(search_plan, "searches", [])
+        tasks = [asyncio.create_task(_bounded_search(item)) for item in items]
+        results = await asyncio.gather(*tasks)
+
+        return [result for result in results if result is not None]
+
+
+class SearchWriter(AgentBase, Generic[ReportType]):
+    """Generic writer agent for search workflow reports.
+
+    Synthesizes search results into a final report. Subclasses implement
+    specific report generation logic by overriding the `_configure_agent` method.
+
+    Methods
+    -------
+    run_agent(query, search_results)
+        Generate a report from search results.
+    _configure_agent()
+        Return AgentConfig for this writer instance.
+    """
+
+    def __init__(
+        self,
+        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.
+        """
+        config = self._configure_agent()
+        super().__init__(
+            config=config,
+            prompt_dir=prompt_dir,
+            default_model=default_model,
+        )
+
+    @abstractmethod
+    def _configure_agent(self) -> AgentConfig:
+        """Return configuration for this writer.
+
+        Returns
+        -------
+        AgentConfig
+            Configuration with name, description, and output_type set.
+
+        Examples
+        --------
+        >>> config = AgentConfig(
+        ...     name="web_writer",
+        ...     description="Write web search report",
+        ...     output_type=WebSearchReportStructure,
+        ... )
+        >>> return config
+        """
+        pass
+
+    async def run_agent(
+        self,
+        query: str,
+        search_results: List[ResultType],
+    ) -> ReportType:
+        """Generate a report from search results.
+
+        Parameters
+        ----------
+        query : str
+            Original search query.
+        search_results : list[ResultType]
+            Results from the search execution phase.
+
+        Returns
+        -------
+        ReportType
+            Final report structure of the configured output type.
+        """
+        template_context = {
+            "original_query": query,
+            "search_results": search_results,
+        }
+        result: ReportType = await self.run_async(
+            input=query,
+            context=template_context,
+            output_type=self._output_type,
+        )
+        return result
+
+
+__all__ = [
+    "SearchPlanner",
+    "SearchToolAgent",
+    "SearchWriter",
+]