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

from __future__ import annotations

from typing import Any, Protocol

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


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,
    ) -> LlmDeployPlan:
        """根据参数和意图生成部署计划。"""
        ...

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

    def chat(self, text: str, context: dict[str, Any] | None = None) -> str:
        """进行普通自然语言对话，不触发部署 workflow。"""
        ...

    def analyze_log(self, log_text: str, question: str | None = None, source_path: str = "") -> str:
        """分析日志文本并给出异常摘要、原因和建议。"""
        ...

    def propose_action(
        self,
        text: str,
        allowed_actions: list[str],
        params: dict[str, Any],
        state_summary: dict[str, Any] | None = None,
    ) -> LlmSingleActionProposal:
        """把自然语言解析为单次 action 调用建议。"""
        ...