sdpy-kit 0.2.6__tar.gz → 0.3.0__tar.gz

{sdpy_kit-0.2.6 → sdpy_kit-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sdpy-kit
-Version: 0.2.6
+Version: 0.3.0
 Summary: SDPY Kit——统一数据库访问层（PG/MySQL/SQLite）与 AI/MCP/Redis/文件/文档/向量工具集
 Author-email: Clark <changhongyuan@126.com>
 License-Expression: MIT
@@ -29,6 +29,8 @@ Requires-Dist: docxtpl>=0.20.2; extra == 'all'
 Requires-Dist: fastmcp>=4.1.0; extra == 'all'
 Requires-Dist: firecrawl-anydoc>=0.2.4; extra == 'all'
 Requires-Dist: httpx>=0.28.1; extra == 'all'
+Requires-Dist: huggingface-hub<2,>=1.5; extra == 'all'
+Requires-Dist: laya>=0.4.6; extra == 'all'
 Requires-Dist: markdown-it-py>=4.2.0; extra == 'all'
 Requires-Dist: marker-pdf[full]>=2.0.0; extra == 'all'
 Requires-Dist: numpy>=2.5.4; extra == 'all'
@@ -46,6 +48,9 @@ Requires-Dist: firecrawl-anydoc>=0.2.4; extra == 'anydoc'
 Requires-Dist: pikepdf>=10.17.0; extra == 'anydoc'
 Provides-Extra: docx
 Requires-Dist: docxtpl>=0.20.2; extra == 'docx'
+Provides-Extra: laya
+Requires-Dist: huggingface-hub<2,>=1.5; extra == 'laya'
+Requires-Dist: laya>=0.4.6; extra == 'laya'
 Provides-Extra: marker
 Requires-Dist: marker-pdf[full]>=2.0.0; extra == 'marker'
 Provides-Extra: mcp

{sdpy_kit-0.2.6 → sdpy_kit-0.3.0}/kit/__init__.py

@@ -23,7 +23,7 @@ Author: Clark Chang
 数据库访问通过 kit.db 子包提供（基于 SQLModel）。
 """
 
-__version__ = "0.2.6"
+__version__ = "0.3.0"
 
 from kit.db import (
     MYSQL,

{sdpy_kit-0.2.6 → sdpy_kit-0.3.0}/kit/config/kit_config.py

@@ -142,6 +142,26 @@ class Settings(BaseSettings):
         description="llama-server 可执行文件路径（None 时沿用系统 LLAMA_CPP_BINARY）",
     )
 
+    # Laya 决策引擎配置（本地小模型，把任意文本变成 choice/score/noul 类型化决策）
+    LAYA_MODEL: str = Field(
+        default="multilingual",
+        description=(
+            "生效检查点：multilingual（多语言含中文）/ english / typed-decisions"
+        ),
+    )
+    LAYA_DEVICE: str | None = Field(
+        default=None,
+        description="推理设备（如 cpu / cuda），None 表示交给 laya 自动选择",
+    )
+    LAYA_HF_ENDPOINT: str = Field(
+        default="https://hf-mirror.com",
+        description="检查点权重下载入口（默认国内镜像），置空则使用 HuggingFace 官方源",
+    )
+    LAYA_HF_DISABLE_XET: bool = Field(
+        default=True,
+        description="禁用 HF Xet 存储后端（国内镜像不支持，开启会导致权重下载挂起）",
+    )
+
     class Config:
         env_file = ".env"
         env_file_encoding = "utf-8"

sdpy_kit-0.3.0/kit/laya_kit.py

@@ -0,0 +1,302 @@
+"""
+Copyright (c) 2021-2026 Clark Chang. All Rights Reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+Project: sdpy
+Author: Clark Chang
+"""
+
+# date: 2026-10-13
+"""laya 决策引擎工具类，把任意文本变成类型化决策
+
+laya（https://github.com/NandhaKishorM/laya）是单次前向传播的类型化决策引擎
+（多语言、非自回归），本工具类封装它的三类决策原语：
+
+- `choice(state, instructions, criteria)`：候选标签里选一个，`decision` 为选中标签；
+- `score(state, instructions, criteria)`：序数标尺上评分，`decision` 为期望值；
+- `noul(state, instructions)`：判断是否成立，`decision` 为 P(true)（0.0-1.0）。
+
+三者都返回 `{decision, answer_confidence, probabilities}`——判断结果 + 置信度；
+需要完整字段（`routing` / `usage`）时用 `predict()` + `brief()`。
+
+关键用法（实测得出，务必遵守）：
+
+- 判断规则必须写进 `instructions`，只靠 `criteria` 描述做语义推断会判错；
+- 候选标签的文字本身会改变输出分布（中文标签与英文标签结果不同）；
+- **措辞敏感**：同一意思换同义词会明显改变 `answer_confidence`（如「退款」→「退费」
+  使置信度由 0.92 降到 0.57），因此**不要用绝对置信度做门控阈值**；需要稳定请在
+  业务侧做输入归一化——本工具类**不改写任何文本**；
+- 上游检查点温度标定无效，置信度未经标定，仅供参考。
+
+配置走 `kit.config.Settings`（`.env` / 环境变量）：`LAYA_MODEL`（检查点）、
+`LAYA_DEVICE`（推理设备）、`LAYA_HF_ENDPOINT`（权重下载入口）、`LAYA_HF_DISABLE_XET`。
+**HF 相关环境变量必须在导入本模块前生效**（本模块导入即设置并加载 laya），
+如需自定义请在 `.env` 或进程启动前设置。
+
+用法：
+    from kit.laya_kit import LayaKit
+
+    result = LayaKit.choice(
+        state="我们三月份被重复扣费了两次，请把重复的那笔退款。",
+        instructions="这封来信应该由哪个部门处理？",
+        criteria={"账务": "账单、付款、退款", "技术": "故障、报错"},
+    )
+    print(result["decision"], result["answer_confidence"])
+
+说明：本模块为可选依赖，需安装 `pip install "sdpy-kit[laya]"`；首次使用会下载
+检查点权重（322M-421M 参数），模型常驻内存，用完可 `LayaKit.unload()` 释放。
+"""
+
+import os
+import threading
+from typing import Any
+
+from kit.config.kit_config import get_settings
+from kit.config.log_config import get_default_logger
+
+logger = get_default_logger(__name__)
+
+_settings = get_settings()
+
+# HuggingFace 相关环境必须在导入 laya / huggingface_hub 之前设置，否则不生效。
+# 统一使用 setdefault：仅当用户未显式设置环境变量时生效，不覆盖显式配置。
+if _settings.LAYA_HF_ENDPOINT:
+    os.environ.setdefault("HF_ENDPOINT", _settings.LAYA_HF_ENDPOINT)
+if _settings.LAYA_HF_DISABLE_XET:
+    os.environ.setdefault("HF_HUB_DISABLE_XET", "1")
+
+try:
+    import laya
+except ImportError as e:
+    raise ImportError(
+        "laya_kit 需要可选依赖，请安装：pip install sdpy-kit[laya]"
+    ) from e
+
+# 单问题封装使用的内部问题 id（调用方无需关心）
+_QID: str = "answer"
+
+# 决策原语的取值键（与 laya 返回体一致，按优先级取第一个存在的）
+_DECISION_KEYS: tuple[str, ...] = ("choice", "score", "noul")
+
+
+class LayaError(Exception):
+    """laya 决策异常（模型加载失败 / 推理失败 / 返回体不符合预期）"""
+
+
+class LayaKit:
+    """laya 决策引擎工具类（无状态，方法均为 `classmethod`）
+
+    Router 为类级单例（模型加载开销极大，必须复用），配置统一走
+    `kit.config.Settings` 的 `LAYA_*` 配置项；**不改写任何输入文本**。
+    """
+
+    _router: Any = None
+    _router_lock: threading.Lock = threading.Lock()
+
+    @classmethod
+    def router(cls) -> Any:
+        """惰性创建并缓存 Router（进程内单例，线程安全）
+
+        Returns:
+            Any: laya.Router 实例
+        """
+        with cls._router_lock:
+            if cls._router is None:
+                kwargs: dict[str, Any] = {"default": _settings.LAYA_MODEL}
+                if _settings.LAYA_DEVICE:
+                    kwargs["device"] = _settings.LAYA_DEVICE
+                logger.info(
+                    f"加载 laya Router：检查点={_settings.LAYA_MODEL}，"
+                    f"设备={_settings.LAYA_DEVICE or 'auto'}"
+                )
+                cls._router = laya.Router(**kwargs)
+        return cls._router
+
+    @classmethod
+    def route(
+        cls, state: str | dict[str, Any], questions: dict[str, Any] | None = None
+    ) -> dict[str, Any]:
+        """纯路由决策（不加载检查点、不下载权重，可离线）
+
+        Args:
+            state: 任意文本或结构化 state
+            questions: 可选问题定义（None 时只做语言/脚本探测）
+
+        Returns:
+            dict[str, Any]: 路由结果，含 `model` / `reason` / `detection`
+        """
+        decision = cls.router().route(state, questions)
+        if isinstance(decision, dict):
+            return decision
+        raw = getattr(decision, "__dict__", None)
+        if isinstance(raw, dict):
+            return raw
+        return {
+            "model": getattr(decision, "model", None),
+            "reason": getattr(decision, "reason", None),
+        }
+
+    @classmethod
+    def predict(
+        cls,
+        state: str | dict[str, Any],
+        questions: dict[str, Any],
+        *,
+        min_confidence: float | None = None,
+    ) -> dict[str, Any]:
+        """多问题一次前向传播，返回 laya 原始结果（`answers` / `routing` / `usage`）
+
+        Args:
+            state: 任意文本或结构化 state
+            questions: 问题定义字典（choice / score / noul 可混合）
+            min_confidence: 置信度门控阈值，低于该值会在答案里标记 low_confidence；
+                注意上游置信度未标定（见模块 docstring），阈值需自行标定
+
+        Returns:
+            dict[str, Any]: laya 原始返回（字段最全，便于调用方自行取用）
+        """
+        kwargs: dict[str, Any] = {"model": _settings.LAYA_MODEL}
+        if min_confidence is not None:
+            kwargs["min_confidence"] = min_confidence
+        return cls.router().predict(state, questions, **kwargs)
+
+    @classmethod
+    def brief(cls, raw: dict[str, Any]) -> dict[str, Any]:
+        """把 predict 原始结果压成「判断结果 + 置信度」两部分
+
+        Args:
+            raw: `predict()` 的原始返回
+
+        Returns:
+            dict[str, Any]: 问题 id → {decision, answer_confidence, probabilities}
+        """
+        brief: dict[str, Any] = {}
+        for qid, answer in (raw.get("answers") or {}).items():
+            if not isinstance(answer, dict):
+                brief[qid] = answer
+                continue
+            decision = next(
+                (answer[key] for key in _DECISION_KEYS if key in answer),
+                None,
+            )
+            brief[qid] = {
+                "decision": decision,
+                "answer_confidence": answer.get("answer_confidence"),
+                "probabilities": answer.get("probabilities"),
+            }
+        return brief
+
+    @classmethod
+    def choice(
+        cls,
+        state: str | dict[str, Any],
+        instructions: str,
+        criteria: dict[str, str],
+        *,
+        min_confidence: float | None = None,
+    ) -> dict[str, Any]:
+        """单选题：在 `criteria` 给出的候选标签里选一个
+
+        Args:
+            state: 待判断的文本或结构化 state
+            instructions: 判断规则与问题——**规则写这里**，不要只写在 criteria 描述里
+            criteria: 候选标签 → 该标签的说明文字
+            min_confidence: 置信度门控阈值
+
+        Returns:
+            dict[str, Any]: {decision: 选中标签, answer_confidence, probabilities}
+        """
+        question = {
+            "type": "choice",
+            "instructions": instructions,
+            "criteria": criteria,
+        }
+        return cls._ask(question, state, min_confidence)
+
+    @classmethod
+    def score(
+        cls,
+        state: str | dict[str, Any],
+        instructions: str,
+        criteria: list[str],
+        *,
+        min_confidence: float | None = None,
+    ) -> dict[str, Any]:
+        """评分题：在 `criteria` 给出的序数标尺上给出期望值
+
+        Args:
+            state: 待判断的文本或结构化 state
+            instructions: 判断规则与问题
+            criteria: 从低到高的等级描述列表
+            min_confidence: 置信度门控阈值
+
+        Returns:
+            dict[str, Any]: {decision: 序数期望值, answer_confidence, probabilities}
+        """
+        question = {
+            "type": "score",
+            "instructions": instructions,
+            "criteria": criteria,
+        }
+        return cls._ask(question, state, min_confidence)
+
+    @classmethod
+    def noul(
+        cls,
+        state: str | dict[str, Any],
+        instructions: str,
+        *,
+        min_confidence: float | None = None,
+    ) -> dict[str, Any]:
+        """是否题：返回 P(true)
+
+        Args:
+            state: 待判断的文本或结构化 state
+            instructions: 待判断的命题（如「客户是否明确要求退款？」）
+            min_confidence: 置信度门控阈值
+
+        Returns:
+            dict[str, Any]: {decision: P(true), answer_confidence, probabilities}
+        """
+        question = {"type": "noul", "instructions": instructions}
+        return cls._ask(question, state, min_confidence)
+
+    @classmethod
+    def _ask(
+        cls,
+        question: dict[str, Any],
+        state: str | dict[str, Any],
+        min_confidence: float | None,
+    ) -> dict[str, Any]:
+        """单问题封装：构造 questions → predict → 取该问的 brief 结果
+
+        Raises:
+            LayaError: laya 未返回该问题的答案时抛出（返回体结构变化）
+        """
+        raw = cls.predict(state, {_QID: question}, min_confidence=min_confidence)
+        brief = cls.brief(raw)
+        if _QID not in brief:
+            raise LayaError(f"laya 未返回问句 {_QID} 的答案：{raw!r}")
+        return brief[_QID]
+
+    @classmethod
+    def unload(cls) -> None:
+        """释放 Router 与模型内存（先调用底层 unload，再置空单例）"""
+        with cls._router_lock:
+            if cls._router is not None:
+                unload_fn = getattr(cls._router, "unload", None)
+                if callable(unload_fn):
+                    unload_fn()
+                cls._router = None
+                logger.info("laya Router 已释放")

{sdpy_kit-0.2.6 → sdpy_kit-0.3.0}/pyproject.toml

@@ -52,6 +52,7 @@ dynamic = ["version"]
 #   docx   → docx_kit（docxtpl + python-docx，模板动态填充）
 #   mineru → mineru_kit（requests）
 #   marker → marker_kit（marker-pdf[full]，本地模型解析 PDF→Markdown+Images）
+#   laya   → laya_kit（laya + torch，本地类型化决策引擎 choice/score/noul）
 # 基础版 = config/log + kit.db 核心，SQLite 常规操作用标准库 sqlite3，零额外依赖。
 [project.optional-dependencies]
 pg = ["psycopg2-binary>=2.9.13"]
@@ -78,6 +79,10 @@ anydoc = [
 docx = ["docxtpl>=0.20.2"]
 mineru = ["requests>=2.34.2"]
 marker = ["marker-pdf[full]>=2.0.0"]
+laya = [
+    "laya>=0.4.6",
+    "huggingface-hub>=1.5,<2",
+]
 all = [
     "psycopg2-binary>=2.9.13",
     "pymysql>=1.2.3",
@@ -95,6 +100,8 @@ all = [
     "docxtpl>=0.20.2",
     "requests>=2.34.2",
     "marker-pdf[full]>=2.0.0",
+    "laya>=0.4.6",
+    "huggingface-hub>=1.5,<2",
 ]
 [tool.hatch.version]
 path = "kit/__init__.py"