symbolicai 0.21.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

symai/models/base.py

@@ -2,12 +2,14 @@ import json
 from enum import Enum
 from functools import lru_cache
 from types import UnionType
-from typing import Any, Literal, Type, Union, get_args, get_origin
+from typing import Any, Literal, Union, get_args, get_origin
 
 from attr import dataclass
 from pydantic import BaseModel, Field, create_model, model_validator
 from pydantic_core import PydanticUndefined
 
+from ..utils import UserMessage
+
 
 @dataclass
 class LengthConstraint:
@@ -22,7 +24,7 @@ class CustomConstraint:
 
 
 def Const(value: str):
-    return Field(default=value, json_schema_extra={'const_value': value})
+    return Field(default=value, json_schema_extra={"const_value": value})
 
 
 class LLMDataModel(BaseModel):
@@ -33,11 +35,9 @@ class LLMDataModel(BaseModel):
 
     _MAX_RECURSION_DEPTH = 50
 
-    section_header: str = Field(
-        default=None, exclude=True, frozen=True
-    )
+    section_header: str = Field(default=None, exclude=True, frozen=True)
 
-    @model_validator(mode='before')
+    @model_validator(mode="before")
     @classmethod
     def validate_const_fields(cls, values):
         """Validate that const fields have their expected values."""
@@ -45,7 +45,7 @@ class LLMDataModel(BaseModel):
             if cls._is_const_field(field_info):
                 const_value = cls._get_const_value(field_info)
                 if field_name in values and values[field_name] != const_value:
-                    raise ValueError(f'{field_name} must be {const_value!r}')
+                    UserMessage(f"{field_name} must be {const_value!r}", raise_with=ValueError)
         return values
 
     @staticmethod
@@ -72,27 +72,32 @@ class LLMDataModel(BaseModel):
     def _is_collection_type(field_type: Any) -> bool:
         """Check if a type is a collection (list, set, tuple, dict, etc.)."""
         origin = get_origin(field_type)
-        return origin in (list, set, frozenset, tuple, dict) or field_type in (list, set, frozenset, tuple, dict)
+        return origin in (list, set, frozenset, tuple, dict) or field_type in (
+            list,
+            set,
+            frozenset,
+            tuple,
+            dict,
+        )
 
     @staticmethod
     def _is_const_field(field_info) -> bool:
         """Check if a field is a const field."""
-        return (
-            field_info.json_schema_extra and
-            'const_value' in field_info.json_schema_extra
-        )
+        return field_info.json_schema_extra and "const_value" in field_info.json_schema_extra
 
     @staticmethod
     def _get_const_value(field_info):
         """Get the const value from a field."""
-        return field_info.json_schema_extra.get('const_value')
+        return field_info.json_schema_extra.get("const_value")
 
     @staticmethod
     def _has_default_value(field_info) -> bool:
         """Check if a field has a default value."""
         return field_info.default != ... and field_info.default != PydanticUndefined
 
-    def format_field(self, key: str, value: Any, indent: int = 0, visited: set = None, depth: int = 0) -> str:
+    def format_field(
+        self, key: str, value: Any, indent: int = 0, visited: set | None = None, depth: int = 0
+    ) -> str:
         """Formats a field value for string representation, handling nested structures."""
         visited = visited or set()
         formatter = self._get_formatter_for_value(value)
@@ -109,22 +114,28 @@ class LLMDataModel(BaseModel):
         }
 
         for type_class, formatter in formatters.items():
-            if type_class == type(None) and value is None:
+            if type_class is type(None) and value is None:
                 return formatter
-            if type_class != type(None) and isinstance(value, type_class):
+            if type_class is not type(None) and isinstance(value, type_class):
                 return formatter
 
         return self._format_primitive_field
 
-    def _format_none_field(self, key: str, value: Any, indent: int, visited: set, depth: int) -> str:
+    def _format_none_field(
+        self, key: str, _value: Any, indent: int, _visited: set, _depth: int
+    ) -> str:
         """Format a None value."""
         return f"{' ' * indent}{key}: None"
 
-    def _format_enum_field(self, key: str, value: Enum, indent: int, visited: set, depth: int) -> str:
+    def _format_enum_field(
+        self, key: str, value: Enum, indent: int, _visited: set, _depth: int
+    ) -> str:
         """Format an Enum value."""
         return f"{' ' * indent}{key}: {value.value}"
 
-    def _format_model_field(self, key: str, value: "LLMDataModel", indent: int, visited: set, depth: int) -> str:
+    def _format_model_field(
+        self, key: str, value: "LLMDataModel", indent: int, visited: set, depth: int
+    ) -> str:
         """Format a nested model field."""
         obj_id = id(value)
         indent_str = " " * indent
@@ -137,7 +148,9 @@ class LLMDataModel(BaseModel):
         visited.discard(obj_id)
         return f"{indent_str}{key}:\n{indent_str}  {nested_str}"
 
-    def _format_list_field(self, key: str, value: list, indent: int, visited: set, depth: int) -> str:
+    def _format_list_field(
+        self, key: str, value: list, indent: int, visited: set, depth: int
+    ) -> str:
         """Format a list field."""
         indent_str = " " * indent
         if not value:
@@ -159,12 +172,16 @@ class LLMDataModel(BaseModel):
                     visited.add(obj_id)
                     item_str = item.__str__(indent + 2, visited, depth + 1).strip()
                     visited.discard(obj_id)
-                    items.append(f"{indent_str}  - : {item_str}" if item_str else f"{indent_str}  - :")
+                    items.append(
+                        f"{indent_str}  - : {item_str}" if item_str else f"{indent_str}  - :"
+                    )
             else:
                 items.append(f"{indent_str}  - : {item}" if item != "" else f"{indent_str}  - :")
         return f"{indent_str}{key}:\n" + "\n".join(items)
 
-    def _format_dict_field(self, key: str, value: dict, indent: int, visited: set, depth: int) -> str:
+    def _format_dict_field(
+        self, key: str, value: dict, indent: int, visited: set, depth: int
+    ) -> str:
         """Format a dictionary field."""
         indent_str = " " * indent
         if not value:
@@ -190,11 +207,13 @@ class LLMDataModel(BaseModel):
         visited.discard(obj_id)
         return f"{indent_str}{key}:\n" + "\n".join(items) if key else "\n".join(items)
 
-    def _format_primitive_field(self, key: str, value: Any, indent: int, visited: set, depth: int) -> str:
+    def _format_primitive_field(
+        self, key: str, value: Any, indent: int, _visited: set, _depth: int
+    ) -> str:
         """Format a primitive field."""
         return f"{' ' * indent}{key}: {value}"
 
-    def __str__(self, indent: int = 0, visited: set = None, depth: int = 0) -> str:
+    def __str__(self, indent: int = 0, visited: set | None = None, depth: int = 0) -> str:
         """
         Converts the model into a formatted string for LLM prompts.
         Handles indentation for nested models and includes an optional section header.
@@ -205,16 +224,10 @@ class LLMDataModel(BaseModel):
         field_list = [
             self.format_field(name, getattr(self, name), indent + 2, visited, depth)
             for name, field in type(self).model_fields.items()
-            if (
-                not getattr(field, "exclude", False)
-                and not name == "section_header"
-            )
+            if (not getattr(field, "exclude", False) and name != "section_header")
         ]
 
-        if field_list:
-            fields = "\n".join(field_list) + "\n"
-        else:
-            fields = ""
+        fields = "\n".join(field_list) + "\n" if field_list else ""
 
         if self.section_header and indent == 0:
             header = f"{indent_str}[[{self.section_header}]]\n"
@@ -227,7 +240,7 @@ class LLMDataModel(BaseModel):
 
     def remedy(self):
         """Default remedy method for the model."""
-        return None
+        return
 
     @classmethod
     @lru_cache(maxsize=128)
@@ -281,8 +294,15 @@ class LLMDataModel(BaseModel):
         return schema.get("$defs", schema.get("definitions", {}))
 
     @classmethod
-    def _format_schema_field(cls, name: str, field_schema: dict, required: bool,
-                            definitions: dict, indent_level: int, visited: set = None) -> str:
+    def _format_schema_field(
+        cls,
+        name: str,
+        field_schema: dict,
+        required: bool,
+        definitions: dict,
+        indent_level: int,
+        visited: set | None = None,
+    ) -> str:
         """Format a single schema field without descriptions (kept for definitions)."""
         visited = visited or set()
 
@@ -312,27 +332,38 @@ class LLMDataModel(BaseModel):
         return result
 
     @classmethod
-    def _format_referenced_object_fields(cls, ref_name: str, definitions: dict,
-                                        indent_level: int, visited: set) -> str:
+    def _format_referenced_object_fields(
+        cls, ref_name: str, definitions: dict, indent_level: int, visited: set
+    ) -> str:
         """Format nested fields for a referenced object definition by name."""
         if ref_name in definitions and ref_name not in visited:
             visited.add(ref_name)
             return cls._format_schema_fields(
                 definitions[ref_name].get("properties", {}),
-                definitions[ref_name], definitions, indent_level + 1, visited.copy()
+                definitions[ref_name],
+                definitions,
+                indent_level + 1,
+                visited.copy(),
             )
         return ""
 
     @classmethod
-    def _format_array_referenced_object_fields(cls, field_schema: dict, definitions: dict,
-                                              indent_level: int, visited: set) -> str:
+    def _format_array_referenced_object_fields(
+        cls, field_schema: dict, definitions: dict, indent_level: int, visited: set
+    ) -> str:
         """Format nested fields for arrays referencing object definitions."""
         ref_name = field_schema.get("items", {}).get("$ref", "").split("/")[-1]
         return cls._format_referenced_object_fields(ref_name, definitions, indent_level, visited)
 
     @classmethod
-    def _format_schema_fields(cls, properties: dict, schema: dict, definitions: dict,
-                             indent_level: int, visited: set = None) -> str:
+    def _format_schema_fields(
+        cls,
+        properties: dict,
+        schema: dict,
+        definitions: dict,
+        indent_level: int,
+        visited: set | None = None,
+    ) -> str:
         """Format multiple schema fields."""
         visited = visited or set()
         required_fields = set(schema.get("required", []))
@@ -343,8 +374,12 @@ class LLMDataModel(BaseModel):
                 continue
             lines.append(
                 cls._format_schema_field(
-                    name, field_schema, name in required_fields,
-                    definitions, indent_level, visited.copy()
+                    name,
+                    field_schema,
+                    name in required_fields,
+                    definitions,
+                    indent_level,
+                    visited.copy(),
                 )
             )
 
@@ -398,10 +433,7 @@ class LLMDataModel(BaseModel):
     @classmethod
     def _resolve_union_type(cls, schemas: list, definitions: dict, separator: str) -> str:
         """Resolve union types (anyOf/oneOf)."""
-        subtypes = [
-            cls._resolve_field_type(subschema, definitions)
-            for subschema in schemas
-        ]
+        subtypes = [cls._resolve_field_type(subschema, definitions) for subschema in schemas]
         return separator.join(subtypes)
 
     @classmethod
@@ -460,138 +492,180 @@ class LLMDataModel(BaseModel):
         Also includes the root model's fields (from root_schema) so their descriptions/examples
         are visible, not just $defs.
         """
-        lines = []
-        visited_defs = set()
-
-        def _format_definition_properties(props: dict) -> list[str]:
-            """Render property lines using only Field(description=...), with const/excerpts.
-
-            Always lists properties; if description is missing, emit a generic guidance message.
-            """
-            out: list[str] = []
-            def _fmt_example_value(val):
-                if isinstance(val, str):
-                    return val
-                try:
-                    return json.dumps(val, ensure_ascii=False)
-                except Exception:
-                    return str(val)
-            for prop_name, prop_schema in props.items():
-                if prop_name == "section_header":
-                    continue
-                desc = prop_schema.get("description")
-                const_note = ""
-                if "const_value" in prop_schema:
-                    const_note = f' (const value: "{prop_schema["const_value"]}")'
-                if not desc:
-                    out.append(
-                        f'  - "{prop_name}": '
-                        'No definition provided. Focus on the [[Schema]] and the prompt to infer '
-                        'the expected structure and constraints.'
-                    )
-                else:
-                    out.append(f'  - "{prop_name}": {desc}{const_note}')
-
-                examples = prop_schema.get("examples")
-                if examples is None and "example" in prop_schema:
-                    examples = prop_schema.get("example")
-
-                if isinstance(examples, (list, tuple)):
-                    if len(examples) > 0:
-                        out.append("    - Examples:")
-                        for ex in examples:
-                            out.append(f"      - {_fmt_example_value(ex)}")
-                elif examples is not None:
-                    out.append(f"    - Example: {_fmt_example_value(examples)}")
-            return out
-
-        # Include root model's fields in Definitions (for descriptions/examples)
-        if root_schema and isinstance(root_schema, dict):
-            root_title = root_schema.get("title", "Root")
-            root_props = cls._extract_schema_properties(root_schema)
-            if root_props:
-                lines.append(f"- {root_title}:")
-                lines.extend(_format_definition_properties(root_props))
+        lines: list[str] = []
+        visited_defs: set[str] = set()
+
+        lines.extend(cls._format_root_definition_lines(root_schema))
 
         for name, definition in definitions.items():
             if name in visited_defs:
                 continue
             visited_defs.add(name)
-            lines.append(f"- {name}:")
+            lines.extend(cls._format_single_definition(name, definition))
 
-            if "enum" in definition:
-                enum_values = ", ".join(map(repr, definition["enum"]))
-                lines.append(f"  Enum values: {enum_values}")
+        return "\n".join(lines)
+
+    @classmethod
+    def _format_root_definition_lines(cls, root_schema: dict | None) -> list[str]:
+        """Format definitions derived from the root schema."""
+        if not (root_schema and isinstance(root_schema, dict)):
+            return []
+        root_props = cls._extract_schema_properties(root_schema)
+        if not root_props:
+            return []
+        root_title = root_schema.get("title", "Root")
+        lines = [f"- {root_title}:"]
+        lines.extend(cls._format_definition_properties(root_props))
+        return lines
+
+    @classmethod
+    def _format_single_definition(cls, name: str, definition: dict) -> list[str]:
+        """Format a single definition block, including enum handling."""
+        lines = [f"- {name}:"]
+        if "enum" in definition:
+            enum_values = ", ".join(map(repr, definition["enum"]))
+            lines.append(f"  Enum values: {enum_values}")
+            return lines
+        props = definition.get("properties", {})
+        lines.extend(cls._format_definition_properties(props))
+        return lines
+
+    @classmethod
+    def _format_definition_properties(cls, props: dict) -> list[str]:
+        """Render property lines using descriptions and examples."""
+        out: list[str] = []
+        for prop_name, prop_schema in props.items():
+            if prop_name == "section_header":
                 continue
+            out.append(cls._format_property_description(prop_name, prop_schema))
+            out.extend(cls._format_property_examples(prop_schema))
+        return out
 
-            props = definition.get("properties", {})
-            lines.extend(_format_definition_properties(props))
+    @staticmethod
+    def _format_property_description(prop_name: str, prop_schema: dict) -> str:
+        """Format the description line for a property, including const hints."""
+        desc = prop_schema.get("description")
+        const_note = ""
+        if "const_value" in prop_schema:
+            const_note = f' (const value: "{prop_schema["const_value"]}")'
+        if not desc:
+            return (
+                f'  - "{prop_name}": '
+                "No definition provided. Focus on the [[Schema]] and the prompt to infer "
+                "the expected structure and constraints."
+            )
+        return f'  - "{prop_name}": {desc}{const_note}'
 
-        return "\n".join(lines)
+    @classmethod
+    def _format_property_examples(cls, prop_schema: dict) -> list[str]:
+        """Format example lines for a property schema."""
+        examples = prop_schema.get("examples")
+        if examples is None and "example" in prop_schema:
+            examples = prop_schema.get("example")
+        if isinstance(examples, (list, tuple)):
+            if not examples:
+                return []
+            lines = ["    - Examples:"]
+            for example in examples:
+                lines.append(f"      - {cls._format_example_value(example)}")
+            return lines
+        if examples is not None:
+            return [f"    - Example: {cls._format_example_value(examples)}"]
+        return []
+
+    @staticmethod
+    def _format_example_value(val: Any) -> str:
+        """Safely format example values for display, preserving human readability."""
+        if isinstance(val, str):
+            return val
+        try:
+            return json.dumps(val, ensure_ascii=False)
+        except Exception:
+            return str(val)
 
     @classmethod
     def _generate_type_description(cls, type_desc: str | dict) -> str:
         """Generate a human-readable description for a type."""
-        if type_desc is None:
+        normalized = cls._normalize_type_descriptor(type_desc)
+        if normalized is None:
             return "unknown"
 
+        composite_description = cls._describe_composite_type(normalized)
+        return composite_description if composite_description is not None else normalized
+
+    @classmethod
+    def _normalize_type_descriptor(cls, type_desc: Any) -> str | None:
+        """Normalize a type descriptor into a descriptive string."""
+        if type_desc is None:
+            return None
         if isinstance(type_desc, dict):
             type_desc = cls._resolve_field_type(type_desc, {})
-
         if isinstance(type_desc, type):
             type_desc = type_desc.__name__
-
         if not isinstance(type_desc, str):
             type_desc = str(type_desc)
+        return type_desc
 
-        def extract_after(text: str, prefix: str) -> str:
-            """Extract text after prefix if it starts with it."""
-            return text.replace(prefix, "", 1) if text.startswith(prefix) else None
-
-        # Define type mappings
-        type_prefixes = {
-            "array of": ("list", "A list"),
-            "set of": ("set", "A set"),
-            "tuple of": ("tuple", "A tuple with specific types:"),
-            "object of": ("dict", "A dictionary"),
+    @classmethod
+    def _describe_composite_type(cls, type_desc: str) -> str | None:
+        """Describe composite collection-like types with friendly language."""
+        handlers = {
+            "array of ": cls._describe_list_type,
+            "set of ": cls._describe_set_type,
+            "tuple of ": cls._describe_tuple_type,
+            "object of ": cls._describe_dict_type,
         }
+        for prefix, handler in handlers.items():
+            if type_desc.startswith(prefix):
+                item_type = type_desc[len(prefix) :]
+                return handler(item_type)
+        return None
 
-        for prefix, (type_name, description) in type_prefixes.items():
-            if item_type := extract_after(type_desc, prefix + " "):
-                if prefix == "tuple of":
-                    return f"{description} {item_type}"
-
-                # Handle nested types
-                if item_type.startswith("nested object"):
-                    element_desc = item_type
-                elif inner := extract_after(item_type, "array of "):
-                    element_desc = f"a list of {inner} values"
-                elif inner := extract_after(item_type, "set of "):
-                    element_desc = f"a set of unique {inner} values"
-                elif inner := extract_after(item_type, "tuple of "):
-                    element_desc = f"a tuple with types: {inner}"
-                elif inner := extract_after(item_type, "object of "):
-                    element_desc = f"a dictionary with {inner} values"
-                else:
-                    # Simple types
-                    if type_name == "list":
-                        return f"A list containing {item_type} values"
-                    elif type_name == "set":
-                        return f"A set containing unique {item_type} values"
-                    elif type_name == "dict":
-                        return f"A dictionary with {item_type} values"
-                    else:
-                        element_desc = item_type
-
-                # Format the final description
-                if type_name == "list":
-                    return f"A list where each element is {element_desc}"
-                elif type_name == "set":
-                    return f"A set where each element is {element_desc}"
-                elif type_name == "dict":
-                    return f"A dictionary where each value is {element_desc}"
+    @classmethod
+    def _describe_list_type(cls, item_type: str) -> str:
+        """Describe a list-style type."""
+        element_desc = cls._nested_element_description(item_type)
+        if element_desc is None:
+            return f"A list containing {item_type} values"
+        return f"A list where each element is {element_desc}"
 
-        return type_desc
+    @classmethod
+    def _describe_set_type(cls, item_type: str) -> str:
+        """Describe a set-style type."""
+        element_desc = cls._nested_element_description(item_type)
+        if element_desc is None:
+            return f"A set containing unique {item_type} values"
+        return f"A set where each element is {element_desc}"
+
+    @staticmethod
+    def _describe_tuple_type(item_type: str) -> str:
+        """Describe a tuple-style type."""
+        return f"A tuple with specific types: {item_type}"
+
+    @classmethod
+    def _describe_dict_type(cls, item_type: str) -> str:
+        """Describe a dictionary-style type."""
+        element_desc = cls._nested_element_description(item_type)
+        if element_desc is None:
+            return f"A dictionary with {item_type} values"
+        return f"A dictionary where each value is {element_desc}"
+
+    @staticmethod
+    def _nested_element_description(item_type: str) -> str | None:
+        """Convert nested composite descriptors into human-friendly text."""
+        if item_type.startswith("nested object"):
+            return item_type
+        nested_mappings = {
+            "array of ": "a list of {} values",
+            "set of ": "a set of unique {} values",
+            "tuple of ": "a tuple with types: {}",
+            "object of ": "a dictionary with {} values",
+        }
+        for prefix, template in nested_mappings.items():
+            if item_type.startswith(prefix):
+                inner = item_type[len(prefix) :]
+                return template.format(inner)
+        return None
 
     @classmethod
     def _compose_schema_output(cls, main_schema: str, definitions_schema: str) -> str:
@@ -612,7 +686,7 @@ class LLMDataModel(BaseModel):
         return cls._generate_example_for_model(model, visited_models)
 
     @staticmethod
-    def _generate_example_for_model(model: Type[BaseModel], visited_models: set) -> dict:
+    def _generate_example_for_model(model: type[BaseModel], visited_models: set) -> dict:
         """Generate example for a model, excluding section_header."""
         example = {}
         for field_name, model_field in model.model_fields.items():
@@ -630,35 +704,35 @@ class LLMDataModel(BaseModel):
 
         if LLMDataModel._has_default_value(model_field):
             default_val = model_field.default
-            desc = getattr(model_field, 'description', None)
-            ann = getattr(model_field, 'annotation', None)
+            desc = getattr(model_field, "description", None)
+            ann = getattr(model_field, "annotation", None)
             is_desc_like = isinstance(default_val, str) and (
-                (desc and default_val.strip() == str(desc).strip()) or
-                len(default_val) >= 30 or
-                any(kw in default_val for kw in ["represents", "should", "Always use", "This is", "This represents"])
+                (desc and default_val.strip() == str(desc).strip())
+                or len(default_val) >= 30
+                or any(
+                    kw in default_val
+                    for kw in ["represents", "should", "Always use", "This is", "This represents"]
+                )
             )
             if is_desc_like and (ann is str or ann is Any or ann is None):
                 return "example_string"
             return default_val
-        elif model_field.default_factory is not None:
+        if model_field.default_factory is not None:
             # For example generation, we want to show structure even if default is empty
             # Check if default_factory would produce an empty container
             default_val = model_field.default_factory()
             if isinstance(default_val, (list, dict, set, tuple)) and len(default_val) == 0:
                 # Generate example data instead of using empty default
-                return LLMDataModel._generate_value_for_type(
-                    model_field.annotation, visited_models
-                )
+                return LLMDataModel._generate_value_for_type(model_field.annotation, visited_models)
             return default_val
-        else:
-            return LLMDataModel._generate_value_for_type(
-                model_field.annotation, visited_models
-            )
+        return LLMDataModel._generate_value_for_type(model_field.annotation, visited_models)
 
     @staticmethod
     def _generate_value_for_type(field_type: Any, visited_models: set) -> Any:
         """Generate a value for a specific type (standard behavior)."""
-        return LLMDataModel._generate_value_for_type_generic(field_type, visited_models, prefer_non_null=False)
+        return LLMDataModel._generate_value_for_type_generic(
+            field_type, visited_models, prefer_non_null=False
+        )
 
     @staticmethod
     def _generate_union_value(field_type: Any, visited_models: set) -> Any:
@@ -666,7 +740,9 @@ class LLMDataModel(BaseModel):
         subtypes = LLMDataModel._get_union_types(field_type, exclude_none=True)
         if not subtypes:
             return None
-        return LLMDataModel._generate_value_for_type_generic(subtypes[0], visited_models, prefer_non_null=False)
+        return LLMDataModel._generate_value_for_type_generic(
+            subtypes[0], visited_models, prefer_non_null=False
+        )
 
     @staticmethod
     def _generate_collection_value(field_type: Any, visited_models: set) -> Any:
@@ -691,7 +767,10 @@ class LLMDataModel(BaseModel):
 
         if LLMDataModel._is_union_type(item_type):
             subtypes = LLMDataModel._get_union_types(item_type)
-            return [LLMDataModel._generate_value_for_type_generic(subtype, visited_models, False) for subtype in subtypes[:2]]
+            return [
+                LLMDataModel._generate_value_for_type_generic(subtype, visited_models, False)
+                for subtype in subtypes[:2]
+            ]
 
         return [LLMDataModel._generate_value_for_type_generic(item_type, visited_models, False)]
 
@@ -701,7 +780,11 @@ class LLMDataModel(BaseModel):
         key_type, value_type = get_args(field_type) if get_args(field_type) else (Any, Any)
 
         example_key = LLMDataModel._example_key_for_type(key_type, visited_models)
-        return {example_key: LLMDataModel._generate_value_for_type_generic(value_type, visited_models, False)}
+        return {
+            example_key: LLMDataModel._generate_value_for_type_generic(
+                value_type, visited_models, False
+            )
+        }
 
     @staticmethod
     def _generate_set_value(field_type: Any, visited_models: set) -> list:
@@ -714,7 +797,10 @@ class LLMDataModel(BaseModel):
         """Generate a value for a tuple type."""
         types = get_args(field_type)
         if types:
-            return tuple(LLMDataModel._generate_value_for_type_generic(t, visited_models, False) for t in types)
+            return tuple(
+                LLMDataModel._generate_value_for_type_generic(t, visited_models, False)
+                for t in types
+            )
         return ("item1", "item2")
 
     @staticmethod
@@ -778,10 +864,7 @@ class LLMDataModel(BaseModel):
     @classmethod
     def _find_non_header_fields(cls) -> dict:
         """Find all fields except section_header."""
-        return {
-            name: f for name, f in cls.model_fields.items()
-            if name != "section_header"
-        }
+        return {name: f for name, f in cls.model_fields.items() if name != "section_header"}
 
     @classmethod
     def _is_single_value_model(cls, fields: dict) -> bool:
@@ -838,7 +921,9 @@ class LLMDataModel(BaseModel):
         return submodel.generate_example_json()
 
     @classmethod
-    def _generate_non_null_example_for_model(cls, model: Type[BaseModel], visited_models: set | None = None) -> dict:
+    def _generate_non_null_example_for_model(
+        cls, model: type[BaseModel], visited_models: set | None = None
+    ) -> dict:
         """Generate an example for a model, preferring non-null for Optional fields (recursive)."""
         if visited_models is None:
             visited_models = set()
@@ -857,13 +942,17 @@ class LLMDataModel(BaseModel):
                 chosen = non_none_types[0] if non_none_types else Any
                 example[field_name] = cls._generate_value_for_type_non_null(chosen, visited_models)
             else:
-                example[field_name] = cls._generate_value_for_type_non_null(model_field.annotation, visited_models)
+                example[field_name] = cls._generate_value_for_type_non_null(
+                    model_field.annotation, visited_models
+                )
         return example
 
     @classmethod
     def _generate_value_for_type_non_null(cls, field_type: Any, visited_models: set) -> Any:
         """Generate a value ensuring non-null choices for unions/optionals."""
-        return cls._generate_value_for_type_generic(field_type, visited_models, prefer_non_null=True)
+        return cls._generate_value_for_type_generic(
+            field_type, visited_models, prefer_non_null=True
+        )
 
     @classmethod
     def _example_key_for_type(cls, key_type: Any, visited_models: set) -> Any:
@@ -876,67 +965,137 @@ class LLMDataModel(BaseModel):
             return True
         if key_type is tuple or get_origin(key_type) is tuple:
             tuple_args = get_args(key_type) if get_args(key_type) else (str, int)
-            return tuple(cls._generate_value_for_type_generic(t, visited_models, True) for t in tuple_args)
+            return tuple(
+                cls._generate_value_for_type_generic(t, visited_models, True) for t in tuple_args
+            )
         if key_type is frozenset or get_origin(key_type) is frozenset:
             item_type = get_args(key_type)[0] if get_args(key_type) else str
-            return frozenset([cls._generate_value_for_type_generic(item_type, visited_models, True)])
+            return frozenset(
+                [cls._generate_value_for_type_generic(item_type, visited_models, True)]
+            )
         return "example_string"
 
     @classmethod
-    def _generate_value_for_type_generic(cls, field_type: Any, visited_models: set, prefer_non_null: bool) -> Any:
+    def _generate_value_for_type_generic(
+        cls, field_type: Any, visited_models: set, prefer_non_null: bool
+    ) -> Any:
         """Unified generator for example values; prefer_non_null to avoid None variants."""
         origin = get_origin(field_type) or field_type
 
-        # Enums
+        handled, value = cls._handle_enum_type(origin)
+        if handled:
+            return value
+
+        handled, value = cls._handle_literal_type(origin, field_type)
+        if handled:
+            return value
+
+        handled, value = cls._handle_model_type(origin, field_type, visited_models, prefer_non_null)
+        if handled:
+            return value
+
+        handled, value = cls._handle_union_type(field_type, visited_models, prefer_non_null)
+        if handled:
+            return value
+
+        handled, value = cls._handle_collection_type(field_type, visited_models, prefer_non_null)
+        if handled:
+            return value
+
+        return LLMDataModel._generate_primitive_value(field_type)
+
+    @staticmethod
+    def _handle_enum_type(origin: Any) -> tuple[bool, Any]:
+        """Handle Enum types when generating example values."""
         if isinstance(origin, type) and issubclass(origin, Enum):
-            return list(origin)[0].value if list(origin) else "enum_value"
+            first_member = next(iter(origin), None)
+            value = first_member.value if first_member is not None else "enum_value"
+            return True, value
+        return False, None
 
-        # Literals
+    @staticmethod
+    def _handle_literal_type(origin: Any, field_type: Any) -> tuple[bool, Any]:
+        """Handle Literal[...] annotations."""
         if origin is Literal:
-            return get_args(field_type)[0]
-
-        # BaseModel
-        if isinstance(origin, type) and issubclass(origin, BaseModel):
-            model_name = field_type.__name__
-            if model_name in visited_models:
-                return {}
-            visited_models.add(model_name)
-            if prefer_non_null:
-                return cls._generate_non_null_example_for_model(field_type, visited_models.copy())
-            return LLMDataModel._generate_example_for_model(field_type, visited_models.copy())
-
-        # Unions
-        if LLMDataModel._is_union_type(field_type):
-            subtypes = LLMDataModel._get_union_types(field_type, exclude_none=True)
-            if not subtypes:
-                return None
-            chosen = subtypes[0]
-            return cls._generate_value_for_type_generic(chosen, visited_models, prefer_non_null)
-
-        # Collections
-        if LLMDataModel._is_collection_type(field_type):
-            origin = get_origin(field_type) or field_type
-            if origin is list:
-                item_type = get_args(field_type)[0] if get_args(field_type) else Any
-                return [cls._generate_value_for_type_generic(item_type, visited_models, prefer_non_null)]
-            if origin is dict:
-                key_type, value_type = get_args(field_type) if get_args(field_type) else (Any, Any)
-                example_key = cls._example_key_for_type(key_type, visited_models)
-                return {example_key: cls._generate_value_for_type_generic(value_type, visited_models, prefer_non_null)}
-            if origin in (set, frozenset):
-                item_type = get_args(field_type)[0] if get_args(field_type) else Any
-                return [cls._generate_value_for_type_generic(item_type, visited_models, prefer_non_null)]
-            if origin is tuple:
-                types = get_args(field_type)
-                if types:
-                    return tuple(cls._generate_value_for_type_generic(t, visited_models, prefer_non_null) for t in types)
-                return ("item1", "item2")
-
-        # Primitives
-        return LLMDataModel._generate_primitive_value(field_type)
+            literal_args = get_args(field_type)
+            return True, literal_args[0] if literal_args else None
+        return False, None
+
+    @classmethod
+    def _handle_model_type(
+        cls, origin: Any, field_type: Any, visited_models: set, prefer_non_null: bool
+    ) -> tuple[bool, Any]:
+        """Handle Pydantic BaseModel subclasses."""
+        if not (isinstance(origin, type) and issubclass(origin, BaseModel)):
+            return False, None
+        model_name = field_type.__name__
+        if model_name in visited_models:
+            return True, {}
+        visited_models.add(model_name)
+        generator = (
+            cls._generate_non_null_example_for_model
+            if prefer_non_null
+            else LLMDataModel._generate_example_for_model
+        )
+        return True, generator(field_type, visited_models.copy())
 
     @classmethod
-    def _format_json_example(cls, obj: Any, indent: int = 0) -> str:
+    def _handle_union_type(
+        cls, field_type: Any, visited_models: set, prefer_non_null: bool
+    ) -> tuple[bool, Any]:
+        """Handle Optional/Union annotations."""
+        if not LLMDataModel._is_union_type(field_type):
+            return False, None
+        subtypes = LLMDataModel._get_union_types(field_type, exclude_none=True)
+        if not subtypes:
+            return True, None
+        chosen = subtypes[0]
+        value = cls._generate_value_for_type_generic(chosen, visited_models, prefer_non_null)
+        return True, value
+
+    @classmethod
+    def _handle_collection_type(
+        cls, field_type: Any, visited_models: set, prefer_non_null: bool
+    ) -> tuple[bool, Any]:
+        """Handle list/dict/set/tuple-like annotations."""
+        if not LLMDataModel._is_collection_type(field_type):
+            return False, None
+
+        origin = get_origin(field_type) or field_type
+        args = get_args(field_type)
+
+        if origin is list:
+            item_type = args[0] if args else Any
+            value = [
+                cls._generate_value_for_type_generic(item_type, visited_models, prefer_non_null)
+            ]
+            return True, value
+        if origin is dict:
+            key_type, value_type = args if args else (Any, Any)
+            example_key = cls._example_key_for_type(key_type, visited_models)
+            example_value = cls._generate_value_for_type_generic(
+                value_type, visited_models, prefer_non_null
+            )
+            return True, {example_key: example_value}
+        if origin in (set, frozenset):
+            item_type = args[0] if args else Any
+            value = [
+                cls._generate_value_for_type_generic(item_type, visited_models, prefer_non_null)
+            ]
+            return True, value
+        if origin is tuple:
+            if args:
+                tuple_values = tuple(
+                    cls._generate_value_for_type_generic(t, visited_models, prefer_non_null)
+                    for t in args
+                )
+                return True, tuple_values
+            return True, ("item1", "item2")
+
+        return True, []
+
+    @classmethod
+    def _format_json_example(cls, obj: Any, _indent: int = 0) -> str:
         """Format an object as a JSON string representation."""
         return json.dumps(obj, indent=2, default=str)
 
@@ -952,22 +1111,22 @@ class LLMDataModel(BaseModel):
         return "\n\n".join(example_blocks)
 
 
-def build_dynamic_llm_datamodel(py_type: Any) -> Type[LLMDataModel]:
+def build_dynamic_llm_datamodel(py_type: Any) -> type[LLMDataModel]:
     """Dynamically create a subclass of LLMDataModel with a single 'value' field."""
     model_name = f"LLMDynamicDataModel_{hash(str(py_type)) & 0xFFFFFFFF:X}"
 
-    model: Type[LLMDataModel] = create_model(
+    model: type[LLMDataModel] = create_model(
         model_name,
         __base__=LLMDataModel,
         value=(
             py_type,
             Field(
                 ...,
-                description="This is a dynamically generated data model. This description is general. " +
-                "If you're dealing with a complex type, or nested types in combination with unions, make sure you " +
-                "understand the instructions provided in the prompt, and select the appropriate data model based on the " +
-                "type at hand, as described in the schema section."
-            )
+                description="This is a dynamically generated data model. This description is general. "
+                "If you're dealing with a complex type, or nested types in combination with unions, make sure you "
+                "understand the instructions provided in the prompt, and select the appropriate data model based on the "
+                "type at hand, as described in the schema section.",
+            ),
         ),
     )