haive.core.utils.naming

Robust naming utilities for OpenAI compliance and tool naming.

This module provides comprehensive utilities for sanitizing and transforming class names, especially generic classes, to be compatible with OpenAI’s function calling requirements and follow consistent naming conventions.

Key Features: - Handles generic classes (e.g., Plan[Task] -> plan_task_generic) - Converts CamelCase to snake_case consistently - Ensures OpenAI API compliance (pattern: ^[a-zA-Z0-9_\.-]+$) - Handles edge cases like acronyms, numbers, and special characters - Provides reverse mapping capabilities for debugging

Example

Basic usage:

from haive.core.utils.naming import sanitize_tool_name

# Generic class handling
name = sanitize_tool_name("Plan[Task]")
# Returns: "plan_task_generic"

# CamelCase conversion
name = sanitize_tool_name("MyComplexModel")
# Returns: "my_complex_model"

# OpenAI compliance
name = sanitize_tool_name("Invalid-Name[With]Brackets!")
# Returns: "invalid_name_with_brackets"

Functions

create_name_mapping(original_names)	Create a mapping from original names to sanitized names.
create_openai_compliant_name(raw_name[, suffix])	Create an OpenAI-compliant name with optional suffix.
get_name_suggestions(raw_name[, count])	Get multiple naming suggestions for a raw name.
sanitize_class_name(cls)	Sanitize a class object's name for tool usage.
sanitize_pydantic_model_name(model)	Sanitize a Pydantic model's name for tool usage.
sanitize_tool_name(raw_name[, preserve_acronyms])	Sanitize tool names for OpenAI compliance and readability.
validate_tool_name(name)	Validate a tool name against OpenAI requirements.

Module Contents

haive.core.utils.naming.create_name_mapping(original_names)

Create a mapping from original names to sanitized names.

Useful for batch processing and maintaining mappings for debugging.

Parameters:

original_names (list[str]) – List of original names to process

Returns:

Dictionary mapping original -> sanitized names

Return type:

dict[str, str]

Examples

>>> create_name_mapping(["Plan[Task]", "MyModel", "HTTPParser"])
{
    'Plan[Task]': 'plan_task_generic',
    'MyModel': 'my_model',
    'HTTPParser': 'http_parser'
}

haive.core.utils.naming.create_openai_compliant_name(raw_name, suffix=None)

Create an OpenAI-compliant name with optional suffix.

This is a higher-level function that creates compliant names and can add suffixes for disambiguation.

Parameters:

• raw_name (str) – Raw name to process

• suffix (str) – Optional suffix to add (e.g., ‘tool’, ‘generic’)

Returns:

OpenAI-compliant name with optional suffix

Return type:

str

Examples

>>> create_openai_compliant_name("Plan[Task]", "tool")
'plan_task_generic_tool'

>>> create_openai_compliant_name("MyModel")
'my_model'

haive.core.utils.naming.get_name_suggestions(raw_name, count=3)

Get multiple naming suggestions for a raw name.

Provides different variations of sanitized names to choose from.

Parameters:

• raw_name (str) – Original name to generate suggestions for

• count (int) – Number of suggestions to generate

Returns:

List of suggested names

Return type:

list[str]

Examples

>>> get_name_suggestions("Plan[Task]")
['plan_task_generic', 'plan_task_tool', 'task_plan_generic']

haive.core.utils.naming.sanitize_class_name(cls)

Sanitize a class object’s name for tool usage.

Parameters:

cls – Class object or class name string

Returns:

Sanitized name suitable for OpenAI tools

Return type:

str

haive.core.utils.naming.sanitize_pydantic_model_name(model)

Sanitize a Pydantic model’s name for tool usage.

Specifically handles Pydantic model naming patterns.

Parameters:

model – Pydantic model class

Returns:

Sanitized name suitable for OpenAI tools

Return type:

str

haive.core.utils.naming.sanitize_tool_name(raw_name, preserve_acronyms=True)

Sanitize tool names for OpenAI compliance and readability.

This is the main function for converting any class name into an OpenAI-compliant tool name. It handles generic classes, CamelCase conversion, and ensures all characters are valid for OpenAI’s function calling API.

Parameters:

• raw_name (str) – Raw tool name from __name__ or other source

• preserve_acronyms (bool) – Whether to treat known acronyms as single words

Returns:

Sanitized snake_case name that’s OpenAI-compliant

Return type:

str

Examples

>>> sanitize_tool_name("Plan[Task]")
'plan_task_generic'

>>> sanitize_tool_name("HTTPSParser")
'https_parser'

>>> sanitize_tool_name("MyModel[String]")
'my_model_string_generic'

>>> sanitize_tool_name("Invalid-Name!")
'invalid_name'

haive.core.utils.naming.validate_tool_name(name)

Validate a tool name against OpenAI requirements.

Parameters:

name (str) – Tool name to validate

Returns:

Tuple of (is_valid, list_of_issues)

Return type:

tuple[bool, list[str]]

Examples

>>> validate_tool_name("valid_tool_name")
(True, [])

>>> validate_tool_name("Invalid[Name]!")
(False, ['Contains invalid characters: [, ], !', 'Contains brackets which are not allowed'])