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

openai_sdk_helpers/__init__.py

@@ -2,15 +2,9 @@
 
 from __future__ import annotations
 
-from .environment import get_data_path, get_model
+from .environment import get_data_path
 from .utils.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,
@@ -23,7 +17,7 @@ from .errors import (
     AsyncExecutionError,
     ResourceCleanupError,
 )
-from .retry import with_exponential_backoff
+
 from .utils.validation import (
     validate_choice,
     validate_dict_mapping,
@@ -51,7 +45,7 @@ from .structure import (
     execute_plan,
 )
 from .prompt import PromptRenderer
-from .config import OpenAISettings
+from .settings import OpenAISettings
 from .files_api import FilesAPIManager, FilePurpose
 from .vector_storage import VectorStorage, VectorStorageFileInfo, VectorStorageFileStats
 from .agent import (
@@ -83,12 +77,7 @@ from .tools import (
     ToolSpec,
     build_tool_definitions,
 )
-from .config import build_openai_settings
-from .utils.deprecation import (
-    deprecated,
-    warn_deprecated,
-    DeprecationHelper,
-)
+from .settings import build_openai_settings
 from .utils.output_validation import (
     ValidationResult,
     ValidationRule,
@@ -98,15 +87,11 @@ from .utils.output_validation import (
     OutputValidator,
     validate_output,
 )
-from .types import (
-    SupportsOpenAIClient,
-    OpenAIClient,
-)
+
 
 __all__ = [
     # Environment utilities
     "get_data_path",
-    "get_model",
     # Async utilities
     "run_coroutine_thread_safe",
     "run_coroutine_with_fallback",
@@ -121,14 +106,6 @@ __all__ = [
     "InputValidationError",
     "AsyncExecutionError",
     "ResourceCleanupError",
-    # Retry utilities
-    "with_exponential_backoff",
-    # Context managers
-    "ManagedResource",
-    "AsyncManagedResource",
-    "ensure_closed",
-    "ensure_closed_async",
-    "async_context",
     # Validation
     "validate_non_empty_string",
     "validate_max_length",
@@ -184,13 +161,6 @@ __all__ = [
     "create_plan",
     "execute_task",
     "execute_plan",
-    # Type definitions
-    "SupportsOpenAIClient",
-    "OpenAIClient",
-    # Deprecation utilities
-    "deprecated",
-    "warn_deprecated",
-    "DeprecationHelper",
     # Output validation
     "ValidationResult",
     "ValidationRule",

openai_sdk_helpers/agent/__init__.py

@@ -1,16 +1,15 @@
 """Shared agent helpers built on the OpenAI Agents SDK."""
 
 from __future__ import annotations
-
 from .base import AgentBase
-from .config import AgentConfiguration, AgentRegistry, get_default_registry
+from .configuration import AgentConfiguration, AgentRegistry, get_default_registry
 from ..structure.plan.enum import AgentEnum
-from .coordination import CoordinatorAgent
+from .coordinator 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 .validator import ValidatorAgent
 from .utils import run_coroutine_agent_sync
 from .search.vector import VectorAgentSearch
 from .search.web import WebAgentSearch

openai_sdk_helpers/agent/base.py

@@ -24,6 +24,7 @@ from ..utils.json.data_class import DataclassJSONSerializable
 from ..structure.base import StructureBase
 from ..structure.prompt import PromptStructure
 
+
 from ..utils import (
     check_filepath,
     log,
@@ -34,7 +35,7 @@ from ..tools import tool_handler_factory
 from .runner import run_async, run_streamed, run_sync
 
 if TYPE_CHECKING:
-    from ..config import OpenAISettings
+    from ..settings import OpenAISettings
     from ..response.base import ResponseBase, ToolHandler
 
 
@@ -130,22 +131,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, default_model="gpt-4o-mini")
     >>> 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, default_model="gpt-4o-mini")
 
     Use async execution:
 
@@ -200,7 +201,7 @@ 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,
@@ -210,29 +211,29 @@ class AgentBase(DataclassJSONSerializable):
 
         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
+            ``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 config does not supply one.
+            Optional fallback model identifier if the configuration does not supply one.
         """
-        name = config.name
-        description = config.description or ""
-        model = config.model or default_model
+        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 = config.resolve_prompt_path(prompt_dir)
+        prompt_path = configuration.resolve_prompt_path(prompt_dir)
 
         # Build template from file or fall back to instructions
         if prompt_path is None:
-            instructions_text = config.instructions_text
+            instructions_text = configuration.instructions_text
             self._template = Template(instructions_text)
             self._instructions = instructions_text
         elif prompt_path.exists():
@@ -261,14 +262,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:
@@ -474,7 +477,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 +486,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 +516,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 +525,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(),
@@ -552,14 +555,14 @@ 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
         -------
         RunResultStreaming
             Streaming output wrapper from the agent execution.
         """
-        # 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
         output_structure_to_use = output_structure or self._output_structure
         result = run_streamed(
@@ -682,7 +685,7 @@ class AgentBase(DataclassJSONSerializable):
         >>> response = agent.build_response(openai_settings=OpenAISettings.from_env())
         """
         from ..response.base import ResponseBase, ToolHandler
-        from ..config import OpenAISettings
+        from ..settings import OpenAISettings
 
         if not isinstance(openai_settings, OpenAISettings):
             raise TypeError("openai_settings must be an OpenAISettings instance")
@@ -770,7 +773,7 @@ class AgentBase(DataclassJSONSerializable):
 
         Examples
         --------
-        >>> agent = AgentBase(config, default_model="gpt-4o-mini")
+        >>> agent = AgentBase(configuration, default_model="gpt-4o-mini")
         >>> try:
         ...     result = agent.run_sync("query")
         ... finally:

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
 
@@ -165,12 +165,12 @@ class AgentConfiguration(DataclassJSONSerializable):
 
     Examples
     --------
-    >>> config = AgentConfiguration(
+    >>> configuration = AgentConfiguration(
     ...     name="summarizer",
     ...     description="Summarizes text",
     ...     model="gpt-4o-mini"
     ... )
-    >>> config.name
+    >>> configuration.name
     'summarizer'
     """
 
@@ -308,7 +308,7 @@ class AgentConfiguration(DataclassJSONSerializable):
         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.
+            Optional fallback model identifier if configuration doesn't specify one.
 
         Returns
         -------
@@ -317,17 +317,17 @@ 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,
@@ -352,10 +352,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 +387,7 @@ class AgentConfiguration(DataclassJSONSerializable):
         >>> response_config.name
         'responder'
         """
-        from ..response.config import ResponseConfiguration
+        from ..response.configuration import ResponseConfiguration
 
         return ResponseConfiguration(
             name=self.name,

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

@@ -11,11 +11,11 @@ from pathlib import Path
 from typing import Any, Callable, Dict, List, Optional
 
 
-from ..structure import TaskStructure, PlanStructure, PromptStructure
-from ..utils import DataclassJSONSerializable, ensure_directory, log
+from ..structure import TaskStructure, PlanStructure, PromptStructure, AgentEnum
+from ..utils import ensure_directory, log
 from .base import AgentBase
-from .config import AgentConfiguration
-from ..structure.plan.enum import AgentEnum
+from .configuration import AgentConfiguration
+
 
 PromptFn = Callable[[str], PromptStructure]
 BuildPlanFn = Callable[[str], PlanStructure]
@@ -40,7 +40,7 @@ class CoordinatorAgent(AgentBase):
         Base path for persisting project artifacts.
     name : str
         Name of the parent module for data organization.
-    config : AgentConfiguration or None, default=None
+    configuration : AgentConfiguration or None, default=None
         Optional agent configuration describing prompts and metadata.
     prompt_dir : Path or None, default=None
         Optional directory holding prompt templates.
@@ -84,7 +84,7 @@ class CoordinatorAgent(AgentBase):
         summarize_fn: SummarizeFn,
         module_data_path: Path,
         name: str,
-        config: Optional[AgentConfiguration] = None,
+        configuration: Optional[AgentConfiguration] = None,
         prompt_dir: Optional[Path] = None,
         default_model: Optional[str] = None,
     ) -> None:
@@ -104,7 +104,7 @@ class CoordinatorAgent(AgentBase):
             Base path for persisting project artifacts.
         name : str
             Name of the parent module for data organization.
-        config : AgentConfiguration or None, default=None
+        configuration : AgentConfiguration or None, default=None
             Optional agent configuration describing prompts and metadata.
         prompt_dir : Path or None, default=None
             Optional directory holding prompt templates.
@@ -127,14 +127,16 @@ class CoordinatorAgent(AgentBase):
         ...     name="test",
         ... )
         """
-        if config is None:
-            config = AgentConfiguration(
+        if configuration is None:
+            configuration = AgentConfiguration(
                 name="coordinator_agent",
                 instructions="Coordinate agents for planning and summarization.",
                 description="Coordinates agents for planning and summarization.",
             )
         super().__init__(
-            config=config, prompt_dir=prompt_dir, default_model=default_model
+            configuration=configuration,
+            prompt_dir=prompt_dir,
+            default_model=default_model,
         )
         self._prompt_fn = prompt_fn
         self._build_plan_fn = build_plan_fn

openai_sdk_helpers/agent/search/base.py

@@ -13,7 +13,7 @@ from pathlib import Path
 from typing import Generic, List, Optional, TypeVar, Union
 
 from ..base import AgentBase
-from ..config import AgentConfiguration
+from ..configuration import AgentConfiguration
 from ...structure.base import StructureBase
 
 # Type variables for search workflow components
@@ -36,7 +36,7 @@ class SearchPlanner(AgentBase, Generic[PlanType]):
     prompt_dir : Path, optional
         Directory containing prompt templates.
     default_model : str, optional
-        Default model identifier to use when not defined in config.
+        Default model identifier to use when not defined in configuration.
 
     Methods
     -------
@@ -68,9 +68,9 @@ class SearchPlanner(AgentBase, Generic[PlanType]):
         default_model: Optional[str] = None,
     ) -> None:
         """Initialize the planner agent."""
-        config = self._configure_agent()
+        configuration = self._configure_agent()
         super().__init__(
-            config=config,
+            configuration=configuration,
             prompt_dir=prompt_dir,
             default_model=default_model,
         )
@@ -86,12 +86,12 @@ class SearchPlanner(AgentBase, Generic[PlanType]):
 
         Examples
         --------
-        >>> config = AgentConfiguration(
+        >>> configuration = AgentConfiguration(
         ...     name="web_planner",
         ...     description="Plan web searches",
         ...     output_structure=WebSearchPlanStructure,
         ... )
-        >>> return config
+        >>> return configuration
         """
         pass
 
@@ -127,7 +127,7 @@ class SearchToolAgent(AgentBase, Generic[ItemType, ResultType, PlanType]):
     prompt_dir : Path, optional
         Directory containing prompt templates.
     default_model : str, optional
-        Default model identifier to use when not defined in config.
+        Default model identifier to use when not defined in configuration.
     max_concurrent_searches : int, default=10
         Maximum number of concurrent search operations.
 
@@ -168,9 +168,9 @@ class SearchToolAgent(AgentBase, Generic[ItemType, ResultType, PlanType]):
     ) -> None:
         """Initialize the search tool agent."""
         self._max_concurrent_searches = max_concurrent_searches
-        config = self._configure_agent()
+        configuration = self._configure_agent()
         super().__init__(
-            config=config,
+            configuration=configuration,
             prompt_dir=prompt_dir,
             default_model=default_model,
         )
@@ -186,13 +186,13 @@ class SearchToolAgent(AgentBase, Generic[ItemType, ResultType, PlanType]):
 
         Examples
         --------
-        >>> config = AgentConfiguration(
+        >>> configuration = AgentConfiguration(
         ...     name="web_search",
         ...     description="Perform web searches",
         ...     input_structure=WebSearchPlanStructure,
         ...     tools=[WebSearchTool()],
         ... )
-        >>> return config
+        >>> return configuration
         """
         pass
 
@@ -250,7 +250,7 @@ class SearchWriter(AgentBase, Generic[ReportType]):
     prompt_dir : Path, optional
         Directory containing prompt templates.
     default_model : str, optional
-        Default model identifier to use when not defined in config.
+        Default model identifier to use when not defined in configuration.
 
     Methods
     -------
@@ -282,9 +282,9 @@ class SearchWriter(AgentBase, Generic[ReportType]):
         default_model: Optional[str] = None,
     ) -> None:
         """Initialize the writer agent."""
-        config = self._configure_agent()
+        configuration = self._configure_agent()
         super().__init__(
-            config=config,
+            configuration=configuration,
             prompt_dir=prompt_dir,
             default_model=default_model,
         )
@@ -300,12 +300,12 @@ class SearchWriter(AgentBase, Generic[ReportType]):
 
         Examples
         --------
-        >>> config = AgentConfiguration(
+        >>> configuration = AgentConfiguration(
         ...     name="web_writer",
         ...     description="Write web search report",
         ...     output_structure=WebSearchReportStructure,
         ... )
-        >>> return config
+        >>> return configuration
         """
         pass