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

openai_sdk_helpers/structure/base.py

@@ -8,33 +8,158 @@ generation, validation, and serialization.
 from __future__ import annotations
 
 # Standard library imports
-import ast
+import copy
+import dataclasses
 import inspect
 import json
-import logging
 from dataclasses import dataclass
-from enum import Enum
 from pathlib import Path
 from typing import (
     Any,
     ClassVar,
+    Mapping,
     TypeVar,
     cast,
-    get_args,
-    get_origin,
 )
 
 # Third-party imports
 from pydantic import BaseModel, ConfigDict, Field
 from openai.types.responses.response_text_config_param import ResponseTextConfigParam
 
-
 # Internal imports
 
-from ..utils import check_filepath, log, BaseModelJSONSerializable
+from ..utils import check_filepath, BaseModelJSONSerializable
 
 T = TypeVar("T", bound="StructureBase")
-DEFAULT_DATA_PATH: Path | None = None
+
+
+def _add_required_fields(target: dict[str, Any]) -> None:
+    """Ensure every object declares its required properties."""
+    properties = target.get("properties")
+    if isinstance(properties, dict) and properties:
+        target["required"] = sorted(properties.keys())
+    for value in target.values():
+        if isinstance(value, dict):
+            _add_required_fields(value)
+        elif isinstance(value, list):
+            for item in value:
+                if isinstance(item, dict):
+                    _add_required_fields(item)
+
+
+def _enforce_additional_properties(target: Any) -> None:
+    """Ensure every object schema disallows additional properties."""
+    if isinstance(target, dict):
+        schema_type = target.get("type")
+        allows_object_type = schema_type == "object" or (
+            isinstance(schema_type, list)
+            and "object" in schema_type
+            and set(schema_type).issubset({"object", "null"})
+        )
+        if (allows_object_type or "properties" in target) and "$ref" not in target:
+            target.setdefault("properties", {})
+            target["additionalProperties"] = False
+        any_of = target.get("anyOf")
+        if isinstance(any_of, list):
+            for entry in any_of:
+                if not isinstance(entry, dict):
+                    continue
+                entry_type = entry.get("type")
+                entry_allows_object_type = entry_type == "object" or (
+                    isinstance(entry_type, list)
+                    and "object" in entry_type
+                    and set(entry_type).issubset({"object", "null"})
+                )
+                if (
+                    entry_allows_object_type or "properties" in entry
+                ) and "$ref" not in entry:
+                    entry.setdefault("properties", {})
+                    entry["additionalProperties"] = False
+        for value in target.values():
+            _enforce_additional_properties(value)
+    elif isinstance(target, list):
+        for item in target:
+            _enforce_additional_properties(item)
+
+
+def _build_any_value_schema(depth: int = 0) -> dict[str, Any]:
+    """Return a JSON schema fragment describing a permissive JSON value.
+
+    Parameters
+    ----------
+    depth : int, optional
+        Current recursion depth for nested arrays. Defaults to 0.
+
+    Returns
+    -------
+    dict[str, Any]
+        JSON schema fragment describing a permissive value.
+    """
+    value_types = ["string", "integer", "number", "null"]
+    any_of: list[dict[str, Any]] = [{"type": value_type} for value_type in value_types]
+
+    any_of.append(
+        {
+            "type": "object",
+            "properties": {},
+            "additionalProperties": False,
+        }
+    )
+    if depth < 1:
+        any_of.append(
+            {
+                "type": "array",
+                "items": _build_any_value_schema(depth + 1),
+            }
+        )
+
+    return {"anyOf": any_of}
+
+
+def _ensure_items_have_schema(target: Any) -> None:
+    """Ensure array item schemas include type information."""
+    if isinstance(target, dict):
+        items = target.get("items")
+        if isinstance(items, dict):
+            if not items:
+                target["items"] = _build_any_value_schema()
+            else:
+                _ensure_schema_has_type(items)
+        for value in target.values():
+            _ensure_items_have_schema(value)
+    elif isinstance(target, list):
+        for item in target:
+            _ensure_items_have_schema(item)
+
+
+def _ensure_schema_has_type(schema: dict[str, Any]) -> None:
+    """Ensure a schema dictionary includes a type entry when possible."""
+    if "type" in schema or "$ref" in schema:
+        return
+    any_of = schema.get("anyOf")
+    if isinstance(any_of, list):
+        inferred_types: set[str] = set()
+        for entry in any_of:
+            if not isinstance(entry, dict):
+                continue
+            entry_type = entry.get("type")
+            if isinstance(entry_type, str):
+                inferred_types.add(entry_type)
+            elif isinstance(entry_type, list):
+                inferred_types.update(
+                    element for element in entry_type if isinstance(element, str)
+                )
+        if inferred_types:
+            schema["type"] = sorted(inferred_types)
+            return
+    if "properties" in schema:
+        schema["type"] = "object"
+        schema.setdefault("additionalProperties", False)
+        return
+    if "items" in schema:
+        schema["type"] = "array"
+        return
+    schema.update(_build_any_value_schema())
 
 
 class StructureBase(BaseModelJSONSerializable):
@@ -51,9 +176,9 @@ class StructureBase(BaseModelJSONSerializable):
 
     Attributes
     ----------
-    DATA_PATH : Path or None, class attribute
-        Optional location for saving schema files. Set at class level
-        before calling save_schema_to_file.
+    model_config : ConfigDict
+        Pydantic model configuration with strict validation and enum handling.
+
 
     Methods
     -------
@@ -85,8 +210,6 @@ class StructureBase(BaseModelJSONSerializable):
         Produce Field overrides for dynamic schema customization.
     print()
         Return a string representation of the structure.
-    console_print()
-        Print the string representation to stdout.
 
     Examples
     --------
@@ -113,10 +236,9 @@ class StructureBase(BaseModelJSONSerializable):
     """
 
     model_config = ConfigDict(
-        title="OutputStructure", use_enum_values=False, strict=True, extra="forbid"
+        title=__qualname__, use_enum_values=False, strict=True, extra="forbid"
     )
-    DATA_PATH: ClassVar[Path | None] = DEFAULT_DATA_PATH
-    """Optional location for saving schema files."""
+    _schema_cache: ClassVar[dict[type["StructureBase"], dict[str, Any]]] = {}
 
     @classmethod
     def get_prompt(cls, add_enum_values: bool = True) -> str:
@@ -137,31 +259,6 @@ class StructureBase(BaseModelJSONSerializable):
             return "No structured prompt available."
         return "# Output Format\n" + "\n".join(prompt_lines)
 
-    @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.
-
-        Results are computed once per class and cached for performance.
-
-        Returns
-        -------
-        dict[Any, Any]
-            Mapping of field names to Pydantic ModelField instances.
-        """
-        # Use class-level caching for performance
-        cache_attr = "_all_fields_cache"
-        if not hasattr(cls, cache_attr):
-            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
-            setattr(cls, cache_attr, fields)
-        return getattr(cls, cache_attr)
-
     @classmethod
     def _get_field_prompt(
         cls, field_name: str, field, add_enum_values: bool = True
@@ -210,12 +307,12 @@ class StructureBase(BaseModelJSONSerializable):
         )
 
     @classmethod
-    def get_input_prompt_list(cls, add_enum_values: bool = True) -> list[str]:
+    def get_input_prompt_list(cls, add_enums: bool = True) -> list[str]:
         """Dynamically build a structured prompt including inherited fields.
 
         Parameters
         ----------
-        add_enum_values : bool, default=True
+        add_enums : bool, default=True
             Whether enumeration values should be included.
 
         Returns
@@ -226,9 +323,7 @@ class StructureBase(BaseModelJSONSerializable):
         prompt_lines = []
         all_fields = cls._get_all_fields()
         for field_name, field in all_fields.items():
-            prompt_lines.append(
-                cls._get_field_prompt(field_name, field, add_enum_values)
-            )
+            prompt_lines.append(cls._get_field_prompt(field_name, field, add_enums))
         return prompt_lines
 
     @classmethod
@@ -282,7 +377,9 @@ class StructureBase(BaseModelJSONSerializable):
         return assistant_format(cls)
 
     @classmethod
-    def response_tool_definition(cls, tool_name: str, *, tool_description: str) -> dict:
+    def response_tool_definition(
+        cls, tool_name: str, *, tool_description: str | None
+    ) -> dict:
         """Build a chat completion tool definition for this structure.
 
         Creates a function tool definition compatible with the chat
@@ -357,12 +454,17 @@ class StructureBase(BaseModelJSONSerializable):
         - Adds null type for fields with None default
         - Cleans up $ref entries for better compatibility
         - Recursively processes nested structures
+        - Caches the computed schema per class
 
         Examples
         --------
         >>> schema = MyStructure.get_schema()
         >>> print(json.dumps(schema, indent=2))
         """
+        cached_schema = cls._schema_cache.get(cls)
+        if cached_schema is not None:
+            return copy.deepcopy(cached_schema)
+
         schema = cls.model_json_schema()
 
         def clean_refs(obj: Any) -> Any:
@@ -380,18 +482,60 @@ class StructureBase(BaseModelJSONSerializable):
 
         cleaned_schema = cast(dict[str, Any], clean_refs(schema))
 
-        def add_required_fields(target: dict[str, Any]) -> None:
-            """Ensure every object declares its required properties."""
-            properties = target.get("properties")
-            if isinstance(properties, dict) and properties:
-                target["required"] = sorted(properties.keys())
-            for value in target.values():
-                if isinstance(value, dict):
-                    add_required_fields(value)
-                elif isinstance(value, list):
-                    for item in value:
-                        if isinstance(item, dict):
-                            add_required_fields(item)
+        def _resolve_ref(
+            ref: str,
+            root: dict[str, Any],
+            seen: set[str],
+        ) -> dict[str, Any] | None:
+            if not ref.startswith("#/"):
+                return None
+            if ref in seen:
+                return None
+            seen.add(ref)
+
+            current: Any = root
+            for part in ref.lstrip("#/").split("/"):
+                part = part.replace("~1", "/").replace("~0", "~")
+                if isinstance(current, dict) and part in current:
+                    current = current[part]
+                else:
+                    seen.discard(ref)
+                    return None
+            if isinstance(current, dict):
+                resolved = cast(dict[str, Any], json.loads(json.dumps(current)))
+            else:
+                resolved = None
+            seen.discard(ref)
+            return resolved
+
+        def _inline_anyof_refs(obj: Any, root: dict[str, Any], seen: set[str]) -> Any:
+            if isinstance(obj, dict):
+                updated: dict[str, Any] = {}
+                for key, value in obj.items():
+                    if key == "anyOf" and isinstance(value, list):
+                        updated_items = []
+                        for item in value:
+                            if (
+                                isinstance(item, dict)
+                                and "$ref" in item
+                                and "type" not in item
+                            ):
+                                resolved = _resolve_ref(item["$ref"], root, seen)
+                                if resolved is not None:
+                                    item = resolved
+                            updated_items.append(_inline_anyof_refs(item, root, seen))
+                        updated[key] = updated_items
+                    else:
+                        updated[key] = _inline_anyof_refs(value, root, seen)
+                return updated
+            if isinstance(obj, list):
+                return [_inline_anyof_refs(item, root, seen) for item in obj]
+            return obj
+
+        cleaned_schema = cast(
+            dict[str, Any], _inline_anyof_refs(cleaned_schema, schema, set())
+        )
+        _ensure_items_have_schema(cleaned_schema)
 
         nullable_fields = {
             name
@@ -422,242 +566,41 @@ class StructureBase(BaseModelJSONSerializable):
                         if not has_null:
                             any_of.append({"type": "null"})
 
-        add_required_fields(cleaned_schema)
-        return cleaned_schema
+        _add_required_fields(cleaned_schema)
+        _enforce_additional_properties(cleaned_schema)
+        cls._schema_cache[cls] = cleaned_schema
+        return copy.deepcopy(cleaned_schema)
 
     @classmethod
-    def save_schema_to_file(cls) -> Path:
+    def save_schema_to_file(cls, file_path: Path) -> Path:
         """Save the generated JSON schema to a file.
 
-        Generates the schema using get_schema and saves it to a JSON file
-        within the DATA_PATH directory. The filename is derived from the
-        class name.
+        Generates the schema using get_schema and saves it to the provided
+        file path.
+
+        Parameters
+        ----------
+        file_path : Path
+            Full path (including filename) where the schema should be saved.
 
         Returns
         -------
         Path
             Absolute path to the saved schema file.
 
-        Raises
-        ------
-        RuntimeError
-            If DATA_PATH is not set on the class.
 
         Examples
         --------
         >>> MyStructure.DATA_PATH = Path("./schemas")
-        >>> schema_path = MyStructure.save_schema_to_file()
+        >>> schema_path = MyStructure.save_schema_to_file(file_path=MyStructure.DATA_PATH / "MyStructure_schema.json")
         >>> print(schema_path)
         PosixPath('./schemas/MyStructure_schema.json')
         """
-        schema = cls.get_schema()
-        if cls.DATA_PATH is None:
-            raise RuntimeError(
-                "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)
         with file_path.open("w", encoding="utf-8") as file_handle:
-            json.dump(schema, file_handle, indent=2, ensure_ascii=False)
+            json.dump(cls.get_schema(), file_handle, indent=2, ensure_ascii=False)
         return file_path
 
-    @classmethod
-    def _extract_enum_class(cls, field_type: Any) -> type[Enum] | None:
-        """Extract an Enum class from a field's type annotation.
-
-        Handles direct Enum types, list[Enum], and optional Enums.
-
-        Parameters
-        ----------
-        field_type : Any
-            Type annotation of a field.
-
-        Returns
-        -------
-        type[Enum] or None
-            Enum class if found, otherwise None.
-        """
-        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 _build_enum_field_mapping(cls) -> dict[str, type[Enum]]:
-        """Build a mapping from field names to their Enum classes.
-
-        Used by from_raw_input 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 from_raw_input(cls: type[T], data: dict) -> T:
-        """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
-            Raw input data dictionary from API response.
-
-        Returns
-        -------
-        T
-            Validated instance of the structure class.
-
-        Examples
-        --------
-        >>> raw_data = {"title": "Test", "score": 0.95}
-        >>> instance = MyStructure.from_raw_input(raw_data)
-        """
-        mapping = cls._build_enum_field_mapping()
-        clean_data = data.copy()
-
-        for field, enum_cls in mapping.items():
-            raw_value = clean_data.get(field)
-
-            if raw_value is None:
-                continue
-
-            # List of enum values
-            if isinstance(raw_value, list):
-                converted = []
-                for v in raw_value:
-                    if isinstance(v, enum_cls):
-                        converted.append(v)
-                    elif isinstance(v, str):
-                        # Check if it's a valid value
-                        if v in enum_cls._value2member_map_:
-                            converted.append(enum_cls(v))
-                        # Check if it's a valid name
-                        elif v in enum_cls.__members__:
-                            converted.append(enum_cls.__members__[v])
-                        else:
-                            log(
-                                f"[{cls.__name__}] Skipping invalid value for '{field}': '{v}' not in {enum_cls.__name__}",
-                                level=logging.WARNING,
-                            )
-                clean_data[field] = converted
-
-            # Single enum value
-            elif (
-                isinstance(raw_value, str) and raw_value in enum_cls._value2member_map_
-            ):
-                clean_data[field] = enum_cls(raw_value)
-
-            elif isinstance(raw_value, enum_cls):
-                # already the correct type
-                continue
-
-            else:
-                log(
-                    message=f"[{cls.__name__}] Invalid value for '{field}': '{raw_value}' not in {enum_cls.__name__}",
-                    level=logging.WARNING,
-                )
-                clean_data[field] = None
-
-        return cls(**clean_data)
-
-    @classmethod
-    def from_tool_arguments(cls: type[T], arguments: str) -> T:
-        """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
-            Raw argument string from the tool call.
-
-        Returns
-        -------
-        dict
-            Parsed dictionary of arguments.
-
-        Raises
-        ------
-        ValueError
-            If the arguments cannot be parsed as JSON.
-
-        Examples
-        --------
-        >>> parse_tool_arguments('{"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_raw_input(structured_data)
-
-    @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 not value:
-            return f"- {label}: None"
-        if isinstance(value, list):
-            return f"- {label}: {', '.join(str(v) for v in value)}"
-        return f"- {label}: {str(value)}"
-
     @classmethod
     def schema_overrides(cls) -> dict[str, Any]:
         """
@@ -686,14 +629,32 @@ class StructureBase(BaseModelJSONSerializable):
             ]
         )
 
-    def console_print(self) -> None:
-        """Output the result of :meth:`print` to stdout.
+    @classmethod
+    def from_dataclass(cls: type[T], data: Any) -> T:
+        """Create an instance from a dataclass object.
+
+        Parameters
+        ----------
+        data : Any
+            Dataclass instance, mapping, or object with attributes to convert.
+            Private attributes (prefixed with ``_``) are ignored.
 
         Returns
         -------
-        None
+        T
+            New instance of the structure populated from the dataclass.
         """
-        print(self.print())
+
+        def _filter_private(items: list[tuple[str, Any]]) -> dict[str, Any]:
+            return {name: value for name, value in items if not name.startswith("_")}
+
+        if dataclasses.is_dataclass(data) and not isinstance(data, type):
+            payload = dataclasses.asdict(data, dict_factory=_filter_private)
+        elif isinstance(data, Mapping):
+            payload = _filter_private(list(data.items()))
+        else:
+            payload = _filter_private(list(vars(data).items()))
+        return cls(**payload)
 
 
 @dataclass(frozen=True)