openai-sdk-helpers 0.4.3__py3-none-any.whl → 0.5.1__py3-none-any.whl

openai_sdk_helpers/agent/base.py

@@ -2,41 +2,37 @@
 
 from __future__ import annotations
 
-import json
-from pathlib import Path
-from typing import TYPE_CHECKING, Any, Callable, Dict, Optional, Protocol, cast
+import logging
+import traceback
 import uuid
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Dict, Optional, Protocol, cast
 
-from agents import (
-    Agent,
-    Handoff,
-    InputGuardrail,
-    OutputGuardrail,
-    RunResultStreaming,
-    Session,
-)
+from agents import Agent, Handoff, InputGuardrail, OutputGuardrail, Session
 from agents.model_settings import ModelSettings
 from agents.run_context import RunContextWrapper
 from agents.tool import Tool
 from jinja2 import Template
 
+from ..environment import get_data_path
 from ..utils.json.data_class import DataclassJSONSerializable
 from ..structure.base import StructureBase
-from ..structure.prompt import PromptStructure
-
+from ..tools import (
+    StructureType,
+    ToolHandlerRegistration,
+    ToolSpec,
+)
 
 from ..utils import (
     check_filepath,
     log,
 )
 
-from ..tools import tool_handler_factory
-
-from .runner import run_async, run_streamed, run_sync
+from .runner import run_async, run_sync
 
 if TYPE_CHECKING:
     from ..settings import OpenAISettings
-    from ..response.base import ResponseBase, ToolHandler
+    from ..response.base import ResponseBase
 
 
 class AgentConfigurationProtocol(Protocol):
@@ -52,18 +48,14 @@ class AgentConfigurationProtocol(Protocol):
         """Agent description."""
         ...
 
-    @property
-    def model(self) -> Optional[str]:
-        """Model identifier."""
-        ...
-
     @property
     def template_path(self) -> Optional[str | Path]:
         """Template path."""
         ...
 
-    def resolve_prompt_path(self, prompt_dir: Path | None = None) -> Path | None:
-        """Resolve the prompt template path."""
+    @property
+    def model(self) -> Optional[str]:
+        """Model identifier."""
         ...
 
     @property
@@ -136,7 +128,7 @@ class AgentBase(DataclassJSONSerializable):
     ...     description="A custom agent",
     ...     model="gpt-4o-mini"
     ... )
-    >>> agent = AgentBase(configuration=configuration, default_model="gpt-4o-mini")
+    >>> agent = AgentBase(configuration=configuration)
     >>> result = agent.run_sync("What is 2+2?")
 
     Use absolute path to template:
@@ -146,7 +138,7 @@ class AgentBase(DataclassJSONSerializable):
     ...     template_path="/absolute/path/to/template.jinja",
     ...     model="gpt-4o-mini"
     ... )
-    >>> agent = AgentBase(configuration=configuration, default_model="gpt-4o-mini")
+    >>> agent = AgentBase(configuration=configuration)
 
     Use async execution:
 
@@ -186,14 +178,14 @@ class AgentBase(DataclassJSONSerializable):
         Execute the agent asynchronously and optionally cast the result.
     run_sync(input, context, output_structure, session)
         Execute the agent synchronously.
-    run_streamed(input, context, output_structure, session)
-        Return a streaming result for the agent execution.
     as_tool()
         Return the agent as a callable tool.
     as_response_tool()
         Return response tool handler and definition for Responses API use.
     build_response(openai_settings, data_path=None, tool_handlers=None, system_vector_store=None)
         Build a ResponseBase instance based on this agent.
+    save_error(exc)
+        Persist error details to a file named with the agent UUID.
     close()
         Clean up agent resources (can be overridden by subclasses).
     """
@@ -204,8 +196,6 @@ class AgentBase(DataclassJSONSerializable):
         configuration: 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 AgentBase using a configuration object.
 
@@ -215,39 +205,31 @@ class AgentBase(DataclassJSONSerializable):
             Configuration describing this agent.
         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. Used when
-            ``configuration.template_path`` is not provided or is relative. If
-            ``configuration.template_path`` is an absolute path, this parameter is
-            ignored.
-        default_model : str or None, default=None
-            Optional fallback model identifier if the configuration does not supply one.
+        data_path : Path | str | None, default=None
+            Optional base path for storing agent data.
         """
-        name = configuration.name
-        description = configuration.description or ""
-        model = configuration.model or default_model
-        if not model:
-            raise ValueError("Model is required to construct the agent.")
-
-        prompt_path = configuration.resolve_prompt_path(prompt_dir)
+        self._configuration = configuration
+        self.uuid = uuid.uuid4()
+        self._model = configuration.model
+        if self._model is None:
+            raise ValueError(
+                f"Model must be specified in configuration for agent '{configuration.name}'."
+            )
 
         # Build template from file or fall back to instructions
-        if prompt_path is None:
+        self._template_path = configuration.template_path
+        if self._template_path is None:
             instructions_text = configuration.instructions_text
             self._template = Template(instructions_text)
             self._instructions = instructions_text
-        elif prompt_path.exists():
-            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._name = name
-        self.uuid = uuid.uuid4()
-        self.description = description
-        self.model = model
+            self._template_path = Path(self._template_path)
+            if not self._template_path.exists():
+                raise FileNotFoundError(
+                    f"Template for agent '{self._configuration.name}' not found at {self._template_path}."
+                )
+            self._template = Template(self._template_path.read_text(encoding="utf-8"))
+            self._instructions = None
 
         # Resolve data_path with class name appended
         class_name = self.__class__.__name__
@@ -258,8 +240,6 @@ class AgentBase(DataclassJSONSerializable):
             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 = configuration.input_structure
@@ -337,7 +317,29 @@ class AgentBase(DataclassJSONSerializable):
         str
             Name used to identify the agent.
         """
-        return self._name
+        return self._configuration.name
+
+    @property
+    def description(self) -> Optional[str]:
+        """Return the description of this agent.
+
+        Returns
+        -------
+        str or None
+            Description of the agent's purpose.
+        """
+        return self._configuration.description
+
+    @property
+    def model(self) -> str:
+        """Return the model identifier for this agent.
+
+        Returns
+        -------
+        str
+            Model identifier used by the agent.
+        """
+        return self._model  # pyright: ignore[reportReturnType]
 
     @property
     def instructions_text(self) -> str:
@@ -348,9 +350,7 @@ class AgentBase(DataclassJSONSerializable):
         str
             Rendered instructions text using the current run context.
         """
-        if self._instructions is not None:
-            return self._instructions
-        return self._build_prompt_from_jinja()
+        return self._configuration.instructions_text
 
     @property
     def tools(self) -> Optional[list]:
@@ -361,7 +361,7 @@ class AgentBase(DataclassJSONSerializable):
         list or None
             Tool definitions configured for the agent.
         """
-        return self._tools
+        return self._configuration.tools
 
     @property
     def output_structure(self) -> Optional[type[StructureBase]]:
@@ -372,7 +372,7 @@ class AgentBase(DataclassJSONSerializable):
         type[StructureBase] or None
             Output type used to cast responses.
         """
-        return self._output_structure
+        return self._configuration.output_structure
 
     @property
     def model_settings(self) -> Optional[ModelSettings]:
@@ -438,14 +438,14 @@ class AgentBase(DataclassJSONSerializable):
             Initialized agent ready for execution.
         """
         agent_config: Dict[str, Any] = {
-            "name": self._name,
-            "instructions": self._build_prompt_from_jinja() or ".",
-            "model": self.model,
+            "name": self._configuration.name,
+            "instructions": self._configuration.instructions_text or ".",
+            "model": self._model,
         }
-        if self._output_structure:
-            agent_config["output_type"] = self._output_structure
-        if self._tools:
-            agent_config["tools"] = self._tools
+        if self._configuration.output_structure:
+            agent_config["output_type"] = self._configuration.output_structure
+        if self._configuration.tools:
+            agent_config["tools"] = self._configuration.tools
         if self._model_settings:
             agent_config["model_settings"] = self._model_settings
         if self._handoffs:
@@ -488,13 +488,29 @@ class AgentBase(DataclassJSONSerializable):
             output_structure = self._output_structure
         # Use session from parameter, fall back to configuration 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_structure=output_structure,
-            session=session_to_use,
-        )
+        try:
+            return await run_async(
+                agent=self.get_agent(),
+                input=input,
+                context=context,
+                output_structure=output_structure,
+                session=session_to_use,
+            )
+        except Exception as exc:
+            try:
+                self.save_error(exc)
+            except Exception as save_exc:
+                log(
+                    f"Failed to save error details for agent {self.uuid}: {save_exc}",
+                    level=logging.ERROR,
+                    exc=save_exc,
+                )
+            log(
+                f"Error running agent '{self.name}': {exc}",
+                level=logging.ERROR,
+                exc=exc,
+            )
+            raise
 
     def run_sync(
         self,
@@ -527,54 +543,29 @@ class AgentBase(DataclassJSONSerializable):
             output_structure = self._output_structure
         # Use session from parameter, fall back to configuration 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_structure=output_structure,
-            session=session_to_use,
-        )
-
-    def run_streamed(
-        self,
-        input: str,
-        *,
-        context: Optional[Dict[str, Any]] = None,
-        output_structure: Optional[type[StructureBase]] = None,
-        session: Optional[Any] = None,
-    ) -> RunResultStreaming | StructureBase:
-        """Stream the agent execution results.
-
-        Parameters
-        ----------
-        input : str
-            Prompt or query for the agent.
-        context : dict or None, default=None
-            Optional 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 across runs.
-            If not provided, uses the session from configuration if available.
-
-        Returns
-        -------
-        RunResultStreaming
-            Streaming output wrapper from the agent execution.
-        """
-        # Use session from parameter, fall back to configuration 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 output_structure_to_use and hasattr(result, "final_output_as"):
-            return cast(Any, result).final_output_as(output_structure_to_use)
-        return result
+        try:
+            return run_sync(
+                agent=self.get_agent(),
+                input=input,
+                context=context,
+                output_structure=output_structure,
+                session=session_to_use,
+            )
+        except Exception as exc:
+            try:
+                self.save_error(exc)
+            except Exception as save_exc:
+                log(
+                    f"Failed to save error details for agent {self.uuid}: {save_exc}",
+                    level=logging.ERROR,
+                    exc=save_exc,
+                )
+            log(
+                f"Error running agent '{self.name}': {exc}",
+                level=logging.ERROR,
+                exc=exc,
+            )
+            raise
 
     def as_tool(self) -> Tool:
         """Return the agent as a callable tool.
@@ -586,78 +577,35 @@ class AgentBase(DataclassJSONSerializable):
         """
         agent = self.get_agent()
         tool_obj: Tool = agent.as_tool(
-            tool_name=self._name, tool_description=self.description
+            tool_name=self._configuration.name,
+            tool_description=self._configuration.description,
         )
         return tool_obj
 
-    def as_response_tool(
+    def as_tool_handler_registration(
         self,
-        *,
-        tool_name: str | None = None,
-        tool_description: str | None = None,
-    ) -> tuple[dict[str, Callable[..., Any]], dict[str, Any]]:
-        """Return response tool handler and definition for Responses API use.
-
-        The returned handler serializes tool output as JSON using
-        ``tool_handler_factory`` so downstream response flows can rely on a
-        consistent payload format.
+    ) -> ToolHandlerRegistration:
+        """Return the agent as a ToolHandlerRegistration for Responses API use.
 
         Parameters
         ----------
         tool_name : str or None, default=None
             Optional override for the tool name. When None, uses the agent name.
-        tool_description : str or None, default=None
-            Optional override for the tool description. When None, uses the
-            agent description.
-
-        Returns
-        -------
-        tuple[dict[str, Callable[..., Any]], dict[str, Any]]
-            Tool handler mapping and tool definition for Responses API usage.
-
-        Examples
-        --------
-        >>> tool_handler, tool_definition = agent.as_response_tool()
-        >>> response = ResponseBase(
-        ...     name="agent_tool",
-        ...     instructions="Use the agent tool when needed.",
-        ...     tools=[tool_definition],
-        ...     output_structure=None,
-        ...     tool_handlers=tool_handler,
-        ...     openai_settings=settings,
-        ... )
-        >>> response.run_sync("Invoke the agent tool")  # doctest: +SKIP
         """
-
-        def _run_agent(**kwargs: Any) -> Any:
-            prompt = kwargs.get("prompt")
-            if prompt is None:
-                if len(kwargs) == 1:
-                    prompt = next(iter(kwargs.values()))
-                else:
-                    prompt = json.dumps(kwargs)
-            return self.run_sync(str(prompt))
-
-        name = tool_name or self.name
-        description = tool_description or self.description
-        input_model = self._input_structure or PromptStructure
-        tool_handler = {name: tool_handler_factory(_run_agent, input_model=input_model)}
-        tool_definition = {
-            "type": "function",
-            "name": name,
-            "description": description,
-            "strict": True,
-            "additionalProperties": False,
-            "parameters": self._build_response_parameters(),
-        }
-        return tool_handler, tool_definition
+        tool_spec = ToolSpec(
+            tool_name=self.name,
+            tool_description=self.description,
+            input_structure=cast(StructureType, self._configuration.input_structure),
+            output_structure=cast(StructureType, self._configuration.output_structure),
+        )
+        return ToolHandlerRegistration(handler=self.run_sync, tool_spec=tool_spec)
 
     def build_response(
         self,
         *,
         openai_settings: OpenAISettings,
         data_path: Path | str | None = None,
-        tool_handlers: dict[str, ToolHandler] | None = None,
+        tool_handlers: dict[str, ToolHandlerRegistration] | None = None,
         system_vector_store: list[str] | None = None,
     ) -> ResponseBase[StructureBase]:
         """Build a ResponseBase instance from this agent configuration.
@@ -669,8 +617,9 @@ class AgentBase(DataclassJSONSerializable):
         data_path : Path, str, or None, default None
             Optional path for storing response artifacts. When None, the
             response uses the default data directory.
-        tool_handlers : dict[str, ToolHandler] or None, default None
-            Optional mapping of tool names to handler callables.
+        tool_handlers : dict[str, ToolHandlerRegistration] or None, default None
+            Optional mapping of tool names to handler registrations. Registrations
+            can include ToolSpec metadata to parse tool outputs by name.
         system_vector_store : list[str] or None, default None
             Optional list of vector store names to attach as system context.
 
@@ -684,7 +633,7 @@ class AgentBase(DataclassJSONSerializable):
         >>> from openai_sdk_helpers import OpenAISettings
         >>> response = agent.build_response(openai_settings=OpenAISettings.from_env())
         """
-        from ..response.base import ResponseBase, ToolHandler
+        from ..response.base import ResponseBase
         from ..settings import OpenAISettings
 
         if not isinstance(openai_settings, OpenAISettings):
@@ -693,8 +642,8 @@ class AgentBase(DataclassJSONSerializable):
         tools = self._normalize_response_tools(self.tools)
 
         return ResponseBase(
-            name=self.name,
-            instructions=self.instructions_text,
+            name=self._configuration.name,
+            instructions=self._configuration.instructions_text,
             tools=tools,
             output_structure=self.output_structure,
             system_vector_store=system_vector_store,
@@ -773,7 +722,7 @@ class AgentBase(DataclassJSONSerializable):
 
         Examples
         --------
-        >>> agent = AgentBase(configuration, default_model="gpt-4o-mini")
+        >>> agent = AgentBase(configuration)
         >>> try:
         ...     result = agent.run_sync("query")
         ... finally:
@@ -790,7 +739,7 @@ class AgentBase(DataclassJSONSerializable):
         str
             String representation including agent name and model.
         """
-        return f"<AgentBase name={self._name!r} model={self.model!r}>"
+        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.
@@ -809,11 +758,41 @@ class AgentBase(DataclassJSONSerializable):
             target = Path(filepath)
         else:
             filename = f"{str(self.uuid).lower()}.json"
-            target = self._data_path / self._name / filename
+            target = self._data_path / self.name / filename
 
         checked = check_filepath(filepath=target)
         self.to_json_file(filepath=checked)
         log(f"Saved messages to {target}")
 
+    def save_error(self, exc: BaseException) -> Path:
+        """Persist error details to a file named with the agent UUID.
+
+        Parameters
+        ----------
+        exc : BaseException
+            Exception instance to serialize.
+
+        Returns
+        -------
+        Path
+            Path to the error file written to disk.
+
+        Examples
+        --------
+        >>> try:
+        ...     agent.run_sync("trigger error")
+        ... except Exception as exc:
+        ...     agent.save_error(exc)
+        """
+        error_text = "".join(
+            traceback.format_exception(type(exc), exc, exc.__traceback__)
+        )
+        filename = f"{str(self.uuid).lower()}_error.txt"
+        target = self._data_path / self.name / filename
+        checked = check_filepath(filepath=target)
+        checked.write_text(error_text, encoding="utf-8")
+        log(f"Saved error details to {checked}")
+        return checked
+
 
 __all__ = ["AgentConfigurationProtocol", "AgentBase"]

openai_sdk_helpers/agent/configuration.py

@@ -150,7 +150,7 @@ class AgentConfiguration(DataclassJSONSerializable):
         Return the resolved instruction content as a string.
     resolve_prompt_path(prompt_dir)
         Resolve the prompt template path for this configuration.
-    gen_agent(run_context_wrapper, prompt_dir, default_model)
+    gen_agent(run_context_wrapper)
         Create a AgentBase instance from this configuration.
     replace(**changes)
         Create a new AgentConfiguration with specified fields replaced.
@@ -176,17 +176,17 @@ class AgentConfiguration(DataclassJSONSerializable):
 
     name: str
     instructions: str | Path
-    description: Optional[str] = None
-    model: Optional[str] = None
-    template_path: Optional[str | Path] = None
-    input_structure: Optional[Type[StructureBase]] = None
-    output_structure: Optional[Type[StructureBase]] = 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
+    description: str | None = None
+    model: str | None = None
+    template_path: str | Path | None = None
+    input_structure: type[StructureBase] | None = None
+    output_structure: type[StructureBase] | None = None
+    tools: list | None = None
+    model_settings: ModelSettings | None = None
+    handoffs: list[Agent | Handoff] | None = None
+    input_guardrails: list[InputGuardrail] | None = None
+    output_guardrails: list[OutputGuardrail] | None = None
+    session: Session | None = None
     add_output_instructions: bool = False
     add_web_search_tool: bool = False
 
@@ -294,8 +294,6 @@ class AgentConfiguration(DataclassJSONSerializable):
     def gen_agent(
         self,
         run_context_wrapper: Any = None,
-        prompt_dir: Path | None = None,
-        default_model: str | None = None,
     ) -> Any:
         """Create a AgentBase instance from this configuration.
 
@@ -305,10 +303,6 @@ class AgentConfiguration(DataclassJSONSerializable):
         ----------
         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 configuration doesn't specify one.
 
         Returns
         -------
@@ -329,8 +323,6 @@ class AgentConfiguration(DataclassJSONSerializable):
         return AgentBase(
             configuration=self,
             run_context_wrapper=run_context_wrapper,
-            prompt_dir=prompt_dir,
-            default_model=default_model,
         )
 
     def replace(self, **changes: Any) -> AgentConfiguration: