openai-sdk-helpers 0.4.2__py3-none-any.whl → 0.5.0__py3-none-any.whl

openai_sdk_helpers/utils/json/base_model.py

@@ -7,14 +7,20 @@ customizable _serialize_fields/_deserialize_fields hooks.
 
 from __future__ import annotations
 
+from enum import Enum
 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
+import inspect
+import logging
+import ast
+from typing import Any, ClassVar, TypeVar, get_args, get_origin
+from pydantic import BaseModel, ConfigDict
+from ...logging import log
+
+from .utils import customJSONEncoder
 
 P = TypeVar("P", bound="BaseModelJSONSerializable")
+_SENTINEL = object()
 
 
 class BaseModelJSONSerializable(BaseModel):
@@ -49,6 +55,89 @@ class BaseModelJSONSerializable(BaseModel):
     {'name': 'test', 'value': 42}
     """
 
+    @staticmethod
+    def format_output(label: str, *, value: Any) -> str:
+        """
+        Format a label and value for string output.
+
+        Handles None values and lists appropriately.
+
+        Parameters
+        ----------
+        label : str
+            Label describing the value.
+        value : Any
+            Value to format for display.
+
+        Returns
+        -------
+        str
+            Formatted string (for example ``"- Label: Value"``).
+        """
+        if value is None:
+            return f"- {label}: None"
+        if isinstance(value, list):
+            formatted = ", ".join(str(v) for v in value)
+            return f"- {label}: {formatted or '[]'}"
+        return f"- {label}: {str(value)}"
+
+    def __repr__(self) -> str:
+        """
+        Generate a string representation of the model fields.
+
+        Returns
+        -------
+        str
+            Formatted string for the model fields.
+        """
+        return "\n".join(
+            [
+                BaseModelJSONSerializable.format_output(field, value=value)
+                for field, value in self.model_dump().items()
+            ]
+        )
+
+    def __str__(self) -> str:
+        """
+        Generate a string representation of the model fields.
+
+        Returns
+        -------
+        str
+            Formatted string for the model fields.
+        """
+        return self.__repr__()
+
+    def to_markdown(self) -> str:
+        """
+        Generate a markdown representation of the model fields.
+
+        Returns
+        -------
+        str
+            Formatted markdown string for the model fields.
+        """
+        return self.__repr__()
+
+    @classmethod
+    def _get_all_fields(cls) -> dict[Any, Any]:
+        """Collect all fields from the class hierarchy including inherited ones.
+
+        Traverses the method resolution order (MRO) to gather fields from
+        all parent classes that inherit from BaseModel, ensuring inherited
+        fields are included in schema generation.
+
+        Returns
+        -------
+        dict[Any, Any]
+            Mapping of field names to Pydantic ModelField instances.
+        """
+        fields = {}
+        for base in reversed(cls.__mro__):  # Traverse inheritance tree
+            if issubclass(base, BaseModel) and hasattr(base, "model_fields"):
+                fields.update(base.model_fields)  # Merge fields from parent
+        return fields
+
     def to_json(self) -> dict[str, Any]:
         """Return a JSON-compatible dict representation.
 
@@ -57,11 +146,7 @@ class BaseModelJSONSerializable(BaseModel):
         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))
+        return self.model_dump()
 
     def to_json_file(self, filepath: str | Path) -> str:
         """Write serialized JSON data to a file path.
@@ -76,6 +161,8 @@ class BaseModelJSONSerializable(BaseModel):
         str
             Absolute path to the written file.
         """
+        from .. import check_filepath
+
         target = Path(filepath)
         check_filepath(fullfilepath=str(target))
         with open(target, "w", encoding="utf-8") as handle:
@@ -88,62 +175,216 @@ class BaseModelJSONSerializable(BaseModel):
             )
         return str(target)
 
-    def _serialize_fields(self, data: dict[str, Any]) -> dict[str, Any]:
-        """Customize field serialization.
+    @classmethod
+    def _extract_enum_class(cls, field_type: Any) -> type[Enum] | None:
+        """Extract an Enum class from a field's type annotation.
 
-        Override this method in subclasses to add custom serialization logic.
+        Handles direct Enum types, list[Enum], and optional Enums.
 
         Parameters
         ----------
-        data : dict[str, Any]
-            Pre-serialized data dictionary.
+        field_type : Any
+            Type annotation of a field.
 
         Returns
         -------
-        dict[str, Any]
-            Modified data dictionary.
+        type[Enum] or None
+            Enum class if found, otherwise None.
         """
-        return data
+        origin = get_origin(field_type)
+        args = get_args(field_type)
+
+        if inspect.isclass(field_type) and issubclass(field_type, Enum):
+            return field_type
+        elif (
+            origin is list
+            and args
+            and inspect.isclass(args[0])
+            and issubclass(args[0], Enum)
+        ):
+            return args[0]
+        elif origin is not None:
+            # Handle Union types
+            for arg in args:
+                enum_cls = cls._extract_enum_class(arg)
+                if enum_cls:
+                    return enum_cls
+        return None
 
     @classmethod
-    def _deserialize_fields(cls, data: dict[str, Any]) -> dict[str, Any]:
-        """Customize field deserialization.
+    def _try_coerce_value(cls, field_name: str, field_type: Any, raw_value: Any) -> Any:
+        """Attempt to coerce a raw value to a specific field type.
 
-        Override this method in subclasses to add custom deserialization logic.
+        Parameters
+        ----------
+        field_name : str
+            Field name being converted.
+        field_type : Any
+            Field type annotation to coerce into.
+        raw_value : Any
+            Value to coerce.
+
+        Returns
+        -------
+        Any
+            Coerced value when conversion is possible, otherwise a sentinel
+            indicating no conversion was applied.
+        """
+        if inspect.isclass(field_type):
+            if issubclass(field_type, Enum):
+                enum_value = cls._coerce_enum_value(field_name, field_type, raw_value)
+                return enum_value
+            if issubclass(field_type, BaseModelJSONSerializable):
+                if isinstance(raw_value, field_type):
+                    return raw_value
+                if isinstance(raw_value, dict):
+                    return field_type.from_json(raw_value)
+                return _SENTINEL
+
+        origin = get_origin(field_type)
+        args = get_args(field_type)
+        if origin is list and args:
+            if not isinstance(raw_value, list):
+                return _SENTINEL
+            item_type = args[0]
+            enum_cls = cls._extract_enum_class(item_type)
+            converted_items = []
+            for item in raw_value:
+                converted_item = cls._coerce_field_value(field_name, item_type, item)
+                if converted_item is None and enum_cls is not None:
+                    continue
+                converted_items.append(converted_item)
+            return converted_items
+        return _SENTINEL
+
+    @classmethod
+    def _coerce_field_value(
+        cls, field_name: str, field_type: Any, raw_value: Any
+    ) -> Any:
+        """Coerce a raw value based on the field's type annotation.
 
         Parameters
         ----------
-        data : dict[str, Any]
-            Raw data dictionary from JSON.
+        field_name : str
+            Field name being converted.
+        field_type : Any
+            Field type annotation to coerce into.
+        raw_value : Any
+            Value to coerce.
 
         Returns
         -------
-        dict[str, Any]
-            Modified data dictionary.
+        Any
+            Coerced value when conversion is possible, otherwise the original
+            raw value.
+        """
+        origin = get_origin(field_type)
+        args = get_args(field_type)
+
+        if origin is not None and origin is not list:
+            for arg in args:
+                if arg is type(None):
+                    continue
+                converted = cls._try_coerce_value(field_name, arg, raw_value)
+                if converted is not _SENTINEL:
+                    return converted
+            return raw_value
+
+        converted = cls._try_coerce_value(field_name, field_type, raw_value)
+        return raw_value if converted is _SENTINEL else converted
+
+    @classmethod
+    def _build_enum_field_mapping(cls) -> dict[str, type[Enum]]:
+        """Build a mapping from field names to their Enum classes.
+
+        Used by from_json to correctly process enum values from raw API
+        responses.
+
+        Returns
+        -------
+        dict[str, type[Enum]]
+            Mapping of field names to Enum types.
+        """
+        mapping: dict[str, type[Enum]] = {}
+
+        for name, model_field in cls.model_fields.items():
+            field_type = model_field.annotation
+            enum_cls = cls._extract_enum_class(field_type)
+
+            if enum_cls is not None:
+                mapping[name] = enum_cls
+
+        return mapping
+
+    @classmethod
+    def _coerce_enum_value(
+        cls, field_name: str, enum_cls: type[Enum], raw_value: Any
+    ) -> Enum | None:
+        """Coerce a raw enum value into an Enum member.
+
+        Parameters
+        ----------
+        field_name : str
+            Field name being converted.
+        enum_cls : type[Enum]
+            Enum class to coerce into.
+        raw_value : Any
+            Value to coerce into an Enum member.
+
+        Returns
+        -------
+        Enum or None
+            Enum member when conversion succeeds, otherwise None.
         """
-        return data
+        if isinstance(raw_value, enum_cls):
+            return raw_value
+        if isinstance(raw_value, str):
+            if raw_value in enum_cls._value2member_map_:
+                return enum_cls(raw_value)
+            if raw_value in enum_cls.__members__:
+                return enum_cls.__members__[raw_value]
+        log(
+            message=(
+                f"[{cls.__name__}] Invalid value for '{field_name}': "
+                f"'{raw_value}' not in {enum_cls.__name__}"
+            ),
+            level=logging.WARNING,
+        )
+        return None
 
     @classmethod
     def from_json(cls: type[P], data: dict[str, Any]) -> P:
-        """Create an instance from a JSON-compatible dict.
+        """Construct an instance from a dictionary of raw input data.
+
+        Particularly useful for converting data from OpenAI API tool calls
+        or assistant outputs into validated structure instances. Handles
+        enum value conversion automatically.
 
         Parameters
         ----------
         data : dict[str, Any]
-            JSON-compatible dictionary containing the instance data.
+            Raw input data dictionary from API response.
 
         Returns
         -------
         P
-            New instance of the class.
+            Validated instance of the model class.
 
         Examples
         --------
-        >>> json_data = {"name": "test", "value": 42}
-        >>> instance = MyConfig.from_json(json_data)
+        >>> raw_data = {"title": "Test", "score": 0.95}
+        >>> instance = MyStructure.from_json(raw_data)
         """
-        processed_data = cls._deserialize_fields(data)
-        return cls(**processed_data)  # type: ignore[return-value]
+        clean_data = data.copy()
+        for field_name, model_field in cls.model_fields.items():
+            raw_value = clean_data.get(field_name)
+            if raw_value is None:
+                continue
+            clean_data[field_name] = cls._coerce_field_value(
+                field_name, model_field.annotation, raw_value
+            )
+
+        return cls(**clean_data)
 
     @classmethod
     def from_json_file(cls: type[P], filepath: str | Path) -> P:
@@ -166,7 +407,7 @@ class BaseModelJSONSerializable(BaseModel):
 
         Examples
         --------
-        >>> instance = MyConfig.from_json_file("config.json")
+        >>> instance = MyConfig.from_json_file("configuration.json")
         """
         target = Path(filepath)
         if not target.exists():
@@ -177,5 +418,47 @@ class BaseModelJSONSerializable(BaseModel):
 
         return cls.from_json(data)
 
+    @classmethod
+    def from_string(cls: type[P], arguments: str) -> P:
+        """Parse tool call arguments which may not be valid JSON.
+
+        The OpenAI API is expected to return well-formed JSON for tool arguments,
+        but minor formatting issues (such as the use of single quotes) can occur.
+        This helper first tries ``json.loads`` and falls back to
+        ``ast.literal_eval`` for simple cases.
+
+        Parameters
+        ----------
+        arguments : str
+            Raw argument string from the tool call.
+
+        Returns
+        -------
+        P
+            Parsed model instance from the arguments.
+
+        Raises
+        ------
+        ValueError
+            If the arguments cannot be parsed as JSON.
+
+        Examples
+        --------
+        >>> MyModel.from_string('{"key": "value"}').key
+        'value'
+        """
+        try:
+            structured_data = json.loads(arguments)
+
+        except json.JSONDecodeError:
+            try:
+                structured_data = ast.literal_eval(arguments)
+            except (SyntaxError, ValueError) as exc:
+                raise ValueError(
+                    f"Invalid JSON arguments: {arguments}. "
+                    f"Expected valid JSON or Python literal."
+                ) from exc
+        return cls.from_json(structured_data)
+
 
 __all__ = ["BaseModelJSONSerializable"]

openai_sdk_helpers/utils/json/data_class.py

@@ -180,7 +180,7 @@ class DataclassJSONSerializable:
 
         Examples
         --------
-        >>> instance = MyClass.from_json_file("config.json")
+        >>> instance = MyClass.from_json_file("configuration.json")
         """
         target = Path(filepath)
         if not target.exists():

openai_sdk_helpers/utils/langextract.py

@@ -0,0 +1,194 @@
+"""LangExtract integration helpers.
+
+This module provides a thin adapter around LangExtract-style extractors to
+normalize how extraction results are collected and validated.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Protocol, TypeVar
+
+from pydantic import BaseModel
+
+TModel = TypeVar("TModel", bound=BaseModel)
+
+
+class LangExtractCallable(Protocol):
+    """Define callable LangExtract extractor behavior.
+
+    Methods
+    -------
+    __call__
+        Extract structured data from text.
+    """
+
+    def __call__(self, text: str, **kwargs: Any) -> Any:
+        """Extract structured data from text.
+
+        Parameters
+        ----------
+        text : str
+            Source text to extract from.
+        **kwargs : Any
+            Extra keyword arguments forwarded to the extractor.
+
+        Returns
+        -------
+        Any
+            Extracted structured data.
+        """
+
+
+class LangExtractExtractor(Protocol):
+    """Define LangExtract extractor object behavior.
+
+    Methods
+    -------
+    extract
+        Extract structured data from text.
+    """
+
+    def extract(self, text: str, **kwargs: Any) -> Any:
+        """Extract structured data from text.
+
+        Parameters
+        ----------
+        text : str
+            Source text to extract from.
+        **kwargs : Any
+            Extra keyword arguments forwarded to the extractor.
+
+        Returns
+        -------
+        Any
+            Extracted structured data.
+        """
+
+
+@dataclass(frozen=True)
+class LangExtractAdapter:
+    """Adapt LangExtract extractors to a consistent interface.
+
+    Parameters
+    ----------
+    extractor : LangExtractCallable | LangExtractExtractor
+        Callable or object providing an ``extract`` method.
+
+    Methods
+    -------
+    extract
+        Extract structured data from text with the configured extractor.
+    extract_to_model
+        Extract structured data and validate it into a Pydantic model.
+    """
+
+    extractor: LangExtractCallable | LangExtractExtractor
+
+    def extract(self, text: str, **kwargs: Any) -> Any:
+        """Extract structured data from text.
+
+        Parameters
+        ----------
+        text : str
+            Source text to extract from.
+        **kwargs : Any
+            Extra keyword arguments forwarded to the underlying extractor.
+
+        Returns
+        -------
+        Any
+            Extracted structured data.
+
+        Raises
+        ------
+        TypeError
+            If the configured extractor cannot be called.
+        """
+        if hasattr(self.extractor, "extract"):
+            extractor = self.extractor  # type: ignore[assignment]
+            return extractor.extract(text, **kwargs)  # type: ignore[union-attr]
+        if callable(self.extractor):
+            return self.extractor(text, **kwargs)
+        raise TypeError("LangExtract extractor must be callable or expose extract().")
+
+    def extract_to_model(
+        self,
+        text: str,
+        model: type[TModel],
+        **kwargs: Any,
+    ) -> TModel:
+        """Extract structured data and validate it into a Pydantic model.
+
+        Parameters
+        ----------
+        text : str
+            Source text to extract from.
+        model : type[BaseModel]
+            Pydantic model class to validate the extracted data.
+        **kwargs : Any
+            Extra keyword arguments forwarded to the underlying extractor.
+
+        Returns
+        -------
+        BaseModel
+            Validated Pydantic model instance.
+        """
+        extracted = self.extract(text, **kwargs)
+        return model.model_validate(extracted)
+
+
+def build_langextract_adapter(
+    extractor: LangExtractCallable | LangExtractExtractor | None = None,
+) -> LangExtractAdapter:
+    """Build a LangExtract adapter from an extractor or module defaults.
+
+    Parameters
+    ----------
+    extractor : LangExtractCallable | LangExtractExtractor, optional
+        Explicit extractor instance or callable. If omitted, this function
+        attempts to load LangExtract and use ``langextract.extract`` or
+        ``langextract.Extractor``.
+
+    Returns
+    -------
+    LangExtractAdapter
+        Configured LangExtract adapter.
+
+    Raises
+    ------
+    ImportError
+        If LangExtract cannot be imported.
+    AttributeError
+        If no supported extractor can be resolved.
+    """
+    if extractor is None:
+        langextract_module = _import_langextract_module()
+        if hasattr(langextract_module, "extract"):
+            resolved_extractor = langextract_module.extract
+        elif hasattr(langextract_module, "Extractor"):
+            resolved_extractor = langextract_module.Extractor()
+        else:
+            raise AttributeError(
+                "LangExtract module does not expose extract or Extractor."
+            )
+        return LangExtractAdapter(extractor=resolved_extractor)
+    return LangExtractAdapter(extractor=extractor)
+
+
+def _import_langextract_module() -> Any:
+    """Import the LangExtract module.
+
+    Returns
+    -------
+    Any
+        Imported LangExtract module.
+
+    Raises
+    ------
+    ImportError
+        If LangExtract is not installed or cannot be imported.
+    """
+    import importlib
+
+    return importlib.import_module("langextract")