Configuration

@dataclass(frozen=True, slots=True)
class TrajectoryConfig:
    """Configuration for trajectory extraction behavior.

    Controls which components are extracted from ADK event streams,
    whether sensitive data should be redacted, and whether large
    values should be truncated.

    Note:
        All configuration fields are immutable after instantiation,
        ensuring consistent extraction behavior throughout evolution.

    Attributes:
        include_tool_calls (bool): Extract tool/function call records.
            Defaults to True.
        include_state_deltas (bool): Extract session state changes.
            Defaults to True.
        include_token_usage (bool): Extract LLM token consumption metrics.
            Defaults to True.
        redact_sensitive (bool): Apply sensitive data redaction. When True,
            fields matching sensitive_keys will be replaced with "[REDACTED]".
            Defaults to True for secure-by-default behavior.
        sensitive_keys (tuple[str, ...]): Field names to redact via exact
            match. Case-sensitive. Defaults to ("password", "api_key", "token").
        max_string_length (int | None): Truncate strings longer than this
            with a marker indicating truncation. None disables truncation.
            Defaults to 10000 characters.

    Examples:
        Default configuration (secure, with truncation):

        ```python
        config = TrajectoryConfig()  # All features enabled, redaction ON
        ```

        Minimal configuration (tool calls only):

        ```python
        config = TrajectoryConfig(
            include_tool_calls=True,
            include_state_deltas=False,
            include_token_usage=False,
            redact_sensitive=False,
        )
        ```

        Custom sensitive keys and truncation:

        ```python
        config = TrajectoryConfig(
            sensitive_keys=("password", "api_key", "token", "ssn"),
            max_string_length=5000,  # Truncate DOM/screenshots earlier
        )
        ```

        Disable truncation (keep full values):

        ```python
        config = TrajectoryConfig(max_string_length=None)
        ```

    Note:
        Redaction takes precedence over truncation. Sensitive values are
        replaced with "[REDACTED]" first, then truncation applies to the
        remaining (non-sensitive) strings.
    """

    include_tool_calls: bool = True
    include_state_deltas: bool = True
    include_token_usage: bool = True
    redact_sensitive: bool = True
    sensitive_keys: tuple[str, ...] = ("password", "api_key", "token")
    max_string_length: int | None = 10000

@dataclass(frozen=True, slots=True)
class ComponentSpec:
    """Structured representation of an agent.component pair for multi-agent addressing.

    Provides type-safe construction and parsing of qualified component names
    in the format `{agent_name}.{component_name}`. Using a dataclass enables
    IDE autocomplete and type checker validation of field access.

    See ADR-012 for the design rationale.

    Attributes:
        agent (str): The agent name (must be a valid Python identifier).
        component (str): The component name (e.g., 'instruction', 'output_schema').

    Examples:
        Construction and qualified name access:

        ```python
        from gepa_adk.domain.types import ComponentSpec

        spec = ComponentSpec(agent="generator", component="instruction")
        print(spec.qualified)  # "generator.instruction"
        ```

        Parsing from qualified string:

        ```python
        spec = ComponentSpec.parse("critic.output_schema")
        print(spec.agent)  # "critic"
        print(spec.component)  # "output_schema"
        ```

        Using with candidates:

        ```python
        spec = ComponentSpec(agent="generator", component="instruction")
        candidate.components[spec.qualified] = "evolved instruction..."
        ```

    Note:
        An immutable (frozen) dataclass that provides type-safe qualified name
        construction. The qualified property returns a QualifiedComponentName
        (NewType) for type safety with handlers.
    """

    agent: str
    component: str

    @property
    def qualified(self) -> QualifiedComponentName:
        """Return dot-separated qualified name.

        Returns:
            QualifiedComponentName: The qualified name in format 'agent.component'.

        Examples:
            ```python
            spec = ComponentSpec(agent="gen", component="instruction")
            name = spec.qualified  # QualifiedComponentName("gen.instruction")
            ```

        Note:
            Output format follows ADR-012 dot-separated convention.
        """
        return QualifiedComponentName(f"{self.agent}.{self.component}")

    @classmethod
    def parse(cls, qualified: QualifiedComponentName | str) -> ComponentSpec:
        """Parse a qualified name into a ComponentSpec.

        Args:
            qualified: A dot-separated qualified name (e.g., 'generator.instruction').

        Returns:
            ComponentSpec: Parsed specification with agent and component fields.

        Raises:
            ValueError: If the qualified name does not contain a dot separator,
                or if agent or component is empty after parsing.

        Examples:
            ```python
            spec = ComponentSpec.parse("critic.output_schema")
            assert spec.agent == "critic"
            assert spec.component == "output_schema"
            ```

        Note:
            Only the first dot is used as separator, allowing component names
            with dots (though this is not recommended).
        """
        name = str(qualified)
        if "." not in name:
            raise ValueError(
                f"Invalid qualified component name '{name}': "
                "expected format 'agent.component'"
            )
        agent, component = name.split(".", 1)
        if not agent or not component:
            raise ValueError(
                f"Invalid qualified component name '{name}': "
                "both agent and component must be non-empty"
            )
        return cls(agent=agent, component=component)

    def __str__(self) -> str:
        """Return the qualified name as a string."""
        return f"{self.agent}.{self.component}"

class FrontierType(str, Enum):
    """Supported frontier tracking strategies for Pareto selection.

    Note:
        All four frontier types enable different Pareto dominance tracking
        strategies for multi-objective optimization.

    Examples:
        ```python
        frontier_type = FrontierType.INSTANCE
        ```
    """

    INSTANCE = "instance"
    OBJECTIVE = "objective"
    HYBRID = "hybrid"
    CARTESIAN = "cartesian"

@dataclass(frozen=True, slots=True)
class SchemaConstraints:
    """Constraints for output schema evolution.

    Controls which fields must be preserved during schema evolution,
    including field existence and type constraints. Used by the
    OutputSchemaHandler to validate proposed schema mutations.

    Attributes:
        required_fields (tuple[str, ...]): Field names that must exist
            in evolved schemas. Mutations removing these fields are rejected.
        preserve_types (dict[str, type | tuple[type, ...]]): Mapping of
            field names to allowed type(s). Mutations changing a field's
            type to an incompatible type are rejected.

    Examples:
        Preserve required fields only:

        ```python
        from gepa_adk.domain.types import SchemaConstraints

        constraints = SchemaConstraints(
            required_fields=("score", "feedback"),
        )
        ```

        Preserve required fields with type constraints:

        ```python
        constraints = SchemaConstraints(
            required_fields=("score",),
            preserve_types={
                "score": (float, int),  # Allow numeric types
                "order_id": str,  # Must stay string
            },
        )
        ```

    Note:
        A frozen dataclass ensures immutability during evolution runs.
        Configuration is validated at evolution start.
    """

    required_fields: tuple[str, ...] = ()
    preserve_types: dict[str, type | tuple[type, ...]] = field(default_factory=dict)

@dataclass(frozen=True, slots=True)
class ProposalResult:
    """Result of a successful proposal operation.

    Attributes:
        candidate (Candidate): The proposed candidate with components.
        parent_indices (list[int]): Indices of parent candidate(s) in ParetoState.
        tag (str): Type of proposal ("mutation" or "merge").
        metadata (dict[str, Any]): Additional proposal-specific metadata.

    Examples:
        Creating a mutation proposal result:

        ```python
        from gepa_adk.domain.types import ProposalResult
        from gepa_adk.domain.models import Candidate

        result = ProposalResult(
            candidate=Candidate(components={"instruction": "Be helpful"}),
            parent_indices=[5],
            tag="mutation",
        )
        ```

        Creating a merge proposal result:

        ```python
        result = ProposalResult(
            candidate=Candidate(components={"instruction": "..."}),
            parent_indices=[5, 8],
            tag="merge",
            metadata={"ancestor_idx": 2},
        )
        ```

    Note:
        A frozen dataclass ensures immutability of proposal results.
        Parent indices must be valid indices into the ParetoState.candidates list.
    """

    candidate: "Candidate"  # Forward reference to avoid circular import
    parent_indices: list[int]
    tag: str
    metadata: dict[str, Any] = field(default_factory=dict)