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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sdpy-kit
-Version: 0.7.3
+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` 返回的是**状态快照**，不是「可用档案列表」。
@@ -1011,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` 保证输出恒等于它：
@@ -1040,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` |
@@ -1645,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.3 → 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` 返回的是**状态快照**，不是「可用档案列表」。
@@ -929,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` 保证输出恒等于它：
@@ -958,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` |
@@ -1563,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.3 → sdpy_kit-0.7.4}/kit/__init__.py

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

{sdpy_kit-0.7.3 → 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)

{sdpy_kit-0.7.3 → 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，通用网页文章抓取转存）