Metadata-Version: 2.5
Name: sdpy-kit
Version: 0.1.8
Summary: SDPY Kit——统一数据库访问层（PG/MySQL/SQLite）与 AI/MCP/Redis/文件/文档/向量工具集
Author-email: Clark <changhongyuan@126.com>
License-Expression: MIT
Keywords: ai,kit,mcp,mysql,postgresql,redis,sdpy,sqlalchemy,sqlite,sqlmodel,向量检索,工具集,开发工具,数据库
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: Chinese (Simplified)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Database
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.13
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: pydantic>=2.0
Requires-Dist: sqlalchemy~=2.0.51
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

# sdpy-kit

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

> 要求 Python 3.13+

## 安装

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

```dotenv
# 日志
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）。

## 快速开始

### 日志与配置

```python
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）

```python
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
