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

openai_sdk_helpers/agent/config.py

@@ -1,68 +1,375 @@
-"""Configuration helpers for ``AgentBase``."""
+"""Configuration helpers for ``BaseAgent``."""
 
 from __future__ import annotations
 
-from typing import Any, List, Optional, Type
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Optional
 
+from agents import Agent, Handoff, InputGuardrail, OutputGuardrail, Session
 from agents.model_settings import ModelSettings
-from pydantic import BaseModel, ConfigDict, Field
 
-from ..structure import BaseStructure
+from ..utils import JSONSerializable
+from ..utils.registry import BaseRegistry
+from ..utils.instructions import resolve_instructions_from_path
 
 
-class AgentConfig(BaseStructure):
-    """Configuration required to build an AgentBase.
+class AgentConfigurationRegistry(BaseRegistry["AgentConfiguration"]):
+    """Registry for managing AgentConfiguration instances.
+
+    Inherits from BaseRegistry to provide centralized storage and retrieval
+    of agent configurations, enabling reusable agent specs across the application.
+
+    Examples
+    --------
+    >>> registry = AgentConfigurationRegistry()
+    >>> config = AgentConfiguration(
+    ...     name="test_agent",
+    ...     model="gpt-4o-mini",
+    ...     instructions="Test instructions"
+    ... )
+    >>> registry.register(config)
+    >>> retrieved = registry.get("test_agent")
+    >>> retrieved.name
+    'test_agent'
+    """
+
+    def load_from_directory(
+        self,
+        path: Path | str,
+        *,
+        config_class: type["AgentConfiguration"] | None = None,
+    ) -> int:
+        """Load all agent configurations from JSON files in a directory.
+
+        Parameters
+        ----------
+        path : Path or str
+            Directory path containing JSON configuration files.
+        config_class : type[AgentConfiguration], optional
+            The configuration class to use for deserialization.
+            Defaults to AgentConfiguration.
+
+        Returns
+        -------
+        int
+            Number of configurations successfully loaded and registered.
+
+        Raises
+        ------
+        FileNotFoundError
+            If the directory does not exist.
+        NotADirectoryError
+            If the path is not a directory.
+
+        Examples
+        --------
+        >>> registry = AgentConfigurationRegistry()
+        >>> count = registry.load_from_directory("./agents")
+        >>> print(f"Loaded {count} configurations")
+        """
+        if config_class is None:
+            config_class = AgentConfiguration
+        return super().load_from_directory(path, config_class=config_class)
+
+
+# Global default registry instance
+_default_registry = AgentConfigurationRegistry()
+
+
+def get_default_registry() -> AgentConfigurationRegistry:
+    """Return the global default registry instance.
+
+    Returns
+    -------
+    AgentConfigurationRegistry
+        Singleton registry for application-wide configuration storage.
+
+    Examples
+    --------
+    >>> registry = get_default_registry()
+    >>> config = AgentConfiguration(
+    ...     name="test", model="gpt-4o-mini", instructions="Test instructions"
+    ... )
+    >>> registry.register(config)
+    """
+    return _default_registry
+
+
+@dataclass(frozen=True, slots=True)
+class AgentConfiguration(JSONSerializable):
+    """Immutable configuration for building a BaseAgent.
+
+    Encapsulates all metadata required to define an agent including its
+    instructions, tools, model settings, handoffs, guardrails, and session
+    management. Inherits from JSONSerializable to support serialization.
+
+    This dataclass is frozen (immutable) to ensure thread-safety and
+    enable use as dictionary keys. All list-type fields use None as the
+    default value rather than mutable defaults like [] to avoid issues
+    with shared state across instances.
+
+    Parameters
+    ----------
+    name : str
+        Unique identifier for the agent. Must be a non-empty string.
+    instructions : str or Path
+        Plain text instructions or a path to a Jinja template file whose
+        contents are loaded at runtime. Required field.
+    description : str, optional
+        Short description of the agent's purpose. Default is None.
+    model : str, optional
+        Model identifier to use (e.g., "gpt-4o-mini"). Default is None.
+    template_path : str or Path, optional
+        Path to the Jinja template (absolute or relative to prompt_dir).
+        This takes precedence over instructions if both are provided.
+        Default is None.
+    input_type : type, optional
+        Type describing the agent input, commonly a Pydantic model.
+        Default is None.
+    output_type : type, optional
+        Type describing the agent output, commonly a Pydantic model or
+        builtin like str. Default is None.
+    tools : list, optional
+        Tool definitions available to the agent. Default is None.
+    model_settings : ModelSettings, optional
+        Additional model configuration settings. Default is None.
+    handoffs : list[Agent or Handoff], optional
+        List of agents or handoff configurations that this agent can
+        delegate to for specific tasks. Default is None.
+    input_guardrails : list[InputGuardrail], optional
+        List of guardrails to validate agent inputs before processing.
+        Default is None.
+    output_guardrails : list[OutputGuardrail], optional
+        List of guardrails to validate agent outputs before returning.
+        Default is None.
+    session : Session, optional
+        Session configuration for automatically maintaining conversation
+        history across agent runs. Default is None.
 
     Methods
     -------
-    print()
-        Return a human-readable representation of the configuration.
+    __post_init__()
+        Validate configuration invariants after initialization.
+    instructions_text
+        Return the resolved instruction content as a string.
+    create_agent(run_context_wrapper, prompt_dir, default_model)
+        Create a BaseAgent instance from this configuration.
+    replace(**changes)
+        Create a new AgentConfiguration with specified fields replaced.
+    to_json()
+        Return a JSON-compatible dict (inherited from JSONSerializable).
+    to_json_file(filepath)
+        Write serialized JSON data to a file (inherited from JSONSerializable).
+    from_json(data)
+        Create an instance from a JSON-compatible dict (inherited from JSONSerializable).
+    from_json_file(filepath)
+        Load an instance from a JSON file (inherited from JSONSerializable).
+
+    Examples
+    --------
+    >>> config = AgentConfiguration(
+    ...     name="summarizer",
+    ...     description="Summarizes text",
+    ...     model="gpt-4o-mini"
+    ... )
+    >>> config.name
+    'summarizer'
     """
 
-    model_config = ConfigDict(arbitrary_types_allowed=True)
-
-    name: str = Field(title="Agent Name", description="Unique name for the agent")
-    description: Optional[str] = Field(
-        default=None, title="Description", description="Short description of the agent"
-    )
-    model: Optional[str] = Field(
-        default=None, title="Model", description="Model identifier to use"
-    )
-    template_path: Optional[str] = Field(
-        default=None,
-        title="Template Path",
-        description="Path to the Jinja template (absolute or relative to prompt_dir)",
-    )
-    input_type: Optional[Type[BaseModel]] = Field(
-        default=None,
-        title="Input Type",
-        description="Pydantic model describing the agent input",
-    )
-    output_type: Optional[Type[Any]] = Field(
-        default=None,
-        title="Output Type",
-        description="Type describing the agent output; commonly a Pydantic model or builtin like ``str``",
-    )
-    tools: Optional[List[Any]] = Field(
-        default=None,
-        title="Tools",
-        description="Tools available to the agent",
-    )
-    model_settings: Optional[ModelSettings] = Field(
-        default=None, title="Model Settings", description="Additional model settings"
-    )
-
-    def print(self) -> str:
-        """Return a human-readable representation.
+    name: str
+    instructions: str | Path
+    description: Optional[str] = None
+    model: Optional[str] = None
+    template_path: Optional[str | Path] = None
+    input_type: Optional[type] = None
+    output_type: Optional[type] = None
+    tools: Optional[list] = None
+    model_settings: Optional[ModelSettings] = None
+    handoffs: Optional[list[Agent | Handoff]] = None
+    input_guardrails: Optional[list[InputGuardrail]] = None
+    output_guardrails: Optional[list[OutputGuardrail]] = None
+    session: Optional[Session] = None
+
+    def __post_init__(self) -> None:
+        """Validate configuration invariants after initialization.
+
+        Ensures that the name is a non-empty string and that instructions
+        are properly formatted.
+
+        Raises
+        ------
+        TypeError
+            If name is not a non-empty string.
+            If instructions is not a string or Path.
+        ValueError
+            If instructions is an empty string.
+        FileNotFoundError
+            If instructions is a Path that doesn't point to a readable file.
+        """
+        if not self.name or not isinstance(self.name, str):
+            raise TypeError("AgentConfiguration.name must be a non-empty str")
+
+        # Validate instructions (required field, like in Response module)
+        instructions_value = self.instructions
+        if isinstance(instructions_value, str):
+            if not instructions_value.strip():
+                raise ValueError(
+                    "AgentConfiguration.instructions must be a non-empty str"
+                )
+        elif isinstance(instructions_value, Path):
+            instruction_path = instructions_value.expanduser()
+            if not instruction_path.is_file():
+                raise FileNotFoundError(
+                    f"Instruction template not found: {instruction_path}"
+                )
+        else:
+            raise TypeError("AgentConfiguration.instructions must be a str or Path")
+
+        if self.template_path is not None and isinstance(self.template_path, Path):
+            # Validate template_path if it's a Path object
+            template = self.template_path.expanduser()
+            if not template.exists():
+                # We don't raise here because template_path might be relative
+                # and resolved later with prompt_dir
+                pass
+
+    @property
+    def instructions_text(self) -> str:
+        """Return the resolved instruction text.
 
         Returns
         -------
         str
-            The agent's name.
+            Plain-text instructions, loading template files when necessary.
+        """
+        return self._resolve_instructions()
+
+    def _resolve_instructions(self) -> str:
+        """Resolve instructions from string or file path."""
+        return resolve_instructions_from_path(self.instructions)
+
+    def create_agent(
+        self,
+        run_context_wrapper: Any = None,
+        prompt_dir: Path | None = None,
+        default_model: str | None = None,
+    ) -> Any:
+        """Create a BaseAgent instance from this configuration.
+
+        This is a convenience method that delegates to BaseAgent.from_configuration().
+
+        Parameters
+        ----------
+        run_context_wrapper : RunContextWrapper or None, default=None
+            Optional wrapper providing runtime context for prompt rendering.
+        prompt_dir : Path or None, default=None
+            Optional directory holding prompt templates.
+        default_model : str or None, default=None
+            Optional fallback model identifier if config doesn't specify one.
+
+        Returns
+        -------
+        BaseAgent
+            Configured agent instance ready for execution.
+
+        Examples
+        --------
+        >>> config = AgentConfiguration(
+        ...     name="helper", model="gpt-4o-mini", instructions="Help the user"
+        ... )
+        >>> agent = config.create_agent()
+        >>> result = agent.run_sync("Hello!")
+        """
+        # Import here to avoid circular dependency
+        from .base import BaseAgent
+
+        return BaseAgent.from_configuration(
+            config=self,
+            run_context_wrapper=run_context_wrapper,
+            prompt_dir=prompt_dir,
+            default_model=default_model,
+        )
+
+    def replace(self, **changes: Any) -> AgentConfiguration:
+        """Create a new AgentConfiguration with specified fields replaced.
+
+        Since AgentConfiguration is frozen (immutable), this method creates a new
+        instance with the specified changes applied. This is useful for
+        creating variations of a configuration.
+
+        Parameters
+        ----------
+        **changes : Any
+            Keyword arguments specifying fields to change and their new values.
+
+        Returns
+        -------
+        AgentConfiguration
+            New configuration instance with changes applied.
+
+        Examples
+        --------
+        >>> config = AgentConfiguration(
+        ...     name="agent1", model="gpt-4o-mini", instructions="Agent instructions"
+        ... )
+        >>> config2 = config.replace(name="agent2", description="Modified")
+        >>> config2.name
+        'agent2'
+        >>> config2.model
+        'gpt-4o-mini'
         """
-        return self.name
+        from dataclasses import replace
+
+        return replace(self, **changes)
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> AgentConfiguration:
+        """Create an AgentConfiguration from JSON data.
+
+        Overrides the default JSONSerializable.from_json to properly handle
+        the instructions field, converting string paths that look like file
+        paths back to Path objects for proper file loading.
+
+        Parameters
+        ----------
+        data : dict[str, Any]
+            Dictionary containing the configuration data.
+
+        Returns
+        -------
+        AgentConfiguration
+            New configuration instance.
+
+        Notes
+        -----
+        This method attempts to preserve the original type of the instructions
+        field. If instructions is a string that represents an existing file path,
+        it will be converted to a Path object to ensure proper file loading
+        behavior is maintained across JSON round-trips.
+        """
+        # Make a copy to avoid modifying the input
+        data = data.copy()
+
+        # Handle instructions field: if it's a string path to an existing file,
+        # convert it back to Path for proper file loading
+        if "instructions" in data and data["instructions"] is not None:
+            instructions_value = data["instructions"]
+            if isinstance(instructions_value, str):
+                # Check if it looks like a file path and the file exists
+                # This preserves the intended behavior for file-based instructions
+                try:
+                    potential_path = Path(instructions_value)
+                    # Only convert to Path if it's an existing file
+                    # This way, plain text instructions stay as strings
+                    if potential_path.exists() and potential_path.is_file():
+                        data["instructions"] = potential_path
+                except (OSError, ValueError):
+                    # If path parsing fails, keep it as a string (likely plain text)
+                    pass
 
+        # Use the parent class method for the rest
+        return super(AgentConfiguration, cls).from_json(data)
 
-__all__ = ["AgentConfig"]
 
-AgentConfig.model_rebuild()
+__all__ = ["AgentConfiguration", "AgentConfigurationRegistry", "get_default_registry"]

openai_sdk_helpers/agent/coordination.py

@@ -13,8 +13,8 @@ from typing import Any, Callable, Dict, List, Optional
 
 from ..structure import TaskStructure, PlanStructure, PromptStructure
 from ..utils import JSONSerializable, ensure_directory, log
-from .base import AgentBase
-from .config import AgentConfig
+from .base import BaseAgent
+from .config import AgentConfiguration
 from ..structure.plan.enum import AgentEnum
 
 PromptFn = Callable[[str], PromptStructure]
@@ -23,7 +23,7 @@ ExecutePlanFn = Callable[[PlanStructure], List[str]]
 SummarizeFn = Callable[[List[str]], str]
 
 
-class CoordinatorAgent(AgentBase, JSONSerializable):
+class CoordinatorAgent(BaseAgent, JSONSerializable):
     """Coordinate agent plans while persisting project state and outputs.
 
     Methods
@@ -63,7 +63,7 @@ class CoordinatorAgent(AgentBase, JSONSerializable):
         summarize_fn: SummarizeFn,
         module_data_path: Path,
         name: str,
-        config: Optional[AgentConfig] = None,
+        config: Optional[AgentConfiguration] = None,
         prompt_dir: Optional[Path] = None,
         default_model: Optional[str] = None,
     ) -> None:
@@ -83,7 +83,7 @@ class CoordinatorAgent(AgentBase, JSONSerializable):
             Base path for persisting project artifacts.
         name : str
             Name of the parent module for data organization.
-        config : AgentConfig or None, default=None
+        config : AgentConfiguration or None, default=None
             Optional agent configuration describing prompts and metadata.
         prompt_dir : Path or None, default=None
             Optional directory holding prompt templates.
@@ -91,8 +91,9 @@ class CoordinatorAgent(AgentBase, JSONSerializable):
             Optional fallback model identifier.
         """
         if config is None:
-            config = AgentConfig(
+            config = AgentConfiguration(
                 name="coordinator_agent",
+                instructions="Coordinate agents for planning and summarization.",
                 description="Coordinates agents for planning and summarization.",
             )
         super().__init__(

openai_sdk_helpers/agent/runner.py

@@ -9,7 +9,7 @@ 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
 
@@ -20,6 +20,7 @@ async def run_async(
     *,
     context: Optional[Dict[str, Any]] = None,
     output_type: Optional[Any] = None,
+    session: Optional[Session] = None,
 ) -> Any:
     """Run an Agent asynchronously.
 
@@ -33,6 +34,8 @@ async def run_async(
         Optional context dictionary passed to the agent.
     output_type : type 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
     -------
@@ -49,7 +52,7 @@ async def run_async(
     ...     return result
     >>> asyncio.run(example())  # doctest: +SKIP
     """
-    result = await Runner.run(agent, input, context=context)
+    result = await Runner.run(agent, input, context=context, session=session)
     if output_type is not None:
         return result.final_output_as(output_type)
     return result
@@ -61,6 +64,7 @@ def run_sync(
     *,
     context: Optional[Dict[str, Any]] = None,
     output_type: Optional[Any] = None,
+    session: Optional[Session] = None,
 ) -> Any:
     """Run an Agent synchronously.
 
@@ -78,6 +82,8 @@ def run_sync(
         Optional context dictionary passed to the agent.
     output_type : type 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
     -------
@@ -95,7 +101,7 @@ 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)
@@ -108,6 +114,7 @@ def run_streamed(
     *,
     context: Optional[Dict[str, Any]] = None,
     output_type: Optional[Any] = None,
+    session: Optional[Session] = None,
 ) -> RunResultStreaming:
     """Stream agent execution results.
 
@@ -121,6 +128,8 @@ def run_streamed(
         Optional context dictionary passed to the agent.
     output_type : type 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,7 +144,7 @@ def run_streamed(
     >>> for chunk in result.stream_text():  # doctest: +SKIP
     ...     print(chunk, end="")
     """
-    result = Runner.run_streamed(agent, input, context=context)
+    result = Runner.run_streamed(agent, input, context=context, session=session)
     if output_type is not None:
         return result.final_output_as(output_type)
     return result

openai_sdk_helpers/agent/search/base.py

@@ -12,8 +12,8 @@ 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
+from ..base import BaseAgent
+from ..config import AgentConfiguration
 
 # Type variables for search workflow components
 ItemType = TypeVar("ItemType")  # Search item structure (e.g., WebSearchItemStructure)
@@ -23,7 +23,7 @@ ReportType = TypeVar("ReportType")  # Final report structure
 OutputType = TypeVar("OutputType")  # Generic output type
 
 
-class SearchPlanner(AgentBase, Generic[PlanType]):
+class SearchPlanner(BaseAgent, Generic[PlanType]):
     """Generic planner agent for search workflows.
 
     Subclasses implement specific planner logic by overriding the
@@ -34,7 +34,7 @@ class SearchPlanner(AgentBase, Generic[PlanType]):
     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.
     """
 
     def __init__(
@@ -59,17 +59,17 @@ class SearchPlanner(AgentBase, Generic[PlanType]):
         )
 
     @abstractmethod
-    def _configure_agent(self) -> AgentConfig:
+    def _configure_agent(self) -> AgentConfiguration:
         """Return configuration for this planner.
 
         Returns
         -------
-        AgentConfig
+        AgentConfiguration
             Configuration with name, description, and output_type set.
 
         Examples
         --------
-        >>> config = AgentConfig(
+        >>> config = AgentConfiguration(
         ...     name="web_planner",
         ...     description="Plan web searches",
         ...     output_type=WebSearchPlanStructure,
@@ -98,7 +98,7 @@ class SearchPlanner(AgentBase, Generic[PlanType]):
         return result
 
 
-class SearchToolAgent(AgentBase, Generic[ItemType, ResultType, PlanType]):
+class SearchToolAgent(BaseAgent, Generic[ItemType, ResultType, PlanType]):
     """Generic tool agent for executing search workflows.
 
     Executes individual searches in a plan with concurrency control.
@@ -112,7 +112,7 @@ 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.
     """
 
     def __init__(
@@ -142,17 +142,17 @@ 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
+        AgentConfiguration
             Configuration with name, description, input_type, and tools set.
 
         Examples
         --------
-        >>> config = AgentConfig(
+        >>> config = AgentConfiguration(
         ...     name="web_search",
         ...     description="Perform web searches",
         ...     input_type=WebSearchPlanStructure,
@@ -205,7 +205,7 @@ class SearchToolAgent(AgentBase, Generic[ItemType, ResultType, PlanType]):
         return [result for result in results if result is not None]
 
 
-class SearchWriter(AgentBase, Generic[ReportType]):
+class SearchWriter(BaseAgent, Generic[ReportType]):
     """Generic writer agent for search workflow reports.
 
     Synthesizes search results into a final report. Subclasses implement
@@ -216,7 +216,7 @@ class SearchWriter(AgentBase, Generic[ReportType]):
     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.
     """
 
     def __init__(
@@ -241,17 +241,17 @@ class SearchWriter(AgentBase, Generic[ReportType]):
         )
 
     @abstractmethod
-    def _configure_agent(self) -> AgentConfig:
+    def _configure_agent(self) -> AgentConfiguration:
         """Return configuration for this writer.
 
         Returns
         -------
-        AgentConfig
+        AgentConfiguration
             Configuration with name, description, and output_type set.
 
         Examples
         --------
-        >>> config = AgentConfig(
+        >>> config = AgentConfiguration(
         ...     name="web_writer",
         ...     description="Write web search report",
         ...     output_type=WebSearchReportStructure,