# -*- coding: utf-8 -*-
"""Location: ./mcpgateway/utils/base_models.py
Copyright 2026
SPDX-License-Identifier: Apache-2.0
Authors: Mihai Criveti

Base model utilities for ContextForge.
This module provides shared base classes and utilities for Pydantic models
to avoid circular dependencies between models.py and schemas.py.
"""

# Standard
from typing import Any, Dict

# Third-Party
from pydantic import BaseModel, ConfigDict


def to_camel_case(s: str) -> str:
    """Convert a string from snake_case to camelCase.

    Args:
        s (str): The string to be converted, which is assumed to be in snake_case.

    Returns:
        str: The string converted to camelCase.

    Examples:
        >>> to_camel_case("hello_world_example")
        'helloWorldExample'
        >>> to_camel_case("alreadyCamel")
        'alreadyCamel'
        >>> to_camel_case("")
        ''
        >>> to_camel_case("single")
        'single'
        >>> to_camel_case("_leading_underscore")
        'LeadingUnderscore'
        >>> to_camel_case("trailing_underscore_")
        'trailingUnderscore'
        >>> to_camel_case("multiple_words_here")
        'multipleWordsHere'
        >>> to_camel_case("api_key_value")
        'apiKeyValue'
        >>> to_camel_case("user_id")
        'userId'
        >>> to_camel_case("created_at")
        'createdAt'
    """
    return "".join(word.capitalize() if i else word for i, word in enumerate(s.split("_")))


class BaseModelWithConfigDict(BaseModel):
    """Base model with common configuration for MCP protocol types.

    This base class provides automatic snake_case → camelCase field name conversion
    to comply with the MCP specification's JSON naming conventions.

    Key Features:
    - **Automatic camelCase conversion**: Field names like `stop_reason` automatically
      serialize as `stopReason` when FastAPI returns the response (via jsonable_encoder).
    - **ORM mode**: Can be constructed from SQLAlchemy models (from_attributes=True).
    - **Flexible input**: Accepts both snake_case and camelCase in input (populate_by_name=True).
    - **Enum values**: Enums serialize as their values, not names (use_enum_values=True).

    Usage:
        Models extending this class will automatically serialize field names to camelCase:

        >>> class MyModel(BaseModelWithConfigDict):
        ...     my_field: str = "value"
        ...     another_field: int = 42
        >>>
        >>> obj = MyModel()
        >>> obj.model_dump(by_alias=True)
        {'myField': 'value', 'anotherField': 42}

    Important:
        FastAPI's default response serialization uses `by_alias=True`, so models extending
        this class will automatically use camelCase in JSON responses without any additional
        code changes. This is critical for MCP spec compliance.

    Examples:
        >>> from mcpgateway.utils.base_models import BaseModelWithConfigDict
        >>> class CreateMessageResult(BaseModelWithConfigDict):
        ...     stop_reason: str = "endTurn"
        >>>
        >>> result = CreateMessageResult()
        >>> # Without by_alias (internal Python usage):
        >>> result.model_dump()
        {'stop_reason': 'endTurn'}
        >>>
        >>> # With by_alias (FastAPI automatic serialization):
        >>> result.model_dump(by_alias=True)
        {'stopReason': 'endTurn'}
    """

    model_config = ConfigDict(
        from_attributes=True,
        alias_generator=to_camel_case,  # Automatic snake_case → camelCase conversion
        populate_by_name=True,
        use_enum_values=True,
        extra="ignore",
        json_schema_extra={"nullable": True},
    )

    def to_dict(self, use_alias: bool = False) -> Dict[str, Any]:
        """Convert the model instance into a dictionary representation.

        Args:
            use_alias (bool): Whether to use aliases for field names (default is False).
                             If True, field names will be converted using the alias generator.

        Returns:
            Dict[str, Any]: A dictionary where keys are field names and values are
                           corresponding field values, with any nested models recursively
                           converted to dictionaries.
        """
        return self.model_dump(by_alias=use_alias)
