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

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"):
@@ -161,9 +130,17 @@ class JSONSerializable:
                         origin = get_origin(field_type)
                         if origin is Union:
                             type_args = get_args(field_type)
-                            # Check if Path is one of the union types
+                            # Only convert to Path if:
+                            # 1. Path is in the union AND
+                            # 2. str is NOT in the union (to avoid converting string fields)
+                            #    OR the field name suggests it's a path (contains "path")
                             if Path in type_args:
-                                should_convert_to_path = True
+                                if str not in type_args:
+                                    # Path-only union (e.g., Union[Path, None])
+                                    should_convert_to_path = True
+                                elif "path" in key.lower():
+                                    # Field name contains "path", likely meant to be a path
+                                    should_convert_to_path = True
 
                     # Convert string to Path if needed
                     if (
@@ -215,8 +192,4 @@ class JSONSerializable:
         return cls.from_json(data)
 
 
-__all__ = [
-    "coerce_jsonable",
-    "JSONSerializable",
-    "customJSONEncoder",
-]
+__all__ = ["DataclassJSONSerializable"]

openai_sdk_helpers/utils/json/ref.py

@@ -0,0 +1,113 @@
+"""Reference encoding helpers for object reconstruction.
+
+This module provides helpers for encoding and decoding object references
+using module and qualname information, enabling serialization of class
+references for later reconstruction.
+"""
+
+from __future__ import annotations
+
+import importlib
+from typing import Any
+
+
+def get_module_qualname(obj: Any) -> tuple[str, str] | None:
+    """Retrieve module and qualname for an object.
+
+    Safe retrieval that returns None if module or qualname cannot be determined.
+
+    Parameters
+    ----------
+    obj : Any
+        Object to get module and qualname from.
+
+    Returns
+    -------
+    tuple[str, str] or None
+        Tuple of (module, qualname) or None if cannot be determined.
+
+    Examples
+    --------
+    >>> class MyClass:
+    ...     pass
+    >>> get_module_qualname(MyClass)
+    ('__main__', 'MyClass')
+    """
+    module = getattr(obj, "__module__", None)
+    qualname = getattr(obj, "__qualname__", None)
+    if module and qualname:
+        return (module, qualname)
+    return None
+
+
+def encode_module_qualname(obj: Any) -> dict[str, Any] | None:
+    """Encode object reference for import reconstruction.
+
+    Parameters
+    ----------
+    obj : Any
+        Object to encode (typically a class).
+
+    Returns
+    -------
+    dict[str, Any] or None
+        Dictionary with 'module' and 'qualname' keys, or None if encoding fails.
+
+    Examples
+    --------
+    >>> class MyClass:
+    ...     pass
+    >>> encode_module_qualname(MyClass)
+    {'module': '__main__', 'qualname': 'MyClass'}
+    """
+    result = get_module_qualname(obj)
+    if result is None:
+        return None
+    module, qualname = result
+    return {"module": module, "qualname": qualname}
+
+
+def decode_module_qualname(ref: dict[str, Any]) -> Any | None:
+    """Import and retrieve object by encoded reference.
+
+    Parameters
+    ----------
+    ref : dict[str, Any]
+        Dictionary with 'module' and 'qualname' keys.
+
+    Returns
+    -------
+    Any or None
+        Retrieved object or None if import/retrieval fails.
+
+    Examples
+    --------
+    >>> ref = {'module': 'pathlib', 'qualname': 'Path'}
+    >>> decode_module_qualname(ref)
+    <class 'pathlib.Path'>
+    """
+    if not isinstance(ref, dict):
+        return None
+
+    module_name = ref.get("module")
+    qualname = ref.get("qualname")
+
+    if not module_name or not qualname:
+        return None
+
+    try:
+        module = importlib.import_module(module_name)
+        # Handle nested qualnames (e.g., "OuterClass.InnerClass")
+        obj = module
+        for attr in qualname.split("."):
+            obj = getattr(obj, attr)
+        return obj
+    except (ImportError, AttributeError):
+        return None
+
+
+__all__ = [
+    "get_module_qualname",
+    "encode_module_qualname",
+    "decode_module_qualname",
+]

openai_sdk_helpers/utils/json/utils.py

@@ -0,0 +1,203 @@
+"""Core JSON serialization utilities.
+
+This module provides the core functions for converting common types to
+JSON-serializable forms, including to_jsonable, coerce_jsonable, and
+customJSONEncoder.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, is_dataclass
+from datetime import datetime
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+from .ref import encode_module_qualname
+
+
+def to_jsonable(value: Any) -> Any:
+    """Convert common types to JSON-safe forms.
+
+    Recursively converts containers, dicts, dataclasses, Pydantic models, enums,
+    paths, datetimes, and StructureBase instances/classes to JSON-serializable forms.
+    Private properties (starting with underscore) are excluded from serialization.
+
+    Parameters
+    ----------
+    value : Any
+        Value to convert to JSON-serializable form.
+
+    Returns
+    -------
+    Any
+        JSON-serializable representation of the value.
+
+    Notes
+    -----
+    Serialization rules:
+    - Enums: use enum.value
+    - Paths: serialize to string
+    - Datetimes: ISO8601 datetime.isoformat()
+    - Dataclasses (instances): asdict followed by recursive conversion
+    - Pydantic-like objects: use model_dump() if available
+    - Dicts/containers: recursively convert values; dict keys coerced to str
+    - Private properties: keys starting with underscore are excluded
+    - StructureBase instances: use .model_dump()
+    - StructureBase classes: encode with {module, qualname, "__structure_class__": True}
+    - Sets: converted to lists
+
+    Examples
+    --------
+    >>> from enum import Enum
+    >>> class Color(Enum):
+    ...     RED = "red"
+    >>> to_jsonable(Color.RED)
+    'red'
+    >>> to_jsonable(Path("/tmp/test"))
+    '/tmp/test'
+    >>> to_jsonable({"public": 1, "_private": 2})
+    {'public': 1}
+    """
+    return _to_jsonable(value)
+
+
+def _to_jsonable(value: Any) -> Any:
+    """Convert common helper types to JSON-serializable forms (internal)."""
+    from openai_sdk_helpers.structure.base import StructureBase
+
+    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 not str(k).startswith("_")
+        }
+    # Check for StructureBase class (not instance) before model_dump check
+    if isinstance(value, type):
+        try:
+            if issubclass(value, StructureBase):
+                encoded = encode_module_qualname(value)
+                if encoded:
+                    encoded["__structure_class__"] = True
+                    return encoded
+                return str(value)
+        except TypeError:
+            # Some type-like objects may pass isinstance(value, type) but
+            # still not be valid arguments to issubclass; ignore these.
+            pass
+    if isinstance(value, StructureBase):
+        return value.model_dump()
+    # Check for model_dump on instances (after class checks)
+    if hasattr(value, "model_dump") and not isinstance(value, type):
+        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 not str(k).startswith("_")
+        }
+    if isinstance(value, (list, tuple, set)):
+        return [_to_jsonable(v) for v in value]
+    return value
+
+
+def coerce_jsonable(value: Any) -> Any:
+    """Ensure json.dumps succeeds.
+
+    Falls back to str when necessary. Special-cases ResponseBase.
+
+    Parameters
+    ----------
+    value : Any
+        Value to coerce to JSON-serializable form.
+
+    Returns
+    -------
+    Any
+        JSON-serializable representation, or str(value) as fallback.
+
+    Notes
+    -----
+    This function first attempts to convert the value using to_jsonable(),
+    then validates it can be serialized with json.dumps(). If serialization
+    fails, it falls back to str(value).
+
+    Special handling for ResponseBase: serialized as messages.to_json().
+
+    Examples
+    --------
+    >>> coerce_jsonable({"key": "value"})
+    {'key': 'value'}
+    >>> class CustomObj:
+    ...     def __str__(self):
+    ...         return "custom"
+    >>> coerce_jsonable(CustomObj())
+    'custom'
+    """
+    from openai_sdk_helpers.response.base import ResponseBase
+
+    if value is None:
+        return None
+    if isinstance(value, ResponseBase):
+        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()
+            if not (isinstance(key, str) and key.startswith("_"))
+        }
+    coerced = _to_jsonable(value)
+    try:
+        json.dumps(coerced)
+        return coerced
+    except TypeError:
+        return str(coerced)
+
+
+class customJSONEncoder(json.JSONEncoder):
+    """JSON encoder delegating to to_jsonable.
+
+    This encoder handles common types like Enum, Path, datetime, dataclasses,
+    sets, StructureBase instances/classes, and Pydantic-like objects.
+
+    Examples
+    --------
+    >>> import json
+    >>> from enum import Enum
+    >>> class Color(Enum):
+    ...     RED = "red"
+    >>> json.dumps({"color": Color.RED}, cls=customJSONEncoder)
+    '{"color": "red"}'
+    """
+
+    def default(self, o: Any) -> Any:
+        """Return JSON-serializable representation of object.
+
+        Parameters
+        ----------
+        o : Any
+            Object to serialize.
+
+        Returns
+        -------
+        Any
+            JSON-serializable representation.
+        """
+        return _to_jsonable(o)
+
+
+__all__ = [
+    "to_jsonable",
+    "coerce_jsonable",
+    "customJSONEncoder",
+]

openai_sdk_helpers/utils/output_validation.py

@@ -82,7 +82,7 @@ class JSONSchemaValidator(ValidationRule):
     Parameters
     ----------
     schema : dict
-        JSON schema to validate against.
+        A dictionary representing the JSON schema to validate against.
 
     Examples
     --------
@@ -100,6 +100,11 @@ class JSONSchemaValidator(ValidationRule):
         ----------
         schema : dict
             JSON schema dictionary.
+
+        Raises
+        ------
+        ValueError
+            If the schema is not a valid dictionary.
         """
         self.schema = schema
 
@@ -186,6 +191,11 @@ class SemanticValidator(ValidationRule):
             Phrases that must not appear.
         must_reference_sources : bool
             Check for source references.
+
+        Raises
+        ------
+        ValueError
+            If any of the parameters are not of the expected type.
         """
         self.must_contain = must_contain or []
         self.must_not_contain = must_not_contain or []
@@ -281,6 +291,11 @@ class LengthValidator(ValidationRule):
             Minimum word count.
         max_words : int, optional
             Maximum word count.
+
+        Raises
+        ------
+        ValueError
+            If any of the parameters are not integers.
         """
         self.min_length = min_length
         self.max_length = max_length
@@ -354,6 +369,11 @@ class OutputValidator:
         ----------
         rules : list[ValidationRule], optional
             Initial validation rules.
+
+        Raises
+        ------
+        ValueError
+            If rules is not a list of ValidationRule instances.
         """
         self.rules = rules or []