"""
Base interface for telemetry engines.

Defines the standard interface that all telemetry engines must implement.
"""

from abc import ABC, abstractmethod
from typing import Any, Dict


class TelemetryEngine(ABC):
    """Base interface for telemetry engines."""

    @abstractmethod
    def export_context_snapshot(self, context: Any, phase: str, metadata: Dict):
        """
        Export context tree snapshot.

        Args:
            context: Context instance
            phase: "pre_call" or "post_call"
            metadata: Additional metadata (agent_id, episode, etc.)
        """
        pass

    @abstractmethod
    def export_provider_thread(self, thread: Any, phase: str, metadata: Dict):
        """
        Export provider thread.

        Args:
            thread: ProviderThread instance
            phase: "pre_call" or "post_call"
            metadata: Additional metadata (agent_id, episode, etc.)
        """
        pass

    @abstractmethod
    def export_component_change(self, operation: str, component: Any, metadata: Dict):
        """
        Export component insert/update/delete.

        Args:
            operation: "insert", "update", or "delete"
            component: ContextComponent instance
            metadata: Additional metadata (agent_id, selector, etc.)
        """
        pass

    @abstractmethod
    def export_scaffold_change(
        self, scaffold_id: str, old_state: Dict, new_state: Dict, metadata: Dict
    ):
        """
        Export scaffold state change.

        Args:
            scaffold_id: Scaffold component ID
            old_state: Previous state dict
            new_state: New state dict
            metadata: Additional metadata (agent_id, operation, etc.)
        """
        pass

    @abstractmethod
    def flush(self):
        """Flush pending telemetry data."""
        pass
