haive.core.utils.naming
=======================

.. py:module:: haive.core.utils.naming

.. autoapi-nested-parse::

   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

   .. rubric:: 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
---------

.. autoapisummary::

   haive.core.utils.naming.create_name_mapping
   haive.core.utils.naming.create_openai_compliant_name
   haive.core.utils.naming.get_name_suggestions
   haive.core.utils.naming.sanitize_class_name
   haive.core.utils.naming.sanitize_pydantic_model_name
   haive.core.utils.naming.sanitize_tool_name
   haive.core.utils.naming.validate_tool_name


Module Contents
---------------

.. py:function:: create_name_mapping(original_names)

   Create a mapping from original names to sanitized names.

   Useful for batch processing and maintaining mappings for debugging.

   :param original_names: List of original names to process

   :returns: Dictionary mapping original -> sanitized names

   .. rubric:: Examples

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


.. py:function:: 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.

   :param raw_name: Raw name to process
   :param suffix: Optional suffix to add (e.g., 'tool', 'generic')

   :returns: OpenAI-compliant name with optional suffix

   .. rubric:: Examples

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

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


.. py:function:: get_name_suggestions(raw_name, count = 3)

   Get multiple naming suggestions for a raw name.

   Provides different variations of sanitized names to choose from.

   :param raw_name: Original name to generate suggestions for
   :param count: Number of suggestions to generate

   :returns: List of suggested names

   .. rubric:: Examples

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


.. py:function:: sanitize_class_name(cls)

   Sanitize a class object's name for tool usage.

   :param cls: Class object or class name string

   :returns: Sanitized name suitable for OpenAI tools


.. py:function:: sanitize_pydantic_model_name(model)

   Sanitize a Pydantic model's name for tool usage.

   Specifically handles Pydantic model naming patterns.

   :param model: Pydantic model class

   :returns: Sanitized name suitable for OpenAI tools


.. py:function:: 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.

   :param raw_name: Raw tool name from __name__ or other source
   :param preserve_acronyms: Whether to treat known acronyms as single words

   :returns: Sanitized snake_case name that's OpenAI-compliant

   .. rubric:: 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'


.. py:function:: validate_tool_name(name)

   Validate a tool name against OpenAI requirements.

   :param name: Tool name to validate

   :returns: Tuple of (is_valid, list_of_issues)

   .. rubric:: Examples

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

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