haive.core.utils.enhanced_naming

Enhanced naming utilities for complex type annotations and tool names.

This module provides advanced utilities for sanitizing complex Python type annotations and generic classes into OpenAI-compliant tool names with descriptive transformations.

Key Features: - Handles nested generics: List[Dict[str, Task]] -> list_dict_str_task_nested_generic - Provides transformation descriptions for debugging - Handles Union, Optional, and complex type annotations - Maintains type hierarchy information in the name - Supports custom naming strategies

Examples

Complex type handling:

from haive.core.utils.enhanced_naming import enhanced_sanitize_tool_name

# Nested generics
result, desc = enhanced_sanitize_tool_name("List[Dict[str, Task]]")
# Returns: ("list_dict_str_task_nested_generic", "3-level nested generic with 4 type parameters")

# Union types
result, desc = enhanced_sanitize_tool_name("Union[str, List[Task]]")
# Returns: ("union_str_list_task_generic", "Union type with 2 alternatives")

# Optional types
result, desc = enhanced_sanitize_tool_name("Optional[Plan[Task]]")
# Returns: ("optional_plan_task_generic", "Optional type wrapping Plan[Task] generic")

Classes

EnhancedGenericParser	Advanced parser for complex generic type annotations.
NamingTransformation	Metadata about a naming transformation.

Functions

analyze_naming_complexity(type_names)	Analyze naming complexity across multiple type names.
enhanced_sanitize_tool_name(raw_name[, ...])	Enhanced tool name sanitization with metadata and complex type support.
get_naming_suggestions_enhanced(raw_name[, count])	Get multiple enhanced naming suggestions with metadata.
sanitize_pydantic_model_name_enhanced(model)	Enhanced Pydantic model name sanitization with metadata.

Module Contents

class haive.core.utils.enhanced_naming.EnhancedGenericParser

Advanced parser for complex generic type annotations.

parse_complex_type(type_name)

Parse complex type annotations into naming transformation.

Parameters:

type_name (str)

Return type:

NamingTransformation

class haive.core.utils.enhanced_naming.NamingTransformation

Metadata about a naming transformation.

haive.core.utils.enhanced_naming.analyze_naming_complexity(type_names)

Analyze naming complexity across multiple type names.

Parameters:

type_names (list[str]) – List of type names to analyze

Returns:

Dictionary with complexity analysis results

Return type:

dict[str, Any]

Examples

>>> results = analyze_naming_complexity([
...     "Plan[Task]",
...     "List[Dict[str, Task]]",
...     "Union[str, Optional[Plan[Task]]]"
... ])
>>> print(f"Average complexity: {results['average_complexity']}")
>>> print(f"Most complex: {results['most_complex']['name']}")

haive.core.utils.enhanced_naming.enhanced_sanitize_tool_name(raw_name, include_metadata=True, max_complexity=5)

Enhanced tool name sanitization with metadata and complex type support.

Parameters:

• raw_name (str) – Raw tool name from __name__ or type annotation

• include_metadata (bool) – Whether to return transformation metadata

• max_complexity (int) – Maximum complexity level to allow (warns if exceeded)

Returns:

Tuple of (sanitized_name, transformation_metadata)

Return type:

tuple[str, NamingTransformation | None]

Examples

>>> name, meta = enhanced_sanitize_tool_name("List[Dict[str, Task]]")
>>> print(name)
'list_dict_str_task_nested_generic'
>>> print(meta.description)
'3-level nested generic with 4 type parameters'

>>> name, meta = enhanced_sanitize_tool_name("Union[str, Optional[Plan[Task]]]")
>>> print(name)
'union_str_optional_plan_task_generic'
>>> print(meta.complexity_level)
2

haive.core.utils.enhanced_naming.get_naming_suggestions_enhanced(raw_name, count=5)

Get multiple enhanced naming suggestions with metadata.

Parameters:

• raw_name (str)

• count (int)

Return type:

list[dict[str, Any]]

haive.core.utils.enhanced_naming.sanitize_pydantic_model_name_enhanced(model)

Enhanced Pydantic model name sanitization with metadata.

Return type:

tuple[str, NamingTransformation | None]