"""LLM client 需要实现的共享协议。"""

from __future__ import annotations

from typing import Any, Protocol

from pam_deploy_graph.models import (
    ActionResult,
    ExecutionStrategy,
    LlmActionAnalysis,
    LlmDeployPlan,
    LlmIntentResult,
    LlmModeDecision,
    LlmParamResult,
)


class LlmClient(Protocol):
    """Agent 使用的最小 LLM 能力接口。"""

    def understand_request(self, text: str) -> LlmIntentResult:
        """识别用户自然语言请求的意图。"""
        ...

    def extract_params(self, text: str, base_params: dict[str, Any] | None = None) -> LlmParamResult:
        """从自然语言中抽取部署参数。"""
        ...

    def generate_plan(
        self,
        *,
        params: dict[str, Any],
        intent: str,
        strategy: ExecutionStrategy,
        skill_policy: dict[str, Any],
        tool_summaries: list[dict[str, Any]],
    ) -> LlmDeployPlan:
        """根据参数和意图生成部署计划。"""
        ...

    def decide_execution_mode(
        self,
        *,
        text: str,
        params: dict[str, Any],
        intent: str,
        strategy: ExecutionStrategy,
        allowed_modes: list[str],
        tool_summaries: list[dict[str, Any]],
    ) -> LlmModeDecision:
        """决定进入固定 runtime 还是 agentic skill 模式。"""
        ...

    def analyze_action_result(
        self,
        *,
        action: str,
        result: ActionResult,
        state_summary: dict[str, Any],
    ) -> LlmActionAnalysis:
        """分析 action 执行结果，并给出是否允许继续执行的建议。"""
        ...