"""Type stubs for attuned."""

from typing import Optional, List, Dict, Any
from enum import IntEnum

__version__: str

# =============================================================================
# Simple API (recommended)
# =============================================================================

class Attuned:
    """
    Universal LLM behavioral layer.

    Declare human state using any of the 23 axes. Get a prompt context
    that conditions LLM behavior appropriately.

    Example:
        >>> state = Attuned(verbosity_preference=0.2, warmth=0.9)
        >>> print(state.prompt())
    """

    presets: "Presets"

    def __init__(self, user_id: str = "default", **axes: float) -> None: ...
    def prompt(self) -> str: ...
    def context(self) -> "PromptContext": ...

    @staticmethod
    def axes() -> List[str]: ...
    @staticmethod
    def axis_info(name: str) -> Dict[str, Any]: ...

    def __repr__(self) -> str: ...


class Presets:
    """Pre-configured Attuned states for common scenarios."""

    @staticmethod
    def anxious_user() -> Attuned: ...
    @staticmethod
    def busy_executive() -> Attuned: ...
    @staticmethod
    def learning_student() -> Attuned: ...
    @staticmethod
    def casual_chat() -> Attuned: ...
    @staticmethod
    def high_stakes() -> Attuned: ...
    @staticmethod
    def overwhelmed() -> Attuned: ...
    @staticmethod
    def privacy_conscious() -> Attuned: ...


# =============================================================================
# Enums
# =============================================================================

class Source(IntEnum):
    """Source of a state snapshot."""
    SelfReport = 0
    Inferred = 1
    Mixed = 2

    @staticmethod
    def from_str(value: str) -> "Source": ...

class Verbosity(IntEnum):
    """Output verbosity level."""
    Low = 0
    Medium = 1
    High = 2

    @staticmethod
    def from_str(value: str) -> "Verbosity": ...

class AxisCategory(IntEnum):
    """Semantic category for axes."""
    Cognitive = 0
    Emotional = 1
    Social = 2
    Preferences = 3
    Control = 4
    Safety = 5

# Core types

class StateSnapshot:
    """A snapshot of user state at a point in time."""

    @staticmethod
    def builder() -> "StateSnapshotBuilder": ...

    @property
    def user_id(self) -> str: ...
    @property
    def updated_at_unix_ms(self) -> int: ...
    @property
    def source(self) -> Source: ...
    @property
    def confidence(self) -> float: ...
    @property
    def axes(self) -> Dict[str, float]: ...

    def get_axis(self, name: str) -> float: ...
    def get_axis_opt(self, name: str) -> Optional[float]: ...
    def to_json(self) -> str: ...

    @staticmethod
    def from_json(json: str) -> "StateSnapshot": ...

class StateSnapshotBuilder:
    """Builder for StateSnapshot."""

    def __init__(self) -> None: ...
    def user_id(self, user_id: str) -> "StateSnapshotBuilder": ...
    def updated_at(self, unix_ms: int) -> "StateSnapshotBuilder": ...
    def source(self, source: Source) -> "StateSnapshotBuilder": ...
    def confidence(self, confidence: float) -> "StateSnapshotBuilder": ...
    def axis(self, name: str, value: float) -> "StateSnapshotBuilder": ...
    def axes(self, axes: Dict[str, float]) -> "StateSnapshotBuilder": ...
    def build(self) -> StateSnapshot: ...

class PromptContext:
    """Context produced by translating user state."""

    @property
    def guidelines(self) -> List[str]: ...
    @property
    def tone(self) -> str: ...
    @property
    def verbosity(self) -> Verbosity: ...
    @property
    def flags(self) -> List[str]: ...

    def format_for_prompt(self) -> str: ...
    def to_json(self) -> str: ...

    @staticmethod
    def from_json(json: str) -> "PromptContext": ...

class Thresholds:
    """Threshold configuration for rule-based translation."""

    def __init__(self, hi: float = 0.7, lo: float = 0.3) -> None: ...

    @property
    def hi(self) -> float: ...
    @property
    def lo(self) -> float: ...

class RuleTranslator:
    """Rule-based translator that converts state to context."""

    def __init__(self, thresholds: Optional[Thresholds] = None) -> None: ...

    @property
    def thresholds(self) -> Thresholds: ...

    def to_prompt_context(self, snapshot: StateSnapshot) -> PromptContext: ...

class AxisDefinition:
    """Complete definition of a single axis with governance metadata."""

    @property
    def name(self) -> str: ...
    @property
    def category(self) -> AxisCategory: ...
    @property
    def description(self) -> str: ...
    @property
    def low_anchor(self) -> str: ...
    @property
    def high_anchor(self) -> str: ...
    @property
    def intent(self) -> List[str]: ...
    @property
    def forbidden_uses(self) -> List[str]: ...
    @property
    def since(self) -> str: ...
    @property
    def is_deprecated(self) -> bool: ...
    @property
    def deprecated_since(self) -> Optional[str]: ...
    @property
    def deprecated_reason(self) -> Optional[str]: ...
    @property
    def deprecated_replacement(self) -> Optional[str]: ...

    def format_summary(self) -> str: ...

class AttunedClient:
    """HTTP client for interacting with an Attuned server."""

    def __init__(
        self,
        base_url: str,
        api_key: Optional[str] = None,
        timeout_secs: int = 30
    ) -> None: ...

    @property
    def base_url(self) -> str: ...
    @property
    def has_api_key(self) -> bool: ...

    def upsert_state(self, snapshot: StateSnapshot) -> None: ...
    def get_state(self, user_id: str) -> Optional[StateSnapshot]: ...
    def get_context(self, user_id: str) -> PromptContext: ...
    def delete_state(self, user_id: str) -> bool: ...
    def health(self) -> bool: ...

# Module functions

def get_axis(name: str) -> Optional[AxisDefinition]: ...
def is_valid_axis_name(name: str) -> bool: ...
def get_axis_names() -> List[str]: ...
def get_all_axes() -> List[AxisDefinition]: ...

# Constants
CANONICAL_AXES: List[AxisDefinition]
