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

openai_sdk_helpers/structure/translation.py

@@ -0,0 +1,32 @@
+"""Structured output model for translations."""
+
+from __future__ import annotations
+
+from .base import StructureBase, spec_field
+
+
+class TranslationStructure(StructureBase):
+    """Structured representation of translated text.
+
+    Attributes
+    ----------
+    text : str
+        Translated text output from the agent.
+
+    Methods
+    -------
+    print()
+        Return the formatted model fields.
+
+    Examples
+    --------
+    >>> translation = TranslationStructure(text="Hola mundo")
+    >>> print(translation.text)
+    'Hola mundo'
+    """
+
+    text: str = spec_field(
+        "text",
+        description="Translated text output from the agent.",
+        examples=["Hola mundo", "Bonjour le monde"],
+    )

openai_sdk_helpers/structure/validation.py

@@ -6,10 +6,10 @@ validation checks on user inputs and agent outputs.
 
 from __future__ import annotations
 
-from .base import BaseStructure, spec_field
+from .base import StructureBase, spec_field
 
 
-class ValidationResultStructure(BaseStructure):
+class ValidationResultStructure(StructureBase):
     """Capture guardrail validation findings for user and agent messages.
 
     Represents the results of safety and policy validation checks performed

openai_sdk_helpers/structure/vector_search.py

@@ -7,10 +7,10 @@ workflows with error tracking and result aggregation.
 
 from __future__ import annotations
 
-from .base import BaseStructure, spec_field
+from .base import StructureBase, spec_field
 
 
-class VectorSearchItemStructure(BaseStructure):
+class VectorSearchItemStructure(StructureBase):
     """A single vector search to perform.
 
     Represents one vector search query with rationale for its inclusion
@@ -35,7 +35,7 @@ class VectorSearchItemStructure(BaseStructure):
     query: str = spec_field("query")
 
 
-class VectorSearchPlanStructure(BaseStructure):
+class VectorSearchPlanStructure(StructureBase):
     """Collection of vector searches required to satisfy the query.
 
     Represents a plan containing multiple vector searches that together
@@ -56,7 +56,7 @@ class VectorSearchPlanStructure(BaseStructure):
     searches: list[VectorSearchItemStructure] = spec_field("searches")
 
 
-class VectorSearchItemResultStructure(BaseStructure):
+class VectorSearchItemResultStructure(StructureBase):
     """Result of a single vector search.
 
     Contains the text results retrieved from executing one vector search query.
@@ -74,7 +74,7 @@ class VectorSearchItemResultStructure(BaseStructure):
     texts: list[str] = spec_field("texts")
 
 
-class VectorSearchItemResultsStructure(BaseStructure):
+class VectorSearchItemResultsStructure(StructureBase):
     """Collection of search results from multiple queries.
 
     Aggregates results from multiple vector searches while tracking any
@@ -119,7 +119,7 @@ class VectorSearchItemResultsStructure(BaseStructure):
         self.item_results.append(item)
 
 
-class VectorSearchReportStructure(BaseStructure):
+class VectorSearchReportStructure(StructureBase):
     """Structured output from the vector search writer agent.
 
     Contains the final synthesized report from vector search results,
@@ -152,7 +152,7 @@ class VectorSearchReportStructure(BaseStructure):
     sources: list[str] = spec_field("sources")
 
 
-class VectorSearchStructure(BaseStructure):
+class VectorSearchStructure(StructureBase):
     """Complete output of a vector search workflow.
 
     Represents the full lifecycle of a vector search operation, from the

openai_sdk_helpers/structure/web_search.py

@@ -7,10 +7,10 @@ workflows with comprehensive reporting.
 
 from __future__ import annotations
 
-from .base import BaseStructure, spec_field
+from .base import StructureBase, spec_field
 
 
-class WebSearchReportStructure(BaseStructure):
+class WebSearchReportStructure(StructureBase):
     """Structured output from the web search writer agent.
 
     Contains the final synthesized report from web search results,
@@ -43,7 +43,7 @@ class WebSearchReportStructure(BaseStructure):
     sources: list[str] = spec_field("sources")
 
 
-class WebSearchItemStructure(BaseStructure):
+class WebSearchItemStructure(StructureBase):
     """A single web search to perform.
 
     Represents one web search query with rationale for its inclusion
@@ -68,7 +68,7 @@ class WebSearchItemStructure(BaseStructure):
     query: str = spec_field("query")
 
 
-class WebSearchItemResultStructure(BaseStructure):
+class WebSearchItemResultStructure(StructureBase):
     """Result of a single web search.
 
     Contains the text content retrieved from executing one web search query.
@@ -86,7 +86,7 @@ class WebSearchItemResultStructure(BaseStructure):
     text: str = spec_field("text")
 
 
-class WebSearchPlanStructure(BaseStructure):
+class WebSearchPlanStructure(StructureBase):
     """Collection of web searches required to satisfy the query.
 
     Represents a plan containing multiple web searches that together
@@ -107,7 +107,7 @@ class WebSearchPlanStructure(BaseStructure):
     searches: list[WebSearchItemStructure] = spec_field("searches")
 
 
-class WebSearchStructure(BaseStructure):
+class WebSearchStructure(StructureBase):
     """Complete output of a web search workflow.
 
     Represents the full lifecycle of a web search operation, from the

openai_sdk_helpers/tools.py

@@ -10,19 +10,21 @@ definitions from named metadata structures.
 
 from __future__ import annotations
 
+import asyncio
 import inspect
+import threading
 from dataclasses import dataclass
 from typing import Any, Callable, TypeAlias, TypeVar
 
 from pydantic import BaseModel, ValidationError
 
 from openai_sdk_helpers.response.tool_call import parse_tool_arguments
-from openai_sdk_helpers.structure.base import BaseStructure
+from openai_sdk_helpers.structure.base import StructureBase
 from openai_sdk_helpers.utils import coerce_jsonable, customJSONEncoder
 import json
 
 T = TypeVar("T", bound=BaseModel)
-StructureType: TypeAlias = type[BaseStructure]
+StructureType: TypeAlias = type[StructureBase]
 
 
 def serialize_tool_result(result: Any) -> str:
@@ -81,7 +83,7 @@ def tool_handler_factory(
     The returned handler:
     1. Parses tool_call.arguments using parse_tool_arguments
     2. Validates arguments with input_model if provided
-    3. Calls func with validated/parsed arguments
+    3. Calls func with validated/parsed arguments (handles both sync and async)
     4. Serializes the result using serialize_tool_result
 
     Parameters
@@ -124,7 +126,13 @@ def tool_handler_factory(
     ...     limit: int = 10
     >>> def search_tool(query: str, limit: int = 10):
     ...     return {"results": [f"Result for {query}"]}
-    >>> handler = tool_handler_factory(search_tool, SearchInput)
+    >>> handler = tool_handler_factory(search_tool, input_model=SearchInput)
+
+    With async function:
+
+    >>> async def async_search_tool(query: str, limit: int = 10):
+    ...     return {"results": [f"Result for {query}"]}
+    >>> handler = tool_handler_factory(async_search_tool)
 
     The handler can then be used with OpenAI tool calls:
 
@@ -135,6 +143,7 @@ def tool_handler_factory(
     >>> tool_call = ToolCall()
     >>> result = handler(tool_call)  # doctest: +SKIP
     """
+    is_async = inspect.iscoroutinefunction(func)
 
     def handler(tool_call: Any) -> str:
         """Handle tool execution with parsing, validation, and serialization.
@@ -170,15 +179,32 @@ def tool_handler_factory(
         else:
             call_kwargs = parsed_args
 
-        # Execute function (sync only - async functions not supported)
-        if inspect.iscoroutinefunction(func):
-            raise TypeError(
-                f"Async functions are not supported by tool_handler_factory. "
-                f"Function '{func.__name__}' is async. "
-                "Wrap async functions in a synchronous adapter before passing to tool_handler_factory."
-            )
-
-        result = func(**call_kwargs)
+        # Execute function (sync or async with event loop detection)
+        if is_async:
+            # Handle async function with proper event loop detection
+            try:
+                loop = asyncio.get_running_loop()
+                # We're inside an event loop, need to run in thread
+                result_holder: dict[str, Any] = {"value": None, "exception": None}
+
+                def _thread_func() -> None:
+                    try:
+                        result_holder["value"] = asyncio.run(func(**call_kwargs))
+                    except Exception as exc:
+                        result_holder["exception"] = exc
+
+                thread = threading.Thread(target=_thread_func)
+                thread.start()
+                thread.join()
+
+                if result_holder["exception"]:
+                    raise result_holder["exception"]
+                result = result_holder["value"]
+            except RuntimeError:
+                # No event loop running, can use asyncio.run directly
+                result = asyncio.run(func(**call_kwargs))
+        else:
+            result = func(**call_kwargs)
 
         # Serialize result
         return serialize_tool_result(result)
@@ -200,14 +226,14 @@ class ToolSpec:
     Attributes
     ----------
     structure : StructureType
-        The BaseStructure class that defines the tool's input parameter schema.
+        The StructureBase class that defines the tool's input parameter schema.
         Used to generate the OpenAI tool definition.
     tool_name : str
         Name identifier for the tool.
     tool_description : str
         Human-readable description of what the tool does.
     output_structure : StructureType or None, default=None
-        Optional BaseStructure class that defines the tool's output schema.
+        Optional StructureBase class that defines the tool's output schema.
         This is for documentation/reference only and is not sent to OpenAI.
         Useful when a tool accepts one type of input but returns a different
         structured output.

openai_sdk_helpers/utils/__init__.py

@@ -21,8 +21,8 @@ coercion
     Numeric coercion helpers and list normalization.
 path_utils
     File and path helpers.
-json_utils
-    JSON encoding helpers and mixins.
+json
+    JSON encoding helpers and mixins for dataclasses and Pydantic models.
 logging_config
     Centralized logger factory and convenience log helper.
 validation
@@ -45,11 +45,18 @@ from .coercion import (
     coerce_optional_int,
     ensure_list,
 )
-from .json_utils import (
-    JSONSerializable,
+from .json import (
+    BaseModelJSONSerializable,
+    DataclassJSONSerializable,
     coerce_jsonable,
     customJSONEncoder,
+    decode_module_qualname,
+    encode_module_qualname,
+    get_module_qualname,
+    to_jsonable,
 )
+from .registry import BaseRegistry
+
 from .path_utils import check_filepath, ensure_directory
 from openai_sdk_helpers.logging_config import log
 from .validation import (
@@ -88,9 +95,14 @@ __all__ = [
     "coerce_optional_float",
     "coerce_optional_int",
     "coerce_dict",
+    "to_jsonable",
     "coerce_jsonable",
-    "JSONSerializable",
+    "DataclassJSONSerializable",
+    "BaseModelJSONSerializable",
     "customJSONEncoder",
+    "get_module_qualname",
+    "encode_module_qualname",
+    "decode_module_qualname",
     "log",
     # Validation helpers
     "validate_non_empty_string",
@@ -122,4 +134,6 @@ __all__ = [
     "create_image_data_url",
     "create_file_data_url",
     "is_image_file",
+    # Registry
+    "BaseRegistry",
 ]

openai_sdk_helpers/utils/json/__init__.py

@@ -0,0 +1,55 @@
+"""JSON serialization helpers for dataclasses, Pydantic models, and reference encoding.
+
+This package provides consistent to_json/from_json flows and a JSONEncoder that
+handles common types including dataclasses, Pydantic models, and reference encoding.
+
+Package Layout
+--------------
+utils.py
+    to_jsonable(), coerce_jsonable(), customJSONEncoder.
+data_class.py
+    DataclassJSONSerializable mixin with to_json, to_json_file, from_json, from_json_file.
+base_model.py
+    BaseModelJSONSerializable for Pydantic, with _serialize_fields/_deserialize_fields hooks.
+ref.py
+    Reference helpers get_module_qualname, encode_module_qualname, decode_module_qualname.
+
+Public API
+----------
+to_jsonable(value)
+    Convert common types to JSON-safe forms; recursive for containers/dicts.
+coerce_jsonable(value)
+    Ensures json.dumps succeeds; falls back to str when necessary. Special-cases ResponseBase.
+customJSONEncoder
+    json.JSONEncoder subclass delegating to to_jsonable.
+DataclassJSONSerializable
+    Mixin adding to_json(), to_json_file(path) -> str, from_json(data) -> T, from_json_file(path) -> T.
+BaseModelJSONSerializable
+    Pydantic BaseModel subclass adding to_json() -> dict, to_json_file(path) -> str,
+    from_json(data) -> T, from_json_file(path) -> T, plus overridable _serialize_fields(data)
+    and _deserialize_fields(data).
+get_module_qualname(obj) -> (module, qualname)
+    Safe retrieval.
+encode_module_qualname(obj) -> dict|None
+    {module, qualname} for import reconstruction.
+decode_module_qualname(ref) -> object|None
+    Import and getattr by encoded reference.
+"""
+
+from __future__ import annotations
+
+from .base_model import BaseModelJSONSerializable
+from .data_class import DataclassJSONSerializable
+from .ref import decode_module_qualname, encode_module_qualname, get_module_qualname
+from .utils import coerce_jsonable, customJSONEncoder, to_jsonable
+
+__all__ = [
+    "to_jsonable",
+    "coerce_jsonable",
+    "customJSONEncoder",
+    "DataclassJSONSerializable",
+    "BaseModelJSONSerializable",
+    "get_module_qualname",
+    "encode_module_qualname",
+    "decode_module_qualname",
+]

openai_sdk_helpers/utils/json/base_model.py

@@ -0,0 +1,181 @@
+"""Pydantic BaseModel JSON serialization support.
+
+This module provides BaseModelJSONSerializable for Pydantic models,
+with to_json, to_json_file, from_json, from_json_file methods and
+customizable _serialize_fields/_deserialize_fields hooks.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, TypeVar
+from pydantic import BaseModel
+from ..path_utils import check_filepath
+from .utils import _to_jsonable, customJSONEncoder
+
+P = TypeVar("P", bound="BaseModelJSONSerializable")
+
+
+class BaseModelJSONSerializable(BaseModel):
+    """Pydantic BaseModel subclass with JSON serialization support.
+
+    Adds to_json(), to_json_file(path), from_json(data), from_json_file(path),
+    plus overridable _serialize_fields(data) and _deserialize_fields(data) hooks.
+
+    Methods
+    -------
+    to_json()
+        Return a JSON-compatible dict representation.
+    to_json_file(filepath)
+        Write serialized JSON data to a file path.
+    from_json(data)
+        Create an instance from a JSON-compatible dict (class method).
+    from_json_file(filepath)
+        Load an instance from a JSON file (class method).
+    _serialize_fields(data)
+        Customize serialization (override in subclasses).
+    _deserialize_fields(data)
+        Customize deserialization (override in subclasses).
+
+    Examples
+    --------
+    >>> from pydantic import BaseModel
+    >>> class MyConfig(BaseModelJSONSerializable, BaseModel):
+    ...     name: str
+    ...     value: int
+    >>> cfg = MyConfig(name="test", value=42)
+    >>> cfg.to_json()
+    {'name': 'test', 'value': 42}
+    """
+
+    def to_json(self) -> dict[str, Any]:
+        """Return a JSON-compatible dict representation.
+
+        Returns
+        -------
+        dict[str, Any]
+            Serialized model data.
+        """
+        if hasattr(self, "model_dump"):
+            data = getattr(self, "model_dump")()
+        else:
+            data = self.__dict__.copy()
+        return self._serialize_fields(_to_jsonable(data))
+
+    def to_json_file(self, filepath: str | Path) -> str:
+        """Write serialized JSON data to a file path.
+
+        Parameters
+        ----------
+        filepath : str or Path
+            Path where the JSON file will be written.
+
+        Returns
+        -------
+        str
+            Absolute path to the written file.
+        """
+        target = Path(filepath)
+        check_filepath(fullfilepath=str(target))
+        with open(target, "w", encoding="utf-8") as handle:
+            json.dump(
+                self.to_json(),
+                handle,
+                indent=2,
+                ensure_ascii=False,
+                cls=customJSONEncoder,
+            )
+        return str(target)
+
+    def _serialize_fields(self, data: dict[str, Any]) -> dict[str, Any]:
+        """Customize field serialization.
+
+        Override this method in subclasses to add custom serialization logic.
+
+        Parameters
+        ----------
+        data : dict[str, Any]
+            Pre-serialized data dictionary.
+
+        Returns
+        -------
+        dict[str, Any]
+            Modified data dictionary.
+        """
+        return data
+
+    @classmethod
+    def _deserialize_fields(cls, data: dict[str, Any]) -> dict[str, Any]:
+        """Customize field deserialization.
+
+        Override this method in subclasses to add custom deserialization logic.
+
+        Parameters
+        ----------
+        data : dict[str, Any]
+            Raw data dictionary from JSON.
+
+        Returns
+        -------
+        dict[str, Any]
+            Modified data dictionary.
+        """
+        return data
+
+    @classmethod
+    def from_json(cls: type[P], data: dict[str, Any]) -> P:
+        """Create an instance from a JSON-compatible dict.
+
+        Parameters
+        ----------
+        data : dict[str, Any]
+            JSON-compatible dictionary containing the instance data.
+
+        Returns
+        -------
+        P
+            New instance of the class.
+
+        Examples
+        --------
+        >>> json_data = {"name": "test", "value": 42}
+        >>> instance = MyConfig.from_json(json_data)
+        """
+        processed_data = cls._deserialize_fields(data)
+        return cls(**processed_data)  # type: ignore[return-value]
+
+    @classmethod
+    def from_json_file(cls: type[P], filepath: str | Path) -> P:
+        """Load an instance from a JSON file.
+
+        Parameters
+        ----------
+        filepath : str or Path
+            Path to the JSON file to load.
+
+        Returns
+        -------
+        P
+            New instance of the class loaded from the file.
+
+        Raises
+        ------
+        FileNotFoundError
+            If the file does not exist.
+
+        Examples
+        --------
+        >>> instance = MyConfig.from_json_file("config.json")
+        """
+        target = Path(filepath)
+        if not target.exists():
+            raise FileNotFoundError(f"JSON file not found: {target}")
+
+        with open(target, "r", encoding="utf-8") as handle:
+            data = json.load(handle)
+
+        return cls.from_json(data)
+
+
+__all__ = ["BaseModelJSONSerializable"]

openai_sdk_helpers/utils/{json_utils.py → json/data_class.py}

@@ -1,73 +1,24 @@
-"""JSON serialization helpers for helper types."""
+"""Dataclass JSON serialization mixin.
+
+This module provides the DataclassJSONSerializable mixin for dataclasses,
+adding to_json, to_json_file, from_json, and from_json_file methods.
+"""
 
 from __future__ import annotations
 
 import json
 from dataclasses import asdict, fields, is_dataclass
-from datetime import datetime
-from enum import Enum
 from pathlib import Path
 from typing import Any, TypeVar, Union, get_args, get_origin, get_type_hints
 
-from .path_utils import check_filepath
-
-T = TypeVar("T", bound="JSONSerializable")
-
-
-def _to_jsonable(value: Any) -> Any:
-    """Convert common helper types to JSON-serializable forms."""
-    from openai_sdk_helpers.structure.base import BaseStructure
-
-    if value is None:
-        return None
-    if isinstance(value, Enum):
-        return value.value
-    if isinstance(value, Path):
-        return str(value)
-    if isinstance(value, datetime):
-        return value.isoformat()
-    if is_dataclass(value) and not isinstance(value, type):
-        return {k: _to_jsonable(v) for k, v in asdict(value).items()}
-    if hasattr(value, "model_dump"):
-        model_dump = getattr(value, "model_dump")
-        return model_dump()
-    if isinstance(value, dict):
-        return {str(k): _to_jsonable(v) for k, v in value.items()}
-    if isinstance(value, (list, tuple, set)):
-        return [_to_jsonable(v) for v in value]
-    if isinstance(value, BaseStructure):
-        return value.model_dump()
-    return value
-
-
-def coerce_jsonable(value: Any) -> Any:
-    """Convert value into a JSON-serializable representation."""
-    from openai_sdk_helpers.response.base import BaseResponse
-
-    if value is None:
-        return None
-    if isinstance(value, BaseResponse):
-        return coerce_jsonable(value.messages.to_json())
-    if is_dataclass(value) and not isinstance(value, type):
-        return {key: coerce_jsonable(item) for key, item in asdict(value).items()}
-    coerced = _to_jsonable(value)
-    try:
-        json.dumps(coerced)
-        return coerced
-    except TypeError:
-        return str(coerced)
-
-
-class customJSONEncoder(json.JSONEncoder):
-    """JSON encoder for common helper types like enums and paths."""
-
-    def default(self, o: Any) -> Any:  # noqa: D401
-        """Return JSON-serializable representation of ``o``."""
-        return _to_jsonable(o)
-
-
-class JSONSerializable:
-    """Mixin for classes that can be serialized to and from JSON.
+from ..path_utils import check_filepath
+from .utils import _to_jsonable, customJSONEncoder
+
+T = TypeVar("T", bound="DataclassJSONSerializable")
+
+
+class DataclassJSONSerializable:
+    """Mixin for dataclasses that can be serialized to and from JSON.
 
     Methods
     -------
@@ -79,10 +30,28 @@ class JSONSerializable:
         Create an instance from a JSON-compatible dict (class method).
     from_json_file(filepath)
         Load an instance from a JSON file (class method).
+
+    Examples
+    --------
+    >>> from dataclasses import dataclass
+    >>> from pathlib import Path
+    >>> @dataclass
+    ... class MyData(DataclassJSONSerializable):
+    ...     name: str
+    ...     path: Path
+    >>> instance = MyData(name="test", path=Path("/tmp/data"))
+    >>> json_data = instance.to_json()
+    >>> restored = MyData.from_json(json_data)
     """
 
     def to_json(self) -> dict[str, Any]:
-        """Return a JSON-compatible dict representation."""
+        """Return a JSON-compatible dict representation.
+
+        Returns
+        -------
+        dict[str, Any]
+            Serialized data dictionary.
+        """
         if is_dataclass(self) and not isinstance(self, type):
             return {k: _to_jsonable(v) for k, v in asdict(self).items()}
         if hasattr(self, "model_dump"):
@@ -223,8 +192,4 @@ class JSONSerializable:
         return cls.from_json(data)
 
 
-__all__ = [
-    "coerce_jsonable",
-    "JSONSerializable",
-    "customJSONEncoder",
-]
+__all__ = ["DataclassJSONSerializable"]