sdpy-kit

SDPY 统一工具集（Kit 体系），供 Python 项目开箱即用：统一数据库访问层（PostgreSQL / MySQL / SQLite，三个 Kit API 完全一致）+ AI 多模型服务池（chat / embedding / rerank / image，多厂商候选链与故障转移）+ MCP 客户端 + Redis / 文件 / 文档 / 向量库 / MinerU 工具。

要求 Python 3.13+

安装

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]"`
`sqliteai`	SQLiteKit 向量方法（numpy / sqliteai-vector，SQLite 向量扩展）	`pip install "sdpy-kit[sqliteai]"`
`zvec`	ZvecKit（zvec，阿里独立向量库）	`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（默认值见下，均可省略）：

# 日志
LOG_LEVEL=INFO
LOG_TO_CONSOLE=true
LOG_TO_FILE=false

# 数据库（三选一，切换只改 DEFAULT_DB_TYPE）
DEFAULT_DB_TYPE=sqlite          # postgresql / mysql / sqlite
DB_HOST=localhost
DB_PORT=5432
DB_DATABASE=postgres
DB_USER=admin
DB_PASSWORD=
MYSQL_PORT=3306
MYSQL_DATABASE=mydb
MYSQL_USER=root
SQLITE_DB_PATH=./data/app.db

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379

AI / MCP 功能的档案文件

AI 与 MCP 功能需要在项目根目录提供两个 JSON 档案文件：

config/ai_models.json —— chat / embedding / rerank / image 四类型多厂商模型档案
config/mcp_servers.json —— MCP 服务器档案

文件缺失时，首次使用相应功能会报错，报错信息中附带可直接复制的最小模板；其中 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）。

快速开始

日志与配置

from kit.config import get_settings, get_default_logger

settings = get_settings()
logger = get_default_logger(__name__)
logger.info("hello %s", settings.APP_NAME)

数据库（SQLiteKit / PgKit / MySqlKit API 完全一致，切换只改 import）

from sqlmodel import SQLModel, Field
from kit.db.sqlite_kit import SQLiteKit

class Item(SQLModel, table=True):
    id: int | None = Field(default=None, primary_key=True)
    name: str

SQLiteKit.connect()
SQLiteKit.create_tables([Item])
item = SQLiteKit.create(Item, {"name": "demo"})

约定：SQLiteKit/PgKit/MySqlKit 方法自动提交；CRUDBase（配合 session_scope）不自动提交；事务用 kit.transactional。

模块总览

模块	内容
`kit.db`	统一数据库访问层：PgKit / MySqlKit / SQLiteKit、CRUDBase、transactional
`kit.ai`	AI 服务池：chat / embedding / rerank / image，多厂商候选链 + 故障转移
`kit.mcp_kit`	通用 MCP 客户端（streamable-http / sse，档案驱动多服务器）
`kit.redis_kit`	Redis 工具
`kit.file_kit`	文件工具
`kit.doc_kit`	文档转换（基于 firecrawl-anydoc / pimd）
`kit.zvec_kit`	zvec 本地向量库
`kit.mineru_kit`	MinerU 文档精准解析 API
`kit.common_kit`	通用工具

License

MIT

Metadata

Release files for sdpy-kit 0.1.10

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for sdpy-kit 0.1.10
File	Size	Uploaded
sdpy_kit-0.1.10.tar.gz	110.4 kB	Sep 21, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for sdpy-kit 0.1.10
File	Interpreter	ABI	Platform	Reset
sdpy_kit-0.1.10-py3-none-any.whl 151.6 kB Sep 21, 2026	Python 3	none	any	Details

Total release size: 262.0 kB

Release files / sdpy_kit-0.1.10.tar.gz

Download URL	sdpy_kit-0.1.10.tar.gz
Size	110.4 kB
Tags	Source
SHA-256 checksum How to use checksums	`fbe9688be258aa58185a4239d9ee3e577b08a0978398bea5cc46719206acd49f`
BLAKE2b-256 checksum How to use checksums	`c3b57a1990ae9412a3964a6c6d4b1fd48997a0f1cbbbc698302ef97d56c90a17`
Upload date	Sep 21, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.11.3 {"installer":{"name":"uv","version":"0.11.3","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}`

Release files / sdpy_kit-0.1.10-py3-none-any.whl

Download URL	sdpy_kit-0.1.10-py3-none-any.whl
Size	151.6 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`9e9acb7f73cd839898625b1c957c167114bf70be0de54f3321219d9111473482`
BLAKE2b-256 checksum How to use checksums	`bb7d307eba7e430996740c756ff6904743a73443b8b90fae3b7695f61ba7357f`
Upload date	Sep 21, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.11.3 {"installer":{"name":"uv","version":"0.11.3","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}`