tketool.llm 1.3.4__py3-none-any.whl

tketool/llm/__init__.py

@@ -0,0 +1,7 @@
+"""Public large-model API for tketool.
+
+The implementation remains available from :mod:`tketool.lmc` for backward
+compatibility. New code should import from :mod:`tketool.llm`.
+"""
+
+from tketool.lmc import *

tketool/lmc/__init__.py

@@ -0,0 +1,5 @@
+from tketool.lmc.lmc_linked import *
+from tketool.lmc.lmc_prompt_invoker import *
+from tketool.lmc.prompts.prompt_controller import get_prompt
+from tketool.lmc.llms.openai import OpenAI_Complete_Model, OpenAI_Response_Model
+from tketool.lmc.embeddings import *

tketool/lmc/agent_framework/__init__.py

@@ -0,0 +1,5 @@
+"""LLM agent framework public interfaces."""
+
+from tketool.lmc.agent_framework.memory import *
+from tketool.lmc.agent_framework.observer import *
+from tketool.lmc.agent_framework.mcp_tools import *

tketool/lmc/agent_framework/mcp_tools/__init__.py

@@ -0,0 +1,4 @@
+from tketool.lmc.agent_framework.mcp_tools.tool_types import *
+from tketool.lmc.agent_framework.mcp_tools.interfaces import *
+from tketool.lmc.agent_framework.mcp_tools.registry import *
+from tketool.lmc.agent_framework.mcp_tools.function_handler import *

tketool/lmc/agent_framework/mcp_tools/demo_tools.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from tketool.lmc.agent_framework.mcp_tools import *
+
+
+@tool_definition(
+    name="calculate_revenue",
+    description="计算总收入：上午收入 + 下午收入。",
+    parameters=[
+        ToolParameter(name="morning_count", type="int", description="上午销售数量"),
+        ToolParameter(name="morning_price", type="float", description="上午单价"),
+        ToolParameter(name="afternoon_count", type="int", description="下午销售数量"),
+        ToolParameter(name="afternoon_price", type="float", description="下午单价"),
+    ],
+    output_schema={"required": ["revenue", "formula"]},
+)
+def calculate_revenue(
+        morning_count: int,
+        morning_price: float,
+        afternoon_count: int,
+        afternoon_price: float,
+) -> dict:
+    """计算今日总收入。"""
+    revenue = morning_count * morning_price + afternoon_count * afternoon_price
+    formula = (
+        f"{morning_count} x {morning_price:g} + "
+        f"{afternoon_count} x {afternoon_price:g} = {revenue:g}"
+    )
+    return {"revenue": revenue, "formula": formula}
+
+
+def build_demo_tool_registry() -> InMemoryToolRegistry:
+    tools = InMemoryToolRegistry()
+    tools.register(FunctionToolHandler(calculate_revenue))
+    return tools

tketool/lmc/agent_framework/mcp_tools/function_handler.py

@@ -0,0 +1,224 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from inspect import Signature, signature
+from typing import Any
+
+from tketool.lmc.agent_framework.mcp_tools.interfaces import ToolHandler
+from tketool.lmc.agent_framework.mcp_tools.tool_types import (
+    ToolCall,
+    ToolDefinition,
+    ToolParameter,
+    ToolResult,
+    ToolResultStatus,
+)
+from tketool.lmc.agent_framework.observer import FrameworkObserver
+
+
+class FunctionToolHandler(ToolHandler):
+    """把普通 Python 函数适配为 ToolHandler。"""
+
+    def __init__(self, func: Callable, definition: ToolDefinition | None = None):
+        self.func = func
+        self.definition = definition or self._definition_from_func(func)
+
+    def before(self, call: ToolCall) -> ToolCall:
+        """执行前补齐默认参数并校验必填参数。"""
+        arguments = dict(call.arguments)
+        missing = []
+        for parameter in self.definition.parameters:
+            if parameter.name not in arguments:
+                if parameter.required:
+                    missing.append(parameter.name)
+                else:
+                    arguments[parameter.name] = parameter.default
+        if missing:
+            raise ValueError(f"缺少必填参数：{', '.join(missing)}")
+        call.arguments = arguments
+        return call
+
+    def execute(self, call: ToolCall) -> ToolResult:
+        """执行函数并把异常转换为标准 ToolResult。"""
+        try:
+            content = self.func(**call.arguments)
+        except Exception as exc:  # noqa: BLE001
+            return ToolResult(
+                status=ToolResultStatus.FATAL_ERROR,
+                error=str(exc),
+                retryable=False,
+                metadata={"tool_name": self.definition.name},
+            )
+        return ToolResult(
+            status=ToolResultStatus.SUCCESS,
+            content=content,
+            metadata={"tool_name": self.definition.name},
+        )
+
+    def after(self, call: ToolCall, result: ToolResult) -> ToolResult:
+        """执行后补充调用信息。"""
+        result.metadata = {
+            **result.metadata,
+            "call_id": call.call_id,
+            "task_id": call.context.task_id,
+            "step_id": call.context.step_id,
+        }
+        return result
+
+    def validate(self, call: ToolCall, result: ToolResult) -> ToolResult:
+        """校验输出是否满足 output_schema 中的 required 字段要求。"""
+        if result.status != ToolResultStatus.SUCCESS:
+            return result
+        required_fields = (self.definition.output_schema or {}).get("required", [])
+        if required_fields:
+            if not isinstance(result.content, dict):
+                return ToolResult(
+                    status=ToolResultStatus.VALIDATION_ERROR,
+                    content=result.content,
+                    error="工具输出不是 dict，无法校验 required 字段。",
+                    retryable=False,
+                    metadata=result.metadata,
+                )
+            missing = [field for field in required_fields if field not in result.content]
+            if missing:
+                return ToolResult(
+                    status=ToolResultStatus.VALIDATION_ERROR,
+                    content=result.content,
+                    error=f"工具输出缺少字段：{', '.join(missing)}",
+                    retryable=False,
+                    metadata=result.metadata,
+                )
+        return result
+
+    def run(self, call: ToolCall, observer_object: FrameworkObserver | None = None) -> ToolResult:
+        """按 before -> execute -> after -> validate 顺序执行工具。"""
+        span_id = None
+        if observer_object is not None:
+            span_id = observer_object.event_start(
+                "mcp.tool_call",
+                source="mcp",
+                phase="tool",
+                task_id=call.context.task_id,
+                node_id=call.context.step_id,
+                subject={"kind": "tool", "id": self.definition.name},
+                payload={
+                    "tool_name": self.definition.name,
+                    "call_id": call.call_id,
+                    "arguments": dict(call.arguments),
+                    "context_metadata": dict(call.context.metadata),
+                },
+            )
+        try:
+            prepared_call = self.before(call)
+        except Exception as exc:  # noqa: BLE001
+            if observer_object is not None:
+                observer_object.error(
+                    "mcp.tool_call_error",
+                    exc,
+                    source="mcp",
+                    phase="tool",
+                    task_id=call.context.task_id,
+                    node_id=call.context.step_id,
+                    payload={"tool_name": self.definition.name, "call_id": call.call_id, "stage": "before"},
+                )
+                if span_id:
+                    observer_object.event_end(
+                        span_id,
+                        level="error",
+                        status="failed",
+                        payload={"tool_name": self.definition.name, "call_id": call.call_id, "stage": "before", "error": str(exc)},
+                    )
+            return ToolResult(
+                status=ToolResultStatus.FATAL_ERROR,
+                error=str(exc),
+                retryable=False,
+                metadata={"tool_name": self.definition.name},
+            )
+        attempts = max(1, self.definition.retry_policy.max_attempts)
+        last_result: ToolResult | None = None
+        for attempt in range(1, attempts + 1):
+            result = self.execute(prepared_call)
+            result.metadata = {**result.metadata, "attempt": attempt}
+            result = self.after(prepared_call, result)
+            result = self.validate(prepared_call, result)
+            last_result = result
+            if observer_object is not None:
+                observer_object.record(
+                    "mcp.tool_call_attempt",
+                    source="mcp",
+                    phase="tool",
+                    level="error" if result.status != ToolResultStatus.SUCCESS else "info",
+                    task_id=prepared_call.context.task_id,
+                    node_id=prepared_call.context.step_id,
+                    message=result.error or "",
+                    payload={
+                        "tool_name": self.definition.name,
+                        "call_id": prepared_call.call_id,
+                        "attempt": attempt,
+                        "status": result.status,
+                        "retryable": result.retryable,
+                    },
+                )
+            # 只有 retry_policy 明确允许的状态才进入下一次尝试。
+            if result.status not in self.definition.retry_policy.retry_on:
+                if observer_object is not None:
+                    observer_object.event_end(
+                        span_id,
+                        level="error" if result.status != ToolResultStatus.SUCCESS else "info",
+                        status=result.status,
+                        message=result.error or "",
+                        payload={
+                            "tool_name": self.definition.name,
+                            "call_id": prepared_call.call_id,
+                            "status": result.status,
+                            "attempts": attempt,
+                            "has_content": result.content is not None,
+                        },
+                    )
+                return result
+        assert last_result is not None
+        if observer_object is not None:
+            observer_object.event_end(
+                span_id,
+                level="error" if last_result.status != ToolResultStatus.SUCCESS else "info",
+                status=last_result.status,
+                message=last_result.error or "",
+                payload={
+                    "tool_name": self.definition.name,
+                    "call_id": prepared_call.call_id,
+                    "status": last_result.status,
+                    "attempts": attempts,
+                    "has_content": last_result.content is not None,
+                },
+            )
+        return last_result
+
+    def _definition_from_func(self, func: Callable) -> ToolDefinition:
+        """从函数签名生成工具定义，优先使用装饰器附加的定义。"""
+        if hasattr(func, "_tool_definition"):
+            return func._tool_definition
+        parameters = [
+            ToolParameter(
+                name=name,
+                type=self._type_name(param.annotation),
+                description=f"函数参数 {name}",
+                required=param.default is param.empty,
+                default=None if param.default is param.empty else param.default,
+            )
+            for name, param in signature(func).parameters.items()
+        ]
+        return ToolDefinition(
+            name=func.__name__,
+            description=func.__doc__ or f"函数工具：{func.__name__}",
+            parameters=parameters,
+        )
+
+    def _type_name(self, annotation: Any) -> str:
+        """把 Python 类型注解转为简短字符串。"""
+        if annotation is Signature.empty:
+            return "Any"
+        return getattr(annotation, "__name__", str(annotation))
+
+
+def build_function_tool_handler(func: Callable) -> FunctionToolHandler:
+    """从普通函数构造 FunctionToolHandler。"""
+    return FunctionToolHandler(func)

tketool/lmc/agent_framework/mcp_tools/interfaces.py

@@ -0,0 +1,91 @@
+from abc import ABC, abstractmethod
+from collections.abc import Callable
+
+from tketool.lmc.agent_framework.observer import FrameworkObserver
+from tketool.lmc.agent_framework.mcp_tools.tool_types import (
+    ToolCall,
+    ToolDefinition,
+    ToolResult,
+)
+
+
+class ToolHandler(ABC):
+    """工具处理器接口，定义一次工具调用的完整生命周期。"""
+
+    definition: ToolDefinition
+
+    @abstractmethod
+    def before(self, call: ToolCall) -> ToolCall:
+        """执行前处理，例如参数补全、权限检查或日志记录。"""
+        ...
+
+    @abstractmethod
+    def execute(self, call: ToolCall) -> ToolResult:
+        """执行实际工具逻辑。"""
+        ...
+
+    @abstractmethod
+    def after(self, call: ToolCall, result: ToolResult) -> ToolResult:
+        """执行后处理，例如格式整理、指标记录或结果裁剪。"""
+        ...
+
+    @abstractmethod
+    def validate(self, call: ToolCall, result: ToolResult) -> ToolResult:
+        """校验工具结果是否满足调度步骤要求。"""
+        ...
+
+    def run(self, call: ToolCall, observer_object: FrameworkObserver | None = None) -> ToolResult:
+        """执行完整工具生命周期。"""
+        prepared_call = self.before(call)
+        result = self.execute(prepared_call)
+        result = self.after(prepared_call, result)
+        return self.validate(prepared_call, result)
+
+
+class ToolRegistry(ABC):
+    """工具注册表接口，供调度器按名称查找可用工具。"""
+
+    @property
+    @abstractmethod
+    def mcplibcode(self) -> str:
+        """当前注册工具名集合的稳定短 ID。"""
+        ...
+
+    @abstractmethod
+    def register(self, handler: ToolHandler) -> None:
+        """注册一个工具处理器。"""
+        ...
+
+    @abstractmethod
+    def get(self, name: str) -> ToolHandler:
+        """根据工具名称获取处理器。"""
+        ...
+
+    @abstractmethod
+    def list_definitions(self) -> list[ToolDefinition]:
+        """列出当前可用工具定义。"""
+        ...
+
+    def search_definitions(self, query: str, top_k: int = 8) -> list[ToolDefinition]:
+        """按查询文本检索候选工具定义；默认实现回退到全量列表截断。"""
+        return self.list_definitions()[:top_k]
+
+
+def tool_definition(
+    name: str,
+    description: str,
+    parameters: list | None = None,
+    **kwargs,
+) -> Callable:
+    """为普通函数附加工具定义元数据。"""
+
+    def decorator(func: Callable) -> Callable:
+        func._tool_definition = ToolDefinition(
+            name=name,
+            description=description,
+            parameters=parameters or [],
+            **kwargs,
+        )
+        return func
+
+    return decorator

tketool/lmc/agent_framework/mcp_tools/registry.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import hashlib
+import re
+
+from tketool.lmc.agent_framework.mcp_tools.interfaces import ToolHandler, ToolRegistry
+from tketool.lmc.agent_framework.mcp_tools.tool_types import ToolDefinition
+
+
+class ToolRegistrationError(ValueError):
+    """工具注册错误。"""
+
+
+class ToolNotFoundError(KeyError):
+    """工具不存在错误。"""
+
+
+class InMemoryToolRegistry(ToolRegistry):
+    """内存版工具注册表，用于本地运行和单元测试。"""
+
+    def __init__(self):
+        self._handlers: dict[str, ToolHandler] = {}
+
+    @property
+    def mcplibcode(self) -> str:
+        """当前工具名集合的稳定短 ID。"""
+        tool_names = sorted(self._handlers)
+        raw = "\n".join(tool_names)
+        return hashlib.sha1(raw.encode("utf-8")).hexdigest()[:12]
+
+    def register(self, handler: ToolHandler) -> None:
+        """注册一个工具处理器；重名工具默认拒绝。"""
+        name = handler.definition.name
+        if name in self._handlers:
+            raise ToolRegistrationError(f"工具已注册：{name}")
+        self._handlers[name] = handler
+
+    def get(self, name: str) -> ToolHandler:
+        """根据名称获取工具处理器；不存在时抛出明确异常。"""
+        if name not in self._handlers:
+            raise ToolNotFoundError(f"工具不存在：{name}")
+        return self._handlers[name]
+
+    def list_definitions(self) -> list[ToolDefinition]:
+        """按工具名稳定列出工具定义。"""
+        return [
+            self._handlers[name].definition
+            for name in sorted(self._handlers)
+        ]
+
+    def search_definitions(self, query: str, top_k: int = 8) -> list[ToolDefinition]:
+        """用轻量关键词打分检索工具定义。"""
+        definitions = self.list_definitions()
+        query_terms = _tokenize_tool_text(query)
+        if not query_terms:
+            return definitions[:top_k]
+        scored = []
+        for definition in definitions:
+            text = " ".join(
+                [
+                    definition.name,
+                    definition.description,
+                    " ".join(parameter.name for parameter in definition.parameters),
+                    " ".join(parameter.description for parameter in definition.parameters),
+                    " ".join(str(value) for value in definition.metadata.values()),
+                ]
+            )
+            terms = set(_tokenize_tool_text(text))
+            score = sum(1 for term in query_terms if term in terms)
+            scored.append((score, definition.name, definition))
+        scored.sort(key=lambda item: (-item[0], item[1]))
+        return [definition for score, _, definition in scored[:top_k] if score > 0] or definitions[:top_k]
+
+
+def _tokenize_tool_text(text: str) -> list[str]:
+    return [token.lower() for token in re.findall(r"[A-Za-z0-9_/-]+|[\u4e00-\u9fff]{2,}", text)]

tketool/lmc/agent_framework/mcp_tools/simple_code.py

@@ -0,0 +1,73 @@
+"""MCP Tools 模块最小运行示例。
+
+运行方式：
+python -m tketool.lmc.agent_framework.mcp_tools.simple_code
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+
+# 允许从当前文件直接运行，同时避免 mcp_tools 目录里的模块名影响标准库导入。
+for path in list(sys.path):
+    if path == "" or path.endswith("/lmc/agent_framework/mcp_tools"):
+        sys.path.remove(path)
+
+PROJECT_ROOT = Path(__file__).resolve().parents[4]
+if str(PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(PROJECT_ROOT))
+
+from tketool.lmc.agent_framework.mcp_tools import (
+    FunctionToolHandler,
+    InMemoryToolRegistry,
+    ToolCall,
+    ToolContext,
+    ToolParameter,
+    ToolResultStatus,
+    tool_definition,
+)
+
+
+@tool_definition(
+    name="calculate_revenue",
+    description="计算收入：数量乘以单价。",
+    parameters=[
+        ToolParameter(name="count", type="int", description="销售数量"),
+        ToolParameter(name="price", type="float", description="单价"),
+    ],
+    output_schema={"required": ["revenue"]},
+)
+def calculate_revenue(count: int, price: float) -> dict:
+    """计算销售收入。"""
+    return {"revenue": count * price}
+
+
+def main() -> None:
+    registry = InMemoryToolRegistry()
+    registry.register(FunctionToolHandler(calculate_revenue))
+
+    print("已注册工具：")
+    for definition in registry.list_definitions():
+        print(f"- {definition.name}: {definition.description}")
+
+    call = ToolCall(
+        tool_name="calculate_revenue",
+        arguments={"count": 3, "price": 20},
+        context=ToolContext(task_id="demo-task", step_id="execute_tool"),
+        call_id="tool-call-1",
+    )
+    handler = registry.get(call.tool_name)
+    result = handler.run(call)
+
+    print("\n工具调用：")
+    print(f"输入: {call.arguments}")
+    print(f"状态: {result.status.value}")
+    print(f"输出: {result.content}")
+    if result.status != ToolResultStatus.SUCCESS:
+        print(f"错误: {result.error}")
+
+
+if __name__ == "__main__":
+    main()

tketool/lmc/agent_framework/mcp_tools/tool_types.py

@@ -0,0 +1,122 @@
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import Any, Optional
+
+
+class ToolRisk(str, Enum):
+    """工具风险等级，用于调度器决定是否需要额外确认或降级。"""
+
+    # 低风险工具，例如只读查询、纯计算、格式转换。
+    LOW = "low"
+    # 中风险工具，例如写入临时文件、调用外部服务、产生费用。
+    MEDIUM = "medium"
+    # 高风险工具，例如删除数据、提交变更、影响生产系统。
+    HIGH = "high"
+
+
+class ToolResultStatus(str, Enum):
+    """工具调用结果状态。"""
+
+    # 调用成功。
+    SUCCESS = "success"
+    # 可重试错误，例如短暂网络失败、限流。
+    RETRYABLE_ERROR = "retryable_error"
+    # 不可重试错误，例如参数非法、工具不存在、权限不足。
+    FATAL_ERROR = "fatal_error"
+    # 工具执行完成，但结果不满足输出要求。
+    VALIDATION_ERROR = "validation_error"
+
+
+@dataclass
+class RetryPolicy:
+    """工具重试策略。"""
+
+    # 最大尝试次数，包含第一次调用。
+    max_attempts: int = 1
+    # 哪些结果状态允许重试。
+    retry_on: list[ToolResultStatus] = field(
+        default_factory=lambda: [ToolResultStatus.RETRYABLE_ERROR]
+    )
+
+
+@dataclass
+class ToolParameter:
+    """工具参数定义。"""
+
+    # 参数名，与 ToolCall.arguments 中的 key 对应。
+    name: str
+    # 参数类型描述，例如 str、int、float、bool、dict。
+    type: str
+    # 参数说明，供 LLM 或调用方理解如何填写。
+    description: str
+    # 是否必填；缺失必填参数时 before 阶段会拒绝。
+    required: bool = True
+    # 默认值；非必填参数缺失时可自动补齐。
+    default: Any = None
+
+
+@dataclass
+class ToolDefinition:
+    """工具能力定义，描述名称、参数、输出和风险等级。"""
+
+    # 工具唯一名称，注册表按该字段查找 ToolHandler。
+    name: str
+    # 工具用途说明，供调度器或 LLM 选择工具时使用。
+    description: str
+    # 工具参数列表。
+    parameters: list[ToolParameter] = field(default_factory=list)
+    # 输出结构约束；第一版只做轻量存在性校验。
+    output_schema: Optional[dict[str, Any]] = None
+    # 工具风险等级。
+    risk: ToolRisk = ToolRisk.LOW
+    # 工具重试策略。
+    retry_policy: RetryPolicy = field(default_factory=RetryPolicy)
+    # 工具扩展信息，例如标签、版本、外部系统名称。
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class ToolContext:
+    """工具调用上下文，记录任务、步骤和调用侧元数据。"""
+
+    # 调用所属任务 ID。
+    task_id: str
+    # 调用所属调度步骤 ID。
+    step_id: str
+    # 调用用户或主体 ID。
+    user: Optional[str] = None
+    # 调用侧扩展信息，例如 trace_id、审批信息、环境。
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class ToolCall:
+    """一次工具调用请求。"""
+
+    # 要调用的工具名称。
+    tool_name: str
+    # 工具入参。
+    arguments: dict[str, Any]
+    # 工具调用上下文。
+    context: ToolContext
+    # 调用 ID，用于日志、重试和幂等；为空时可由调用方后续补齐。
+    call_id: Optional[str] = None
+    # 调用创建时间。
+    created_at: datetime = field(default_factory=datetime.now)
+
+
+@dataclass
+class ToolResult:
+    """一次工具调用结果。"""
+
+    # 调用结果状态。
+    status: ToolResultStatus
+    # 成功时的返回内容。
+    content: Any = None
+    # 失败时的错误说明。
+    error: Optional[str] = None
+    # 是否可重试，通常和 status/retry_policy 联合使用。
+    retryable: bool = False
+    # 结果扩展信息，例如耗时、尝试次数、校验细节。
+    metadata: dict[str, Any] = field(default_factory=dict)

tketool/lmc/agent_framework/memory/__init__.py

@@ -0,0 +1,2 @@
+from tketool.lmc.agent_framework.memory.types import *
+from tketool.lmc.agent_framework.memory.interfaces import *