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 按需安装（均为延迟导入，不装不影响基础使用，缺依赖时报错会提示安装命令）：

配置（.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 可选字段

候选链切换语义（两类，勿混淆）

• 跨调用切换：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。

模块总览

License

MIT