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

openai_sdk_helpers/__init__.py

@@ -54,8 +54,8 @@ from .config import OpenAISettings
 from .files_api import FilesAPIManager, FilePurpose
 from .vector_storage import VectorStorage, VectorStorageFileInfo, VectorStorageFileStats
 from .agent import (
-    AgentBase,
-    AgentConfig,
+    BaseAgent,
+    AgentConfiguration,
     AgentEnum,
     CoordinatorAgent,
     SummarizerAgent,
@@ -150,8 +150,8 @@ __all__ = [
     "TaskStructure",
     "PlanStructure",
     "AgentEnum",
-    "AgentBase",
-    "AgentConfig",
+    "BaseAgent",
+    "AgentConfiguration",
     "CoordinatorAgent",
     "SummarizerAgent",
     "TranslatorAgent",

openai_sdk_helpers/agent/__init__.py

@@ -2,8 +2,8 @@
 
 from __future__ import annotations
 
-from .base import AgentBase
-from .config import AgentConfig
+from .base import BaseAgent
+from .config import AgentConfiguration, AgentConfigurationRegistry, get_default_registry
 from ..structure.plan.enum import AgentEnum
 from .coordination import CoordinatorAgent
 from .runner import run_sync, run_async, run_streamed
@@ -16,8 +16,10 @@ from .search.vector import VectorSearch
 from .search.web import WebAgentSearch
 
 __all__ = [
-    "AgentBase",
-    "AgentConfig",
+    "BaseAgent",
+    "AgentConfiguration",
+    "AgentConfigurationRegistry",
+    "get_default_registry",
     "AgentEnum",
     "CoordinatorAgent",
     "run_sync",

openai_sdk_helpers/agent/base.py

@@ -5,56 +5,128 @@ from __future__ import annotations
 from pathlib import Path
 from typing import Any, Dict, Optional, Protocol
 
-from agents import Agent, RunResult, RunResultStreaming, Runner
+from agents import (
+    Agent,
+    Handoff,
+    InputGuardrail,
+    OutputGuardrail,
+    RunResult,
+    RunResultStreaming,
+    Runner,
+    Session,
+)
+from agents.model_settings import ModelSettings
 from agents.run_context import RunContextWrapper
-from agents.tool import FunctionTool
+from agents.tool import Tool
 from jinja2 import Template
 
 from .runner import run_async, run_streamed, run_sync
 
 
-class AgentConfigLike(Protocol):
-    """Protocol describing the configuration attributes for AgentBase."""
-
-    name: str
-    description: Optional[str]
-    model: Optional[str]
-    template_path: Optional[str]
-    input_type: Optional[Any]
-    output_type: Optional[Any]
-    tools: Optional[Any]
-    model_settings: Optional[Any]
-
-
-class AgentBase:
+class AgentConfigurationLike(Protocol):
+    """Protocol describing the configuration attributes for BaseAgent."""
+
+    @property
+    def name(self) -> str:
+        """Agent name."""
+        ...
+
+    @property
+    def description(self) -> Optional[str]:
+        """Agent description."""
+        ...
+
+    @property
+    def model(self) -> Optional[str]:
+        """Model identifier."""
+        ...
+
+    @property
+    def template_path(self) -> Optional[str | Path]:
+        """Template path."""
+        ...
+
+    @property
+    def instructions(self) -> str | Path:
+        """Instructions."""
+        ...
+
+    @property
+    def instructions_text(self) -> str:
+        """Resolved instructions text."""
+        ...
+
+    @property
+    def input_type(self) -> Optional[type]:
+        """Input type."""
+        ...
+
+    @property
+    def output_type(self) -> Optional[type]:
+        """Output type."""
+        ...
+
+    @property
+    def tools(self) -> Optional[list]:
+        """Tools."""
+        ...
+
+    @property
+    def model_settings(self) -> Optional[ModelSettings]:
+        """Model settings."""
+        ...
+
+    @property
+    def handoffs(self) -> Optional[list[Agent | Handoff]]:
+        """Handoffs."""
+        ...
+
+    @property
+    def input_guardrails(self) -> Optional[list[InputGuardrail]]:
+        """Input guardrails."""
+        ...
+
+    @property
+    def output_guardrails(self) -> Optional[list[OutputGuardrail]]:
+        """Output guardrails."""
+        ...
+
+    @property
+    def session(self) -> Optional[Session]:
+        """Session."""
+        ...
+
+
+class BaseAgent:
     """Factory for creating and configuring specialized agents.
 
-    ``AgentBase`` provides the foundation for building OpenAI agents with support
-    for Jinja2 prompt templates, custom tools, and both synchronous and
-    asynchronous execution modes. All specialized agents in this package extend
-    this base class.
+    ``BaseAgent`` provides the foundation for building OpenAI agents with support
+    for Jinja2 prompt templates, custom tools, handoffs for agent delegation,
+    input and output guardrails for validation, session management for
+    conversation history, and both synchronous and asynchronous execution modes.
+    All specialized agents in this package extend this base class.
 
     Examples
     --------
     Create a basic agent from configuration:
 
-    >>> from openai_sdk_helpers.agent import AgentBase, AgentConfig
-    >>> config = AgentConfig(
+    >>> from openai_sdk_helpers.agent import BaseAgent, AgentConfiguration
+    >>> config = AgentConfiguration(
     ...     name="my_agent",
     ...     description="A custom agent",
     ...     model="gpt-4o-mini"
     ... )
-    >>> agent = AgentBase(config=config, default_model="gpt-4o-mini")
+    >>> agent = BaseAgent(config=config, default_model="gpt-4o-mini")
     >>> result = agent.run_sync("What is 2+2?")
 
     Use absolute path to template:
 
-    >>> config = AgentConfig(
+    >>> config = AgentConfiguration(
     ...     name="my_agent",
     ...     template_path="/absolute/path/to/template.jinja",
     ...     model="gpt-4o-mini"
     ... )
-    >>> agent = AgentBase(config=config, default_model="gpt-4o-mini")
+    >>> agent = BaseAgent(config=config, default_model="gpt-4o-mini")
 
     Use async execution:
 
@@ -66,38 +138,38 @@ class AgentBase:
 
     Methods
     -------
-    from_config(config, run_context_wrapper)
-        Instantiate a ``AgentBase`` from configuration.
+    from_configuration(config, run_context_wrapper, prompt_dir, default_model)
+        Instantiate a ``BaseAgent`` from configuration.
     build_prompt_from_jinja(run_context_wrapper)
         Render the agent prompt using Jinja and optional context.
     get_prompt(run_context_wrapper, _)
         Render the agent prompt using the provided run context.
     get_agent()
         Construct the configured :class:`agents.Agent` instance.
-    run(input, context, output_type)
-        Execute the agent asynchronously (alias of ``run_async``).
-    run_async(input, context, output_type)
+    run_async(input, context, output_type, session)
         Execute the agent asynchronously and optionally cast the result.
-    run_sync(input, context, output_type)
+    run_sync(input, context, output_type, session)
         Execute the agent synchronously.
-    run_streamed(input, context, output_type)
+    run_streamed(input, context, output_type, session)
         Return a streaming result for the agent execution.
     as_tool()
         Return the agent as a callable tool.
+    close()
+        Clean up agent resources (can be overridden by subclasses).
     """
 
     def __init__(
         self,
-        config: AgentConfigLike,
+        config: AgentConfigurationLike,
         run_context_wrapper: Optional[RunContextWrapper[Dict[str, Any]]] = None,
         prompt_dir: Optional[Path] = None,
         default_model: Optional[str] = None,
     ) -> None:
-        """Initialize the AgentBase using a configuration object.
+        """Initialize the BaseAgent using a configuration object.
 
         Parameters
         ----------
-        config : AgentConfigLike
+        config : AgentConfigurationLike
             Configuration describing this agent.
         run_context_wrapper : RunContextWrapper or None, default=None
             Optional wrapper providing runtime context for prompt rendering.
@@ -123,8 +195,24 @@ class AgentBase:
         else:
             prompt_path = None
 
+        # Build template from file or fall back to instructions
         if prompt_path is None:
-            self._template = Template("")
+            # No template path - use instructions (always available now)
+            if hasattr(config, "instructions_text"):
+                # AgentConfiguration has this property - use it for proper resolution
+                instructions_text = config.instructions_text
+            else:
+                # Fall back to resolving instructions ourselves
+                if isinstance(config.instructions, Path):
+                    try:
+                        instructions_text = config.instructions.read_text(
+                            encoding="utf-8"
+                        )
+                    except OSError:
+                        instructions_text = ""  # Leave empty if file can't be read
+                else:
+                    instructions_text = config.instructions
+            self._template = Template(instructions_text)
         elif prompt_path.exists():
             self._template = Template(prompt_path.read_text())
         else:
@@ -140,22 +228,29 @@ class AgentBase:
         self._output_type = config.output_type or config.input_type
         self._tools = config.tools
         self._model_settings = config.model_settings
+        self._handoffs = config.handoffs
+        self._input_guardrails = config.input_guardrails
+        self._output_guardrails = config.output_guardrails
+        self._session = config.session
         self._run_context_wrapper = run_context_wrapper
 
+        # Store instructions if provided directly in config
+        self._instructions = getattr(config, "instructions", None)
+
     @classmethod
-    def from_config(
+    def from_configuration(
         cls,
-        config: AgentConfigLike,
+        config: AgentConfigurationLike,
         *,
         run_context_wrapper: Optional[RunContextWrapper[Dict[str, Any]]] = None,
         prompt_dir: Optional[Path] = None,
         default_model: Optional[str] = None,
-    ) -> AgentBase:
-        """Create an AgentBase instance from configuration.
+    ) -> BaseAgent:
+        """Create a BaseAgent instance from configuration.
 
         Parameters
         ----------
-        config : AgentConfigLike
+        config : AgentConfigurationLike
             Configuration describing the agent.
         run_context_wrapper : RunContextWrapper or None, default=None
             Optional wrapper providing runtime context.
@@ -169,7 +264,7 @@ class AgentBase:
 
         Returns
         -------
-        AgentBase
+        BaseAgent
             Instantiated agent.
         """
         return cls(
@@ -252,6 +347,12 @@ class AgentBase:
             agent_config["tools"] = self._tools
         if self._model_settings:
             agent_config["model_settings"] = self._model_settings
+        if self._handoffs:
+            agent_config["handoffs"] = self._handoffs
+        if self._input_guardrails:
+            agent_config["input_guardrails"] = self._input_guardrails
+        if self._output_guardrails:
+            agent_config["output_guardrails"] = self._output_guardrails
 
         return Agent(**agent_config)
 
@@ -261,6 +362,7 @@ class AgentBase:
         *,
         context: Optional[Dict[str, Any]] = None,
         output_type: Optional[Any] = None,
+        session: Optional[Any] = None,
     ) -> Any:
         """Execute the agent asynchronously.
 
@@ -272,6 +374,9 @@ class AgentBase:
             Optional 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 across runs.
+            If not provided, uses the session from config if available.
 
         Returns
         -------
@@ -280,11 +385,14 @@ class AgentBase:
         """
         if self._output_type is not None and output_type is None:
             output_type = self._output_type
+        # Use session from parameter, fall back to config session
+        session_to_use = session if session is not None else self._session
         return await run_async(
             agent=self.get_agent(),
             input=input,
             context=context,
             output_type=output_type,
+            session=session_to_use,
         )
 
     def run_sync(
@@ -293,6 +401,7 @@ class AgentBase:
         *,
         context: Optional[Dict[str, Any]] = None,
         output_type: Optional[Any] = None,
+        session: Optional[Any] = None,
     ) -> Any:
         """Run the agent synchronously.
 
@@ -304,17 +413,23 @@ class AgentBase:
             Optional 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 across runs.
+            If not provided, uses the session from config if available.
 
         Returns
         -------
         Any
             Agent result, optionally converted to ``output_type``.
         """
+        # Use session from parameter, fall back to config session
+        session_to_use = session if session is not None else self._session
         return run_sync(
             agent=self.get_agent(),
             input=input,
             context=context,
             output_type=output_type,
+            session=session_to_use,
         )
 
     def run_streamed(
@@ -323,6 +438,7 @@ class AgentBase:
         *,
         context: Optional[Dict[str, Any]] = None,
         output_type: Optional[Any] = None,
+        session: Optional[Any] = None,
     ) -> RunResultStreaming:
         """Stream the agent execution results.
 
@@ -334,16 +450,22 @@ class AgentBase:
             Optional 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 across runs.
+            If not provided, uses the session from config if available.
 
         Returns
         -------
         RunResultStreaming
             Streaming output wrapper from the agent execution.
         """
+        # Use session from parameter, fall back to config session
+        session_to_use = session if session is not None else self._session
         result = run_streamed(
             agent=self.get_agent(),
             input=input,
             context=context,
+            session=session_to_use,
         )
         if self._output_type and not output_type:
             output_type = self._output_type
@@ -351,19 +473,61 @@ class AgentBase:
             return result.final_output_as(output_type)
         return result
 
-    def as_tool(self) -> FunctionTool:
+    def as_tool(self) -> Tool:
         """Return the agent as a callable tool.
 
         Returns
         -------
-        FunctionTool
+        Tool
             Tool instance wrapping this agent.
         """
         agent = self.get_agent()
-        tool_obj: FunctionTool = agent.as_tool(
+        tool_obj: Tool = agent.as_tool(
             tool_name=self.agent_name, tool_description=self.description
-        )  # type: ignore
+        )
         return tool_obj
 
+    def __enter__(self) -> BaseAgent:
+        """Enter the context manager for resource management.
+
+        Returns
+        -------
+        BaseAgent
+            Self reference for use in with statements.
+        """
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        """Exit the context manager and clean up resources.
+
+        Parameters
+        ----------
+        exc_type : type or None
+            Exception type if an exception occurred, otherwise None.
+        exc_val : Exception or None
+            Exception instance if an exception occurred, otherwise None.
+        exc_tb : traceback or None
+            Traceback object if an exception occurred, otherwise None.
+        """
+        self.close()
+
+    def close(self) -> None:
+        """Clean up agent resources.
+
+        This method is called automatically when using the agent as a
+        context manager. Override in subclasses to implement custom
+        cleanup logic.
+
+        Examples
+        --------
+        >>> agent = BaseAgent(config, default_model="gpt-4o-mini")
+        >>> try:
+        ...     result = agent.run_sync("query")
+        ... finally:
+        ...     agent.close()
+        """
+        # Base implementation does nothing, but subclasses can override
+        pass
+
 
-__all__ = ["AgentConfigLike", "AgentBase"]
+__all__ = ["AgentConfigurationLike", "BaseAgent"]