tketool.llm 1.3.4__tar.gz

tketool_llm-1.3.4/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: tketool.llm
+Version: 1.3.4
+Summary: OpenAI-compatible LLM, structured prompt, scheduler, and memory APIs for tketool
+Author-email: Ke <jiangke1207@icloud.com>
+License-Expression: MIT
+Project-URL: Homepage, https://pypi.org/project/tketool.llm/
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: tketool.core==1.3.4
+Requires-Dist: tketool.ml==1.3.4
+Requires-Dist: openai<4,>=3
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: langchain-core<1.7,>=1.6
+Requires-Dist: pydantic<3,>=2.10
+Provides-Extra: local-embeddings
+Requires-Dist: torch<3,>=2.4; extra == "local-embeddings"
+Requires-Dist: transformers<6,>=5; extra == "local-embeddings"
+Provides-Extra: memory
+Requires-Dist: hindsight-all<1,>=0.9; extra == "memory"
+Provides-Extra: test
+Requires-Dist: pytest<9,>=8; extra == "test"
+
+# tketool.llm
+
+OpenAI-compatible large-model access, structured-output prompts, embeddings,
+memory, tools, and the current scheduler.
+
+```bash
+pip install tketool.llm
+```
+
+## Chat Completions
+
+```python
+import os
+
+from tketool.llm import OpenAI_Complete_Model
+
+llm = OpenAI_Complete_Model(
+    model_name="gpt-4o-mini",
+    apitoken=os.environ["OPENAI_API_KEY"],
+    base_url="https://api.openai.com/v1",
+    call_dict={"temperature": 0.2},
+)
+
+text = llm("用三句话解释向量检索", return_detail=False)
+print(text)
+```
+
+## Responses API
+
+```python
+import os
+
+from tketool.llm import OpenAI_Response_Model
+
+llm = OpenAI_Response_Model(
+    model_name="gpt-5-mini",
+    apitoken=os.environ["OPENAI_API_KEY"],
+    base_url="https://api.openai.com/v1",
+    call_dict={"max_output_tokens": 300},
+)
+
+text, detail = llm("给出一个最小 RAG 流程", return_detail=True)
+print(text)
+print(detail)
+```
+
+Both transports accept a complete `messages` list and return the same detail
+shape. OpenAI-compatible gateways are supported by changing `base_url` and
+`model_name`.
+
+```python
+messages = [
+    {"role": "system", "content": "回答要简洁。"},
+    {"role": "user", "content": "什么是结构化输出？"},
+]
+
+answer = llm("", return_detail=False, messages=messages)
+```
+
+New code should import from `tketool.llm`. The existing `tketool.lmc` path is
+kept as a compatibility API during migration.
+
+Local Hugging Face embeddings are optional:
+
+```bash
+pip install "tketool.llm[local-embeddings]"
+```
+
+The optional `memory` extra requires Python 3.11 or newer because its external
+backend does. The legacy `agent`/`context` implementation was removed because
+it depended on the retired scheduler; use `scheduler2` for current agent flows.

tketool_llm-1.3.4/README.md

@@ -0,0 +1,71 @@
+# tketool.llm
+
+OpenAI-compatible large-model access, structured-output prompts, embeddings,
+memory, tools, and the current scheduler.
+
+```bash
+pip install tketool.llm
+```
+
+## Chat Completions
+
+```python
+import os
+
+from tketool.llm import OpenAI_Complete_Model
+
+llm = OpenAI_Complete_Model(
+    model_name="gpt-4o-mini",
+    apitoken=os.environ["OPENAI_API_KEY"],
+    base_url="https://api.openai.com/v1",
+    call_dict={"temperature": 0.2},
+)
+
+text = llm("用三句话解释向量检索", return_detail=False)
+print(text)
+```
+
+## Responses API
+
+```python
+import os
+
+from tketool.llm import OpenAI_Response_Model
+
+llm = OpenAI_Response_Model(
+    model_name="gpt-5-mini",
+    apitoken=os.environ["OPENAI_API_KEY"],
+    base_url="https://api.openai.com/v1",
+    call_dict={"max_output_tokens": 300},
+)
+
+text, detail = llm("给出一个最小 RAG 流程", return_detail=True)
+print(text)
+print(detail)
+```
+
+Both transports accept a complete `messages` list and return the same detail
+shape. OpenAI-compatible gateways are supported by changing `base_url` and
+`model_name`.
+
+```python
+messages = [
+    {"role": "system", "content": "回答要简洁。"},
+    {"role": "user", "content": "什么是结构化输出？"},
+]
+
+answer = llm("", return_detail=False, messages=messages)
+```
+
+New code should import from `tketool.llm`. The existing `tketool.lmc` path is
+kept as a compatibility API during migration.
+
+Local Hugging Face embeddings are optional:
+
+```bash
+pip install "tketool.llm[local-embeddings]"
+```
+
+The optional `memory` extra requires Python 3.11 or newer because its external
+backend does. The legacy `agent`/`context` implementation was removed because
+it depended on the retired scheduler; use `scheduler2` for current agent flows.

tketool_llm-1.3.4/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tketool.llm"
+version = "1.3.4"
+description = "OpenAI-compatible LLM, structured prompt, scheduler, and memory APIs for tketool"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Ke", email = "jiangke1207@icloud.com" }]
+dependencies = [
+  "tketool.core==1.3.4",
+  "tketool.ml==1.3.4",
+  "openai>=3,<4",
+  "httpx>=0.27,<1",
+  "langchain-core>=1.6,<1.7",
+  "pydantic>=2.10,<3",
+]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Operating System :: OS Independent",
+]
+
+[project.optional-dependencies]
+local-embeddings = ["torch>=2.4,<3", "transformers>=5,<6"]
+memory = ["hindsight-all>=0.9,<1"]
+test = ["pytest>=8,<9"]
+
+[project.scripts]
+lmc = "tketool.lmc_console_tool:main"
+
+[project.urls]
+Homepage = "https://pypi.org/project/tketool.llm/"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["tketool*"]
+namespaces = true
+
+[tool.setuptools.package-data]
+"tketool.lmc.prompts" = ["templates/*/*.txt"]

tketool_llm-1.3.4/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tketool_llm-1.3.4/src/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_llm-1.3.4/src/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_llm-1.3.4/src/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_llm-1.3.4/src/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_llm-1.3.4/src/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_llm-1.3.4/src/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_llm-1.3.4/src/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_llm-1.3.4/src/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)]