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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sdpy-kit
-Version: 0.2.5
+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
@@ -512,7 +517,15 @@ PgKit.search_vectors("my_vec", [0.1] * 384, top_k=5, id_col="vid", column="vec")
 > 新增（非破坏性）：`VECTOR_CAPABILITIES` 能力声明、`id_col` / `column` 逃生口参数、
 > `insert_vectors` 支持二维 numpy 数组与批量提交。
 
-#### 0.2.5 变更（开发中，未发布）
+#### 0.2.6 变更
+
+| 编号 | 变更 | 影响 |
+|------|------|------|
+| D1 | `prepare_statement` 的 `params` 支持**参数行列表**（`list[dict]`）：**原样返回该列表** → `session.execute(*prepare_statement(sql, params))` 即批量执行（executemany），与 `build_insert_vectors` 的返回形态直接对接；行键集不一致或行值含序列 → 本地可操作 `ValueError`（与 `execute` 批量形态**同一规则**） | 向后兼容：单字典 / `None` 形态行为不变；行列表形态**不做** `IN` 展开（与批量互斥） |
+| D1 | 文档：修正「自有事务」示例——0.2.5 的示例把 `build_insert_vectors` 返回的**行列表**传给了单字典形态，照抄会抛 `AttributeError: 'list' object has no attribute 'items'` | **纯文档缺陷修正**（0.2.5 示例照抄即崩） |
+| — | 文档：批量执行补充 `rowcount` 备注——忽略型写入（如 SQLite `INSERT OR IGNORE`）的冲突行不计入 `rowcount`（即 `rowcount` = 实际插入数；⚠ 仅 SQLite 实测） | 文档 |
+
+#### 0.2.5 变更
 
 | 编号 | 变更 | 影响 |
 |------|------|------|

{sdpy_kit-0.2.5 → sdpy_kit-0.3.0}/README.md

@@ -442,7 +442,15 @@ PgKit.search_vectors("my_vec", [0.1] * 384, top_k=5, id_col="vid", column="vec")
 > 新增（非破坏性）：`VECTOR_CAPABILITIES` 能力声明、`id_col` / `column` 逃生口参数、
 > `insert_vectors` 支持二维 numpy 数组与批量提交。
 
-#### 0.2.5 变更（开发中，未发布）
+#### 0.2.6 变更
+
+| 编号 | 变更 | 影响 |
+|------|------|------|
+| D1 | `prepare_statement` 的 `params` 支持**参数行列表**（`list[dict]`）：**原样返回该列表** → `session.execute(*prepare_statement(sql, params))` 即批量执行（executemany），与 `build_insert_vectors` 的返回形态直接对接；行键集不一致或行值含序列 → 本地可操作 `ValueError`（与 `execute` 批量形态**同一规则**） | 向后兼容：单字典 / `None` 形态行为不变；行列表形态**不做** `IN` 展开（与批量互斥） |
+| D1 | 文档：修正「自有事务」示例——0.2.5 的示例把 `build_insert_vectors` 返回的**行列表**传给了单字典形态，照抄会抛 `AttributeError: 'list' object has no attribute 'items'` | **纯文档缺陷修正**（0.2.5 示例照抄即崩） |
+| — | 文档：批量执行补充 `rowcount` 备注——忽略型写入（如 SQLite `INSERT OR IGNORE`）的冲突行不计入 `rowcount`（即 `rowcount` = 实际插入数；⚠ 仅 SQLite 实测） | 文档 |
+
+#### 0.2.5 变更
 
 | 编号 | 变更 | 影响 |
 |------|------|------|

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

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

{sdpy_kit-0.2.5 → 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.2.5 → sdpy_kit-0.3.0}/kit/db/base_db_kit.py

@@ -202,14 +202,24 @@ _EXPANDING_TYPES = (list, tuple, set, frozenset)
 
 
 def prepare_statement(
-    sql: str, params: FieldData | None = None
-) -> tuple[TextClause, FieldData | None]:
-    """把 SQL 文本 + 参数字典转为（可直接执行的语句, 归一化后的参数）
+    sql: str, params: FieldData | builtins.list[FieldData] | None = None
+) -> tuple[TextClause, FieldData | builtins.list[FieldData] | None]:
+    """把 SQL 文本 + 参数转为（可直接执行的语句, 参数）
 
     供调用方在**自有事务**（`*Kit.transaction()`）内执行原生 SQL，
-    与 ``query`` / ``execute`` 使用**同一实现**（单一事实源）——后两者等价于
-    ``session.execute(*prepare_statement(sql, params))``；本函数**不建连接、
-    不改状态、不执行**。
+    与 ``query`` / ``execute`` 使用**同一套参数规则**（单一事实源）——
+    单字典形态下后两者等价于 ``session.execute(*prepare_statement(sql, params))``；
+    本函数**不建连接、不改状态、不执行**。
+
+    两种参数形态（与 ``execute`` 对称）：
+
+    - **单字典**：值为 ``list`` / ``tuple`` / ``set`` / ``frozenset`` 的键按
+      SQLAlchemy **expanding** 语义绑定，可直接书写 ``WHERE id IN :ids``
+      （三库通用）；第二项为归一化后的参数字典；
+    - **字典列表**（批量 / executemany）：第二项**原样返回该列表**，语句为
+      裸 ``text(sql)``（**不做** ``IN`` 展开——批量与展开参数互斥，与
+      ``execute`` 的批量约束一致）；经 ``_validate_batch_rows`` 本地预校验
+      （各行键集一致、行值为标量）。
 
     典型用法（调用方**无须 import sqlalchemy**）::
 
@@ -221,7 +231,13 @@ def prepare_statement(
         with SQLiteKit.transaction() as session:
             session.execute(stmt, bound)          # 第二个值必须一并传入
 
-    三条实现约束（与 ``query`` / ``execute`` 现有语义完全一致）：
+        stmt, rows = prepare_statement(           # 批量（executemany）
+            "INSERT INTO t (a, b) VALUES (:a, :b)", [{"a": 1, "b": 2}]
+        )
+        with SQLiteKit.transaction() as session:
+            session.execute(stmt, rows)
+
+    三条实现约束（**单字典形态**，与 ``query`` / ``execute`` 现有语义完全一致）：
 
     1. 只对**确实出现在 SQL 文本中**的参数名做 expanding —— 否则传入"未使用的
        序列参数"会触发 SQLAlchemy 的 ``ArgumentError: This text() construct
@@ -233,20 +249,31 @@ def prepare_statement(
 
     Args:
         sql: SQL 语句（使用命名参数 ``:param``）
-        params: 参数字典，值为 ``list`` / ``tuple`` / ``set`` / ``frozenset`` 的键
-            按 ``IN`` 展开（三库通用）
+        params: **单个参数字典**（值为 ``list`` / ``tuple`` / ``set`` / ``frozenset``
+            的键按 ``IN`` 展开，三库通用）或**参数字典的列表**（批量，行值须为标量）
 
     Returns:
-        ``(语句, 归一化后的参数字典)``：执行时**必须**把第二个值一并传给
-        ``session.execute``；``params`` 为 None 时第二项即 None
+        ``(语句, 参数)``：执行时**必须**把第二个值一并传给 ``session.execute``；
+        ``params`` 为 None 时第二项即 None，为列表时**原样返回该列表**
 
     Note:
         ``:name::type`` 这类 PostgreSQL 风格 cast **不被 SQLAlchemy 的 ``text()``
         识别**（该写法在支持本函数之前同样不可用），请改用 ``CAST(:name AS type)``。
 
+    Raises:
+        ValueError: 列表形态的行键集不一致或行值含序列类型（来自
+            ``_validate_batch_rows``，与 ``execute`` 批量形态同一规则）
+
     See Also:
         ``query`` / ``execute``：kit 自管事务的原生 SQL 入口（同样支持列表参数）。
     """
+    if isinstance(params, builtins.list):
+        # 批量形态：语句不做 IN 展开，参数行列表原样返回（由 execute/session
+        # 以 executemany 执行）；空列表不校验、不报错（构造期无副作用）
+        if params:
+            _validate_batch_rows(params)
+        return text(sql), params
+
     statement = text(sql)
     if not params:
         return statement, params

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.5 → 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"