"""
Base protocol for trace platforms.

Defines the interface that all observability platform integrations
must implement (LangSmith, mock, etc.).
"""

from __future__ import annotations

from typing import Any, Dict, List, Optional, Protocol, Tuple


class TracePlatform(Protocol):
    """Protocol for querying traces from observability platforms."""

    def query_traces(
        self,
        filter: Dict[str, Any],
        limit: int = 100,
        time_range: Optional[Tuple[str, str]] = None,
    ) -> List[Dict[str, Any]]:
        """Query traces matching filter criteria."""
        ...

    def get_trace(self, trace_id: str) -> Dict[str, Any]:
        """Get a single trace by ID."""
        ...

    def test_connection(self) -> bool:
        """Test that the platform connection is working."""
        ...

    def get_platform_name(self) -> str:
        """Return the platform name (e.g., 'langsmith', 'mock')."""
        ...
