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

from __future__ import annotations

from typing import Any, Protocol

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