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

openai_sdk_helpers/streamlit_app/config.py

@@ -11,14 +11,15 @@ import importlib.util
 from pathlib import Path
 from types import ModuleType
 from typing import Callable, Sequence, cast
-from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+from pydantic import ConfigDict, Field, field_validator, model_validator
 
-from openai_sdk_helpers.response.base import BaseResponse
-from openai_sdk_helpers.structure.base import BaseStructure
-from openai_sdk_helpers.utils import ensure_list
+from openai_sdk_helpers.response.base import ResponseBase
+from openai_sdk_helpers.structure.base import StructureBase
+from openai_sdk_helpers.utils import RegistryBase, ensure_list
+from ..utils.json import BaseModelJSONSerializable
 
 
-class StreamlitAppConfig(BaseModel):
+class StreamlitAppConfig(BaseModelJSONSerializable):
     """Validated configuration for Streamlit chat applications.
 
     Manages all settings required to run a configuration-driven Streamlit
@@ -28,7 +29,9 @@ class StreamlitAppConfig(BaseModel):
 
     Attributes
     ----------
-    response : BaseResponse, type[BaseResponse], Callable, or None
+    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
         Title displayed at the top of the Streamlit page.
@@ -46,9 +49,7 @@ class StreamlitAppConfig(BaseModel):
     normalized_vector_stores()
         Return configured system vector stores as a list.
     create_response()
-        Instantiate and return the configured BaseResponse.
-    load_app_config(config_path)
-        Load, validate, and return configuration from a Python module.
+        Instantiate and return the configured ResponseBase.
 
     Examples
     --------
@@ -62,11 +63,15 @@ class StreamlitAppConfig(BaseModel):
 
     model_config = ConfigDict(extra="forbid", arbitrary_types_allowed=True)
 
-    response: BaseResponse[BaseStructure] | type[BaseResponse] | Callable | None = (
+    name: str = Field(
+        default="streamlit_app",
+        description="Unique configuration identifier used for registry lookup.",
+    )
+    response: ResponseBase[StructureBase] | type[ResponseBase] | Callable | None = (
         Field(
             default=None,
             description=(
-                "Configured ``BaseResponse`` subclass, instance, or callable that returns"
+                "Configured ``ResponseBase`` subclass, instance, or callable that returns"
                 " a response instance."
             ),
         )
@@ -130,37 +135,37 @@ class StreamlitAppConfig(BaseModel):
     @field_validator("response")
     @classmethod
     def validate_response(
-        cls, value: BaseResponse[BaseStructure] | type[BaseResponse] | Callable | None
-    ) -> BaseResponse[BaseStructure] | type[BaseResponse] | Callable | None:
+        cls, value: ResponseBase[StructureBase] | type[ResponseBase] | Callable | None
+    ) -> ResponseBase[StructureBase] | type[ResponseBase] | Callable | None:
         """Validate that the response field is a valid handler source.
 
-        Ensures the provided response can be used to create a BaseResponse
+        Ensures the provided response can be used to create a ResponseBase
         instance for handling chat interactions.
 
         Parameters
         ----------
-        value : BaseResponse, type[BaseResponse], Callable, or None
+        value : ResponseBase, type[ResponseBase], Callable, or None
             Response handler as instance, class, or factory function.
 
         Returns
         -------
-        BaseResponse, type[BaseResponse], Callable, or None
+        ResponseBase, type[ResponseBase], Callable, or None
             Validated response handler.
 
         Raises
         ------
         TypeError
-            If value is not a BaseResponse, subclass, or callable.
+            If value is not a ResponseBase, subclass, or callable.
         """
         if value is None:
             return None
-        if isinstance(value, BaseResponse):
+        if isinstance(value, ResponseBase):
             return value
-        if isinstance(value, type) and issubclass(value, BaseResponse):
+        if isinstance(value, type) and issubclass(value, ResponseBase):
             return value
         if callable(value):
             return value
-        raise TypeError("response must be a BaseResponse, subclass, or callable")
+        raise TypeError("response must be a ResponseBase, subclass, or callable")
 
     def normalized_vector_stores(self) -> list[str]:
         """Return configured system vector stores as a list.
@@ -201,21 +206,21 @@ class StreamlitAppConfig(BaseModel):
             raise ValueError("response must be provided.")
         return self
 
-    def create_response(self) -> BaseResponse[BaseStructure]:
+    def create_response(self) -> ResponseBase[StructureBase]:
         """Instantiate and return the configured response handler.
 
         Converts the response field (whether class, instance, or callable)
-        into an active BaseResponse instance ready for chat interactions.
+        into an active ResponseBase instance ready for chat interactions.
 
         Returns
         -------
-        BaseResponse[BaseStructure]
+        ResponseBase[StructureBase]
             Active response instance for handling chat messages.
 
         Raises
         ------
         TypeError
-            If the configured response cannot produce a BaseResponse.
+            If the configured response cannot produce a ResponseBase.
 
         Examples
         --------
@@ -224,6 +229,39 @@ class StreamlitAppConfig(BaseModel):
         """
         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,
@@ -257,7 +295,7 @@ class StreamlitAppConfig(BaseModel):
         Examples
         --------
         >>> from pathlib import Path
-        >>> config = StreamlitAppConfig.load_app_config(
+        >>> config = StreamlitAppRegistry.load_app_config(
         ...     Path("./my_config.py")
         ... )
         """
@@ -311,7 +349,7 @@ def _extract_config(module: ModuleType) -> StreamlitAppConfig:
 
     Looks for APP_CONFIG in the module and converts it to a validated
     StreamlitAppConfig instance. Supports multiple input formats including
-    dictionaries, BaseResponse instances, and existing config objects.
+    dictionaries, ResponseBase instances, and existing config objects.
 
     Parameters
     ----------
@@ -328,7 +366,7 @@ def _extract_config(module: ModuleType) -> StreamlitAppConfig:
     ValueError
         If APP_CONFIG is missing from the module.
     TypeError
-        If APP_CONFIG is not a valid type (dict, BaseResponse, callable,
+        If APP_CONFIG is not a valid type (dict, ResponseBase, callable,
         or StreamlitAppConfig).
 
     Examples
@@ -345,20 +383,20 @@ def _extract_config(module: ModuleType) -> StreamlitAppConfig:
         return raw_config
     if isinstance(raw_config, dict):
         return _config_from_mapping(raw_config)
-    if isinstance(raw_config, BaseResponse):
+    if isinstance(raw_config, ResponseBase):
         return StreamlitAppConfig(response=raw_config)
-    if isinstance(raw_config, type) and issubclass(raw_config, BaseResponse):
+    if isinstance(raw_config, type) and issubclass(raw_config, ResponseBase):
         return StreamlitAppConfig(response=raw_config)
     if callable(raw_config):
         return StreamlitAppConfig(response=raw_config)
 
     raise TypeError(
-        "APP_CONFIG must be a dict, callable, BaseResponse, or StreamlitAppConfig."
+        "APP_CONFIG must be a dict, callable, ResponseBase, or StreamlitAppConfig."
     )
 
 
-def _instantiate_response(candidate: object) -> BaseResponse[BaseStructure]:
-    """Convert a response candidate into a BaseResponse instance.
+def _instantiate_response(candidate: object) -> ResponseBase[StructureBase]:
+    """Convert a response candidate into a ResponseBase instance.
 
     Handles multiple candidate types: existing instances (returned as-is),
     classes (instantiated with no arguments), and callables (invoked to
@@ -371,31 +409,31 @@ def _instantiate_response(candidate: object) -> BaseResponse[BaseStructure]:
 
     Returns
     -------
-    BaseResponse[BaseStructure]
+    ResponseBase[StructureBase]
         Active response instance ready for use.
 
     Raises
     ------
     TypeError
-        If candidate cannot produce a BaseResponse instance.
+        If candidate cannot produce a ResponseBase instance.
 
     Examples
     --------
     >>> response = _instantiate_response(MyResponse)
-    >>> isinstance(response, BaseResponse)
+    >>> isinstance(response, ResponseBase)
     True
     """
-    if isinstance(candidate, BaseResponse):
+    if isinstance(candidate, ResponseBase):
         return candidate
-    if isinstance(candidate, type) and issubclass(candidate, BaseResponse):
-        response_cls = cast(type[BaseResponse[BaseStructure]], candidate)
+    if isinstance(candidate, type) and issubclass(candidate, ResponseBase):
+        response_cls = cast(type[ResponseBase[StructureBase]], candidate)
         return response_cls()  # type: ignore[call-arg]
     if callable(candidate):
-        response_callable = cast(Callable[[], BaseResponse[BaseStructure]], candidate)
+        response_callable = cast(Callable[[], ResponseBase[StructureBase]], candidate)
         response = response_callable()
-        if isinstance(response, BaseResponse):
+        if isinstance(response, ResponseBase):
             return response
-    raise TypeError("response must be a BaseResponse, subclass, or callable")
+    raise TypeError("response must be a ResponseBase, subclass, or callable")
 
 
 def _config_from_mapping(raw_config: dict) -> StreamlitAppConfig:
@@ -432,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
@@ -486,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]
 
@@ -497,6 +509,6 @@ def _load_configuration(config_path: Path) -> StreamlitAppConfig:
 
 __all__ = [
     "StreamlitAppConfig",
-    "load_app_config",
+    "StreamlitAppRegistry",
     "_load_configuration",
 ]

openai_sdk_helpers/streamlit_app/streamlit_web_search.py

@@ -3,7 +3,7 @@
 import json
 from openai_sdk_helpers.agent.search.web import WebAgentSearch
 from openai_sdk_helpers.config import OpenAISettings
-from openai_sdk_helpers.response.base import BaseResponse
+from openai_sdk_helpers.response.base import ResponseBase
 from openai_sdk_helpers.structure.web_search import WebSearchStructure
 from openai_sdk_helpers.structure.prompt import PromptStructure
 from openai_sdk_helpers.tools import ToolSpec, build_tool_definitions
@@ -11,7 +11,7 @@ from openai_sdk_helpers.utils import coerce_jsonable, customJSONEncoder
 from openai_sdk_helpers.environment import DEFAULT_MODEL
 
 
-class StreamlitWebSearch(BaseResponse[WebSearchStructure]):
+class StreamlitWebSearch(ResponseBase[WebSearchStructure]):
     """Response tuned for a generic chat experience with structured output.
 
     Methods

openai_sdk_helpers/structure/__init__.py

@@ -7,7 +7,7 @@ generating OpenAI-compatible schema definitions.
 
 Classes
 -------
-BaseStructure
+StructureBase
     Base class for all structured output models with schema generation.
 SchemaOptions
     Configuration options for schema generation behavior.
@@ -27,6 +27,8 @@ SummaryStructure
     Basic summary with topic breakdown.
 ExtendedSummaryStructure
     Enhanced summary with additional metadata.
+TranslationStructure
+    Structured translation output.
 WebSearchStructure
     Web search results structure.
 WebSearchPlanStructure
@@ -74,12 +76,13 @@ from .plan import *
 from .prompt import PromptStructure
 from .responses import *
 from .summary import *
+from .translation import TranslationStructure
 from .validation import ValidationResultStructure
 from .vector_search import *
 from .web_search import *
 
 __all__ = [
-    "BaseStructure",
+    "StructureBase",
     "SchemaOptions",
     "spec_field",
     "AgentBlueprint",
@@ -93,6 +96,7 @@ __all__ = [
     "SummaryTopic",
     "SummaryStructure",
     "ExtendedSummaryStructure",
+    "TranslationStructure",
     "WebSearchStructure",
     "WebSearchPlanStructure",
     "WebSearchItemStructure",

openai_sdk_helpers/structure/agent_blueprint.py

@@ -6,12 +6,12 @@ converting them into executable plans with validation and deployment steps.
 
 from __future__ import annotations
 
-from .base import BaseStructure, spec_field
+from .base import StructureBase, spec_field
 from .plan import PlanStructure, TaskStructure
 from .plan.enum import AgentEnum
 
 
-class AgentBlueprint(BaseStructure):
+class AgentBlueprint(StructureBase):
     """Capture requirements for creating a new agent.
 
     Defines the complete specification for an agent including mission,

openai_sdk_helpers/structure/base.py

@@ -1,6 +1,6 @@
 """Base classes for structured output models.
 
-This module provides the foundational BaseStructure class and utilities for
+This module provides the foundational StructureBase class and utilities for
 defining Pydantic-based structured output models with OpenAI-compatible schema
 generation, validation, and serialization.
 """
@@ -12,7 +12,6 @@ import ast
 import inspect
 import json
 import logging
-from collections.abc import Mapping, Sequence
 from dataclasses import dataclass
 from enum import Enum
 from pathlib import Path
@@ -32,13 +31,13 @@ from openai.types.responses.response_text_config_param import ResponseTextConfig
 
 # Internal imports
 
-from ..utils import check_filepath, customJSONEncoder, log
+from ..utils import check_filepath, log, BaseModelJSONSerializable
 
-T = TypeVar("T", bound="BaseStructure")
+T = TypeVar("T", bound="StructureBase")
 DEFAULT_DATA_PATH: Path | None = None
 
 
-class BaseStructure(BaseModel):
+class StructureBase(BaseModelJSONSerializable):
     """Base class for structured output models with schema generation.
 
     Provides Pydantic-based schema definition and serialization utilities
@@ -93,8 +92,8 @@ class BaseStructure(BaseModel):
     --------
     Define a custom structure:
 
-    >>> from openai_sdk_helpers.structure import BaseStructure, spec_field
-    >>> class MyOutput(BaseStructure):
+    >>> from openai_sdk_helpers.structure import StructureBase, spec_field
+    >>> class MyOutput(StructureBase):
     ...     title: str = spec_field("title", description="The title")
     ...     score: float = spec_field("score", description="Quality score")
 
@@ -454,7 +453,7 @@ class BaseStructure(BaseModel):
         schema = cls.get_schema()
         if cls.DATA_PATH is None:
             raise RuntimeError(
-                "DATA_PATH is not set. Set BaseStructure.DATA_PATH before saving."
+                "DATA_PATH is not set. Set StructureBase.DATA_PATH before saving."
             )
         file_path = cls.DATA_PATH / f"{cls.__name__}_schema.json"
         check_filepath(file_path)
@@ -462,96 +461,6 @@ class BaseStructure(BaseModel):
             json.dump(schema, file_handle, indent=2, ensure_ascii=False)
         return file_path
 
-    def to_json(self) -> dict[str, Any]:
-        """Serialize the instance to a JSON-compatible dictionary.
-
-        Converts the Pydantic model instance to a dictionary suitable for
-        JSON serialization. Enum members are converted to their values,
-        and nested structures are recursively processed.
-
-        Returns
-        -------
-        dict[str, Any]
-            Model instance serialized as a dictionary with JSON-compatible types.
-
-        Examples
-        --------
-        >>> instance = MyStructure(title="Test", score=0.95)
-        >>> data = instance.to_json()
-        >>> print(json.dumps(data))
-        """
-
-        def convert(obj: Any) -> Any:
-            if isinstance(obj, Enum):
-                return obj.value
-            if isinstance(obj, BaseStructure):
-                return obj.to_json()
-            if isinstance(obj, Mapping):
-                return {str(k): convert(v) for k, v in obj.items()}
-            if isinstance(obj, Sequence) and not isinstance(
-                obj, (str, bytes, bytearray)
-            ):
-                return [convert(item) for item in obj]
-            return obj
-
-        payload = convert(self.model_dump())
-
-        def is_list_field(field) -> bool:
-            annotation = getattr(field, "annotation", None)
-            if annotation is None:
-                return False
-
-            origins_to_match = {list, Sequence, tuple, set}
-
-            origin = get_origin(annotation)
-            if origin in origins_to_match or annotation in origins_to_match:
-                return True
-
-            # Check for Union types (e.g., list[str] | None)
-            if origin is not None:
-                # Handle Union by checking args
-                args = get_args(annotation)
-                return any(
-                    get_origin(arg) in origins_to_match or arg in origins_to_match
-                    for arg in args
-                )
-            return False
-
-        for name, field in self.__class__.model_fields.items():
-            if name not in payload:
-                continue
-            if not is_list_field(field):
-                continue
-            value = payload[name]
-            if value is None:
-                continue
-            if isinstance(value, (str, bytes, bytearray)):
-                payload[name] = [value]
-            elif not isinstance(value, list):
-                payload[name] = [value]
-
-        return payload
-
-    def to_json_file(self, filepath: str) -> str:
-        """Write :meth:`to_json` output to ``filepath``.
-
-        Parameters
-        ----------
-        filepath : str
-            Destination path for the JSON file.
-
-        Returns
-        -------
-        str
-            Path to the written file.
-        """
-        check_filepath(fullfilepath=filepath)
-        with open(file=filepath, mode="w", encoding="utf-8") as f:
-            json.dump(
-                self.to_json(), f, ensure_ascii=False, indent=4, cls=customJSONEncoder
-            )
-        return filepath
-
     @classmethod
     def _extract_enum_class(cls, field_type: Any) -> type[Enum] | None:
         """Extract an Enum class from a field's type annotation.
@@ -772,7 +681,7 @@ class BaseStructure(BaseModel):
         """
         return "\n".join(
             [
-                BaseStructure.format_output(field, value=value)
+                StructureBase.format_output(field, value=value)
                 for field, value in self.model_dump().items()
             ]
         )

openai_sdk_helpers/structure/plan/plan.py

@@ -14,12 +14,12 @@ from typing import Any, Awaitable, Coroutine, cast
 from collections.abc import Mapping
 
 from .enum import AgentEnum
-from ..base import BaseStructure, spec_field
+from ..base import StructureBase, spec_field
 from .task import TaskStructure
 from .types import AgentCallable, AgentRegistry
 
 
-class PlanStructure(BaseStructure):
+class PlanStructure(StructureBase):
     """Structured representation of an ordered list of agent tasks.
 
     Represents a complete execution plan consisting of multiple agent tasks

openai_sdk_helpers/structure/plan/task.py

@@ -12,10 +12,10 @@ from typing import Literal
 from pydantic import field_validator
 
 from .enum import AgentEnum
-from ..base import BaseStructure, spec_field
+from ..base import StructureBase, spec_field
 
 
-class TaskStructure(BaseStructure):
+class TaskStructure(StructureBase):
     """Structured representation of a single agent task.
 
     Represents one task in an agent execution plan, including its type,
@@ -140,13 +140,13 @@ class TaskStructure(BaseStructure):
         """
         return "\n".join(
             [
-                BaseStructure.format_output("Task type", value=self.task_type),
-                BaseStructure.format_output("Prompt", value=self.prompt),
-                BaseStructure.format_output("Context", value=self.context),
-                BaseStructure.format_output("Status", value=self.status),
-                BaseStructure.format_output("Start date", value=self.start_date),
-                BaseStructure.format_output("End date", value=self.end_date),
-                BaseStructure.format_output("Results", value=self.results),
+                StructureBase.format_output("Task type", value=self.task_type),
+                StructureBase.format_output("Prompt", value=self.prompt),
+                StructureBase.format_output("Context", value=self.context),
+                StructureBase.format_output("Status", value=self.status),
+                StructureBase.format_output("Start date", value=self.start_date),
+                StructureBase.format_output("End date", value=self.end_date),
+                StructureBase.format_output("Results", value=self.results),
             ]
         )
 

openai_sdk_helpers/structure/prompt.py

@@ -6,10 +6,10 @@ used in OpenAI API requests.
 
 from __future__ import annotations
 
-from .base import BaseStructure, spec_field
+from .base import StructureBase, spec_field
 
 
-class PromptStructure(BaseStructure):
+class PromptStructure(StructureBase):
     """Structured representation of prompt text for OpenAI API requests.
 
     Simple structure containing a single prompt string with examples.