openai-sdk-helpers 0.0.7__py3-none-any.whl → 0.0.9__py3-none-any.whl

openai_sdk_helpers/__init__.py

@@ -2,15 +2,59 @@
 
 from __future__ import annotations
 
-from .structure import *
+from .async_utils import run_coroutine_thread_safe, run_coroutine_with_fallback
+from .context_manager import (
+    AsyncManagedResource,
+    ManagedResource,
+    async_context,
+    ensure_closed,
+    ensure_closed_async,
+)
+from .errors import (
+    OpenAISDKError,
+    ConfigurationError,
+    PromptNotFoundError,
+    AgentExecutionError,
+    VectorStorageError,
+    ToolExecutionError,
+    ResponseGenerationError,
+    InputValidationError,
+    AsyncExecutionError,
+    ResourceCleanupError,
+)
+from .logging_config import LoggerFactory
+from .retry import with_exponential_backoff
+from .validation import (
+    validate_choice,
+    validate_dict_mapping,
+    validate_list_items,
+    validate_max_length,
+    validate_non_empty_string,
+    validate_safe_path,
+    validate_url_format,
+)
+from .structure import (
+    BaseStructure,
+    SchemaOptions,
+    PlanStructure,
+    TaskStructure,
+    WebSearchStructure,
+    VectorSearchStructure,
+    PromptStructure,
+    spec_field,
+    SummaryStructure,
+    ExtendedSummaryStructure,
+    ValidationResultStructure,
+    AgentBlueprint,
+)
 from .prompt import PromptRenderer
 from .config import OpenAISettings
-from .vector_storage import *
+from .vector_storage import VectorStorage, VectorStorageFileInfo, VectorStorageFileStats
 from .agent import (
     AgentBase,
     AgentConfig,
     AgentEnum,
-    ProjectManager,
+    CoordinatorAgent,
     SummarizerAgent,
     TranslatorAgent,
     ValidatorAgent,
@@ -18,13 +62,47 @@ from .agent import (
     WebAgentSearch,
 )
 from .response import (
-    ResponseBase,
+    BaseResponse,
     ResponseMessage,
     ResponseMessages,
     ResponseToolCall,
+    attach_vector_store,
 )
 
 __all__ = [
+    # Async utilities
+    "run_coroutine_thread_safe",
+    "run_coroutine_with_fallback",
+    # Error classes
+    "OpenAISDKError",
+    "ConfigurationError",
+    "PromptNotFoundError",
+    "AgentExecutionError",
+    "VectorStorageError",
+    "ToolExecutionError",
+    "ResponseGenerationError",
+    "InputValidationError",
+    "AsyncExecutionError",
+    "ResourceCleanupError",
+    # Logging
+    "LoggerFactory",
+    # Retry utilities
+    "with_exponential_backoff",
+    # Context managers
+    "ManagedResource",
+    "AsyncManagedResource",
+    "ensure_closed",
+    "ensure_closed_async",
+    "async_context",
+    # Validation
+    "validate_non_empty_string",
+    "validate_max_length",
+    "validate_url_format",
+    "validate_dict_mapping",
+    "validate_list_items",
+    "validate_choice",
+    "validate_safe_path",
+    # Main structure classes
     "BaseStructure",
     "SchemaOptions",
     "spec_field",
@@ -33,10 +111,6 @@ __all__ = [
     "VectorStorage",
     "VectorStorageFileInfo",
     "VectorStorageFileStats",
-    "assistant_tool_definition",
-    "assistant_format",
-    "response_tool_definition",
-    "response_format",
     "SummaryStructure",
     "PromptStructure",
     "AgentBlueprint",
@@ -45,7 +119,7 @@ __all__ = [
     "AgentEnum",
     "AgentBase",
     "AgentConfig",
-    "ProjectManager",
+    "CoordinatorAgent",
     "SummarizerAgent",
     "TranslatorAgent",
     "ValidatorAgent",
@@ -55,8 +129,9 @@ __all__ = [
     "WebSearchStructure",
     "VectorSearchStructure",
     "ValidationResultStructure",
-    "ResponseBase",
+    "BaseResponse",
     "ResponseMessage",
     "ResponseMessages",
     "ResponseToolCall",
+    "attach_vector_store",
 ]

openai_sdk_helpers/agent/__init__.py

@@ -5,24 +5,28 @@ from __future__ import annotations
 from .base import AgentBase
 from .config import AgentConfig
 from ..structure.plan.enum import AgentEnum
-from .project_manager import ProjectManager
+from .coordination import CoordinatorAgent
 from .runner import run_sync, run_async, run_streamed
+from .search.base import SearchPlanner, SearchToolAgent, SearchWriter
 from .summarizer import SummarizerAgent
 from .translator import TranslatorAgent
 from .validation import ValidatorAgent
 from .utils import run_coroutine_agent_sync
-from .vector_search import VectorSearch
-from .web_search import WebAgentSearch
+from .search.vector import VectorSearch
+from .search.web import WebAgentSearch
 
 __all__ = [
     "AgentBase",
     "AgentConfig",
     "AgentEnum",
-    "ProjectManager",
+    "CoordinatorAgent",
     "run_sync",
     "run_async",
     "run_streamed",
     "run_coroutine_agent_sync",
+    "SearchPlanner",
+    "SearchToolAgent",
+    "SearchWriter",
     "SummarizerAgent",
     "TranslatorAgent",
     "ValidatorAgent",

openai_sdk_helpers/agent/base.py

@@ -2,16 +2,15 @@
 
 from __future__ import annotations
 
-import asyncio
-import threading
 from pathlib import Path
 from typing import Any, Dict, Optional, Protocol
 
-from agents import Agent, Runner, RunResult, RunResultStreaming
+from agents import Agent, RunResult, RunResultStreaming, Runner
 from agents.run_context import RunContextWrapper
 from agents.tool import FunctionTool
 from jinja2 import Template
-from .runner import run_sync, run_streamed, run_async
+
+from .runner import run_async, run_streamed, run_sync
 
 
 class AgentConfigLike(Protocol):
@@ -30,6 +29,41 @@ class AgentConfigLike(Protocol):
 class AgentBase:
     """Factory for creating and configuring specialized agents.
 
+    ``AgentBase`` provides the foundation for building OpenAI agents with support
+    for Jinja2 prompt templates, custom tools, and both synchronous and
+    asynchronous execution modes. All specialized agents in this package extend
+    this base class.
+
+    Examples
+    --------
+    Create a basic agent from configuration:
+
+    >>> from openai_sdk_helpers.agent import AgentBase, AgentConfig
+    >>> config = AgentConfig(
+    ...     name="my_agent",
+    ...     description="A custom agent",
+    ...     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:
+
+    >>> config = AgentConfig(
+    ...     name="my_agent",
+    ...     template_path="/absolute/path/to/template.jinja",
+    ...     model="gpt-4o-mini"
+    ... )
+    >>> agent = AgentBase(config=config, default_model="gpt-4o-mini")
+
+    Use async execution:
+
+    >>> import asyncio
+    >>> async def main():
+    ...     result = await agent.run_async("Explain quantum physics")
+    ...     return result
+    >>> asyncio.run(main())
+
     Methods
     -------
     from_config(config, run_context_wrapper)
@@ -59,23 +93,21 @@ class AgentBase:
         prompt_dir: Optional[Path] = None,
         default_model: Optional[str] = None,
     ) -> None:
-        """Initialize the ``AgentBase`` using a configuration object.
+        """Initialize the AgentBase using a configuration object.
 
         Parameters
         ----------
-        config
+        config : AgentConfigLike
             Configuration describing this agent.
-        run_context_wrapper
+        run_context_wrapper : RunContextWrapper or None, default=None
             Optional wrapper providing runtime context for prompt rendering.
-            Default ``None``.
-        prompt_dir
-            Optional directory holding prompt templates.
-        default_model
+        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.
-
-        Returns
-        -------
-        None
         """
         name = config.name
         description = config.description or ""
@@ -117,18 +149,21 @@ class AgentBase:
         run_context_wrapper: Optional[RunContextWrapper[Dict[str, Any]]] = None,
         prompt_dir: Optional[Path] = None,
         default_model: Optional[str] = None,
-    ) -> "AgentBase":
-        """Create a :class:`AgentBase` instance from configuration.
+    ) -> AgentBase:
+        """Create an AgentBase instance from configuration.
 
         Parameters
         ----------
-        config
+        config : AgentConfigLike
             Configuration describing the agent.
-        run_context_wrapper
-            Optional wrapper providing runtime context. Default ``None``.
-        prompt_dir
-            Optional directory holding prompt templates.
-        default_model
+        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
@@ -144,7 +179,7 @@ class AgentBase:
         )
 
     def _build_prompt_from_jinja(self) -> str:
-        """Return the rendered instructions prompt for this agent.
+        """Render the instructions prompt for this agent.
 
         Returns
         -------
@@ -162,9 +197,9 @@ class AgentBase:
 
         Parameters
         ----------
-        run_context_wrapper
+        run_context_wrapper : RunContextWrapper or None, default=None
             Wrapper whose ``context`` dictionary is used to render the Jinja
-            template. Default ``None``.
+            template.
 
         Returns
         -------
@@ -184,11 +219,11 @@ class AgentBase:
 
         Parameters
         ----------
-        run_context_wrapper
+        run_context_wrapper : RunContextWrapper
             Wrapper around the current run context whose ``context`` dictionary
             is used to render the Jinja template.
-        _
-            Underlying :class:`agents.Agent` instance (ignored).
+        _ : Agent
+            Underlying Agent instance (ignored).
 
         Returns
         -------
@@ -207,7 +242,7 @@ class AgentBase:
         """
         agent_config: Dict[str, Any] = {
             "name": self.agent_name,
-            "instructions": self._build_prompt_from_jinja(),
+            "instructions": self._build_prompt_from_jinja() or ".",
             "model": self.model,
         }
         if self._output_type:
@@ -229,12 +264,12 @@ class AgentBase:
 
         Parameters
         ----------
-        input
+        input : str
             Prompt or query for the agent.
-        context
-            Optional dictionary passed to the agent. Default ``None``.
-        output_type
-            Optional type used to cast the final output. Default ``None``.
+        context : dict or None, default=None
+            Optional dictionary passed to the agent.
+        output_type : type or None, default=None
+            Optional type used to cast the final output.
 
         Returns
         -------
@@ -260,12 +295,12 @@ class AgentBase:
 
         Parameters
         ----------
-        input
+        input : str
             Prompt or query for the agent.
-        context
-            Optional dictionary passed to the agent. Default ``None``.
-        output_type
-            Optional type used to cast the final output. Default ``None``.
+        context : dict or None, default=None
+            Optional dictionary passed to the agent.
+        output_type : type or None, default=None
+            Optional type used to cast the final output.
 
         Returns
         -------
@@ -285,16 +320,16 @@ class AgentBase:
         context: Optional[Dict[str, Any]] = None,
         output_type: Optional[Any] = None,
     ) -> RunResultStreaming:
-        """Return a streaming result for the agent execution.
+        """Stream the agent execution results.
 
         Parameters
         ----------
-        input
+        input : str
             Prompt or query for the agent.
-        context
-            Optional dictionary passed to the agent. Default ``None``.
-        output_type
-            Optional type used to cast the final output. Default ``None``.
+        context : dict or None, default=None
+            Optional dictionary passed to the agent.
+        output_type : type or None, default=None
+            Optional type used to cast the final output.
 
         Returns
         -------

openai_sdk_helpers/agent/config.py

@@ -11,12 +11,12 @@ from ..structure import BaseStructure
 
 
 class AgentConfig(BaseStructure):
-    """Configuration required to build a :class:`AgentBase`.
+    """Configuration required to build an AgentBase.
 
     Methods
     -------
     print()
-        Return a human readable representation of the configuration.
+        Return a human-readable representation of the configuration.
     """
 
     model_config = ConfigDict(arbitrary_types_allowed=True)
@@ -29,7 +29,9 @@ class AgentConfig(BaseStructure):
         default=None, title="Model", description="Model identifier to use"
     )
     template_path: Optional[str] = Field(
-        default=None, title="Template Path", description="Path to the Jinja template"
+        default=None,
+        title="Template Path",
+        description="Path to the Jinja template (absolute or relative to prompt_dir)",
     )
     input_type: Optional[Type[BaseModel]] = Field(
         default=None,
@@ -51,7 +53,7 @@ class AgentConfig(BaseStructure):
     )
 
     def print(self) -> str:
-        """Return a human readable representation.
+        """Return a human-readable representation.
 
         Returns
         -------

openai_sdk_helpers/agent/{project_manager.py → coordination.py}

@@ -24,7 +24,7 @@ ExecutePlanFn = Callable[[PlanStructure], List[str]]
 SummarizeFn = Callable[[List[str]], str]
 
 
-class ProjectManager(AgentBase, JSONSerializable):
+class CoordinatorAgent(AgentBase, JSONSerializable):
     """Coordinate agent plans while persisting project state and outputs.
 
     Methods
@@ -54,7 +54,7 @@ class ProjectManager(AgentBase, JSONSerializable):
         execute_plan_fn: ExecutePlanFn,
         summarize_fn: SummarizeFn,
         module_data_path: Path,
-        module_name: str,
+        name: str,
         config: Optional[AgentConfig] = None,
         prompt_dir: Optional[Path] = None,
         default_model: Optional[str] = None,
@@ -63,32 +63,28 @@ class ProjectManager(AgentBase, JSONSerializable):
 
         Parameters
         ----------
-        prompt_fn
+        prompt_fn : PromptFn
             Callable that generates a prompt brief from the input string.
-        build_plan_fn
+        build_plan_fn : BuildPlanFn
             Callable that generates a plan from the prompt brief.
-        execute_plan_fn
+        execute_plan_fn : ExecutePlanFn
             Callable that executes a plan and returns results.
-        summarize_fn
+        summarize_fn : SummarizeFn
             Callable that summarizes a list of result strings.
-        module_data_path
+        module_data_path : Path
             Base path for persisting project artifacts.
-        module_name
+        name : str
             Name of the parent module for data organization.
-        config
+        config : AgentConfig or None, default=None
             Optional agent configuration describing prompts and metadata.
-        prompt_dir
+        prompt_dir : Path or None, default=None
             Optional directory holding prompt templates.
-        default_model
+        default_model : str or None, default=None
             Optional fallback model identifier.
-
-        Returns
-        -------
-        None
         """
         if config is None:
             config = AgentConfig(
-                name="project_manager",
+                name="coordinator_agent",
                 description="Coordinates agents for planning and summarization.",
             )
         super().__init__(
@@ -99,7 +95,7 @@ class ProjectManager(AgentBase, JSONSerializable):
         self._execute_plan_fn = execute_plan_fn
         self._summarize_fn = summarize_fn
         self._module_data_path = Path(module_data_path)
-        self._module_name = module_name
+        self._name = name
 
         self.prompt: Optional[str] = None
         self.brief: Optional[PromptStructure] = None
@@ -109,16 +105,12 @@ class ProjectManager(AgentBase, JSONSerializable):
         self.end_date: Optional[datetime] = None
 
     def build_prompt(self, prompt: str) -> None:
-        """Return a concise brief for the project.
+        """Generate a concise brief for the project.
 
         Parameters
         ----------
         prompt : str
             The core request or goal for the project.
-
-        Returns
-        -------
-        None
         """
         log("build_prompt", level=logging.INFO)
         self.start_date = datetime.now(timezone.utc)
@@ -133,10 +125,6 @@ class ProjectManager(AgentBase, JSONSerializable):
         ------
         ValueError
             If called before :meth:`build_prompt`.
-
-        Returns
-        -------
-        None
         """
         log("build_plan", level=logging.INFO)
         if not self.brief:
@@ -148,7 +136,7 @@ class ProjectManager(AgentBase, JSONSerializable):
         self.save()
 
     def execute_plan(self) -> List[str]:
-        """Run each task, updating status, timestamps, and recorded results.
+        """Execute each task, updating status, timestamps, and recorded results.
 
         Returns
         -------
@@ -169,9 +157,9 @@ class ProjectManager(AgentBase, JSONSerializable):
 
         Parameters
         ----------
-        results : list[str], optional
-            List of string outputs gathered from task execution. Defaults to
-            ``None``, which uses the stored plan task results if available.
+        results : list[str] or None, default=None
+            List of string outputs gathered from task execution. When ``None``,
+            uses the stored plan task results if available.
 
         Returns
         -------
@@ -202,10 +190,6 @@ class ProjectManager(AgentBase, JSONSerializable):
         ----------
         prompt : str
             The request or question to analyze and summarize.
-
-        Returns
-        -------
-        None
         """
         self.build_prompt(prompt)
         self.build_plan()
@@ -224,7 +208,7 @@ class ProjectManager(AgentBase, JSONSerializable):
         if not self.start_date:
             self.start_date = datetime.now(timezone.utc)
         start_date_str = self.start_date.strftime(DATETIME_FMT)
-        return self._module_data_path / self._module_name / f"{start_date_str}.json"
+        return self._module_data_path / self._name / f"{start_date_str}.json"
 
     def save(self) -> Path:
         """Persist the current project state to disk.
@@ -259,7 +243,7 @@ class ProjectManager(AgentBase, JSONSerializable):
         Any
             Raw output from the underlying callable.
         """
-        task_type = ProjectManager._normalize_task_type(task.task_type)
+        task_type = CoordinatorAgent._normalize_task_type(task.task_type)
         prompt_with_context = task.prompt
         if aggregated_context and task_type not in {"WebAgentSearch", "VectorSearch"}:
             context_block = "\n".join(aggregated_context)
@@ -284,7 +268,7 @@ class ProjectManager(AgentBase, JSONSerializable):
                 level=logging.ERROR,
             )
             return f"Task error: {exc}"
-        return ProjectManager._resolve_result(output)
+        return CoordinatorAgent._resolve_result(output)
 
     @staticmethod
     def _run_task_in_thread(
@@ -312,7 +296,7 @@ class ProjectManager(AgentBase, JSONSerializable):
 
         def _runner() -> None:
             try:
-                result_container["result"] = ProjectManager._run_task(
+                result_container["result"] = CoordinatorAgent._run_task(
                     task,
                     agent_callable=agent_callable,
                     aggregated_context=aggregated_context,
@@ -363,14 +347,14 @@ class ProjectManager(AgentBase, JSONSerializable):
                         "await the task instead."
                     )
                 return asyncio.run_coroutine_threadsafe(
-                    ProjectManager._await_wrapper(result), owning_loop
+                    CoordinatorAgent._await_wrapper(result), owning_loop
                 ).result()
 
         awaitable: asyncio.Future[Any] | asyncio.Task[Any] | Any = result
         coroutine = (
             awaitable
             if inspect.iscoroutine(awaitable)
-            else ProjectManager._await_wrapper(awaitable)
+            else CoordinatorAgent._await_wrapper(awaitable)
         )
 
         try:
@@ -394,7 +378,7 @@ class ProjectManager(AgentBase, JSONSerializable):
 
     @staticmethod
     async def _await_wrapper(awaitable: Any) -> Any:
-        """Await a generic awaitable and return its result.
+        """Resolve an awaitable and return its result.
 
         Parameters
         ----------
@@ -459,8 +443,8 @@ class ProjectManager(AgentBase, JSONSerializable):
             timestamp = datetime.now(timezone.utc).strftime("%Y%m%d_%H%M%S")
             self._run_directory = (
                 self._module_data_path
-                / Path(self._module_name)
-                / "project_manager"
+                / Path(self._name)
+                / "coordinator_agent"
                 / timestamp
             )
         self._run_directory.mkdir(parents=True, exist_ok=True)
@@ -480,7 +464,7 @@ class ProjectManager(AgentBase, JSONSerializable):
         str
             Lowercase label safe for filesystem usage.
         """
-        task_type = ProjectManager._normalize_task_type(task.task_type)
+        task_type = CoordinatorAgent._normalize_task_type(task.task_type)
         base = (task_type or "task").replace(" ", "_").lower()
         return f"{base}_{task_type}"
 
@@ -508,4 +492,4 @@ class ProjectManager(AgentBase, JSONSerializable):
             return str(task_type)
 
 
-__all__ = ["ProjectManager"]
+__all__ = ["CoordinatorAgent"]

openai_sdk_helpers/agent/prompt_utils.py

@@ -1,4 +1,10 @@
-"""Shared helpers for locating bundled prompt templates."""
+"""Shared helpers for locating bundled prompt templates.
+
+Attributes
+----------
+DEFAULT_PROMPT_DIR : Path
+    Default directory containing bundled prompt templates.
+"""
 
 from __future__ import annotations