openai-sdk-helpers 0.4.0__tar.gz → 0.4.1__tar.gz

{openai_sdk_helpers-0.4.0 → openai_sdk_helpers-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openai-sdk-helpers
-Version: 0.4.0
+Version: 0.4.1
 Summary: Composable helpers for OpenAI SDK agents, prompts, and storage
 Author: openai-sdk-helpers maintainers
 License: MIT

{openai_sdk_helpers-0.4.0 → openai_sdk_helpers-0.4.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "openai-sdk-helpers"
-version = "0.4.0"
+version = "0.4.1"
 requires-python = ">=3.10"
 readme = "README.md"
 description = "Composable helpers for OpenAI SDK agents, prompts, and storage"

{openai_sdk_helpers-0.4.0 → openai_sdk_helpers-0.4.1}/src/openai_sdk_helpers/agent/__init__.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from .base import AgentBase
-from .config import AgentConfiguration, AgentConfigurationRegistry, get_default_registry
+from .config import AgentConfiguration, AgentRegistry, get_default_registry
 from ..structure.plan.enum import AgentEnum
 from .coordination import CoordinatorAgent
 from .runner import run_sync, run_async, run_streamed
@@ -18,7 +18,7 @@ from .search.web import WebAgentSearch
 __all__ = [
     "AgentBase",
     "AgentConfiguration",
-    "AgentConfigurationRegistry",
+    "AgentRegistry",
     "get_default_registry",
     "AgentEnum",
     "CoordinatorAgent",

{openai_sdk_helpers-0.4.0 → openai_sdk_helpers-0.4.1}/src/openai_sdk_helpers/agent/base.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from pathlib import Path
-from typing import Any, Dict, Optional, Protocol, cast
+from typing import Any, Callable, Dict, Optional, Protocol, cast
 import uuid
 
 from agents import (
@@ -30,7 +30,7 @@ from ..utils import (
 from .runner import run_async, run_streamed, run_sync
 
 
-class AgentConfigurationLike(Protocol):
+class AgentConfigurationProtocol(Protocol):
     """Protocol describing the configuration attributes for AgentBase."""
 
     @property
@@ -188,7 +188,7 @@ class AgentBase(DataclassJSONSerializable):
     def __init__(
         self,
         *,
-        config: AgentConfigurationLike,
+        config: AgentConfigurationProtocol,
         run_context_wrapper: Optional[RunContextWrapper[Dict[str, Any]]] = None,
         data_path: Path | str | None = None,
         prompt_dir: Optional[Path] = None,
@@ -198,7 +198,7 @@ class AgentBase(DataclassJSONSerializable):
 
         Parameters
         ----------
-        config : AgentConfigurationLike
+        config : AgentConfigurationProtocol
             Configuration describing this agent.
         run_context_wrapper : RunContextWrapper or None, default=None
             Optional wrapper providing runtime context for prompt rendering.
@@ -428,7 +428,7 @@ class AgentBase(DataclassJSONSerializable):
             "model": self.model,
         }
         if self._output_structure:
-            agent_config["output_structure"] = self._output_structure
+            agent_config["output_type"] = self._output_structure
         if self._tools:
             agent_config["tools"] = self._tools
         if self._model_settings:
@@ -575,6 +575,26 @@ class AgentBase(DataclassJSONSerializable):
         )
         return tool_obj
 
+    def as_response_tool(self) -> tuple[dict[str, Callable[..., Any]], dict[str, Any]]:
+        """Return the agent as a callable response tool.
+
+        Returns
+        -------
+        Tool
+            Tool instance wrapping this agent for response generation.
+        """
+        tool_handler = {self.name: self.run_sync}
+        tool_definition = {
+            "type": "function",
+            "name": self.name,
+            "description": self.description,
+            "strict": True,
+            "additionalProperties": False,
+        }
+        if self.output_structure:
+            tool_definition["parameters"] = self.output_structure.get_schema()
+        return tool_handler, tool_definition
+
     def __enter__(self) -> AgentBase:
         """Enter the context manager for resource management.
 
@@ -651,4 +671,4 @@ class AgentBase(DataclassJSONSerializable):
         log(f"Saved messages to {target}")
 
 
-__all__ = ["AgentConfigurationLike", "AgentBase"]
+__all__ = ["AgentConfigurationProtocol", "AgentBase"]

{openai_sdk_helpers-0.4.0 → openai_sdk_helpers-0.4.1}/src/openai_sdk_helpers/agent/config.py

@@ -10,20 +10,20 @@ from agents import Agent, Handoff, InputGuardrail, OutputGuardrail, Session
 from agents.model_settings import ModelSettings
 
 from ..utils.json.data_class import DataclassJSONSerializable
-from ..utils.registry import BaseRegistry
+from ..utils.registry import RegistryBase
 from ..utils.instructions import resolve_instructions_from_path
 from ..structure.base import StructureBase
 
 
-class AgentConfigurationRegistry(BaseRegistry["AgentConfiguration"]):
+class AgentRegistry(RegistryBase["AgentConfiguration"]):
     """Registry for managing AgentConfiguration instances.
 
-    Inherits from BaseRegistry to provide centralized storage and retrieval
+    Inherits from RegistryBase to provide centralized storage and retrieval
     of agent configurations, enabling reusable agent specs across the application.
 
     Examples
     --------
-    >>> registry = AgentConfigurationRegistry()
+    >>> registry = AgentRegistry()
     >>> config = AgentConfiguration(
     ...     name="test_agent",
     ...     model="gpt-4o-mini",
@@ -65,7 +65,7 @@ class AgentConfigurationRegistry(BaseRegistry["AgentConfiguration"]):
 
         Examples
         --------
-        >>> registry = AgentConfigurationRegistry()
+        >>> registry = AgentRegistry()
         >>> count = registry.load_from_directory("./agents")
         >>> print(f"Loaded {count} configurations")
         """
@@ -74,12 +74,12 @@ class AgentConfigurationRegistry(BaseRegistry["AgentConfiguration"]):
         return super().load_from_directory(path, config_class=config_class)
 
 
-def get_default_registry() -> AgentConfigurationRegistry:
+def get_default_registry() -> AgentRegistry:
     """Return the global default registry instance.
 
     Returns
     -------
-    AgentConfigurationRegistry
+    AgentRegistry
         Singleton registry for application-wide configuration storage.
 
     Examples
@@ -424,6 +424,6 @@ class AgentConfiguration(DataclassJSONSerializable):
 
 
 # Global default registry instance
-_default_registry = AgentConfigurationRegistry()
+_default_registry = AgentRegistry()
 
-__all__ = ["AgentConfiguration", "AgentConfigurationRegistry", "get_default_registry"]
+__all__ = ["AgentConfiguration", "AgentRegistry", "get_default_registry"]

{openai_sdk_helpers-0.4.0 → openai_sdk_helpers-0.4.1}/src/openai_sdk_helpers/response/config.py

@@ -10,17 +10,17 @@ from ..config import OpenAISettings
 from ..structure.base import StructureBase
 from ..response.base import ResponseBase, ToolHandler
 from ..utils.json.data_class import DataclassJSONSerializable
-from ..utils.registry import BaseRegistry
+from ..utils.registry import RegistryBase
 from ..utils.instructions import resolve_instructions_from_path
 
 TIn = TypeVar("TIn", bound="StructureBase")
 TOut = TypeVar("TOut", bound="StructureBase")
 
 
-class ResponseRegistry(BaseRegistry["ResponseConfiguration"]):
+class ResponseRegistry(RegistryBase["ResponseConfiguration"]):
     """Registry for managing ResponseConfiguration instances.
 
-    Inherits from BaseRegistry to provide centralized storage and retrieval
+    Inherits from RegistryBase to provide centralized storage and retrieval
     of response configurations, enabling reusable response specs across the application.
 
     Examples
@@ -108,8 +108,6 @@ class ResponseConfiguration(DataclassJSONSerializable, Generic[TIn, TOut]):
     -------
     __post_init__()
         Validate configuration invariants and enforce StructureBase subclassing.
-    instructions_text
-        Return the resolved instruction content as a string.
     to_json()
         Return a JSON-compatible dict representation (inherited from JSONSerializable).
     to_json_file(filepath)
@@ -138,6 +136,7 @@ class ResponseConfiguration(DataclassJSONSerializable, Generic[TIn, TOut]):
     output_structure: Optional[Type[TOut]]
     system_vector_store: Optional[list[str]] = None
     add_output_instructions: bool = True
+    add_web_search_tool: bool = False
 
     def __post_init__(self) -> None:
         """
@@ -185,7 +184,7 @@ class ResponseConfiguration(DataclassJSONSerializable, Generic[TIn, TOut]):
             raise TypeError("Configuration.tools must be a Sequence or None")
 
     @property
-    def instructions_text(self) -> str:
+    def get_resolved_instructions(self) -> str:
         """Return the resolved instruction text.
 
         Returns
@@ -204,6 +203,20 @@ class ResponseConfiguration(DataclassJSONSerializable, Generic[TIn, TOut]):
 
         return resolved_instructions
 
+    @property
+    def get_resolved_tools(self) -> list:
+        """Return the complete list of tools, including optional web search tool.
+
+        Returns
+        -------
+        list
+            List of tool definitions, including web search tool if enabled.
+        """
+        tools = self.tools or []
+        if self.add_web_search_tool:
+            tools = tools + [{"type": "web_search"}]
+        return tools
+
     def gen_response(
         self,
         *,
@@ -229,8 +242,8 @@ class ResponseConfiguration(DataclassJSONSerializable, Generic[TIn, TOut]):
         """
         return ResponseBase[TOut](
             name=self.name,
-            instructions=self.instructions_text,
-            tools=self.tools,
+            instructions=self.get_resolved_instructions,
+            tools=self.get_resolved_tools,
             output_structure=self.output_structure,
             system_vector_store=self.system_vector_store,
             data_path=data_path,

{openai_sdk_helpers-0.4.0 → openai_sdk_helpers-0.4.1}/src/openai_sdk_helpers/streamlit_app/__init__.py

@@ -8,23 +8,23 @@ Classes
 -------
 StreamlitAppConfig
     Validated configuration for Streamlit chat applications.
+StreamlitAppRegistry
+    Registry for storing Streamlit app configurations.
 
 Functions
 ---------
-load_app_config
-    Load and validate configuration from a Python module.
 _load_configuration
     Load configuration with user-friendly error handling for Streamlit UI.
 """
 
 from .config import (
     StreamlitAppConfig,
+    StreamlitAppRegistry,
     _load_configuration,
-    load_app_config,
 )
 
 __all__ = [
     "StreamlitAppConfig",
+    "StreamlitAppRegistry",
     "_load_configuration",
-    "load_app_config",
 ]

{openai_sdk_helpers-0.4.0 → openai_sdk_helpers-0.4.1}/src/openai_sdk_helpers/streamlit_app/config.py

@@ -15,7 +15,7 @@ from pydantic import ConfigDict, Field, field_validator, model_validator
 
 from openai_sdk_helpers.response.base import ResponseBase
 from openai_sdk_helpers.structure.base import StructureBase
-from openai_sdk_helpers.utils import ensure_list
+from openai_sdk_helpers.utils import RegistryBase, ensure_list
 from ..utils.json import BaseModelJSONSerializable
 
 
@@ -29,6 +29,8 @@ class StreamlitAppConfig(BaseModelJSONSerializable):
 
     Attributes
     ----------
+    name : str
+        Unique configuration identifier. Default is ``"streamlit_app"``.
     response : ResponseBase, type[ResponseBase], Callable, or None
         Response handler as an instance, class, or callable factory.
     display_title : str
@@ -48,8 +50,6 @@ class StreamlitAppConfig(BaseModelJSONSerializable):
         Return configured system vector stores as a list.
     create_response()
         Instantiate and return the configured ResponseBase.
-    load_app_config(config_path)
-        Load, validate, and return configuration from a Python module.
 
     Examples
     --------
@@ -63,6 +63,10 @@ class StreamlitAppConfig(BaseModelJSONSerializable):
 
     model_config = ConfigDict(extra="forbid", arbitrary_types_allowed=True)
 
+    name: str = Field(
+        default="streamlit_app",
+        description="Unique configuration identifier used for registry lookup.",
+    )
     response: ResponseBase[StructureBase] | type[ResponseBase] | Callable | None = (
         Field(
             default=None,
@@ -225,6 +229,39 @@ class StreamlitAppConfig(BaseModelJSONSerializable):
         """
         return _instantiate_response(self.response)
 
+
+class StreamlitAppRegistry(RegistryBase[StreamlitAppConfig]):
+    """Registry for managing StreamlitAppConfig instances.
+
+    Inherits from RegistryBase to provide centralized storage and retrieval
+    of Streamlit app configurations, enabling reuse across applications.
+
+    Methods
+    -------
+    register(config)
+        Add a configuration to the registry.
+    get(name)
+        Retrieve a configuration by name.
+    list_names()
+        Return all registered configuration names.
+    clear()
+        Remove all registered configurations.
+    save_to_directory(path)
+        Export all registered configurations to JSON files.
+    load_from_directory(path)
+        Load configurations from JSON files in a directory.
+    load_app_config(config_path)
+        Load, validate, and return configuration from a Python module.
+
+    Examples
+    --------
+    >>> registry = StreamlitAppRegistry()
+    >>> config = StreamlitAppConfig(response=MyResponse)
+    >>> registry.register(config)
+    >>> registry.get(config.name)
+    StreamlitAppConfig(...)
+    """
+
     @staticmethod
     def load_app_config(
         config_path: Path,
@@ -258,7 +295,7 @@ class StreamlitAppConfig(BaseModelJSONSerializable):
         Examples
         --------
         >>> from pathlib import Path
-        >>> config = StreamlitAppConfig.load_app_config(
+        >>> config = StreamlitAppRegistry.load_app_config(
         ...     Path("./my_config.py")
         ... )
         """
@@ -433,36 +470,10 @@ def _config_from_mapping(raw_config: dict) -> StreamlitAppConfig:
     return StreamlitAppConfig(**config_kwargs)
 
 
-def load_app_config(
-    config_path: Path,
-) -> StreamlitAppConfig:
-    """Load and validate Streamlit configuration from a Python module.
-
-    Convenience function that proxies to StreamlitAppConfig.load_app_config
-    for backward compatibility.
-
-    Parameters
-    ----------
-    config_path : Path
-        Filesystem path to the configuration module.
-
-    Returns
-    -------
-    StreamlitAppConfig
-        Validated configuration loaded from the module.
-
-    Examples
-    --------
-    >>> from pathlib import Path
-    >>> config = load_app_config(Path("./my_config.py"))
-    """
-    return StreamlitAppConfig.load_app_config(config_path=config_path)
-
-
 def _load_configuration(config_path: Path) -> StreamlitAppConfig:
     """Load configuration with user-friendly error handling for Streamlit.
 
-    Wraps StreamlitAppConfig.load_app_config with exception handling that
+    Wraps StreamlitAppRegistry.load_app_config with exception handling that
     displays errors in the Streamlit UI and halts execution gracefully.
 
     Parameters
@@ -487,7 +498,7 @@ def _load_configuration(config_path: Path) -> StreamlitAppConfig:
     than raising exceptions that crash the app.
     """
     try:
-        return StreamlitAppConfig.load_app_config(config_path=config_path)
+        return StreamlitAppRegistry.load_app_config(config_path=config_path)
     except Exception as exc:  # pragma: no cover - surfaced in UI
         import streamlit as st  # type: ignore[import-not-found]
 
@@ -498,6 +509,6 @@ def _load_configuration(config_path: Path) -> StreamlitAppConfig:
 
 __all__ = [
     "StreamlitAppConfig",
-    "load_app_config",
+    "StreamlitAppRegistry",
     "_load_configuration",
 ]

{openai_sdk_helpers-0.4.0 → openai_sdk_helpers-0.4.1}/src/openai_sdk_helpers/utils/__init__.py

@@ -55,7 +55,7 @@ from .json import (
     get_module_qualname,
     to_jsonable,
 )
-from .registry import BaseRegistry
+from .registry import RegistryBase
 
 from .path_utils import check_filepath, ensure_directory
 from openai_sdk_helpers.logging_config import log
@@ -135,5 +135,5 @@ __all__ = [
     "create_file_data_url",
     "is_image_file",
     # Registry
-    "BaseRegistry",
+    "RegistryBase",
 ]

{openai_sdk_helpers-0.4.0 → openai_sdk_helpers-0.4.1}/src/openai_sdk_helpers/utils/registry.py

@@ -4,15 +4,42 @@ from __future__ import annotations
 
 import warnings
 from pathlib import Path
-from typing import Generic, TypeVar
+from typing import Generic, Protocol, TypeVar
+from typing_extensions import Self
 
-from ..utils.json.data_class import DataclassJSONSerializable
 from .path_utils import ensure_directory
 
-T = TypeVar("T", bound=DataclassJSONSerializable)
 
+class RegistrySerializable(Protocol):
+    """Protocol describing serializable registry entries.
 
-class BaseRegistry(Generic[T]):
+    Methods
+    -------
+    to_json_file(filepath)
+        Write the instance to a JSON file path.
+    from_json_file(filepath)
+        Load an instance from a JSON file path.
+    """
+
+    @property
+    def name(self) -> str:
+        """Return the configuration name."""
+        ...
+
+    def to_json_file(self, filepath: Path | str) -> str:
+        """Write serialized JSON data to a file path."""
+        ...
+
+    @classmethod
+    def from_json_file(cls, filepath: Path | str) -> Self:
+        """Load an instance from a JSON file."""
+        ...
+
+
+T = TypeVar("T", bound=RegistrySerializable)
+
+
+class RegistryBase(Generic[T]):
     """Base registry for managing configuration instances.
 
     Provides centralized storage and retrieval of configurations,