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

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

@@ -11,11 +11,10 @@ from pathlib import Path
 from typing import Any, Callable, Dict, List, Optional
 
 
-from ..structure import TaskStructure, PlanStructure, PromptStructure
-from ..utils import DataclassJSONSerializable, ensure_directory, log
+from ..structure import TaskStructure, PlanStructure, PromptStructure, AgentEnum
+from ..utils import ensure_directory, log
 from .base import AgentBase
-from .config import AgentConfiguration
-from ..structure.plan.enum import AgentEnum
+from .configuration import AgentConfiguration
 
 PromptFn = Callable[[str], PromptStructure]
 BuildPlanFn = Callable[[str], PlanStructure]
@@ -40,12 +39,12 @@ class CoordinatorAgent(AgentBase):
         Base path for persisting project artifacts.
     name : str
         Name of the parent module for data organization.
-    config : AgentConfiguration or None, default=None
+    configuration : AgentConfiguration or None, default=None
         Optional agent configuration describing prompts and metadata.
-    prompt_dir : Path or None, default=None
-        Optional directory holding prompt templates.
-    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
     -------
@@ -84,9 +83,9 @@ class CoordinatorAgent(AgentBase):
         summarize_fn: SummarizeFn,
         module_data_path: Path,
         name: str,
-        config: Optional[AgentConfiguration] = None,
-        prompt_dir: Optional[Path] = None,
-        default_model: Optional[str] = None,
+        configuration: Optional[AgentConfiguration] = None,
+        template_path: Optional[Path] = None,
+        model: Optional[str] = None,
     ) -> None:
         """Initialize the project manager with injected workflow helpers.
 
@@ -104,12 +103,12 @@ class CoordinatorAgent(AgentBase):
             Base path for persisting project artifacts.
         name : str
             Name of the parent module for data organization.
-        config : AgentConfiguration or None, default=None
+        configuration : AgentConfiguration or None, default=None
             Optional agent configuration describing prompts and metadata.
-        prompt_dir : Path or None, default=None
-            Optional directory holding prompt templates.
-        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
         ------
@@ -127,15 +126,15 @@ class CoordinatorAgent(AgentBase):
         ...     name="test",
         ... )
         """
-        if config is None:
-            config = AgentConfiguration(
-                name="coordinator_agent",
+        if configuration is None:
+            configuration = AgentConfiguration(
+                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__(
-            config=config, 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,10 +10,10 @@ 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 ..config import AgentConfiguration
+from ..configuration import AgentConfiguration
 from ...structure.base import StructureBase
 
 # Type variables for search workflow components
@@ -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 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
     -------
@@ -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."""
-        config = self._configure_agent()
-        super().__init__(
-            config=config,
-            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
@@ -86,12 +90,12 @@ class SearchPlanner(AgentBase, Generic[PlanType]):
 
         Examples
         --------
-        >>> config = AgentConfiguration(
+        >>> configuration = AgentConfiguration(
         ...     name="web_planner",
         ...     description="Plan web searches",
         ...     output_structure=WebSearchPlanStructure,
         ... )
-        >>> return config
+        >>> return configuration
         """
         pass
 
@@ -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 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.
     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
-        config = self._configure_agent()
-        super().__init__(
-            config=config,
-            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
@@ -186,13 +197,13 @@ class SearchToolAgent(AgentBase, Generic[ItemType, ResultType, PlanType]):
 
         Examples
         --------
-        >>> config = AgentConfiguration(
+        >>> configuration = AgentConfiguration(
         ...     name="web_search",
         ...     description="Perform web searches",
         ...     input_structure=WebSearchPlanStructure,
         ...     tools=[WebSearchTool()],
         ... )
-        >>> return config
+        >>> return configuration
         """
         pass
 
@@ -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 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
     -------
@@ -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."""
-        config = self._configure_agent()
-        super().__init__(
-            config=config,
-            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
-        --------
-        >>> config = AgentConfiguration(
-        ...     name="web_writer",
-        ...     description="Write web search report",
-        ...     output_structure=WebSearchReportStructure,
-        ... )
-        >>> return config
-        """
-        pass
-
     async def run_agent(
         self,
         query: str,