python-basekit 0.0.11__tar.gz

python_basekit-0.0.11/PKG-INFO

@@ -0,0 +1,46 @@
+Metadata-Version: 2.3
+Name: python-basekit
+Version: 0.0.11
+Summary: Python Base Kit
+Author: YanSH
+Author-email: YanSH <yansh97@foxmail.com>
+Requires-Dist: aiosqlite>=0.22.1
+Requires-Dist: beautifulsoup4>=4.14.3
+Requires-Dist: curl-cffi>=0.14.0
+Requires-Dist: filetype>=1.2.0
+Requires-Dist: flowmark>=0.6.5
+Requires-Dist: greenlet>=3.3.2
+Requires-Dist: httpx[http2]>=0.28.1
+Requires-Dist: jinja2>=3.1.6
+Requires-Dist: logfire>=4.27.0
+Requires-Dist: lxml>=6.0.2
+Requires-Dist: markdown-it-py>=4.0.0
+Requires-Dist: markdownify>=1.2.2
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: pydantic-settings>=2.13.1
+Requires-Dist: python-dotenv>=1.2.2
+Requires-Dist: rich>=14.3.3
+Requires-Dist: sqlalchemy>=2.0.48
+Requires-Dist: tenacity>=9.1.4
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# Base Kit
+
+一个面向内部使用的 Python 基础工具包。
+
+## 环境
+
+Python `>=3.12`
+
+## 安装
+
+```bash
+uv add python-basekit
+```
+
+## 使用
+
+```python
+import basekit
+```

python_basekit-0.0.11/README.md

@@ -0,0 +1,19 @@
+# Base Kit
+
+一个面向内部使用的 Python 基础工具包。
+
+## 环境
+
+Python `>=3.12`
+
+## 安装
+
+```bash
+uv add python-basekit
+```
+
+## 使用
+
+```python
+import basekit
+```

python_basekit-0.0.11/pyproject.toml

@@ -0,0 +1,92 @@
+[project]
+name = "python-basekit"
+version = "0.0.11"
+description = "Python Base Kit"
+readme = "README.md"
+authors = [{ name = "YanSH", email = "yansh97@foxmail.com" }]
+requires-python = ">=3.12"
+dependencies = [
+    "aiosqlite>=0.22.1",
+    "beautifulsoup4>=4.14.3",
+    "curl-cffi>=0.14.0",
+    "filetype>=1.2.0",
+    "flowmark>=0.6.5",
+    "greenlet>=3.3.2",
+    "httpx[http2]>=0.28.1",
+    "jinja2>=3.1.6",
+    "logfire>=4.27.0",
+    "lxml>=6.0.2",
+    "markdown-it-py>=4.0.0",
+    "markdownify>=1.2.2",
+    "pydantic>=2.12.5",
+    "pydantic-settings>=2.13.1",
+    "python-dotenv>=1.2.2",
+    "rich>=14.3.3",
+    "sqlalchemy>=2.0.48",
+    "tenacity>=9.1.4",
+]
+
+[dependency-groups]
+dev = ["pytest>=9.0.2", "pytest-asyncio>=1.3.0", "ruff>=0.15.5"]
+
+[build-system]
+requires = ["uv_build>=0.11.10,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.uv]
+environments = ["sys_platform == 'darwin'", "sys_platform == 'linux'"]
+
+[tool.uv.build-backend]
+module-name = "basekit"
+
+# ruff 配置
+[tool.ruff]
+cache-dir = ".cache/.ruff_cache"
+
+# pytest 配置
+[tool.pytest.ini_options]
+
+# 测试文件查找路径
+testpaths = ["tests"]
+
+# 测试文件/类/函数的命名规则
+python_files = ["test_*.py", "*_test.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+
+# pytest 缓存目录统一到 .cache/
+cache_dir = ".cache/.pytest_cache"
+
+# 异步测试配置
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+asyncio_default_test_loop_scope = "function"
+
+# Logfire 测试配置
+logfire = false
+
+# pytest 命令行默认选项
+addopts = "-ra --showlocals --strict-markers --strict-config --tb=auto --import-mode=importlib"
+
+# 测试标记
+markers = [
+    "zero_cost: 无成本测试，不调用 AI 实际接口",
+    "low_cost: 低成本测试，仅 create_message 相关",
+    "high_cost: 高成本测试，如 structured/tool_use/image 等",
+]
+
+# 警告视为错误，早发现潜在问题
+filterwarnings = "error"
+
+# 进度条风格
+console_output_style = "progress"
+
+# pyright 配置
+[tool.pyright]
+
+# 与项目运行时版本保持一致，避免误报语法不支持
+pythonVersion = "3.12"
+
+# 虚拟环境路径
+venvPath = "."
+venv = ".venv"

python_basekit-0.0.11/src/basekit/ai/clients/anthropic.py

@@ -0,0 +1,192 @@
+from collections.abc import Callable
+from typing import ClassVar, override
+
+import logfire
+from httpx import Response
+from pydantic import BaseModel
+
+from basekit.ai.schema import AIClient, Tool, Usage, ValidationError
+from basekit.ai.utils import transform_schema
+from basekit.utils.misc import recursive_merge
+
+
+class AnthropicClient(AIClient):
+    cache_key_fields: ClassVar[tuple[str, ...]] = ("max_tokens",)
+
+    api_key: str
+    base_url: str = "https://api.anthropic.com"
+    max_tokens: int = 16000
+
+    def _headers(self) -> dict:
+        return {
+            "X-Api-Key": self.api_key,
+            "Anthropic-Version": "2023-06-01",
+            "Content-Type": "application/json",
+        }
+
+    def _message_url(self) -> str:
+        return f"{self.base_url}/v1/messages"
+
+    def _message_params(self, system: str, prompt: str, /) -> dict:
+        return {
+            "model": self.model.request_name,
+            "system": system,
+            "messages": [{"role": "user", "content": prompt}],
+            "max_tokens": self.max_tokens,
+        }
+
+    def _structured_message_params(self, schema: dict, /) -> dict:
+        return {"output_config": {"format": {"type": "json_schema", "schema": schema}}}
+
+    def _tool_use_params(self, tool: dict, /) -> dict:
+        return {"tools": [tool], "tool_choice": {"type": "any"}}
+
+    def _get_block(
+        self, data: dict, stop_reason: str, filter_: Callable[[dict], bool], /
+    ) -> dict:
+        if data["stop_reason"] != stop_reason:
+            raise ValueError(f"STOP REASON：{data['stop_reason']}")
+
+        blocks: list[dict] = [c for c in data["content"] if filter_(c)]
+        if len(blocks) != 1:
+            raise ValueError(f"LEN(BLOCKS)：{len(blocks)}")
+
+        return blocks[0]
+
+    def _get_usage(self, data: dict, /) -> Usage:
+        usage: dict = data["usage"]
+        cache_creation_tokens: int = usage.get("cache_creation_input_tokens", 0)
+        cache_read_tokens: int = usage.get("cache_read_input_tokens", 0)
+        return Usage(
+            input_tokens=usage["input_tokens"]
+            + cache_creation_tokens
+            + cache_read_tokens,
+            cache_creation_tokens=cache_creation_tokens,
+            cache_read_tokens=cache_read_tokens,
+            output_tokens=usage["output_tokens"],
+        )
+
+    @override
+    async def _create_message_once(
+        self, system: str, prompt: str, extra: dict | None
+    ) -> str:
+        with logfire.span("anthropic client | create message") as span:
+            span.set_attribute(key="model", value=self.model)
+            span.set_attribute(key="system", value=system)
+            span.set_attribute(key="prompt", value=prompt)
+            span.set_attribute(key="extra", value=extra)
+
+            async with self._limiter:
+                response: Response = await self._http_client.post(
+                    self._message_url(),
+                    headers=self._headers(),
+                    data=recursive_merge(
+                        self._message_params(system, prompt),
+                        self.model.extra_params,
+                        extra,
+                    ),
+                )
+
+            try:
+                data: dict = response.json()
+                block: dict = self._get_block(
+                    data, "end_turn", lambda x: x["type"] == "text"
+                )
+                message: str = block["text"]
+                usage: Usage = self._get_usage(data)
+
+                span.set_attribute(key="return", value=message)
+                span.set_attribute(key="usage", value=usage)
+                span.message = f"{span.message} -> {usage.format()} tokens"
+                return message
+            except Exception as exc:
+                raise ValidationError("生成消息失败") from exc
+
+    @override
+    async def _create_structured_message_once[T: BaseModel](
+        self, system: str, prompt: str, schema: type[T], extra: dict | None
+    ) -> T:
+        schema_name: str = schema.__name__
+        with logfire.span(
+            f"anthropic client | create structured message | {schema_name}"
+        ) as span:
+            schema_data: dict = transform_schema(schema.model_json_schema())
+
+            span.set_attribute(key="model", value=self.model)
+            span.set_attribute(key="system", value=system)
+            span.set_attribute(key="prompt", value=prompt)
+            span.set_attribute(key="schema", value=schema_data)
+            span.set_attribute(key="extra", value=extra)
+
+            async with self._limiter:
+                response: Response = await self._http_client.post(
+                    self._message_url(),
+                    headers=self._headers(),
+                    data=recursive_merge(
+                        self._message_params(system, prompt),
+                        self._structured_message_params(schema_data),
+                        self.model.extra_params,
+                        extra,
+                    ),
+                )
+
+            try:
+                data: dict = response.json()
+                block: dict = self._get_block(
+                    data, "end_turn", lambda x: x["type"] == "text"
+                )
+                result: T = schema.model_validate_json(json_data=block["text"])
+                usage: Usage = self._get_usage(data)
+
+                span.set_attribute(key="return", value=result)
+                span.set_attribute(key="usage", value=usage)
+                span.message = f"{span.message} -> {usage.format()} tokens"
+                return result
+            except Exception as exc:
+                raise ValidationError("生成结构化消息失败") from exc
+
+    @override
+    async def _create_tool_use_once[T: BaseModel](
+        self, system: str, prompt: str, tool: Tool[T], extra: dict | None
+    ) -> T:
+        tool_name: str = tool.name
+        with logfire.span(f"anthropic client | create tool use | {tool_name}") as span:
+            tool_: dict = {
+                "name": tool.name,
+                "description": tool.description,
+                "input_schema": transform_schema(tool.input_schema.model_json_schema()),
+                "strict": True,
+            }
+
+            span.set_attribute(key="model", value=self.model)
+            span.set_attribute(key="system", value=system)
+            span.set_attribute(key="prompt", value=prompt)
+            span.set_attribute(key="tool", value=tool_)
+            span.set_attribute(key="extra", value=extra)
+
+            async with self._limiter:
+                response: Response = await self._http_client.post(
+                    self._message_url(),
+                    headers=self._headers(),
+                    data=recursive_merge(
+                        self._message_params(system, prompt),
+                        self._tool_use_params(tool_),
+                        self.model.extra_params,
+                        extra,
+                    ),
+                )
+
+            try:
+                data: dict = response.json()
+                block: dict = self._get_block(
+                    data, "tool_use", lambda x: x["type"] == "tool_use"
+                )
+                result: T = tool.input_schema.model_validate(obj=block["input"])
+                usage: Usage = self._get_usage(data)
+
+                span.set_attribute(key="return", value=result)
+                span.set_attribute(key="usage", value=usage)
+                span.message = f"{span.message} -> {usage.format()} tokens"
+                return result
+            except Exception as exc:
+                raise ValidationError("生成工具调用失败") from exc

python_basekit-0.0.11/src/basekit/ai/clients/dashscope.py

@@ -0,0 +1,133 @@
+from collections.abc import Callable
+from typing import ClassVar, override
+
+import logfire
+from httpx import Response
+from pydantic import BaseModel
+
+from basekit.ai.schema import (
+    AIClient,
+    ImageRatio,
+    ImageSize,
+    NotSupportedError,
+    ValidationError,
+)
+from basekit.utils.misc import recursive_merge
+
+
+class ImageUsage(BaseModel):
+    width: int
+    height: int
+
+    def format(self) -> str:
+        return f"{self.width}x{self.height}"
+
+
+class DashScopeClient(AIClient):
+    cache_key_fields: ClassVar[tuple[str, ...]] = ()
+
+    api_key: str
+    base_url: str = "https://dashscope.aliyuncs.com/api/v1"
+
+    def _headers(self) -> dict:
+        return {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+        }
+
+    def _image_url(self) -> str:
+        return f"{self.base_url}/services/aigc/multimodal-generation/generation"
+
+    def _image_resolution(self, ratio: ImageRatio, size: ImageSize, /) -> str:
+        base_resolution_map: dict[ImageRatio, tuple[int, int]] = {
+            "9:16": (768, 1344),
+            "2:3": (832, 1248),
+            "3:4": (864, 1184),
+            "4:5": (896, 1152),
+            "1:1": (1024, 1024),
+            "5:4": (1152, 896),
+            "4:3": (1184, 864),
+            "3:2": (1248, 832),
+            "16:9": (1344, 768),
+        }
+        resolution_ratio_map: dict[ImageSize, int] = {"1K": 1, "2K": 2, "4K": 4}
+
+        width: int = base_resolution_map[ratio][0] * resolution_ratio_map[size]
+        height: int = base_resolution_map[ratio][1] * resolution_ratio_map[size]
+        resolution: str = f"{width}*{height}"
+
+        match self.model.name:
+            case "qwen-image-2.0" | "qwen-image-2.0-pro":
+                if size not in {"1K", "2K"}:
+                    raise NotSupportedError(
+                        f"模型 {self.model.name} 仅支持 1K 和 2K 分辨率"
+                    )
+                return resolution
+            case _:
+                raise NotSupportedError(f"模型 {self.model.name} 不合法")
+
+    def _image_params(self, prompt: str, resolution: str, /) -> dict:
+        return {
+            "model": self.model.request_name,
+            "input": {"messages": [{"role": "user", "content": [{"text": prompt}]}]},
+            "parameters": {"size": resolution},
+        }
+
+    def _get_block(self, data: dict, filter_: Callable[[dict], bool], /) -> dict:
+        choices: list = data["output"]["choices"]
+        if len(choices) != 1:
+            raise ValueError(f"LEN(CHOICES)：{len(choices)}")
+
+        choice: dict = choices[0]
+        if choice["finish_reason"] != "stop":
+            raise ValueError(f"FINISH REASON：{choice['finish_reason']}")
+
+        blocks: list[dict] = [c for c in choice["message"]["content"] if filter_(c)]
+        if not blocks:
+            raise ValueError(f"LEN(BLOCKS)：{len(blocks)}")
+
+        return blocks[0]
+
+    def _get_usage(self, data: dict, /) -> ImageUsage:
+        usage: dict = data["usage"]
+        return ImageUsage(width=usage["width"], height=usage["height"])
+
+    @override
+    async def _create_image_once(
+        self, prompt: str, ratio: ImageRatio, size: ImageSize, extra: dict | None
+    ) -> bytes:
+        with logfire.span("dashscope client | create image") as span:
+            resolution: str = self._image_resolution(ratio, size)
+
+            span.set_attribute(key="model", value=self.model)
+            span.set_attribute(key="prompt", value=prompt)
+            span.set_attribute(key="ratio", value=ratio)
+            span.set_attribute(key="size", value=size)
+            span.set_attribute(key="extra", value=extra)
+            span.set_attribute(key="resolution", value=resolution)
+
+            async with self._limiter:
+                response: Response = await self._http_client.post(
+                    self._image_url(),
+                    headers=self._headers(),
+                    data=recursive_merge(
+                        self._image_params(prompt, resolution),
+                        self.model.extra_params,
+                        extra,
+                    ),
+                )
+
+            try:
+                data: dict = response.json()
+                block: dict = self._get_block(data, lambda c: "image" in c)
+                image_url: str = block["image"]
+                image: bytes = (await self._http_client.get(image_url)).content
+                usage: ImageUsage = self._get_usage(data)
+
+                span.set_attribute(key="image_url", value=image_url)
+                span.set_attribute(key="filesize", value=len(image))
+                span.set_attribute(key="usage", value=usage)
+                span.message = f"{span.message} -> {usage.format()} pixels"
+                return image
+            except Exception as exc:
+                raise ValidationError("生成图像失败") from exc