sdpy-kit 0.1.4__tar.gz → 0.1.6__tar.gz

{sdpy_kit-0.1.4 → sdpy_kit-0.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sdpy-kit
-Version: 0.1.4
+Version: 0.1.6
 Summary: SDPY Kit——统一数据库访问层（PG/MySQL/SQLite）与 AI/MCP/Redis/文件/文档/向量工具集
 Author-email: Clark <changhongyuan@126.com>
 License-Expression: MIT
@@ -17,32 +17,42 @@ Classifier: Topic :: Database
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.13
-Requires-Dist: firecrawl-anydoc>=0.2.4
-Requires-Dist: httpx>=0.28.1
-Requires-Dist: markdown-it-py>=3.0
-Requires-Dist: numpy>=2.0
-Requires-Dist: pimd[pdfa]>=2.2.5
 Requires-Dist: pydantic-settings>=2.0
 Requires-Dist: pydantic>=2.0
-Requires-Dist: python-dotenv>=1.2.3
-Requires-Dist: requests>=2.34.0
 Requires-Dist: sqlalchemy~=2.0.51
-Requires-Dist: sqliteai-vector>=1.0.0
 Requires-Dist: sqlmodel>=0.0.39
+Provides-Extra: ai
+Requires-Dist: httpx>=0.28.1; extra == 'ai'
 Provides-Extra: all
 Requires-Dist: fastmcp>=4.0.3; extra == 'all'
+Requires-Dist: firecrawl-anydoc>=0.2.4; extra == 'all'
+Requires-Dist: httpx>=0.28.1; extra == 'all'
+Requires-Dist: markdown-it-py>=3.0; extra == 'all'
+Requires-Dist: numpy>=2.0; extra == 'all'
+Requires-Dist: pimd[pdfa]>=2.2.5; extra == 'all'
 Requires-Dist: psycopg2-binary>=2.9.12; extra == 'all'
 Requires-Dist: pymysql>=1.2.0; extra == 'all'
 Requires-Dist: redis>=5.0.0; extra == 'all'
+Requires-Dist: requests>=2.34.0; extra == 'all'
+Requires-Dist: sqliteai-vector>=1.1.0; extra == 'all'
 Requires-Dist: zvec>=0.6.0; extra == 'all'
+Provides-Extra: doc
+Requires-Dist: firecrawl-anydoc>=0.2.4; extra == 'doc'
+Requires-Dist: markdown-it-py>=3.0; extra == 'doc'
+Requires-Dist: pimd[pdfa]>=2.2.5; extra == 'doc'
 Provides-Extra: mcp
 Requires-Dist: fastmcp>=4.0.3; extra == 'mcp'
+Provides-Extra: mineru
+Requires-Dist: requests>=2.34.0; extra == 'mineru'
 Provides-Extra: mysql
 Requires-Dist: pymysql>=1.2.0; extra == 'mysql'
 Provides-Extra: pg
 Requires-Dist: psycopg2-binary>=2.9.12; extra == 'pg'
 Provides-Extra: redis
 Requires-Dist: redis>=5.0.0; extra == 'redis'
+Provides-Extra: sqliteai-vector
+Requires-Dist: numpy>=2.0; extra == 'sqliteai-vector'
+Requires-Dist: sqliteai-vector>=1.1.0; extra == 'sqliteai-vector'
 Provides-Extra: zvec
 Requires-Dist: zvec>=0.6.0; extra == 'zvec'
 Description-Content-Type: text/markdown
@@ -56,11 +66,26 @@ SDPY 统一工具集（Kit 体系），供 Python 项目开箱即用：统一数
 ## 安装
 
 ```bash
-pip install sdpy-kit
+pip install sdpy-kit            # 基础版：config/log + kit.db 核心（SQLite 常规操作零额外依赖）
 # 或
 uv add sdpy-kit
 ```
 
+可选能力按 extras 按需安装（均为延迟导入，不装不影响基础使用，缺依赖时报错会提示安装命令）：
+
+| extra | 能力 | 安装 |
+|-------|------|------|
+| `pg` | PgKit（PostgreSQL 驱动） | `pip install "sdpy-kit[pg]"` |
+| `mysql` | MySqlKit（MySQL 驱动） | `pip install "sdpy-kit[mysql]"` |
+| `vec` | SQLiteKit 向量方法（numpy / sqliteai-vector，SQLite 向量扩展） | `pip install "sdpy-kit[vec]"` |
+| `zvec` | ZvecKit（zvec，阿里独立向量库，与 `vec` 完全独立） | `pip install "sdpy-kit[zvec]"` |
+| `redis` | RedisKit | `pip install "sdpy-kit[redis]"` |
+| `mcp` | McpKit（fastmcp） | `pip install "sdpy-kit[mcp]"` |
+| `ai` | AI 服务池（httpx） | `pip install "sdpy-kit[ai]"` |
+| `doc` | DocKit 文档转换 | `pip install "sdpy-kit[doc]"` |
+| `mineru` | MineruKit 解析 API | `pip install "sdpy-kit[mineru]"` |
+| `all` | 全部能力 | `pip install "sdpy-kit[all]"` |
+
 ## 配置（.env）
 
 kit 通过 pydantic-settings 读取项目根目录 `.env`（默认值见下，均可省略）：
@@ -98,6 +123,24 @@ AI 与 MCP 功能需要在项目根目录提供两个 JSON 档案文件：
 文件缺失时，首次使用相应功能会报错，**报错信息中附带可直接复制的最小模板**；
 其中 `api_key` / `token_env` 字段填写环境变量名，真实密钥配置在 `.env`。
 
+### ai_models.json 可选字段
+
+| 层级 | 字段 | 说明 |
+|------|------|------|
+| 档案级 | `timeout` | 请求超时秒数（默认 60） |
+| 档案级 | `max_tokens` | 输出上限（chat 用）；`AI.chat_ask/chat_complete/chat_stream` 也可按调用点传参，逐级回落：调用点 → 档案 → provider 默认 |
+| 档案级 | `retries` | 5xx 重试次数（默认 2；超时不重试，候选链切换才是有效重试） |
+| 类型级 | `chain_timeout` | 整链预算秒数（与 `default_profile` 同级）；门面同步等待上限。未配置时按 `sum(候选 timeout) + 10s` 自适应，也可用环境变量 `KIT_AI_CHAIN_TIMEOUT` 全局覆盖 |
+
+### 候选链切换语义（两类，勿混淆）
+
+- **跨调用切换**：`AI.use()` 与其它请求产生的失败冷却均只影响**下一次**请求——每次调用的候选计划在开始时定格；
+- **一次调用内降级**：本次调用按开始时定格的计划串行尝试（首帧前失败/首帧超时切下一候选），中途的 `use` / 冷却变化不影响它。
+
+全部候选失败（或整链预算耗尽）抛 `AIAggregateError`（`AIRequestError` 子类）：
+全候选状态码一致时透传（如整链 429 可用 `exc.status_code == 429` 判定），
+429 的 `Retry-After` 解析后挂于 `exc.retry_after`（冷却钳制 5–300s）。
+
 ## 快速开始
 
 ### 日志与配置

{sdpy_kit-0.1.4 → sdpy_kit-0.1.6}/README.md

@@ -7,11 +7,26 @@ SDPY 统一工具集（Kit 体系），供 Python 项目开箱即用：统一数
 ## 安装
 
 ```bash
-pip install sdpy-kit
+pip install sdpy-kit            # 基础版：config/log + kit.db 核心（SQLite 常规操作零额外依赖）
 # 或
 uv add sdpy-kit
 ```
 
+可选能力按 extras 按需安装（均为延迟导入，不装不影响基础使用，缺依赖时报错会提示安装命令）：
+
+| extra | 能力 | 安装 |
+|-------|------|------|
+| `pg` | PgKit（PostgreSQL 驱动） | `pip install "sdpy-kit[pg]"` |
+| `mysql` | MySqlKit（MySQL 驱动） | `pip install "sdpy-kit[mysql]"` |
+| `vec` | SQLiteKit 向量方法（numpy / sqliteai-vector，SQLite 向量扩展） | `pip install "sdpy-kit[vec]"` |
+| `zvec` | ZvecKit（zvec，阿里独立向量库，与 `vec` 完全独立） | `pip install "sdpy-kit[zvec]"` |
+| `redis` | RedisKit | `pip install "sdpy-kit[redis]"` |
+| `mcp` | McpKit（fastmcp） | `pip install "sdpy-kit[mcp]"` |
+| `ai` | AI 服务池（httpx） | `pip install "sdpy-kit[ai]"` |
+| `doc` | DocKit 文档转换 | `pip install "sdpy-kit[doc]"` |
+| `mineru` | MineruKit 解析 API | `pip install "sdpy-kit[mineru]"` |
+| `all` | 全部能力 | `pip install "sdpy-kit[all]"` |
+
 ## 配置（.env）
 
 kit 通过 pydantic-settings 读取项目根目录 `.env`（默认值见下，均可省略）：
@@ -49,6 +64,24 @@ AI 与 MCP 功能需要在项目根目录提供两个 JSON 档案文件：
 文件缺失时，首次使用相应功能会报错，**报错信息中附带可直接复制的最小模板**；
 其中 `api_key` / `token_env` 字段填写环境变量名，真实密钥配置在 `.env`。
 
+### ai_models.json 可选字段
+
+| 层级 | 字段 | 说明 |
+|------|------|------|
+| 档案级 | `timeout` | 请求超时秒数（默认 60） |
+| 档案级 | `max_tokens` | 输出上限（chat 用）；`AI.chat_ask/chat_complete/chat_stream` 也可按调用点传参，逐级回落：调用点 → 档案 → provider 默认 |
+| 档案级 | `retries` | 5xx 重试次数（默认 2；超时不重试，候选链切换才是有效重试） |
+| 类型级 | `chain_timeout` | 整链预算秒数（与 `default_profile` 同级）；门面同步等待上限。未配置时按 `sum(候选 timeout) + 10s` 自适应，也可用环境变量 `KIT_AI_CHAIN_TIMEOUT` 全局覆盖 |
+
+### 候选链切换语义（两类，勿混淆）
+
+- **跨调用切换**：`AI.use()` 与其它请求产生的失败冷却均只影响**下一次**请求——每次调用的候选计划在开始时定格；
+- **一次调用内降级**：本次调用按开始时定格的计划串行尝试（首帧前失败/首帧超时切下一候选），中途的 `use` / 冷却变化不影响它。
+
+全部候选失败（或整链预算耗尽）抛 `AIAggregateError`（`AIRequestError` 子类）：
+全候选状态码一致时透传（如整链 429 可用 `exc.status_code == 429` 判定），
+429 的 `Retry-After` 解析后挂于 `exc.retry_after`（冷却钳制 5–300s）。
+
 ## 快速开始
 
 ### 日志与配置

{sdpy_kit-0.1.4 → sdpy_kit-0.1.6}/kit/__init__.py

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

{sdpy_kit-0.1.4 → sdpy_kit-0.1.6}/kit/ai/base_service.py

@@ -113,8 +113,16 @@ class BaseAIService[RequestT, ResponseT](ABC):
     def _parse_response(self, data: JSONObject) -> ResponseT:
         """将 JSON 响应体解析为业务结果。"""
 
-    async def _call(self, request: RequestT) -> ResponseT:
-        """统一编排：构造请求体 → 发送 → 解析响应（含中文 info 日志）。"""
+    async def _call(
+        self, request: RequestT, *, deadline: float | None = None
+    ) -> ResponseT:
+        """统一编排：构造请求体 → 发送 → 解析响应（含中文 info 日志）。
+
+        Args:
+            request: 请求模型
+            deadline: 整链预算截止时刻（``time.monotonic()`` 秒），透传给
+                ``post_json`` 的重试预算检查；None 表示不限制
+        """
         desc = self._log_desc()
         payload = self._build_payload(request)
         params = _truncate(
@@ -124,7 +132,7 @@ class BaseAIService[RequestT, ResponseT](ABC):
         logger.info(f"请求参数: {params}")
         start = time.perf_counter()
         try:
-            data = await self._client.post_json(payload)
+            data = await self._client.post_json(payload, deadline=deadline)
             result = self._parse_response(data)
         except AIError as exc:
             logger.error(

{sdpy_kit-0.1.4 → sdpy_kit-0.1.6}/kit/ai/chat_service.py

@@ -65,8 +65,14 @@ class ChatService(BaseAIService[ChatRequest, str]):
         }
         if request.temperature is not None:
             payload["temperature"] = request.temperature
-        if request.max_tokens is not None:
-            payload["max_tokens"] = request.max_tokens
+        # max_tokens 逐级回落：调用点显式传入 → 档案配置 → 不写（provider 默认）
+        max_tokens = (
+            request.max_tokens
+            if request.max_tokens is not None
+            else self._profile.max_tokens
+        )
+        if max_tokens is not None:
+            payload["max_tokens"] = max_tokens
         return cast(JSONObject, payload)
 
     @override
@@ -82,9 +88,16 @@ class ChatService(BaseAIService[ChatRequest, str]):
         *,
         temperature: float | None = None,
         max_tokens: int | None = None,
+        deadline: float | None = None,
     ) -> str:
+        """多轮对话，返回模型回答文本。
+
+        Args:
+            deadline: 整链预算截止时刻（``time.monotonic()`` 秒），约束
+                5xx 重试预算；None 表示不限制
+        """
         request = ChatRequest(messages, temperature=temperature, max_tokens=max_tokens)
-        return await self._call(request)
+        return await self._call(request, deadline=deadline)
 
     async def complete(
         self,
@@ -92,9 +105,12 @@ class ChatService(BaseAIService[ChatRequest, str]):
         *,
         temperature: float | None = None,
         max_tokens: int | None = None,
+        deadline: float | None = None,
     ) -> str:
         messages: list[Message] = [{"role": "user", "content": prompt}]
-        return await self.ask(messages, temperature=temperature, max_tokens=max_tokens)
+        return await self.ask(
+            messages, temperature=temperature, max_tokens=max_tokens, deadline=deadline
+        )
 
     async def stream(
         self,

sdpy_kit-0.1.6/kit/ai/exceptions.py

@@ -0,0 +1,99 @@
+"""
+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-08-21
+"""kit/ai 统一异常体系
+
+继承链：
+    AIError                基类
+    ├── AIConfigError      档案文件缺失/非法、档案不存在、密钥未配置、必填字段缺失
+    ├── AIRequestError     网络异常、HTTP >= 400
+    │   ├── AITimeoutError   请求超时（可用于重试策略）
+    │   └── AIAggregateError 候选链聚合异常（全部候选失败或整链预算耗尽）
+    └── AIResponseError    响应结构解析失败、流式数据无法解析
+"""
+
+
+class AIError(Exception):
+    """AI 模型服务基类异常"""
+
+
+class AIConfigError(AIError):
+    """模型档案配置异常（文件缺失/非法、档案不存在、密钥未配置、必填字段缺失）"""
+
+
+class AIRequestError(AIError):
+    """模型服务请求异常（网络异常、HTTP >= 400）。
+
+    Attributes:
+        status_code: HTTP 状态码；非 HTTP 错误（超时、连接失败等）为 None。
+        retry_after: 服务端 ``Retry-After`` 建议等待秒数（429 时解析，
+            整数秒与 HTTP-date 两种格式）；未提供为 None。
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        retry_after: float | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code: int | None = status_code
+        self.retry_after: float | None = retry_after
+
+
+class AITimeoutError(AIRequestError):
+    """模型服务请求超时异常（可用于重试策略）"""
+
+
+class AIAggregateError(AIRequestError):
+    """候选链聚合异常：全部候选失败（或整链预算耗尽）时抛出。
+
+    继承 ``AIRequestError``：业务按 ``AIRequestError`` 捕获零改动。
+    ``status_code`` 在「全部候选状态码一致」时透传该值（如整链 429），
+    否则为 None——业务可据此一行判定限流。
+
+    Attributes:
+        tried: 已尝试的档案名列表。
+        statuses: 各候选异常的 HTTP 状态码（非 HTTP 错误为 None）。
+        last_error: 最后一个候选的异常；预算耗尽且无候选失败时为 None。
+        budget_exhausted: 是否因整链预算耗尽而提前终止（未再发起新候选）。
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        retry_after: float | None = None,
+        tried: list[str] | None = None,
+        statuses: list[int | None] | None = None,
+        last_error: AIError | None = None,
+        budget_exhausted: bool = False,
+    ) -> None:
+        super().__init__(message, status_code=status_code, retry_after=retry_after)
+        self.tried: list[str] = list(tried or [])
+        self.statuses: list[int | None] = list(statuses or [])
+        self.last_error: AIError | None = last_error
+        self.budget_exhausted: bool = budget_exhausted
+
+
+class AIResponseError(AIError):
+    """模型服务响应异常（响应结构解析失败、流式数据无法解析）"""