"""Backend integration ports.

These interfaces define the boundary between engine runtime logic and
backend-side capabilities (config lookup, history persistence, retrieval,
and tool resource discovery).
"""

from __future__ import annotations

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


class AssistantConfigProvider(Protocol):
    """Port for loading trusted assistant runtime configuration."""

    async def fetch_assistant_config(self, assistant_id: str) -> Optional[Dict[str, Any]]:
        """Fetch assistant configuration payload."""


class HistoryWriter(Protocol):
    """Port for persisting call and transcript history."""

    async def create_call_record(
        self,
        *,
        user_id: int,
        assistant_id: Optional[str],
        source: str = "debug",
    ) -> Optional[str]:
        """Create a call record and return backend call ID."""

    async def add_transcript(
        self,
        *,
        call_id: str,
        turn_index: int,
        speaker: str,
        content: str,
        start_ms: int,
        end_ms: int,
        confidence: Optional[float] = None,
        duration_ms: Optional[int] = None,
    ) -> bool:
        """Append one transcript turn segment."""

    async def finalize_call_record(
        self,
        *,
        call_id: str,
        status: str,
        duration_seconds: int,
    ) -> bool:
        """Finalize a call record."""


class KnowledgeSearcher(Protocol):
    """Port for RAG / knowledge retrieval operations."""

    async def search_knowledge_context(
        self,
        *,
        kb_id: str,
        query: str,
        n_results: int = 5,
    ) -> List[Dict[str, Any]]:
        """Search a knowledge source and return ranked snippets."""


class ToolResourceResolver(Protocol):
    """Port for resolving tool metadata/configuration."""

    async def fetch_tool_resource(self, tool_id: str) -> Optional[Dict[str, Any]]:
        """Fetch tool resource configuration."""


class BackendGateway(
    AssistantConfigProvider,
    HistoryWriter,
    KnowledgeSearcher,
    ToolResourceResolver,
    Protocol,
):
    """Composite backend gateway interface used by engine services."""