sdpy-kit 0.1.0__py3-none-any.whl

kit/__init__.py

@@ -0,0 +1,68 @@
+"""
+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-23
+"""Kit 模块——统一数据库访问层 + 工具集
+
+数据库访问通过 kit.db 子包提供（基于 SQLModel）。
+"""
+
+__version__ = "0.1.0"
+
+from kit.db import (
+    MYSQL,
+    POSTGRESQL,
+    SQLITE,
+    CRUDBase,
+    DBError,
+    NotFoundError,
+    close_all_engines,
+    close_engine,
+    create_tables,
+    get_engine,
+    get_session,
+    list_tables,
+    session_scope,
+    table_exists,
+    transactional,
+)
+
+__all__ = [
+    # 引擎管理
+    "get_engine",
+    "create_tables",
+    "list_tables",
+    "table_exists",
+    "close_all_engines",
+    "close_engine",
+    # 常量
+    "POSTGRESQL",
+    "MYSQL",
+    "SQLITE",
+    # 会话
+    "session_scope",
+    "get_session",
+    # 异常
+    "DBError",
+    "NotFoundError",
+    # CRUD
+    "CRUDBase",
+    # 事务
+    "transactional",
+]

kit/ai/__init__.py

@@ -0,0 +1,47 @@
+"""
+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 - AI 模型服务模块（纯异步，Python 3.13+）
+
+提供开箱即用的各类模型基础服务：
+- ChatService: 对话模型
+- EmbeddingService: 文本嵌入向量
+- RerankService: 重排序
+- ImageService: 文生图
+"""
+
+from kit.ai.chat_service import ChatRequest, ChatService
+from kit.ai.embedding_service import EmbeddingRequest, EmbeddingService
+from kit.ai.image_service import ImageRequest, ImageService
+from kit.ai.model_builder import ModelBuilder
+from kit.ai.rerank_service import RerankHit, RerankRequest, RerankService
+
+__all__ = [
+    "ChatRequest",
+    "ChatService",
+    "EmbeddingRequest",
+    "EmbeddingService",
+    "ImageRequest",
+    "ImageService",
+    "ModelBuilder",
+    "RerankHit",
+    "RerankRequest",
+    "RerankService",
+]

kit/ai/base_service.py

@@ -0,0 +1,94 @@
+"""
+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
+"""
+
+from abc import ABC, abstractmethod
+from typing import Self, override
+
+from kit.ai.exceptions import AIResponseError
+from kit.ai.model_client import ModelClient
+from kit.ai.profiles import ModelProfile
+from kit.ai.types import JSONObject, JSONValue
+
+__all__ = ["BaseAIService", "safe_get"]
+
+
+def safe_get(data: JSONValue, *path: str | int) -> JSONValue:
+    """按层级路径安全取值，支持 dict 键（str）与 list 索引（int）。
+
+    Raises:
+        AIResponseError: 路径任一环节缺失或类型不符。
+    """
+    cur: JSONValue = data
+    for key in path:
+        if isinstance(key, int):
+            if not isinstance(cur, list) or key < 0 or key >= len(cur):
+                raise AIResponseError(f"响应缺少索引 {path}: {str(data)[:200]}")
+            cur = cur[key]
+        else:
+            if not isinstance(cur, dict) or key not in cur:
+                raise AIResponseError(
+                    f"响应缺少字段 {'.'.join(map(str, path))}: {str(data)[:200]}"
+                )
+            cur = cur[key]
+    return cur
+
+
+class BaseAIService[RequestT, ResponseT](ABC):
+    """AI 服务基类（模板方法 + 泛型）。
+
+    子类实现同步的 ``_build_payload``（请求模型→JSON 请求体）与
+    ``_parse_response``（JSON 响应体→业务结果），公共的「构造请求、
+    发送、解析」由 ``_call`` 统一编排。请求类型 ``RequestT`` 与结果
+    类型 ``ResponseT`` 由泛型绑定，保证覆写签名一致、类型自洽。
+    """
+
+    def __init__(self, profile: ModelProfile) -> None:
+        self._profile: ModelProfile = profile
+        self._client: ModelClient = ModelClient(profile)
+
+    @property
+    def profile(self) -> ModelProfile:
+        return self._profile
+
+    @abstractmethod
+    def _build_payload(self, request: RequestT) -> JSONObject:
+        """将请求模型构造为 JSON 请求体。"""
+
+    @abstractmethod
+    def _parse_response(self, data: JSONObject) -> ResponseT:
+        """将 JSON 响应体解析为业务结果。"""
+
+    async def _call(self, request: RequestT) -> ResponseT:
+        """统一编排：构造请求体 → 发送 → 解析响应。"""
+        payload = self._build_payload(request)
+        data = await self._client.post_json(payload)
+        return self._parse_response(data)
+
+    async def close(self) -> None:
+        await self._client.close()
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(self, *exc_info: object) -> None:
+        await self.close()
+
+    @override
+    def __str__(self) -> str:
+        return f"{type(self).__name__}({self._profile.name})"

kit/ai/chat_service.py

@@ -0,0 +1,110 @@
+"""
+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
+"""
+
+from collections.abc import AsyncIterator
+from dataclasses import dataclass
+from typing import cast, override
+
+from kit.ai.base_service import BaseAIService, safe_get
+from kit.ai.exceptions import AIResponseError
+from kit.ai.types import JSONObject
+from kit.config.log_config import get_default_logger
+
+__all__ = ["ChatRequest", "ChatService"]
+
+logger = get_default_logger(__name__)
+
+Message = dict[str, str]
+
+
+@dataclass(frozen=True)
+class ChatRequest:
+    """对话请求模型。"""
+
+    messages: list[Message]
+    temperature: float | None = None
+    max_tokens: int | None = None
+    stream: bool = False
+
+
+class ChatService(BaseAIService[ChatRequest, str]):
+    """对话类模型服务（全异步）。"""
+
+    @override
+    def _build_payload(self, request: ChatRequest) -> JSONObject:
+        payload: dict[str, object] = {
+            "model": self._profile.model,
+            "messages": request.messages,
+            "stream": request.stream,
+        }
+        if request.temperature is not None:
+            payload["temperature"] = request.temperature
+        if request.max_tokens is not None:
+            payload["max_tokens"] = request.max_tokens
+        return cast(JSONObject, payload)
+
+    @override
+    def _parse_response(self, data: JSONObject) -> str:
+        content = safe_get(data, "choices", 0, "message", "content")
+        if not isinstance(content, str):
+            raise AIResponseError(f"content 类型异常: {type(content).__name__}")
+        return content
+
+    async def ask(
+        self,
+        messages: list[Message],
+        *,
+        temperature: float | None = None,
+        max_tokens: int | None = None,
+    ) -> str:
+        request = ChatRequest(messages, temperature=temperature, max_tokens=max_tokens)
+        return await self._call(request)
+
+    async def complete(
+        self,
+        prompt: str,
+        *,
+        temperature: float | None = None,
+        max_tokens: int | None = None,
+    ) -> str:
+        messages: list[Message] = [{"role": "user", "content": prompt}]
+        return await self.ask(messages, temperature=temperature, max_tokens=max_tokens)
+
+    async def stream(
+        self,
+        messages: list[Message],
+        *,
+        temperature: float | None = None,
+        max_tokens: int | None = None,
+    ) -> AsyncIterator[str]:
+        request = ChatRequest(
+            messages, temperature=temperature, max_tokens=max_tokens, stream=True
+        )
+        payload = self._build_payload(request)
+        async for parsed in self._client.stream_json(payload):
+            if parsed is None:
+                continue
+            try:
+                delta = safe_get(parsed, "choices", 0, "delta", "content")
+            except AIResponseError:
+                # 流式结束帧等无 delta 的正常帧，跳过
+                logger.debug("流式帧缺少 delta.content，跳过")
+                continue
+            if isinstance(delta, str) and delta:
+                yield delta

kit/ai/embedding_service.py

@@ -0,0 +1,133 @@
+"""
+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
+"""
+
+import asyncio
+import itertools
+from dataclasses import dataclass
+from typing import cast, override
+
+from kit.ai.base_service import BaseAIService, safe_get
+from kit.ai.exceptions import AIError, AIRequestError, AIResponseError
+from kit.ai.profiles import ModelProfile
+from kit.ai.types import JSONObject
+
+__all__ = ["EmbeddingRequest", "EmbeddingService"]
+
+_DEFAULT_CONCURRENCY = 4
+
+
+@dataclass(frozen=True)
+class EmbeddingRequest:
+    """向量化请求模型（单批）。"""
+
+    texts: list[str]
+
+
+class EmbeddingService(BaseAIService[EmbeddingRequest, list[list[float]]]):
+    """向量化服务（全异步）。
+
+    公网 API 有限流限速前提，通过分批 + 可选并发（信号量）控制压力。
+    信号量在运行中的事件循环内惰性创建，避免构造期绑定循环的隐患。
+    """
+
+    def __init__(self, profile: ModelProfile) -> None:
+        super().__init__(profile)
+        if profile.dimension is None:
+            raise ValueError(f"模型 {profile.model} 未配置 dimension，无法用于向量化")
+
+    @property
+    def dimension(self) -> int:
+        dim = self._profile.dimension
+        if not isinstance(dim, int):
+            raise AIResponseError("dimension 在构造期已校验非空，不应缺失")
+        return dim
+
+    @override
+    def _build_payload(self, request: EmbeddingRequest) -> JSONObject:
+        return cast(
+            JSONObject,
+            {
+                "model": self._profile.model,
+                "input": request.texts,
+                "encoding_format": "float",
+            },
+        )
+
+    @override
+    def _parse_response(self, data: JSONObject) -> list[list[float]]:
+        items = safe_get(data, "data")
+        if not isinstance(items, list):
+            raise AIResponseError(f"向量化响应 data 必须是数组: {str(data)[:200]}")
+        vectors: list[list[float]] = []
+        for item in items:
+            if not isinstance(item, dict):
+                raise AIResponseError(f"向量化响应条目非法: {str(item)[:200]}")
+            embedding = item.get("embedding")
+            if not isinstance(embedding, list):
+                raise AIResponseError(f"向量化响应 embedding 非法: {str(item)[:200]}")
+            floats: list[float] = []
+            for value in embedding:
+                if not isinstance(value, (int, float)):
+                    raise AIResponseError(
+                        f"向量化响应 embedding 元素非法: {str(item)[:200]}"
+                    )
+                floats.append(float(value))
+            vectors.append(floats)
+        return vectors
+
+    async def embed_text(self, text: str) -> list[float]:
+        vectors = await self._call(EmbeddingRequest([text]))
+        return vectors[0]
+
+    async def embed_texts(
+        self,
+        texts: list[str],
+        *,
+        batch_size: int | None = None,
+        concurrency: int = _DEFAULT_CONCURRENCY,
+    ) -> list[list[float]]:
+        if not texts:
+            return []
+
+        batch = batch_size or self._profile.batch_size
+        semaphore = asyncio.Semaphore(concurrency)
+        results: list[list[float] | None] = [None] * len(texts)
+        failures: list[str] = []
+
+        async def _one(batch_index: int, chunk: tuple[str, ...]) -> None:
+            async with semaphore:
+                try:
+                    vectors = await self._call(EmbeddingRequest(list(chunk)))
+                except AIError as exc:
+                    failures.append(f"批次 {batch_index}: {exc}")
+                    return
+                start = batch_index * batch
+                for offset, vec in enumerate(vectors):
+                    results[start + offset] = vec
+
+        batches = list(itertools.batched(texts, batch, strict=False))
+        await asyncio.gather(*(_one(i, chunk) for i, chunk in enumerate(batches)))
+
+        if failures:
+            raise AIRequestError(
+                f"有 {len(failures)}/{len(batches)} 批向量化失败: "
+                + " | ".join(failures)
+            )
+
+        return [vec for vec in results if vec is not None]

kit/ai/exceptions.py

@@ -0,0 +1,57 @@
+"""
+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 请求超时（可用于重试策略）
+    └── AIResponseError  响应结构解析失败、流式数据无法解析
+"""
+
+
+class AIError(Exception):
+    """AI 模型服务基类异常"""
+
+
+class AIConfigError(AIError):
+    """模型档案配置异常（文件缺失/非法、档案不存在、密钥未配置、必填字段缺失）"""
+
+
+class AIRequestError(AIError):
+    """模型服务请求异常（网络异常、HTTP >= 400）。
+
+    Attributes:
+        status_code: HTTP 状态码；非 HTTP 错误（超时、连接失败等）为 None。
+    """
+
+    def __init__(self, message: str, *, status_code: int | None = None) -> None:
+        super().__init__(message)
+        self.status_code: int | None = status_code
+
+
+class AITimeoutError(AIRequestError):
+    """模型服务请求超时异常（可用于重试策略）"""
+
+
+class AIResponseError(AIError):
+    """模型服务响应异常（响应结构解析失败、流式数据无法解析）"""