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

openai_sdk_helpers/agent/base.py

@@ -2,40 +2,36 @@
 
 from __future__ import annotations
 
-import json
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, Callable, Dict, Optional, Protocol, cast
+from typing import TYPE_CHECKING, Any, Dict, Optional, Protocol, cast
 import uuid
 
-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 ..config import OpenAISettings
-    from ..response.base import ResponseBase, ToolHandler
+    from ..settings import OpenAISettings
+    from ..response.base import ResponseBase
 
 
 class AgentConfigurationProtocol(Protocol):
@@ -51,18 +47,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
@@ -130,22 +122,22 @@ class AgentBase(DataclassJSONSerializable):
     Create a basic agent from configuration:
 
     >>> from openai_sdk_helpers.agent import AgentBase, AgentConfiguration
-    >>> config = AgentConfiguration(
+    >>> configuration = AgentConfiguration(
     ...     name="my_agent",
     ...     description="A custom agent",
     ...     model="gpt-4o-mini"
     ... )
-    >>> agent = AgentBase(config=config, default_model="gpt-4o-mini")
+    >>> agent = AgentBase(configuration=configuration)
     >>> result = agent.run_sync("What is 2+2?")
 
     Use absolute path to template:
 
-    >>> config = AgentConfiguration(
+    >>> configuration = 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 = AgentBase(configuration=configuration)
 
     Use async execution:
 
@@ -185,8 +177,6 @@ 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()
@@ -200,53 +190,43 @@ class AgentBase(DataclassJSONSerializable):
     def __init__(
         self,
         *,
-        config: AgentConfigurationProtocol,
+        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.
 
         Parameters
         ----------
-        config : AgentConfigurationProtocol
+        configuration : AgentConfigurationProtocol
             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
-            ``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 if the config does not supply one.
+        data_path : Path | str | None, default=None
+            Optional base path for storing agent data.
         """
-        name = config.name
-        description = config.description or ""
-        model = config.model or default_model
-        if not model:
-            raise ValueError("Model is required to construct the agent.")
-
-        prompt_path = config.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:
-            instructions_text = config.instructions_text
+        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__
@@ -261,14 +241,16 @@ class AgentBase(DataclassJSONSerializable):
 
             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
-        self._input_guardrails = config.input_guardrails
-        self._output_guardrails = config.output_guardrails
-        self._session = config.session
+        self._input_structure = configuration.input_structure
+        self._output_structure = (
+            configuration.output_structure or configuration.input_structure
+        )
+        self._tools = configuration.tools
+        self._model_settings = configuration.model_settings
+        self._handoffs = configuration.handoffs
+        self._input_guardrails = configuration.input_guardrails
+        self._output_guardrails = configuration.output_guardrails
+        self._session = configuration.session
         self._run_context_wrapper = run_context_wrapper
 
     def _build_prompt_from_jinja(self) -> str:
@@ -334,7 +316,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:
@@ -345,9 +349,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]:
@@ -358,7 +360,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]]:
@@ -369,7 +371,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]:
@@ -435,14 +437,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:
@@ -474,7 +476,7 @@ class AgentBase(DataclassJSONSerializable):
             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.
+            If not provided, uses the session from configuration if available.
 
         Returns
         -------
@@ -483,7 +485,7 @@ class AgentBase(DataclassJSONSerializable):
         """
         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
+        # 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(),
@@ -513,7 +515,7 @@ class AgentBase(DataclassJSONSerializable):
             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.
+            If not provided, uses the session from configuration if available.
 
         Returns
         -------
@@ -522,7 +524,7 @@ class AgentBase(DataclassJSONSerializable):
         """
         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
+        # 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(),
@@ -532,47 +534,6 @@ class AgentBase(DataclassJSONSerializable):
             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 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
-        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
-
     def as_tool(self) -> Tool:
         """Return the agent as a callable tool.
 
@@ -583,78 +544,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.
@@ -666,8 +584,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.
 
@@ -681,8 +600,8 @@ 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 ..config import OpenAISettings
+        from ..response.base import ResponseBase
+        from ..settings import OpenAISettings
 
         if not isinstance(openai_settings, OpenAISettings):
             raise TypeError("openai_settings must be an OpenAISettings instance")
@@ -690,8 +609,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,
@@ -770,7 +689,7 @@ class AgentBase(DataclassJSONSerializable):
 
         Examples
         --------
-        >>> agent = AgentBase(config, default_model="gpt-4o-mini")
+        >>> agent = AgentBase(configuration)
         >>> try:
         ...     result = agent.run_sync("query")
         ... finally:
@@ -787,7 +706,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.
@@ -806,7 +725,7 @@ 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)

openai_sdk_helpers/agent/{config.py → configuration.py}

@@ -24,12 +24,12 @@ class AgentRegistry(RegistryBase["AgentConfiguration"]):
     Examples
     --------
     >>> registry = AgentRegistry()
-    >>> config = AgentConfiguration(
+    >>> configuration = AgentConfiguration(
     ...     name="test_agent",
     ...     model="gpt-4o-mini",
     ...     instructions="Test instructions"
     ... )
-    >>> registry.register(config)
+    >>> registry.register(configuration)
     >>> retrieved = registry.get("test_agent")
     >>> retrieved.name
     'test_agent'
@@ -85,10 +85,10 @@ def get_default_registry() -> AgentRegistry:
     Examples
     --------
     >>> registry = get_default_registry()
-    >>> config = AgentConfiguration(
+    >>> configuration = AgentConfiguration(
     ...     name="test", model="gpt-4o-mini", instructions="Test instructions"
     ... )
-    >>> registry.register(config)
+    >>> registry.register(configuration)
     """
     return _default_registry
 
@@ -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.
@@ -165,28 +165,28 @@ class AgentConfiguration(DataclassJSONSerializable):
 
     Examples
     --------
-    >>> config = AgentConfiguration(
+    >>> configuration = AgentConfiguration(
     ...     name="summarizer",
     ...     description="Summarizes text",
     ...     model="gpt-4o-mini"
     ... )
-    >>> config.name
+    >>> configuration.name
     'summarizer'
     """
 
     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 config doesn't specify one.
 
         Returns
         -------
@@ -317,20 +311,18 @@ class AgentConfiguration(DataclassJSONSerializable):
 
         Examples
         --------
-        >>> config = AgentConfiguration(
+        >>> configuration = AgentConfiguration(
         ...     name="helper", model="gpt-4o-mini", instructions="Help the user"
         ... )
-        >>> agent = config.gen_agent()
+        >>> agent = configuration.gen_agent()
         >>> result = agent.run_sync("Hello!")
         """
         # Import here to avoid circular dependency
         from .base import AgentBase
 
         return AgentBase(
-            config=self,
+            configuration=self,
             run_context_wrapper=run_context_wrapper,
-            prompt_dir=prompt_dir,
-            default_model=default_model,
         )
 
     def replace(self, **changes: Any) -> AgentConfiguration:
@@ -352,10 +344,10 @@ class AgentConfiguration(DataclassJSONSerializable):
 
         Examples
         --------
-        >>> config = AgentConfiguration(
+        >>> configuration = AgentConfiguration(
         ...     name="agent1", model="gpt-4o-mini", instructions="Agent instructions"
         ... )
-        >>> config2 = config.replace(name="agent2", description="Modified")
+        >>> config2 = configuration.replace(name="agent2", description="Modified")
         >>> config2.name
         'agent2'
         >>> config2.model
@@ -387,7 +379,7 @@ class AgentConfiguration(DataclassJSONSerializable):
         >>> response_config.name
         'responder'
         """
-        from ..response.config import ResponseConfiguration
+        from ..response.configuration import ResponseConfiguration
 
         return ResponseConfiguration(
             name=self.name,