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

openai_sdk_helpers/agent/config.py

@@ -1,17 +1,18 @@
-"""Configuration helpers for ``BaseAgent``."""
+"""Configuration helpers for ``AgentBase``."""
 
 from __future__ import annotations
 
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from pathlib import Path
-from typing import Any, Optional
+from typing import Any, Optional, Type
 
 from agents import Agent, Handoff, InputGuardrail, OutputGuardrail, Session
 from agents.model_settings import ModelSettings
 
-from ..utils import JSONSerializable
+from ..utils.json.data_class import DataclassJSONSerializable
 from ..utils.registry import BaseRegistry
 from ..utils.instructions import resolve_instructions_from_path
+from ..structure.base import StructureBase
 
 
 class AgentConfigurationRegistry(BaseRegistry["AgentConfiguration"]):
@@ -73,10 +74,6 @@ class AgentConfigurationRegistry(BaseRegistry["AgentConfiguration"]):
         return super().load_from_directory(path, config_class=config_class)
 
 
-# Global default registry instance
-_default_registry = AgentConfigurationRegistry()
-
-
 def get_default_registry() -> AgentConfigurationRegistry:
     """Return the global default registry instance.
 
@@ -97,12 +94,12 @@ def get_default_registry() -> AgentConfigurationRegistry:
 
 
 @dataclass(frozen=True, slots=True)
-class AgentConfiguration(JSONSerializable):
-    """Immutable configuration for building a BaseAgent.
+class AgentConfiguration(DataclassJSONSerializable):
+    """Immutable configuration for building a AgentBase.
 
     Encapsulates all metadata required to define an agent including its
     instructions, tools, model settings, handoffs, guardrails, and session
-    management. Inherits from JSONSerializable to support serialization.
+    management. Inherits from DataclassJSONSerializable to support serialization.
 
     This dataclass is frozen (immutable) to ensure thread-safety and
     enable use as dictionary keys. All list-type fields use None as the
@@ -124,12 +121,10 @@ class AgentConfiguration(JSONSerializable):
         Path to the Jinja template (absolute or relative to prompt_dir).
         This takes precedence over instructions if both are provided.
         Default is None.
-    input_type : type, optional
-        Type describing the agent input, commonly a Pydantic model.
-        Default is None.
-    output_type : type, optional
-        Type describing the agent output, commonly a Pydantic model or
-        builtin like str. Default is None.
+    input_structure : type[StructureBase], optional
+        Structure class describing the agent input. Default is None.
+    output_structure : type[StructureBase], optional
+        Structure class describing the agent output. Default is None.
     tools : list, optional
         Tool definitions available to the agent. Default is None.
     model_settings : ModelSettings, optional
@@ -153,8 +148,10 @@ class AgentConfiguration(JSONSerializable):
         Validate configuration invariants after initialization.
     instructions_text
         Return the resolved instruction content as a string.
-    create_agent(run_context_wrapper, prompt_dir, default_model)
-        Create a BaseAgent instance from this configuration.
+    resolve_prompt_path(prompt_dir)
+        Resolve the prompt template path for this configuration.
+    gen_agent(run_context_wrapper, prompt_dir, default_model)
+        Create a AgentBase instance from this configuration.
     replace(**changes)
         Create a new AgentConfiguration with specified fields replaced.
     to_json()
@@ -182,14 +179,17 @@ class AgentConfiguration(JSONSerializable):
     description: Optional[str] = None
     model: Optional[str] = None
     template_path: Optional[str | Path] = None
-    input_type: Optional[type] = None
-    output_type: Optional[type] = 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
+    _instructions_cache: Optional[str] = field(
+        default=None, init=False, repr=False, compare=False
+    )
 
     def __post_init__(self) -> None:
         """Validate configuration invariants after initialization.
@@ -202,6 +202,8 @@ class AgentConfiguration(JSONSerializable):
         TypeError
             If name is not a non-empty string.
             If instructions is not a string or Path.
+            If input_structure or output_structure is not a class.
+            If input_structure or output_structure does not subclass StructureBase.
         ValueError
             If instructions is an empty string.
         FileNotFoundError
@@ -226,6 +228,19 @@ class AgentConfiguration(JSONSerializable):
         else:
             raise TypeError("AgentConfiguration.instructions must be a str or Path")
 
+        for attr in ("input_structure", "output_structure"):
+            cls = getattr(self, attr)
+            if cls is None:
+                continue
+            if not isinstance(cls, type):
+                raise TypeError(
+                    f"AgentConfiguration.{attr} must be a class (Type[StructureBase]) or None"
+                )
+            if not issubclass(cls, StructureBase):
+                raise TypeError(
+                    f"AgentConfiguration.{attr} must subclass StructureBase"
+                )
+
         if self.template_path is not None and isinstance(self.template_path, Path):
             # Validate template_path if it's a Path object
             template = self.template_path.expanduser()
@@ -243,21 +258,44 @@ class AgentConfiguration(JSONSerializable):
         str
             Plain-text instructions, loading template files when necessary.
         """
-        return self._resolve_instructions()
+        cached = self._instructions_cache
+        if cached is None:
+            cached = self._resolve_instructions()
+            object.__setattr__(self, "_instructions_cache", cached)
+        return cached
 
     def _resolve_instructions(self) -> str:
         """Resolve instructions from string or file path."""
         return resolve_instructions_from_path(self.instructions)
 
-    def create_agent(
+    def resolve_prompt_path(self, prompt_dir: Path | None = None) -> Path | None:
+        """Resolve the prompt template path for this configuration.
+
+        Parameters
+        ----------
+        prompt_dir : Path or None, default=None
+            Directory holding prompt templates when a relative path is needed.
+
+        Returns
+        -------
+        Path or None
+            Resolved prompt path if a template is configured or discovered.
+        """
+        if self.template_path:
+            return Path(self.template_path)
+        if prompt_dir is not None:
+            return prompt_dir / f"{self.name}.jinja"
+        return None
+
+    def gen_agent(
         self,
         run_context_wrapper: Any = None,
         prompt_dir: Path | None = None,
         default_model: str | None = None,
     ) -> Any:
-        """Create a BaseAgent instance from this configuration.
+        """Create a AgentBase instance from this configuration.
 
-        This is a convenience method that delegates to BaseAgent.from_configuration().
+        This is a convenience method that instantiates ``AgentBase`` directly.
 
         Parameters
         ----------
@@ -270,7 +308,7 @@ class AgentConfiguration(JSONSerializable):
 
         Returns
         -------
-        BaseAgent
+        AgentBase
             Configured agent instance ready for execution.
 
         Examples
@@ -278,13 +316,13 @@ class AgentConfiguration(JSONSerializable):
         >>> config = AgentConfiguration(
         ...     name="helper", model="gpt-4o-mini", instructions="Help the user"
         ... )
-        >>> agent = config.create_agent()
+        >>> agent = config.gen_agent()
         >>> result = agent.run_sync("Hello!")
         """
         # Import here to avoid circular dependency
-        from .base import BaseAgent
+        from .base import AgentBase
 
-        return BaseAgent.from_configuration(
+        return AgentBase(
             config=self,
             run_context_wrapper=run_context_wrapper,
             prompt_dir=prompt_dir,
@@ -323,6 +361,18 @@ class AgentConfiguration(JSONSerializable):
 
         return replace(self, **changes)
 
+    def to_json(self) -> dict[str, Any]:
+        """Return a JSON-compatible dict representation.
+
+        Returns
+        -------
+        dict[str, Any]
+            Serialized configuration data without cached fields.
+        """
+        data = DataclassJSONSerializable.to_json(self)
+        data.pop("_instructions_cache", None)
+        return data
+
     @classmethod
     def from_json(cls, data: dict[str, Any]) -> AgentConfiguration:
         """Create an AgentConfiguration from JSON data.
@@ -350,6 +400,7 @@ class AgentConfiguration(JSONSerializable):
         """
         # Make a copy to avoid modifying the input
         data = data.copy()
+        data.pop("_instructions_cache", None)
 
         # Handle instructions field: if it's a string path to an existing file,
         # convert it back to Path for proper file loading
@@ -372,4 +423,7 @@ class AgentConfiguration(JSONSerializable):
         return super(AgentConfiguration, cls).from_json(data)
 
 
+# Global default registry instance
+_default_registry = AgentConfigurationRegistry()
+
 __all__ = ["AgentConfiguration", "AgentConfigurationRegistry", "get_default_registry"]

openai_sdk_helpers/agent/coordination.py

@@ -12,8 +12,8 @@ from typing import Any, Callable, Dict, List, Optional
 
 
 from ..structure import TaskStructure, PlanStructure, PromptStructure
-from ..utils import JSONSerializable, ensure_directory, log
-from .base import BaseAgent
+from ..utils import DataclassJSONSerializable, ensure_directory, log
+from .base import AgentBase
 from .config import AgentConfiguration
 from ..structure.plan.enum import AgentEnum
 
@@ -23,9 +23,30 @@ ExecutePlanFn = Callable[[PlanStructure], List[str]]
 SummarizeFn = Callable[[List[str]], str]
 
 
-class CoordinatorAgent(BaseAgent, JSONSerializable):
+class CoordinatorAgent(AgentBase):
     """Coordinate agent plans while persisting project state and outputs.
 
+    Parameters
+    ----------
+    prompt_fn : PromptFn
+        Callable that generates a prompt brief from the input string.
+    build_plan_fn : BuildPlanFn
+        Callable that generates a plan from the prompt brief.
+    execute_plan_fn : ExecutePlanFn
+        Callable that executes a plan and returns results.
+    summarize_fn : SummarizeFn
+        Callable that summarizes a list of result strings.
+    module_data_path : Path
+        Base path for persisting project artifacts.
+    name : str
+        Name of the parent module for data organization.
+    config : AgentConfiguration or None, default=None
+        Optional agent configuration describing prompts and metadata.
+    prompt_dir : Path or None, default=None
+        Optional directory holding prompt templates.
+    default_model : str or None, default=None
+        Optional fallback model identifier.
+
     Methods
     -------
     build_prompt(prompt)
@@ -89,6 +110,22 @@ class CoordinatorAgent(BaseAgent, JSONSerializable):
             Optional directory holding prompt templates.
         default_model : str or None, default=None
             Optional fallback model identifier.
+
+        Raises
+        ------
+        ValueError
+            If the provided configuration is invalid.
+
+        Examples
+        --------
+        >>> coordinator = CoordinatorAgent(
+        ...     prompt_fn=lambda p: PromptStructure(prompt=p),
+        ...     build_plan_fn=lambda p: PlanStructure(),
+        ...     execute_plan_fn=lambda p: [],
+        ...     summarize_fn=lambda r: "summary",
+        ...     module_data_path=Path("."),
+        ...     name="test",
+        ... )
         """
         if config is None:
             config = AgentConfiguration(
@@ -120,6 +157,10 @@ class CoordinatorAgent(BaseAgent, JSONSerializable):
         ----------
         prompt : str
             The core request or goal for the project.
+
+        Examples
+        --------
+        >>> coordinator.build_prompt("Analyze the impact of AI on healthcare.")
         """
         log("build_prompt", level=logging.INFO)
         self.start_date = datetime.now(timezone.utc)
@@ -134,6 +175,11 @@ class CoordinatorAgent(BaseAgent, JSONSerializable):
         ------
         ValueError
             If called before :meth:`build_prompt`.
+
+        Examples
+        --------
+        >>> coordinator.build_prompt("Analyze AI in healthcare.")
+        >>> coordinator.build_plan()
         """
         log("build_plan", level=logging.INFO)
         if not self.brief:
@@ -151,6 +197,12 @@ class CoordinatorAgent(BaseAgent, JSONSerializable):
         -------
         list[str]
             Flattened list of results from all executed tasks.
+
+        Examples
+        --------
+        >>> coordinator.build_prompt("Analyze AI.")
+        >>> coordinator.build_plan()
+        >>> results = coordinator.execute_plan()
         """
         log("execute_plan", level=logging.INFO)
         if not self.plan:
@@ -174,6 +226,11 @@ class CoordinatorAgent(BaseAgent, JSONSerializable):
         -------
         str
             Concise summary derived from the provided results.
+
+        Examples
+        --------
+        >>> results = ["AI is impacting healthcare.", "New models are faster."]
+        >>> summary = coordinator.summarize_plan(results)
         """
         log("summarize_plan", level=logging.INFO)
 
@@ -199,37 +256,16 @@ class CoordinatorAgent(BaseAgent, JSONSerializable):
         ----------
         prompt : str
             The request or question to analyze and summarize.
+
+        Examples
+        --------
+        >>> coordinator.run_plan("Analyze the future of AI.")
         """
         self.build_prompt(prompt)
         self.build_plan()
         results = self.execute_plan()
         self.summarize_plan(results)
 
-    @property
-    def file_path(self) -> Path:
-        """Return the path where the project snapshot will be stored.
-
-        Returns
-        -------
-        Path
-            Location of the JSON artifact for the current run.
-        """
-        if not self.start_date:
-            self.start_date = datetime.now(timezone.utc)
-        start_date_str = self.start_date.strftime("%Y%m%d_%H%M%S")
-        return self._module_data_path / self._name / f"{start_date_str}.json"
-
-    def save(self) -> Path:
-        """Persist the current project state to disk.
-
-        Returns
-        -------
-        Path
-            Path to the saved JSON artifact.
-        """
-        self.to_json_file(self.file_path)
-        return self.file_path
-
     @staticmethod
     def _run_task(
         task: TaskStructure,

openai_sdk_helpers/agent/runner.py

@@ -12,6 +12,7 @@ from typing import Any, Dict, Optional
 from agents import Agent, RunResult, RunResultStreaming, Runner, Session
 
 from openai_sdk_helpers.utils.async_utils import run_coroutine_with_fallback
+from ..structure.base import StructureBase
 
 
 async def run_async(
@@ -19,7 +20,7 @@ async def run_async(
     input: str,
     *,
     context: Optional[Dict[str, Any]] = None,
-    output_type: Optional[Any] = None,
+    output_structure: Optional[type[StructureBase]] = None,
     session: Optional[Session] = None,
 ) -> Any:
     """Run an Agent asynchronously.
@@ -32,7 +33,7 @@ async def run_async(
         Prompt or query string for the agent.
     context : dict or None, default=None
         Optional context 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.
@@ -40,7 +41,7 @@ async def run_async(
     Returns
     -------
     Any
-        Agent response, optionally converted to ``output_type``.
+        Agent response, optionally converted to ``output_structure``.
 
     Examples
     --------
@@ -53,8 +54,8 @@ async def run_async(
     >>> asyncio.run(example())  # doctest: +SKIP
     """
     result = await Runner.run(agent, input, context=context, session=session)
-    if output_type is not None:
-        return result.final_output_as(output_type)
+    if output_structure is not None:
+        return result.final_output_as(output_structure)
     return result
 
 
@@ -63,7 +64,7 @@ def run_sync(
     input: str,
     *,
     context: Optional[Dict[str, Any]] = None,
-    output_type: Optional[Any] = None,
+    output_structure: Optional[type[StructureBase]] = None,
     session: Optional[Session] = None,
 ) -> Any:
     """Run an Agent synchronously.
@@ -80,7 +81,7 @@ def run_sync(
         Prompt or query string for the agent.
     context : dict or None, default=None
         Optional context 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.
@@ -88,7 +89,7 @@ def run_sync(
     Returns
     -------
     Any
-        Agent response, optionally converted to ``output_type``.
+        Agent response, optionally converted to ``output_structure``.
 
     Raises
     ------
@@ -103,8 +104,8 @@ def run_sync(
     """
     coro = Runner.run(agent, input, context=context, session=session)
     result: RunResult = run_coroutine_with_fallback(coro)
-    if output_type is not None:
-        return result.final_output_as(output_type)
+    if output_structure is not None:
+        return result.final_output_as(output_structure)
     return result
 
 
@@ -113,9 +114,9 @@ def run_streamed(
     input: str,
     *,
     context: Optional[Dict[str, Any]] = None,
-    output_type: Optional[Any] = None,
+    output_structure: Optional[type[StructureBase]] = None,
     session: Optional[Session] = None,
-) -> RunResultStreaming:
+) -> RunResultStreaming | StructureBase:
     """Stream agent execution results.
 
     Parameters
@@ -126,7 +127,7 @@ def run_streamed(
         Prompt or query string for the agent.
     context : dict or None, default=None
         Optional context 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.
@@ -145,8 +146,8 @@ def run_streamed(
     ...     print(chunk, end="")
     """
     result = Runner.run_streamed(agent, input, context=context, session=session)
-    if output_type is not None:
-        return result.final_output_as(output_type)
+    if output_structure is not None:
+        return result.final_output_as(output_structure)
     return result