openai-sdk-helpers 0.3.0__py3-none-any.whl → 0.4.0__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.response.base import ResponseBase
+from openai_sdk_helpers.structure.base import StructureBase
 from openai_sdk_helpers.utils import 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,7 @@ class StreamlitAppConfig(BaseModel):
 
     Attributes
     ----------
-    response : BaseResponse, type[BaseResponse], Callable, or None
+    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,7 +47,7 @@ class StreamlitAppConfig(BaseModel):
     normalized_vector_stores()
         Return configured system vector stores as a list.
     create_response()
-        Instantiate and return the configured BaseResponse.
+        Instantiate and return the configured ResponseBase.
     load_app_config(config_path)
         Load, validate, and return configuration from a Python module.
 
@@ -62,11 +63,11 @@ class StreamlitAppConfig(BaseModel):
 
     model_config = ConfigDict(extra="forbid", arbitrary_types_allowed=True)
 
-    response: BaseResponse[BaseStructure] | type[BaseResponse] | Callable | None = (
+    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 +131,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 +202,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
         --------
@@ -311,7 +312,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 +329,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 +346,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 +372,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:

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.

openai_sdk_helpers/structure/responses.py

@@ -1,7 +1,7 @@
 """OpenAI response and tool helpers for structured outputs.
 
 This module provides helper functions for creating OpenAI API response formats
-and tool definitions from BaseStructure classes. These helpers simplify the
+and tool definitions from StructureBase classes. These helpers simplify the
 process of configuring structured outputs for both Assistant and chat
 completion APIs.
 """
@@ -13,12 +13,12 @@ from openai.types.responses.response_format_text_json_schema_config_param import
 )
 from openai.types.responses.response_text_config_param import ResponseTextConfigParam
 
-from .base import BaseStructure
+from .base import StructureBase
 from ..utils import log
 
 
 def assistant_tool_definition(
-    structure: type[BaseStructure], name: str, description: str
+    structure: type[StructureBase], name: str, description: str
 ) -> dict:
     """Build a function tool definition for OpenAI Assistants.
 
@@ -27,7 +27,7 @@ def assistant_tool_definition(
 
     Parameters
     ----------
-    structure : type[BaseStructure]
+    structure : type[StructureBase]
         Structure class that defines the tool schema.
     name : str
         Name of the function tool.
@@ -41,9 +41,9 @@ def assistant_tool_definition(
 
     Examples
     --------
-    >>> from openai_sdk_helpers.structure import BaseStructure
+    >>> from openai_sdk_helpers.structure import StructureBase
     >>> tool = assistant_tool_definition(
-    ...     BaseStructure,
+    ...     StructureBase,
     ...     "process_data",
     ...     "Process input data"
     ... )
@@ -59,7 +59,7 @@ def assistant_tool_definition(
     }
 
 
-def assistant_format(structure: type[BaseStructure]) -> dict:
+def assistant_format(structure: type[StructureBase]) -> dict:
     """Build a response format definition for OpenAI Assistants.
 
     Creates a response format specification that instructs the Assistant API
@@ -67,7 +67,7 @@ def assistant_format(structure: type[BaseStructure]) -> dict:
 
     Parameters
     ----------
-    structure : type[BaseStructure]
+    structure : type[StructureBase]
         Structure class that defines the response schema.
 
     Returns
@@ -77,7 +77,7 @@ def assistant_format(structure: type[BaseStructure]) -> dict:
 
     Examples
     --------
-    >>> format_def = assistant_format(BaseStructure)
+    >>> format_def = assistant_format(StructureBase)
     """
     log(f"{structure.__name__}::assistant_format")
     return {
@@ -90,7 +90,7 @@ def assistant_format(structure: type[BaseStructure]) -> dict:
 
 
 def response_tool_definition(
-    structure: type[BaseStructure],
+    structure: type[StructureBase],
     tool_name: str,
     tool_description: str,
 ) -> dict:
@@ -101,7 +101,7 @@ def response_tool_definition(
 
     Parameters
     ----------
-    structure : type[BaseStructure]
+    structure : type[StructureBase]
         Structure class that defines the tool schema.
     tool_name : str
         Name of the function tool.
@@ -116,7 +116,7 @@ def response_tool_definition(
     Examples
     --------
     >>> tool = response_tool_definition(
-    ...     BaseStructure,
+    ...     StructureBase,
     ...     "analyze",
     ...     "Analyze data"
     ... )
@@ -132,7 +132,7 @@ def response_tool_definition(
     }
 
 
-def response_format(structure: type[BaseStructure]) -> ResponseTextConfigParam:
+def response_format(structure: type[StructureBase]) -> ResponseTextConfigParam:
     """Build a response format for OpenAI chat completions.
 
     Creates a response format specification that instructs the chat
@@ -140,7 +140,7 @@ def response_format(structure: type[BaseStructure]) -> ResponseTextConfigParam:
 
     Parameters
     ----------
-    structure : type[BaseStructure]
+    structure : type[StructureBase]
         Structure class that defines the response schema.
 
     Returns
@@ -150,7 +150,7 @@ def response_format(structure: type[BaseStructure]) -> ResponseTextConfigParam:
 
     Examples
     --------
-    >>> format_spec = response_format(BaseStructure)
+    >>> format_spec = response_format(StructureBase)
     """
     log(f"{structure.__name__}::response_format")
     response_format_text_JSONSchema_config_param = (

openai_sdk_helpers/structure/summary.py

@@ -6,10 +6,10 @@ including topic-level summaries with citations and consolidated text summaries.
 
 from __future__ import annotations
 
-from .base import BaseStructure, spec_field
+from .base import StructureBase, spec_field
 
 
-class SummaryTopic(BaseStructure):
+class SummaryTopic(StructureBase):
     """Capture a topic-level summary with supporting citations.
 
     Represents a single topic or micro-trend identified in source excerpts,
@@ -55,7 +55,7 @@ class SummaryTopic(BaseStructure):
     )
 
 
-class SummaryStructure(BaseStructure):
+class SummaryStructure(StructureBase):
     """Consolidated summary returned by the summarizer agent.
 
     Represents a synthesized summary text derived from multiple source excerpts.