sdpy-kit 0.7.2__tar.gz → 0.7.4__tar.gz

{sdpy_kit-0.7.2 → sdpy_kit-0.7.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sdpy-kit
-Version: 0.7.2
+Version: 0.7.4
 Summary: SDPY Kit——统一数据库访问层（PG/MySQL/SQLite）与 AI/Redis/文件/文档/向量工具集
 Author-email: Clark <changhongyuan@126.com>
 License-Expression: MIT
@@ -180,7 +180,7 @@ SQLITE_DB_PATH=./data/sqlite.db
 # MinerU（仅精准解析需要 Key，Agent 轻量解析免登录）
 # MINERU_API_KEY=
 
-# Marker（本地解析，可选依赖 sdpy-kit[marker]）
+# Marker（0.7.0 起暂停发布，无 marker extra；需要请用 sdpy-kit==0.6.10）
 # MARKER_MODE=fast              # None=按设备自动（GPU→balanced / CPU、MPS→fast）
 # MARKER_HF_ENDPOINT=https://hf-mirror.com
 # MARKER_HF_DISABLE_XET=true
@@ -812,7 +812,7 @@ page = qb.paginate(page=1, per_page=20)            # {"items", "total", ...}
 传输：chat / embedding / image 走 `openai` SDK（`>=3.44,<4`，
 自带 `httpx2`），rerank 走 httpx 自研传输（SDK 无 `/rerank` 资源）。
 档案里的 `endpoint` **对前三类不再生效**——SDK 固定拼 `/chat/completions`、
-`/embeddings`、`/images/generations`，仅 rerank 与探活仍使用该字段。
+`/embeddings`、`/images/generations`，仅 rerank 仍使用该字段（探活走 openai SDK 的 `GET {base_url}/models`，不读本字段）。
 
 > 安装提示：`openai` 3.x 会引入 `httpx2`，与 rerank 用的 `httpx` 并存（两个包名不同，不冲突）。
 
@@ -838,10 +838,10 @@ shutdown()                                                     # 应用退出前
 | chat | `chat_stream(messages, *, max_tokens=None, thinking=None, json_mode=None, response_format=None) -> Iterator[str]` | 同步流式逐 token 迭代器（建议 `with` 使用）；结束后可读 `reasoning_chars` / `content_chars` / `finish_reason` / `requested_max_tokens` / `truncated` / `empty_kind` / `thinking_applied` / `json_mode_applied` |
 | embedding | `embed_text(text) -> list[float]` | 单文本向量化 |
 | embedding | `embed_texts(texts) -> list[list[float]]` | 批量向量化 |
-| rerank | `rerank(query, documents, top_n=None) -> list[RerankHit]` | 返回 `RerankHit`（`index` / `score` / `document`）降序列表；**`top_n` 是返回条数上限，由 kit 本地裁剪**（服务端返回超量也按分数截断），`top_n=None` 返回全部命中 |
+| rerank | `rerank(query, documents, top_n=None) -> list[RerankHit]` | 返回 `RerankHit`（`index` / `score` / `document`）降序列表；**`top_n` 是返回条数上限，由 kit 本地裁剪**（服务端返回超量也按分数截断），`top_n=None` 返回全部命中，`top_n<=0` 直接返回空列表 |
 | image | `generate_image(prompt, *, size=None, n=1, return_base64=False, ratio=None) -> ImageResult` | 文生图，返回 `ImageResult`（`url` / `b64` 至少一个非空） |
 | 管理 | `use(model_type, profile) -> None` | 切换该类型当前档案（`chat` / `embedding` / `rerank` / `image`） |
-| 管理 | `available(model_type) -> list[ProfileStatus]` | 各档案状态快照（含未配置密钥与被剔除者）；**类型未在 `ai_models.json` 中配置时返回 `[]`**（不再抛异常），类型名非法仍抛 `AIConfigError` |
+| 管理 | `available(model_type) -> list[ProfileStatus]` | 各档案状态快照（含未配置密钥与被剔除者）；**类型未在 `ai_models.json` 中配置时返回 `[]`**（不再抛异常），类型名非法抛 `AIModelTypeNotConfiguredError`（`AIConfigError` 子类） |
 | 管理 | `reload_config(*, model_type=None, reload_file=False, probe=True, immediate=False) -> ReloadResult` | 配置热重载，改密钥 / 档案后无需重启；同时清空思考/结构化输出的告警去重表（修正档案后同一原因会重新提示） |
 
 **可用性查询（`available`）**：`available` 返回的是**状态快照**，不是「可用档案列表」。
@@ -885,7 +885,8 @@ with AI.chat_stream([{"role": "user", "content": "写一首短诗"}]) as stream:
 | `no_finish` | 结束原因缺失或非 `stop`（端点未发送 `finish_reason`） | 可原样重试；连续出现检查端点 |
 | `stopped_empty` | 无推理、`finish_reason=stop`、正文 0 | 检查提示词与模型输出 |
 
-正文非空时 `empty_kind is None`。判定只用「是否截断 + 是否有推理 + 结束原因」，不依赖 token 数（kit 目前不采集 `usage`）：
+正文非空时 `empty_kind is None`。判定只用「是否截断 + 是否有推理 + 结束原因」，不依赖 token 数（kit 目前不采集 `usage`）。
+注意：该属性**仅在流正常结束后可读**，迭代中与异常 / 中断后为 `None`（避免把「正文还没到」误判成 `no_finish`）；`requested_max_tokens` 无此限制。
 
 ```python
 with AI.chat_stream(messages, max_tokens=450) as stream:
@@ -1010,7 +1011,7 @@ await service.close()
 | `RerankService` | `rerank(query, documents, *, top_n=None) -> list[RerankHit]`（已按 score 降序） |
 | `ImageService` | `generate(prompt, *, size=None, n=1, return_base64=False, ratio=None) -> ImageResult` |
 | `ModelBuilder` | `build(model_type, model=None, *, api_key=None)` 及各类型专用 `build_chat / build_embedding / build_rerank / build_image` |
-| `BaseAIService` | `profile` 属性、`await close()`、支持 `async with` |
+| `SdkServiceBase` | `profile` 属性、`await close()`、支持 `async with` |
 
 **embedding 维度契约**：`ai_models.json` 里 embedding 档案的 `dimension` 是**目标向量维度**
 （不是模型原生维度），`EmbeddingService` 保证输出恒等于它：
@@ -1039,7 +1040,8 @@ from kit.ai.exceptions import (
 | 异常 | 触发场景 / 可用属性 |
 |------|---------------------|
 | `AIError` | 基类 |
-| `AIConfigError` | 档案缺失或非法、档案不存在、密钥未配置、必填字段缺失 |
+| `AIConfigError` | 档案缺失或非法、档案不存在、密钥未配置、必填字段缺失、`default_profile` 未在 `profiles` 中定义（加载期校验） |
+| `AIModelTypeNotConfiguredError` | 模型类型名非法（合法类型但未配置返回 `[]` 不抛）；`AIConfigError` 子类 |
 | `AIRequestError` | 单次请求失败；`status_code`、`retry_after`（429 时解析 `Retry-After`） |
 | `AITimeoutError` | 请求超时（继承 `AIRequestError`） |
 | `AIAggregateError` | 全部候选失败或整链预算耗尽；`tried`、`statuses`、`last_error`、`budget_exhausted` |
@@ -1644,7 +1646,7 @@ AI 功能需要在项目根目录提供 `config/ai_models.json`（chat / embeddi
 | 层级 | 字段 | 说明 |
 |------|------|------|
 | 档案级 | `endpoint` | 请求路径。**仅 rerank 生效**：chat / embedding / image 由 openai SDK 固定拼路径，本字段被忽略（保留仅为兼容旧配置，不报错） |
-| 档案级 | `timeout` | 请求超时秒数（默认 60）；SDK 侧为单次调用总超时 |
+| 档案级 | `timeout` | 请求超时秒数（默认 60）；SDK 侧为单次调用总超时。**流式例外**：流式请求 `timeout=None`，由门面首帧 60s + 帧间隔 120s 兜底 |
 | 档案级 | `max_tokens` | 输出上限（chat 用）；`AI.chat_ask/chat_complete/chat_stream` 也可按调用点传参，逐级回落：调用点 → 档案 → provider 默认 |
 | 档案级 | `retries` | 5xx 重试次数（默认 2；超时不重试，候选链切换才是有效重试） |
 | 档案级 | `extra_body` | 厂商专有请求体字段透传（如 GLM/Qwen 关闭思考的 `{"thinking": {"type": "disabled"}}`、`{"reasoning_effort": "low"}`）；与服务构造的同名键冲突时**以服务的值为准**，故 `model` / `messages` / `stream` 等保留键不可覆盖；改名类需求（如 OpenAI o 系列的 `max_completion_tokens`）无法用它实现。逐调用 `thinking` 与之同键时**以逐调用为准**并打 `WARNING`。改文件后需 `reload_config(reload_file=True)` 生效 |

{sdpy_kit-0.7.2 → sdpy_kit-0.7.4}/README.md

@@ -98,7 +98,7 @@ SQLITE_DB_PATH=./data/sqlite.db
 # MinerU（仅精准解析需要 Key，Agent 轻量解析免登录）
 # MINERU_API_KEY=
 
-# Marker（本地解析，可选依赖 sdpy-kit[marker]）
+# Marker（0.7.0 起暂停发布，无 marker extra；需要请用 sdpy-kit==0.6.10）
 # MARKER_MODE=fast              # None=按设备自动（GPU→balanced / CPU、MPS→fast）
 # MARKER_HF_ENDPOINT=https://hf-mirror.com
 # MARKER_HF_DISABLE_XET=true
@@ -730,7 +730,7 @@ page = qb.paginate(page=1, per_page=20)            # {"items", "total", ...}
 传输：chat / embedding / image 走 `openai` SDK（`>=3.44,<4`，
 自带 `httpx2`），rerank 走 httpx 自研传输（SDK 无 `/rerank` 资源）。
 档案里的 `endpoint` **对前三类不再生效**——SDK 固定拼 `/chat/completions`、
-`/embeddings`、`/images/generations`，仅 rerank 与探活仍使用该字段。
+`/embeddings`、`/images/generations`，仅 rerank 仍使用该字段（探活走 openai SDK 的 `GET {base_url}/models`，不读本字段）。
 
 > 安装提示：`openai` 3.x 会引入 `httpx2`，与 rerank 用的 `httpx` 并存（两个包名不同，不冲突）。
 
@@ -756,10 +756,10 @@ shutdown()                                                     # 应用退出前
 | chat | `chat_stream(messages, *, max_tokens=None, thinking=None, json_mode=None, response_format=None) -> Iterator[str]` | 同步流式逐 token 迭代器（建议 `with` 使用）；结束后可读 `reasoning_chars` / `content_chars` / `finish_reason` / `requested_max_tokens` / `truncated` / `empty_kind` / `thinking_applied` / `json_mode_applied` |
 | embedding | `embed_text(text) -> list[float]` | 单文本向量化 |
 | embedding | `embed_texts(texts) -> list[list[float]]` | 批量向量化 |
-| rerank | `rerank(query, documents, top_n=None) -> list[RerankHit]` | 返回 `RerankHit`（`index` / `score` / `document`）降序列表；**`top_n` 是返回条数上限，由 kit 本地裁剪**（服务端返回超量也按分数截断），`top_n=None` 返回全部命中 |
+| rerank | `rerank(query, documents, top_n=None) -> list[RerankHit]` | 返回 `RerankHit`（`index` / `score` / `document`）降序列表；**`top_n` 是返回条数上限，由 kit 本地裁剪**（服务端返回超量也按分数截断），`top_n=None` 返回全部命中，`top_n<=0` 直接返回空列表 |
 | image | `generate_image(prompt, *, size=None, n=1, return_base64=False, ratio=None) -> ImageResult` | 文生图，返回 `ImageResult`（`url` / `b64` 至少一个非空） |
 | 管理 | `use(model_type, profile) -> None` | 切换该类型当前档案（`chat` / `embedding` / `rerank` / `image`） |
-| 管理 | `available(model_type) -> list[ProfileStatus]` | 各档案状态快照（含未配置密钥与被剔除者）；**类型未在 `ai_models.json` 中配置时返回 `[]`**（不再抛异常），类型名非法仍抛 `AIConfigError` |
+| 管理 | `available(model_type) -> list[ProfileStatus]` | 各档案状态快照（含未配置密钥与被剔除者）；**类型未在 `ai_models.json` 中配置时返回 `[]`**（不再抛异常），类型名非法抛 `AIModelTypeNotConfiguredError`（`AIConfigError` 子类） |
 | 管理 | `reload_config(*, model_type=None, reload_file=False, probe=True, immediate=False) -> ReloadResult` | 配置热重载，改密钥 / 档案后无需重启；同时清空思考/结构化输出的告警去重表（修正档案后同一原因会重新提示） |
 
 **可用性查询（`available`）**：`available` 返回的是**状态快照**，不是「可用档案列表」。
@@ -803,7 +803,8 @@ with AI.chat_stream([{"role": "user", "content": "写一首短诗"}]) as stream:
 | `no_finish` | 结束原因缺失或非 `stop`（端点未发送 `finish_reason`） | 可原样重试；连续出现检查端点 |
 | `stopped_empty` | 无推理、`finish_reason=stop`、正文 0 | 检查提示词与模型输出 |
 
-正文非空时 `empty_kind is None`。判定只用「是否截断 + 是否有推理 + 结束原因」，不依赖 token 数（kit 目前不采集 `usage`）：
+正文非空时 `empty_kind is None`。判定只用「是否截断 + 是否有推理 + 结束原因」，不依赖 token 数（kit 目前不采集 `usage`）。
+注意：该属性**仅在流正常结束后可读**，迭代中与异常 / 中断后为 `None`（避免把「正文还没到」误判成 `no_finish`）；`requested_max_tokens` 无此限制。
 
 ```python
 with AI.chat_stream(messages, max_tokens=450) as stream:
@@ -928,7 +929,7 @@ await service.close()
 | `RerankService` | `rerank(query, documents, *, top_n=None) -> list[RerankHit]`（已按 score 降序） |
 | `ImageService` | `generate(prompt, *, size=None, n=1, return_base64=False, ratio=None) -> ImageResult` |
 | `ModelBuilder` | `build(model_type, model=None, *, api_key=None)` 及各类型专用 `build_chat / build_embedding / build_rerank / build_image` |
-| `BaseAIService` | `profile` 属性、`await close()`、支持 `async with` |
+| `SdkServiceBase` | `profile` 属性、`await close()`、支持 `async with` |
 
 **embedding 维度契约**：`ai_models.json` 里 embedding 档案的 `dimension` 是**目标向量维度**
 （不是模型原生维度），`EmbeddingService` 保证输出恒等于它：
@@ -957,7 +958,8 @@ from kit.ai.exceptions import (
 | 异常 | 触发场景 / 可用属性 |
 |------|---------------------|
 | `AIError` | 基类 |
-| `AIConfigError` | 档案缺失或非法、档案不存在、密钥未配置、必填字段缺失 |
+| `AIConfigError` | 档案缺失或非法、档案不存在、密钥未配置、必填字段缺失、`default_profile` 未在 `profiles` 中定义（加载期校验） |
+| `AIModelTypeNotConfiguredError` | 模型类型名非法（合法类型但未配置返回 `[]` 不抛）；`AIConfigError` 子类 |
 | `AIRequestError` | 单次请求失败；`status_code`、`retry_after`（429 时解析 `Retry-After`） |
 | `AITimeoutError` | 请求超时（继承 `AIRequestError`） |
 | `AIAggregateError` | 全部候选失败或整链预算耗尽；`tried`、`statuses`、`last_error`、`budget_exhausted` |
@@ -1562,7 +1564,7 @@ AI 功能需要在项目根目录提供 `config/ai_models.json`（chat / embeddi
 | 层级 | 字段 | 说明 |
 |------|------|------|
 | 档案级 | `endpoint` | 请求路径。**仅 rerank 生效**：chat / embedding / image 由 openai SDK 固定拼路径，本字段被忽略（保留仅为兼容旧配置，不报错） |
-| 档案级 | `timeout` | 请求超时秒数（默认 60）；SDK 侧为单次调用总超时 |
+| 档案级 | `timeout` | 请求超时秒数（默认 60）；SDK 侧为单次调用总超时。**流式例外**：流式请求 `timeout=None`，由门面首帧 60s + 帧间隔 120s 兜底 |
 | 档案级 | `max_tokens` | 输出上限（chat 用）；`AI.chat_ask/chat_complete/chat_stream` 也可按调用点传参，逐级回落：调用点 → 档案 → provider 默认 |
 | 档案级 | `retries` | 5xx 重试次数（默认 2；超时不重试，候选链切换才是有效重试） |
 | 档案级 | `extra_body` | 厂商专有请求体字段透传（如 GLM/Qwen 关闭思考的 `{"thinking": {"type": "disabled"}}`、`{"reasoning_effort": "low"}`）；与服务构造的同名键冲突时**以服务的值为准**，故 `model` / `messages` / `stream` 等保留键不可覆盖；改名类需求（如 OpenAI o 系列的 `max_completion_tokens`）无法用它实现。逐调用 `thinking` 与之同键时**以逐调用为准**并打 `WARNING`。改文件后需 `reload_config(reload_file=True)` 生效 |

{sdpy_kit-0.7.2 → sdpy_kit-0.7.4}/kit/__init__.py

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

{sdpy_kit-0.7.2 → sdpy_kit-0.7.4}/kit/ai/runner.py

@@ -816,9 +816,10 @@ class AI:
                     if done:
                         break
 
-        流结束后可读 ``reasoning_chars`` / ``content_chars`` / ``finish_reason`` /
-        ``truncated`` / ``thinking_applied`` / ``json_mode_applied``，用于区分
-        「模型没返回内容」与「输出预算被思考吃光」，以及确认开关是否真的生效::
+        流结束后可读八个只读属性：``reasoning_chars`` / ``content_chars`` /
+        ``finish_reason`` / ``requested_max_tokens`` / ``truncated`` / ``empty_kind`` /
+        ``thinking_applied`` / ``json_mode_applied``，用于区分「模型没返回内容」与
+        「输出预算被思考吃光」（``empty_kind`` 给出五类归因），以及确认开关是否真的生效::
 
             with AI.chat_stream(messages, max_tokens=450) as stream:
                 body = "".join(stream)
@@ -846,10 +847,14 @@ class _StreamIterator:
     直接 ``for`` 中途 ``break`` 或迭代器被 GC，``close``/``__del__`` 也会
     兜底取消后台 producer，避免任务残留。
 
-    流结束后可读 ``reasoning_chars`` / ``content_chars`` / ``finish_reason`` /
-    ``truncated`` / ``thinking_applied`` / ``json_mode_applied`` 六个只读属性
-    （跨线程共享同一累加器：结束后为最终值，流式过程中为尽力而为的中间值；
-    提前 ``break`` 时为截至中断的累计值）。
+    流结束后可读八个只读属性：``reasoning_chars`` / ``content_chars`` /
+    ``finish_reason`` / ``requested_max_tokens`` / ``truncated`` / ``empty_kind`` /
+    ``thinking_applied`` / ``json_mode_applied``（跨线程共享同一累加器：
+    结束后为最终值，流式过程中为尽力而为的中间值；提前 ``break`` 时为截至
+    中断的累计值）。
+
+    ``empty_kind`` 例外：**仅在流正常结束后可读**，迭代中与异常 / 中断后
+    恒为 ``None``（避免把「正文还没到」误判成 ``no_finish``）。
     """
 
     def __init__(
@@ -871,6 +876,8 @@ class _StreamIterator:
         self._started = False
         self._closed = False
         self._got_first = False
+        # 正常收尾（收到哨兵）才置真：empty_kind 只在结束后给结论
+        self._exhausted = False
         self._task: concurrent.futures.Future[None] | None = None
 
     def __iter__(self) -> Iterator[str]:
@@ -931,6 +938,7 @@ class _StreamIterator:
                 f"流式帧间隔超过 {_STREAM_FRAME_INTERVAL_TIMEOUT:g}s 未收到新帧"
             ) from exc
         if item is _SENTINEL:
+            self._exhausted = True
             self.close()
             raise StopIteration
         if isinstance(item, BaseException):
@@ -971,6 +979,27 @@ class _StreamIterator:
         """结构化输出是否生效：None 未要求注入 / True 已注入 / False 被忽略。"""
         return self._stats.json_mode_applied
 
+    @property
+    def requested_max_tokens(self) -> int | None:
+        """本次实际下发的输出上限（调用方 → 档案回落）；未发请求为 None。"""
+        return self._stats.requested_max_tokens
+
+    @property
+    def empty_kind(self) -> str | None:
+        """正文为空时的诊断分级；**仅在流正常结束后可读，其余时刻为 None**。
+
+        取值同 ``StreamStats.empty_kind``（``budget_exhausted`` /
+        ``truncated_empty`` / ``reasoning_only`` / ``no_finish`` /
+        ``stopped_empty``；正文非空为 None）。
+
+        迭代中不给中间结论：此时正文尚未产出，``content_chars`` 恒为 0，
+        直接转发会把「还没出正文」误报成 ``no_finish``；异常 / 中途 ``break``
+        同理不置收尾标志。
+        """
+        if not self._exhausted:
+            return None
+        return self._stats.empty_kind
+
 
 async def _delayed_close(services: list[Service]) -> None:
     """延迟回收旧 service：给在途调用留宽限期，到期统一关闭（须在 loop 内）。"""

{sdpy_kit-0.7.2 → sdpy_kit-0.7.4}/pyproject.toml

@@ -52,8 +52,8 @@ dynamic = ["version"]
 #   docx   → kit.docs.docx_kit（docxtpl + python-docx，模板动态填充）
 #   docx-parse → kit.docs.rc_docparser_kit（rc-docparser，离线 docx → md + images）
 #   mineru → kit.docs.mineru_kit（requests）
-#   marker → kit.docs.marker_kit（marker-pdf，本地模型解析 PDF/图片→Markdown+Images；
-#            不含 [full]——其 docx/pptx/xlsx/html/epub 渲染依赖 weasyprint/GTK，已不在支持面）
+#   （marker 自 0.7.0 起暂停：marker-pdf 移出依赖、extra 与 wheel 内容均不包含，
+#     需要请用 sdpy-kit[marker]==0.6.10）
 #   laya   → laya_kit（laya + torch，本地类型化决策引擎 choice/score/noul）
 #   decima → decima_kit（decima-ai + onnxruntime，选项乱序不变、置信度已标定的决策模型）
 #   web-article → crawl/web_article_kit（trafilatura，通用网页文章抓取转存）