"""
Type definitions for the SwisperStudio SDK public interface.

These types define the contracts for SDK consumers.
Reference: docs/plans/plan_technical_cleanup_v1.md (Phase P1)
"""

from typing import TypedDict, Optional, Dict, Any, Callable, TypeVar
from typing_extensions import NotRequired


class InitializationStatus(TypedDict):
    """Status returned by safe_initialize and auto_trace."""
    
    enabled: bool
    """Whether tracing is enabled by configuration."""
    
    redis: bool
    """Redis connectivity OK."""
    
    write: bool
    """Write permission OK."""
    
    consumer: bool
    """Consumer detected and healthy."""
    
    initialized: bool
    """Overall initialization success."""


class AutoTraceStatus(TypedDict):
    """Extended status returned by auto_trace."""
    
    enabled: bool
    """Whether tracing is enabled by config (SWISPER_STUDIO_ENABLED)."""
    
    initialized: bool
    """Overall success."""
    
    redis: bool
    """Redis connectivity OK."""
    
    write: bool
    """Write permission OK."""
    
    consumer: bool
    """Consumer detected and healthy."""
    
    langgraph_patched: bool
    """StateGraph auto-patching OK."""
    
    llm_wrapper: bool
    """LLM adapter wrapping OK."""
    
    environment: NotRequired[Optional[str]]
    """Environment tag (from SWISPER_STUDIO_ENVIRONMENT)."""
    
    error: NotRequired[Optional[str]]
    """Error message if failed."""


class TracingConfig(TypedDict, total=False):
    """Configuration options for tracing."""
    
    redis_url: str
    """Redis connection URL (e.g., 'redis://redis:6379')."""
    
    project_id: str
    """SwisperStudio project ID."""
    
    stream_name: str
    """Redis stream name for events (default: 'observability:events')."""
    
    max_stream_length: int
    """Max events to keep in stream (default: 100000)."""
    
    verify_consumer: bool
    """Whether to verify consumer is running (default: True)."""
    
    connection_timeout: float
    """Max time to wait for Redis connection (default: 5.0)."""
    
    enabled: bool
    """Whether to enable tracing (default: True)."""


# Type variable for generic function wrapping
T = TypeVar('T')
F = TypeVar('F', bound=Callable[..., Any])


class ObservationType:
    """Constants for observation types."""
    
    AUTO = "AUTO"
    """Auto-detect based on captured data."""
    
    SPAN = "SPAN"
    """Generic execution span."""
    
    GENERATION = "GENERATION"
    """LLM generation."""
    
    TOOL = "TOOL"
    """Tool execution."""
    
    AGENT = "AGENT"
    """Agent execution."""
