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

openai_sdk_helpers/__init__.py

@@ -33,7 +33,7 @@ from .utils.validation import (
     validate_url_format,
 )
 from .structure import (
-    BaseStructure,
+    StructureBase,
     SchemaOptions,
     PlanStructure,
     TaskStructure,
@@ -54,7 +54,7 @@ from .config import OpenAISettings
 from .files_api import FilesAPIManager, FilePurpose
 from .vector_storage import VectorStorage, VectorStorageFileInfo, VectorStorageFileStats
 from .agent import (
-    BaseAgent,
+    AgentBase,
     AgentConfiguration,
     AgentEnum,
     CoordinatorAgent,
@@ -65,7 +65,7 @@ from .agent import (
     WebAgentSearch,
 )
 from .response import (
-    BaseResponse,
+    ResponseBase,
     ResponseMessage,
     ResponseMessages,
     ResponseToolCall,
@@ -134,7 +134,7 @@ __all__ = [
     "validate_choice",
     "validate_safe_path",
     # Main structure classes
-    "BaseStructure",
+    "StructureBase",
     "SchemaOptions",
     "spec_field",
     "PromptRenderer",
@@ -150,7 +150,7 @@ __all__ = [
     "TaskStructure",
     "PlanStructure",
     "AgentEnum",
-    "BaseAgent",
+    "AgentBase",
     "AgentConfiguration",
     "CoordinatorAgent",
     "SummarizerAgent",
@@ -162,7 +162,7 @@ __all__ = [
     "WebSearchStructure",
     "VectorSearchStructure",
     "ValidationResultStructure",
-    "BaseResponse",
+    "ResponseBase",
     "ResponseMessage",
     "ResponseMessages",
     "ResponseToolCall",

openai_sdk_helpers/agent/__init__.py

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

openai_sdk_helpers/agent/base.py

@@ -3,16 +3,15 @@
 from __future__ import annotations
 
 from pathlib import Path
-from typing import Any, Dict, Optional, Protocol
+from typing import Any, Callable, Dict, Optional, Protocol, cast
+import uuid
 
 from agents import (
     Agent,
     Handoff,
     InputGuardrail,
     OutputGuardrail,
-    RunResult,
     RunResultStreaming,
-    Runner,
     Session,
 )
 from agents.model_settings import ModelSettings
@@ -20,11 +19,19 @@ from agents.run_context import RunContextWrapper
 from agents.tool import Tool
 from jinja2 import Template
 
+from ..utils.json.data_class import DataclassJSONSerializable
+from ..structure.base import StructureBase
+
+from ..utils import (
+    check_filepath,
+    log,
+)
+
 from .runner import run_async, run_streamed, run_sync
 
 
-class AgentConfigurationLike(Protocol):
-    """Protocol describing the configuration attributes for BaseAgent."""
+class AgentConfigurationProtocol(Protocol):
+    """Protocol describing the configuration attributes for AgentBase."""
 
     @property
     def name(self) -> str:
@@ -46,6 +53,10 @@ class AgentConfigurationLike(Protocol):
         """Template path."""
         ...
 
+    def resolve_prompt_path(self, prompt_dir: Path | None = None) -> Path | None:
+        """Resolve the prompt template path."""
+        ...
+
     @property
     def instructions(self) -> str | Path:
         """Instructions."""
@@ -57,12 +68,12 @@ class AgentConfigurationLike(Protocol):
         ...
 
     @property
-    def input_type(self) -> Optional[type]:
+    def input_structure(self) -> Optional[type[StructureBase]]:
         """Input type."""
         ...
 
     @property
-    def output_type(self) -> Optional[type]:
+    def output_structure(self) -> Optional[type[StructureBase]]:
         """Output type."""
         ...
 
@@ -97,10 +108,10 @@ class AgentConfigurationLike(Protocol):
         ...
 
 
-class BaseAgent:
+class AgentBase(DataclassJSONSerializable):
     """Factory for creating and configuring specialized agents.
 
-    ``BaseAgent`` provides the foundation for building OpenAI agents with support
+    ``AgentBase`` 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.
@@ -110,13 +121,13 @@ class BaseAgent:
     --------
     Create a basic agent from configuration:
 
-    >>> from openai_sdk_helpers.agent import BaseAgent, AgentConfiguration
+    >>> from openai_sdk_helpers.agent import AgentBase, AgentConfiguration
     >>> config = AgentConfiguration(
     ...     name="my_agent",
     ...     description="A custom agent",
     ...     model="gpt-4o-mini"
     ... )
-    >>> agent = BaseAgent(config=config, default_model="gpt-4o-mini")
+    >>> agent = AgentBase(config=config, default_model="gpt-4o-mini")
     >>> result = agent.run_sync("What is 2+2?")
 
     Use absolute path to template:
@@ -126,7 +137,7 @@ class BaseAgent:
     ...     template_path="/absolute/path/to/template.jinja",
     ...     model="gpt-4o-mini"
     ... )
-    >>> agent = BaseAgent(config=config, default_model="gpt-4o-mini")
+    >>> agent = AgentBase(config=config, default_model="gpt-4o-mini")
 
     Use async execution:
 
@@ -138,19 +149,35 @@ class BaseAgent:
 
     Methods
     -------
-    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.
+    name
+        Return the name of this agent.
+    instructions_text
+        Return the resolved instructions for this agent.
+    tools
+        Return the tools configured for this agent.
+    output_structure
+        Return the output type configured for this agent.
+    model_settings
+        Return the model settings configured for this agent.
+    handoffs
+        Return the handoff configurations for this agent.
+    input_guardrails
+        Return the input guardrails configured for this agent.
+    output_guardrails
+        Return the output guardrails configured for this agent.
+    session
+        Return the session configured for this agent.
     get_agent()
         Construct the configured :class:`agents.Agent` instance.
-    run_async(input, context, output_type, session)
+    run_async(input, context, output_structure, session)
         Execute the agent asynchronously and optionally cast the result.
-    run_sync(input, context, output_type, session)
+    run_sync(input, context, output_structure, session)
         Execute the agent synchronously.
-    run_streamed(input, context, output_type, session)
+    run_streamed(input, context, output_structure, session)
         Return a streaming result for the agent execution.
     as_tool()
         Return the agent as a callable tool.
@@ -160,16 +187,18 @@ class BaseAgent:
 
     def __init__(
         self,
-        config: AgentConfigurationLike,
+        *,
+        config: AgentConfigurationProtocol,
         run_context_wrapper: Optional[RunContextWrapper[Dict[str, Any]]] = None,
+        data_path: Path | str | None = None,
         prompt_dir: Optional[Path] = None,
         default_model: Optional[str] = None,
     ) -> None:
-        """Initialize the BaseAgent using a configuration object.
+        """Initialize the AgentBase using a configuration object.
 
         Parameters
         ----------
-        config : AgentConfigurationLike
+        config : AgentConfigurationProtocol
             Configuration describing this agent.
         run_context_wrapper : RunContextWrapper or None, default=None
             Optional wrapper providing runtime context for prompt rendering.
@@ -187,45 +216,41 @@ class BaseAgent:
         if not model:
             raise ValueError("Model is required to construct the agent.")
 
-        prompt_path: Optional[Path]
-        if config.template_path:
-            prompt_path = Path(config.template_path)
-        elif prompt_dir is not None:
-            prompt_path = prompt_dir / f"{name}.jinja"
-        else:
-            prompt_path = None
+        prompt_path = config.resolve_prompt_path(prompt_dir)
 
         # Build template from file or fall back to instructions
         if prompt_path is None:
-            # 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
+            instructions_text = config.instructions_text
             self._template = Template(instructions_text)
+            self._instructions = instructions_text
         elif prompt_path.exists():
-            self._template = Template(prompt_path.read_text())
+            self._template = Template(prompt_path.read_text(encoding="utf-8"))
+            self._instructions = None
         else:
             raise FileNotFoundError(
                 f"Prompt template for agent '{name}' not found at {prompt_path}."
             )
 
-        self.agent_name = name
+        self._name = name
+        self.uuid = uuid.uuid4()
         self.description = description
         self.model = model
 
-        self._input_type = config.input_type
-        self._output_type = config.output_type or config.input_type
+        # Resolve data_path with class name appended
+        class_name = self.__class__.__name__
+        if data_path is not None:
+            data_path_obj = Path(data_path)
+            if data_path_obj.name == class_name:
+                self._data_path = data_path_obj
+            else:
+                self._data_path = data_path_obj / class_name
+        else:
+            from ..environment import get_data_path
+
+            self._data_path = get_data_path(self.__class__.__name__)
+
+        self._input_structure = config.input_structure
+        self._output_structure = config.output_structure or config.input_structure
         self._tools = config.tools
         self._model_settings = config.model_settings
         self._handoffs = config.handoffs
@@ -234,46 +259,6 @@ class BaseAgent:
         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_configuration(
-        cls,
-        config: AgentConfigurationLike,
-        *,
-        run_context_wrapper: Optional[RunContextWrapper[Dict[str, Any]]] = None,
-        prompt_dir: Optional[Path] = None,
-        default_model: Optional[str] = None,
-    ) -> BaseAgent:
-        """Create a BaseAgent instance from configuration.
-
-        Parameters
-        ----------
-        config : AgentConfigurationLike
-            Configuration describing the agent.
-        run_context_wrapper : RunContextWrapper or None, default=None
-            Optional wrapper providing runtime context.
-        prompt_dir : Path or None, default=None
-            Optional directory holding prompt templates. Used when
-            ``config.template_path`` is not provided or is relative. If
-            ``config.template_path`` is an absolute path, this parameter is
-            ignored.
-        default_model : str or None, default=None
-            Optional fallback model identifier.
-
-        Returns
-        -------
-        BaseAgent
-            Instantiated agent.
-        """
-        return cls(
-            config=config,
-            run_context_wrapper=run_context_wrapper,
-            prompt_dir=prompt_dir,
-            default_model=default_model,
-        )
-
     def _build_prompt_from_jinja(self) -> str:
         """Render the instructions prompt for this agent.
 
@@ -328,6 +313,107 @@ class BaseAgent:
         """
         return self.build_prompt_from_jinja(run_context_wrapper)
 
+    @property
+    def name(self) -> str:
+        """Return the name of this agent.
+
+        Returns
+        -------
+        str
+            Name used to identify the agent.
+        """
+        return self._name
+
+    @property
+    def instructions_text(self) -> str:
+        """Return the resolved instructions for this agent.
+
+        Returns
+        -------
+        str
+            Rendered instructions text using the current run context.
+        """
+        if self._instructions is not None:
+            return self._instructions
+        return self._build_prompt_from_jinja()
+
+    @property
+    def tools(self) -> Optional[list]:
+        """Return the tools configured for this agent.
+
+        Returns
+        -------
+        list or None
+            Tool definitions configured for the agent.
+        """
+        return self._tools
+
+    @property
+    def output_structure(self) -> Optional[type[StructureBase]]:
+        """Return the output type configured for this agent.
+
+        Returns
+        -------
+        type[StructureBase] or None
+            Output type used to cast responses.
+        """
+        return self._output_structure
+
+    @property
+    def model_settings(self) -> Optional[ModelSettings]:
+        """Return the model settings configured for this agent.
+
+        Returns
+        -------
+        ModelSettings or None
+            Model settings applied to the agent.
+        """
+        return self._model_settings
+
+    @property
+    def handoffs(self) -> Optional[list[Agent | Handoff]]:
+        """Return the handoff configurations for this agent.
+
+        Returns
+        -------
+        list[Agent or Handoff] or None
+            Handoff configurations available to the agent.
+        """
+        return self._handoffs
+
+    @property
+    def input_guardrails(self) -> Optional[list[InputGuardrail]]:
+        """Return the input guardrails configured for this agent.
+
+        Returns
+        -------
+        list[InputGuardrail] or None
+            Input guardrails applied to the agent.
+        """
+        return self._input_guardrails
+
+    @property
+    def output_guardrails(self) -> Optional[list[OutputGuardrail]]:
+        """Return the output guardrails configured for this agent.
+
+        Returns
+        -------
+        list[OutputGuardrail] or None
+            Output guardrails applied to the agent.
+        """
+        return self._output_guardrails
+
+    @property
+    def session(self) -> Optional[Session]:
+        """Return the session configured for this agent.
+
+        Returns
+        -------
+        Session or None
+            Session configuration used for maintaining conversation history.
+        """
+        return self._session
+
     def get_agent(self) -> Agent:
         """Construct and return the configured :class:`agents.Agent` instance.
 
@@ -337,12 +423,12 @@ class BaseAgent:
             Initialized agent ready for execution.
         """
         agent_config: Dict[str, Any] = {
-            "name": self.agent_name,
+            "name": self._name,
             "instructions": self._build_prompt_from_jinja() or ".",
             "model": self.model,
         }
-        if self._output_type:
-            agent_config["output_type"] = self._output_type
+        if self._output_structure:
+            agent_config["output_type"] = self._output_structure
         if self._tools:
             agent_config["tools"] = self._tools
         if self._model_settings:
@@ -361,7 +447,7 @@ class BaseAgent:
         input: str,
         *,
         context: Optional[Dict[str, Any]] = None,
-        output_type: Optional[Any] = None,
+        output_structure: Optional[type[StructureBase]] = None,
         session: Optional[Any] = None,
     ) -> Any:
         """Execute the agent asynchronously.
@@ -372,7 +458,7 @@ class BaseAgent:
             Prompt or query for the agent.
         context : dict or None, default=None
             Optional 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 across runs.
@@ -381,17 +467,17 @@ class BaseAgent:
         Returns
         -------
         Any
-            Agent result, optionally converted to ``output_type``.
+            Agent result, optionally converted to ``output_structure``.
         """
-        if self._output_type is not None and output_type is None:
-            output_type = self._output_type
+        if self._output_structure is not None and output_structure is None:
+            output_structure = self._output_structure
         # 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,
+            output_structure=output_structure,
             session=session_to_use,
         )
 
@@ -400,7 +486,7 @@ class BaseAgent:
         input: str,
         *,
         context: Optional[Dict[str, Any]] = None,
-        output_type: Optional[Any] = None,
+        output_structure: Optional[type[StructureBase]] = None,
         session: Optional[Any] = None,
     ) -> Any:
         """Run the agent synchronously.
@@ -411,7 +497,7 @@ class BaseAgent:
             Prompt or query for the agent.
         context : dict or None, default=None
             Optional 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 across runs.
@@ -420,15 +506,17 @@ class BaseAgent:
         Returns
         -------
         Any
-            Agent result, optionally converted to ``output_type``.
+            Agent result, optionally converted to ``output_structure``.
         """
+        if self._output_structure is not None and output_structure is None:
+            output_structure = self._output_structure
         # 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,
+            output_structure=output_structure,
             session=session_to_use,
         )
 
@@ -437,9 +525,9 @@ class BaseAgent:
         input: str,
         *,
         context: Optional[Dict[str, Any]] = None,
-        output_type: Optional[Any] = None,
+        output_structure: Optional[type[StructureBase]] = None,
         session: Optional[Any] = None,
-    ) -> RunResultStreaming:
+    ) -> RunResultStreaming | StructureBase:
         """Stream the agent execution results.
 
         Parameters
@@ -448,7 +536,7 @@ class BaseAgent:
             Prompt or query for the agent.
         context : dict or None, default=None
             Optional 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 across runs.
@@ -461,16 +549,16 @@ class BaseAgent:
         """
         # Use session from parameter, fall back to config session
         session_to_use = session if session is not None else self._session
+        output_structure_to_use = output_structure or self._output_structure
         result = run_streamed(
             agent=self.get_agent(),
             input=input,
             context=context,
+            output_structure=output_structure_to_use,
             session=session_to_use,
         )
-        if self._output_type and not output_type:
-            output_type = self._output_type
-        if output_type:
-            return result.final_output_as(output_type)
+        if output_structure_to_use and hasattr(result, "final_output_as"):
+            return cast(Any, result).final_output_as(output_structure_to_use)
         return result
 
     def as_tool(self) -> Tool:
@@ -483,16 +571,36 @@ class BaseAgent:
         """
         agent = self.get_agent()
         tool_obj: Tool = agent.as_tool(
-            tool_name=self.agent_name, tool_description=self.description
+            tool_name=self._name, tool_description=self.description
         )
         return tool_obj
 
-    def __enter__(self) -> BaseAgent:
+    def as_response_tool(self) -> tuple[dict[str, Callable[..., Any]], dict[str, Any]]:
+        """Return the agent as a callable response tool.
+
+        Returns
+        -------
+        Tool
+            Tool instance wrapping this agent for response generation.
+        """
+        tool_handler = {self.name: self.run_sync}
+        tool_definition = {
+            "type": "function",
+            "name": self.name,
+            "description": self.description,
+            "strict": True,
+            "additionalProperties": False,
+        }
+        if self.output_structure:
+            tool_definition["parameters"] = self.output_structure.get_schema()
+        return tool_handler, tool_definition
+
+    def __enter__(self) -> AgentBase:
         """Enter the context manager for resource management.
 
         Returns
         -------
-        BaseAgent
+        AgentBase
             Self reference for use in with statements.
         """
         return self
@@ -520,14 +628,47 @@ class BaseAgent:
 
         Examples
         --------
-        >>> agent = BaseAgent(config, default_model="gpt-4o-mini")
+        >>> agent = AgentBase(config, default_model="gpt-4o-mini")
         >>> try:
         ...     result = agent.run_sync("query")
         ... finally:
         ...     agent.close()
         """
-        # Base implementation does nothing, but subclasses can override
-        pass
+        log(f"Closing session {self.uuid} for {self.__class__.__name__}")
+        self.save()
+
+    def __repr__(self) -> str:
+        """Return a string representation of the AgentBase.
+
+        Returns
+        -------
+        str
+            String representation including agent name and model.
+        """
+        return f"<AgentBase name={self._name!r} model={self.model!r}>"
+
+    def save(self, filepath: str | Path | None = None) -> None:
+        """Serialize the message history to a JSON file.
+
+        Saves the current message history to a specified file path in JSON format.
+        If no file path is provided, it saves to a default location based on
+        the agent's UUID.
+
+        Parameters
+        ----------
+        filepath : str | Path | None, default=None
+            Optional file path to save the serialized history. If None,
+            uses a default filename based on the agent name.
+        """
+        if filepath is not None:
+            target = Path(filepath)
+        else:
+            filename = f"{str(self.uuid).lower()}.json"
+            target = self._data_path / self._name / filename
+
+        checked = check_filepath(filepath=target)
+        self.to_json_file(filepath=checked)
+        log(f"Saved messages to {target}")
 
 
-__all__ = ["AgentConfigurationLike", "BaseAgent"]
+__all__ = ["AgentConfigurationProtocol", "AgentBase"]