"""Xulcan Protocol Layer: Standardized types for model interactions.

This package establishes a provider-agnostic contract for generative model
interactions, enforcing strict type safety and immutability. It implements
Defense-in-Depth validation to protect against malformed payloads, injection
attacks, and resource exhaustion from untrusted inputs.

Architecture:
    Level 1 (Protocol Layer) sits above Level 0 (Core) in the Skyscraper
    Architecture. It depends only on core types and provides the canonical
    interfaces for model I/O, message structures, and tool invocations.

Package Structure:
    - utils: Shared validation logic and constants
    - parts: Multimodal content primitives (TextPart, ImagePart, AudioPart)
    - tools: Function definitions and tool invocation contracts
    - message: Conversation protocol (SystemMessage, UserMessage, etc.)
    - io: Response formats (UnifiedResponse, streaming chunks)

Public API:
    All classes, enums, and type aliases are re-exported from this module
    to provide a single import point for consumers:
        from xulcan.protocol import UserMessage, ToolCall, UnifiedResponse

Security Guarantees:
    - Input sanitization at all boundaries
    - Recursion depth limits prevent stack overflow
    - JSON serializability enforced for untrusted data
    - MIME type allowlists prevent arbitrary file uploads
    - Discriminated unions enable type-safe polymorphism
"""

# ═══════════════════════════════════════════════════════════════════════════
# UTILITIES
# ═══════════════════════════════════════════════════════════════════════════

from .utils import (
    MAX_NESTING_DEPTH,
    MAX_CHUNK_SIZE,
)

# ═══════════════════════════════════════════════════════════════════════════
# MULTIMODAL CONTENT PARTS
# ═══════════════════════════════════════════════════════════════════════════

from .parts import (
    ContentType,
    TextPart,
    ImagePart,
    AudioPart,
    ContentPart,
)

# ═══════════════════════════════════════════════════════════════════════════
# TOOL INFRASTRUCTURE
# ═══════════════════════════════════════════════════════════════════════════

from .tools import (
    ToolChoiceType,
    ToolCall,
    FunctionDef,
    FunctionIdentity,
    ToolDefinition,
    NamedToolChoice,
    ToolChoice,
)

# ═══════════════════════════════════════════════════════════════════════════
# MESSAGE PROTOCOL
# ═══════════════════════════════════════════════════════════════════════════

from .message import (
    Role,
    BaseMessage,
    SystemMessage,
    UserMessage,
    ToolMessage,
    AssistantMessage,
    UnifiedMessage,
)

# ═══════════════════════════════════════════════════════════════════════════
# INPUT/OUTPUT CONTRACTS
# ═══════════════════════════════════════════════════════════════════════════

from .io import (
    FinishReason,
    UnifiedResponse,
    DeltaContent,
    UnifiedChunk,
)

# ═══════════════════════════════════════════════════════════════════════════
# PUBLIC API DEFINITION
# ═══════════════════════════════════════════════════════════════════════════


__all__ = [
    # Utilities
    "MAX_NESTING_DEPTH",
    "MAX_CHUNK_SIZE",
    
    # Content Parts
    "ContentType",
    "TextPart",
    "ImagePart",
    "AudioPart",
    "ContentPart",
    
    # Tools
    "ToolChoiceType",
    "ToolCall",
    "FunctionDef",
    "FunctionIdentity",
    "ToolDefinition",
    "NamedToolChoice",
    "ToolChoice",
    
    # Messages
    "Role",
    "BaseMessage",
    "SystemMessage",
    "UserMessage",
    "ToolMessage",
    "AssistantMessage",
    "UnifiedMessage",
    
    # I/O
    "FinishReason",
    "UnifiedResponse",
    "DeltaContent",
    "UnifiedChunk",
]