"""共享 Protocol 端口定义。

LLMProvider / VLMProvider / TelemetryRecorder 是跨子包共享接口，
被 core/agent/、core/evolution/、app/ 各模块引用。
adapters/ 提供具体实现。
"""
from __future__ import annotations

from pathlib import Path
from typing import Any, Protocol, runtime_checkable

from core.types import LLMResponse


@runtime_checkable
class LLMProvider(Protocol):
    """LLM 文本调用端口。"""

    async def chat(
        self,
        messages: list[dict[str, Any]],
        *,
        session_id: str | None = None,
        parent_call_id: str | None = None,
    ) -> LLMResponse: ...


@runtime_checkable
class VLMProvider(Protocol):
    """VLM 图文调用端口。"""

    async def chat_with_images(
        self,
        messages: list[dict[str, Any]],
        images: list[str | Path],
        *,
        session_id: str | None = None,
        parent_call_id: str | None = None,
    ) -> LLMResponse: ...


@runtime_checkable
class TelemetryRecorder(Protocol):
    """LLM 调用遥测记录端口。"""

    async def record_llm_call(
        self,
        *,
        call_id: str,
        parent_call_id: str | None,
        session_id: str | None,
        model_name: str,
        provider: str,
        messages: str,
        response: str,
        thinking: str,
        prompt_tokens: int,
        completion_tokens: int,
        latency_ms: int,
        ttft_ms: float | None,
        max_inter_token_ms: float | None,
        cache_hit: bool,
        error: str | None,
    ) -> None: ...