my-llmkit 0.3.0__py3-none-any.whl

my_llmkit/__init__.py

@@ -0,0 +1,7 @@
+# coding=utf-8
+#
+# my_llmkit 包初始化
+# 导入 log 模块以确保日志配置生效
+#
+
+from . import log  # noqa: F401

my_llmkit/chat/__init__.py

@@ -0,0 +1,93 @@
+# coding=utf-8
+#
+# chat 包对外门面，保持 my_llmkit.chat 导入路径不变
+#
+from dotenv import load_dotenv
+
+load_dotenv()
+
+from .types import (
+    UnifiedToolCall,
+    UnifiedUsage,
+    UnifiedChunk,
+    UnifiedResponse,
+    ContentBlock,
+    TextContent,
+    ImageContent,
+    DocumentContent,
+    UnifiedToolResult,
+    UnifiedMessage,
+    UnifiedToolParam,
+)
+from .events import (
+    Usage,
+    ChatCompletionStreamContentEvent,
+    ChatCompletionStreamReasoningContentEvent,
+    ChatCompletionStreamToolApprovalRequestEvent,
+    ChatCompletionStreamToolApprovalResultEvent,
+    ChatCompletionStreamToolCallStartEvent,
+    ChatCompletionStreamToolCallResultEvent,
+    ChatCompletionStreamUsageEvent,
+)
+from .approval import (
+    DenyToolApprovalHandler,
+    ToolApprovalDecision,
+    ToolApprovalHandler,
+    ToolApprovalRequest,
+)
+from .tools import (
+    ToolFunction,
+    ToolFunctions,
+    ToolExecutor,
+    make_mcp_tool_name,
+    set_tool_approval,
+)
+from .processor import ChatCompletionStreamProcessor
+from .runner import (
+    ChatCompletionResult,
+    ChatCompletionStreamRunner,
+    MaxRoundsExceededError,
+    MessagePreparer,
+)
+from .base import LLMChatCompletion
+from .openai_compatible import OpenAICompatibleChatCompletion
+from .claude import ClaudeChatCompletion
+
+__all__ = [
+    "UnifiedToolCall",
+    "UnifiedUsage",
+    "UnifiedChunk",
+    "UnifiedResponse",
+    "ContentBlock",
+    "TextContent",
+    "ImageContent",
+    "DocumentContent",
+    "UnifiedToolResult",
+    "UnifiedMessage",
+    "UnifiedToolParam",
+    "Usage",
+    "ChatCompletionStreamContentEvent",
+    "ChatCompletionStreamReasoningContentEvent",
+    "ChatCompletionStreamToolApprovalRequestEvent",
+    "ChatCompletionStreamToolApprovalResultEvent",
+    "ChatCompletionStreamToolCallStartEvent",
+    "ChatCompletionStreamToolCallResultEvent",
+    "ChatCompletionStreamUsageEvent",
+    "DenyToolApprovalHandler",
+    "ToolApprovalDecision",
+    "ToolApprovalHandler",
+    "ToolApprovalRequest",
+    "ToolFunction",
+    "ToolFunctions",
+    "ToolExecutor",
+    "make_mcp_tool_name",
+    "set_tool_approval",
+    "ChatCompletionStreamProcessor",
+    "ChatCompletionResult",
+    "ChatCompletionStreamRunner",
+    "MaxRoundsExceededError",
+    "MessagePreparer",
+    "LLMChatCompletion",
+    "OpenAICompatibleChatCompletion",
+    "ClaudeChatCompletion",
+]

my_llmkit/chat/approval.py

@@ -0,0 +1,64 @@
+# coding=utf-8
+#
+# Tool approval primitives
+#
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass
+from typing import Protocol
+
+from .types import UnifiedToolCall
+
+
+@dataclass
+class ToolApprovalRequest:
+    approval_id: str
+    tool_call_id: str
+    tool_name: str
+    arguments: str
+    reason: str | None = None
+
+    @classmethod
+    def from_tool_call(
+        cls,
+        tool_call: UnifiedToolCall,
+        reason: str | None = None,
+    ) -> "ToolApprovalRequest":
+        return cls(
+            approval_id=f"appr_{uuid.uuid4().hex}",
+            tool_call_id=tool_call.id,
+            tool_name=tool_call.name,
+            arguments=tool_call.arguments or "{}",
+            reason=reason,
+        )
+
+
+@dataclass
+class ToolApprovalDecision:
+    approved: bool
+    reason: str | None = None
+
+
+class ToolApprovalHandler(Protocol):
+    async def request_approval(
+        self,
+        request: ToolApprovalRequest,
+    ) -> ToolApprovalDecision:
+        ...
+
+
+class DenyToolApprovalHandler:
+    def __init__(self, reason: str = "Tool execution denied"):
+        self.reason = reason
+
+    async def request_approval(
+        self,
+        request: ToolApprovalRequest,
+    ) -> ToolApprovalDecision:
+        return ToolApprovalDecision(approved=False, reason=self.reason)
+
+
+def denied_tool_result(request: ToolApprovalRequest, reason: str | None = None) -> str:
+    detail = reason or "Tool execution was not approved"
+    return f"Tool approval denied for {request.tool_name}: {detail}"

my_llmkit/chat/base.py

@@ -0,0 +1,193 @@
+# coding=utf-8
+#
+# 抽象基类
+#
+import logging
+from abc import ABC, abstractmethod
+from typing import AsyncIterator, Optional, Type, Union
+
+
+from .model_settings import ModelSettings
+from pydantic import BaseModel
+
+from ..mcp.mcp_client import MCPServerType
+from .approval import DenyToolApprovalHandler, ToolApprovalHandler
+from .events import Usage
+from .runner import (
+    ChatCompletionResult,
+    ChatCompletionStreamRunner,
+    MaxRoundsExceededError,
+    MessagePreparer,
+)
+from .tools import ToolExecutor, ToolFunctions
+from .types import UnifiedChunk, UnifiedMessage, UnifiedResponse
+
+logger = logging.getLogger(__name__)
+
+
+class LLMChatCompletion(ABC):
+    """
+    LLM 客户端抽象基类 - 使用统一类型，与任何 SDK 解耦。
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        api_base: str,
+        model: str,
+        model_settings: Optional[ModelSettings] = None,
+        timeout: Optional[float] = None,
+    ):
+        self.api_key = api_key
+        self.api_base = api_base
+        self.model = model
+        self.model_settings = model_settings or ModelSettings()
+        self.timeout = timeout
+
+    @abstractmethod
+    async def acreate_stream(
+        self,
+        messages: list[UnifiedMessage],
+        tools: Optional[ToolFunctions] = None,
+        mcp_servers: Optional[dict[str, MCPServerType]] = None,
+        response_format: Optional[Union[Type[BaseModel], dict]] = None,
+    ) -> AsyncIterator[UnifiedChunk]:
+        """
+        发起流式请求，返回统一格式的 UnifiedChunk 流。
+        子类负责将厂商特定格式转换为 UnifiedChunk。
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    async def acreate(
+        self,
+        messages: list[UnifiedMessage],
+        tools: Optional[ToolFunctions] = None,
+        mcp_servers: Optional[dict[str, MCPServerType]] = None,
+        response_format: Optional[Union[Type[BaseModel], dict]] = None,
+    ) -> UnifiedResponse:
+        """
+        发起非流式请求，返回统一格式的 UnifiedResponse。
+        子类负责将厂商特定格式转换为 UnifiedResponse。
+        """
+        raise NotImplementedError
+
+    def run_stream(
+        self,
+        messages: list[UnifiedMessage],
+        tools: Optional[ToolFunctions] = None,
+        mcp_servers: Optional[dict[str, MCPServerType]] = None,
+        max_rounds: int = 10,
+        response_format: Optional[Union[Type[BaseModel], dict]] = None,
+        approval_handler: Optional[ToolApprovalHandler] = None,
+        message_preparer: Optional[MessagePreparer] = None,
+    ) -> ChatCompletionStreamRunner:
+        return ChatCompletionStreamRunner(
+            self,
+            messages,
+            tools=tools,
+            mcp_servers=mcp_servers,
+            max_rounds=max_rounds,
+            response_format=response_format,
+            approval_handler=approval_handler,
+            message_preparer=message_preparer,
+        )
+
+    async def run(
+        self,
+        messages: list[UnifiedMessage],
+        tools: Optional[ToolFunctions] = None,
+        mcp_servers: Optional[dict[str, MCPServerType]] = None,
+        max_rounds: int = 10,
+        response_format: Optional[Union[Type[BaseModel], dict]] = None,
+        message_preparer: Optional[MessagePreparer] = None,
+    ) -> ChatCompletionResult:
+        """
+        非流式多轮对话，直接返回完整结果。
+        """
+        inner_messages = messages.copy()
+        usages: list[Usage] = []
+        last_content: Optional[str] = None
+        current_round = 0
+        finished = False
+        tool_executor = ToolExecutor(tools, mcp_servers)
+        approval_handler = DenyToolApprovalHandler(
+            "Tool approval is not available in non-streaming mode"
+        )
+
+        while current_round < max_rounds:
+            logger.debug("========== Round: %s =========", current_round)
+            current_round += 1
+
+            request_messages = (
+                message_preparer(inner_messages)
+                if message_preparer
+                else inner_messages.copy()
+            )
+
+            # 调用模型（非流式）。工具循环的权威历史仍是 inner_messages。
+            response = await self.acreate(
+                messages=request_messages,
+                tools=tools,
+                mcp_servers=mcp_servers,
+                response_format=response_format,
+            )
+
+            # 记录 usage
+            if response.usage:
+                usages.append(
+                    Usage(
+                        completion_tokens=response.usage.completion_tokens,
+                        prompt_tokens=response.usage.prompt_tokens,
+                        total_tokens=response.usage.total_tokens,
+                        reasoning_tokens=response.usage.reasoning_tokens,
+                        cached_tokens=response.usage.cached_tokens,
+                        model=response.usage.model,
+                    )
+                )
+
+            # 构建 assistant 消息
+            assistant_message = UnifiedMessage(
+                role="assistant",
+                content=response.content if response.content else None,
+                reasoning_content=response.reasoning_content
+                if response.reasoning_content
+                else None,
+                tool_calls=response.tool_calls if response.tool_calls else None,
+                vendor_metadata=response.vendor_metadata,
+            )
+            inner_messages.append(assistant_message)
+
+            # 如果没有工具调用，结束循环
+            if not response.tool_calls:
+                last_content = response.content
+                finished = True
+                break
+
+            # 执行工具调用
+            for tool_call in response.tool_calls:
+                tool_result = await tool_executor.execute_result_with_approval(
+                    tool_call,
+                    approval_handler,
+                )
+                tool_message = UnifiedMessage(
+                    role="tool",
+                    content=tool_result.text,
+                    tool_call_id=tool_call.id,
+                    tool_result=tool_result,
+                )
+                inner_messages.append(tool_message)
+
+        if not finished:
+            logger.error("Max rounds exceeded: %s", max_rounds)
+            raise MaxRoundsExceededError(max_rounds)
+
+        return ChatCompletionResult(
+            last_content=last_content,
+            usages=usages,
+            messages=inner_messages,
+            response_format=response_format
+            if isinstance(response_format, type)
+            and issubclass(response_format, BaseModel)
+            else None,
+        )