provider-sdk 0.1.0__tar.gz

provider_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 provider-sdk contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

provider_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: provider-sdk
+Version: 0.1.0
+Summary: Provider-V2 平台插件 SDK — 第三方平台适配器开发与加载
+Author: provider-sdk
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/nichengfuben/provider-sdk
+Project-URL: Documentation, https://github.com/nichengfuben/provider-sdk/blob/main/docs/guide.md
+Project-URL: Repository, https://github.com/nichengfuben/provider-sdk
+Project-URL: Issues, https://github.com/nichengfuben/provider-sdk/issues
+Keywords: provider,llm,gateway,plugin,sdk,openai
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.9.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Dynamic: license-file
+
+# provider-sdk
+
+Provider-V2 平台插件 SDK。对标 [maibot-plugin-sdk](https://github.com/Mai-with-u/maibot-plugin-sdk) 的插件契约，为第三方**平台适配器**提供独立开发与加载能力。
+
+## 安装
+
+```bash
+pip install -e X:\Project\provider-sdk
+```
+
+## 快速开始
+
+在 Provider Host 的 `plugins/` 目录下创建插件文件夹：
+
+```
+plugins/
+  my_platform/
+    _manifest.json
+    plugin.py
+    config.toml          # 可选，由 Host 管理
+```
+
+`plugin.py` 最小示例见 [`examples/echo_platform/plugin.py`](examples/echo_platform/plugin.py)。
+
+```python
+from provider_sdk import ProviderPlugin, PlatformAdapter, Candidate, make_id
+
+class MyPlugin(ProviderPlugin, PlatformAdapter):
+    @property
+    def name(self) -> str:
+        return "my_platform"
+
+    async def on_load(self) -> None:
+        self.ctx.logger.info("loaded")
+
+    async def init(self, session): ...
+    async def candidates(self) -> list[Candidate]: ...
+    async def ensure_candidates(self, count: int) -> int: ...
+    async def complete(self, candidate, messages, model, stream, **kw): ...
+    async def close(self) -> None: ...
+
+def create_plugin() -> MyPlugin:
+    return MyPlugin()
+```
+
+## 与 MaiBot SDK 的对应关系
+
+| MaiBot | provider-sdk |
+|--------|----------------|
+| `MaiBotPlugin` | `ProviderPlugin` |
+| `create_plugin()` | `create_plugin()` |
+| `_manifest.json` | `_manifest.json` |
+| `on_load` / `on_unload` / `on_config_update` | 相同 |
+| `self.ctx.send` / `gateway` 等 | `self.ctx.config` / `http` / `logger` |
+| `@Tool` / `@Command` | 平台插件以 `PlatformAdapter` 能力为主 |
+
+## Host 集成
+
+```python
+from pathlib import Path
+from provider_sdk.integrate import load_platform_plugins, register_loaded_plugins
+
+loaded = await load_platform_plugins(Path("plugins"), session)
+register_loaded_plugins(registry, loaded)
+```
+
+完整说明见 [`docs/guide.md`](docs/guide.md)。
+
+## 开发
+
+```bash
+pip install -e ".[dev]"
+pytest -q
+```

provider_sdk-0.1.0/README.md

@@ -0,0 +1,74 @@
+# provider-sdk
+
+Provider-V2 平台插件 SDK。对标 [maibot-plugin-sdk](https://github.com/Mai-with-u/maibot-plugin-sdk) 的插件契约，为第三方**平台适配器**提供独立开发与加载能力。
+
+## 安装
+
+```bash
+pip install -e X:\Project\provider-sdk
+```
+
+## 快速开始
+
+在 Provider Host 的 `plugins/` 目录下创建插件文件夹：
+
+```
+plugins/
+  my_platform/
+    _manifest.json
+    plugin.py
+    config.toml          # 可选，由 Host 管理
+```
+
+`plugin.py` 最小示例见 [`examples/echo_platform/plugin.py`](examples/echo_platform/plugin.py)。
+
+```python
+from provider_sdk import ProviderPlugin, PlatformAdapter, Candidate, make_id
+
+class MyPlugin(ProviderPlugin, PlatformAdapter):
+    @property
+    def name(self) -> str:
+        return "my_platform"
+
+    async def on_load(self) -> None:
+        self.ctx.logger.info("loaded")
+
+    async def init(self, session): ...
+    async def candidates(self) -> list[Candidate]: ...
+    async def ensure_candidates(self, count: int) -> int: ...
+    async def complete(self, candidate, messages, model, stream, **kw): ...
+    async def close(self) -> None: ...
+
+def create_plugin() -> MyPlugin:
+    return MyPlugin()
+```
+
+## 与 MaiBot SDK 的对应关系
+
+| MaiBot | provider-sdk |
+|--------|----------------|
+| `MaiBotPlugin` | `ProviderPlugin` |
+| `create_plugin()` | `create_plugin()` |
+| `_manifest.json` | `_manifest.json` |
+| `on_load` / `on_unload` / `on_config_update` | 相同 |
+| `self.ctx.send` / `gateway` 等 | `self.ctx.config` / `http` / `logger` |
+| `@Tool` / `@Command` | 平台插件以 `PlatformAdapter` 能力为主 |
+
+## Host 集成
+
+```python
+from pathlib import Path
+from provider_sdk.integrate import load_platform_plugins, register_loaded_plugins
+
+loaded = await load_platform_plugins(Path("plugins"), session)
+register_loaded_plugins(registry, loaded)
+```
+
+完整说明见 [`docs/guide.md`](docs/guide.md)。
+
+## 开发
+
+```bash
+pip install -e ".[dev]"
+pytest -q
+```

provider_sdk-0.1.0/provider_sdk/__init__.py

@@ -0,0 +1,39 @@
+"""Provider-V2 平台插件 SDK。
+
+插件作者的唯一依赖入口。插件不得导入 ``src.*``，只能通过本 SDK 与 Host 交互。
+
+核心导出：
+
+- :class:`ProviderPlugin` — 插件基类（生命周期 + 配置）
+- :class:`PlatformAdapter` — 平台适配器抽象接口
+- :class:`PluginContext` — 运行时上下文（日志 / 配置 / HTTP）
+- :class:`PluginConfigBase` — 插件配置模型基类
+- :class:`Candidate` — 网关候选项
+"""
+
+from provider_sdk.config import Field, PluginConfigBase
+from provider_sdk.context import PluginContext
+from provider_sdk.platform import PlatformAdapter
+from provider_sdk.plugin import ProviderPlugin
+from provider_sdk.types import (
+    CONFIG_RELOAD_SCOPE_GLOBAL,
+    CONFIG_RELOAD_SCOPE_SELF,
+    ALL_CAPABILITIES,
+)
+from provider_sdk.types.candidate import Candidate, make_id
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ProviderPlugin",
+    "PlatformAdapter",
+    "PluginContext",
+    "PluginConfigBase",
+    "Field",
+    "Candidate",
+    "make_id",
+    "CONFIG_RELOAD_SCOPE_SELF",
+    "CONFIG_RELOAD_SCOPE_GLOBAL",
+    "ALL_CAPABILITIES",
+    "__version__",
+]

provider_sdk-0.1.0/provider_sdk/capabilities/__init__.py

@@ -0,0 +1,73 @@
+"""能力代理：配置、HTTP、日志。"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Awaitable, Callable, Mapping
+from typing import Any, Optional
+
+import aiohttp
+
+__all__ = ["ConfigCapability", "HttpCapability", "LoggingCapability"]
+
+GetConfigFn = Callable[[str, str], Any]
+GetGlobalConfigFn = Callable[[], Mapping[str, Any]]
+
+
+class LoggingCapability:
+    """插件日志能力。"""
+
+    def __init__(self, logger: logging.Logger) -> None:
+        self._logger = logger
+
+    @property
+    def logger(self) -> logging.Logger:
+        return self._logger
+
+
+class ConfigCapability:
+    """插件配置读取能力。"""
+
+    def __init__(
+        self,
+        *,
+        get_plugin_config: Callable[[], Mapping[str, Any]],
+        get_global_config: Optional[GetGlobalConfigFn] = None,
+    ) -> None:
+        self._get_plugin_config = get_plugin_config
+        self._get_global_config = get_global_config
+
+    def get_plugin(self) -> dict[str, Any]:
+        """返回当前插件配置字典副本。"""
+        raw = self._get_plugin_config()
+        return dict(raw) if isinstance(raw, Mapping) else {}
+
+    def get_global(self) -> dict[str, Any]:
+        """返回 Host 全局配置字典副本。"""
+        if self._get_global_config is None:
+            return {}
+        raw = self._get_global_config()
+        return dict(raw) if isinstance(raw, Mapping) else {}
+
+    def get(self, section: str, key: str, default: Any = None) -> Any:
+        """读取全局配置中的嵌套键。"""
+        data = self.get_global()
+        node = data.get(section)
+        if isinstance(node, Mapping):
+            return node.get(key, default)
+        return default
+
+
+class HttpCapability:
+    """共享 HTTP 会话能力。"""
+
+    def __init__(self, session: aiohttp.ClientSession) -> None:
+        self._session = session
+
+    @property
+    def session(self) -> aiohttp.ClientSession:
+        return self._session
+
+    async def request(self, method: str, url: str, **kwargs: Any) -> aiohttp.ClientResponse:
+        """对共享会话发起请求。"""
+        return await self._session.request(method, url, **kwargs)

provider_sdk-0.1.0/provider_sdk/config.py

@@ -0,0 +1,78 @@
+"""插件配置模型与校验工具。"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Mapping
+from typing import Any, ClassVar, TypeVar, cast
+
+from pydantic import BaseModel, ConfigDict, Field
+
+__all__ = [
+    "Field",
+    "PluginConfigBase",
+    "build_plugin_default_config",
+    "is_plugin_config_class",
+    "merge_plugin_config_data",
+    "validate_plugin_config",
+]
+
+PluginConfigT = TypeVar("PluginConfigT", bound="PluginConfigBase")
+
+
+class PluginConfigBase(BaseModel):
+    """插件配置模型基类。
+
+    插件作者继承此类声明配置结构；Host 据此生成默认配置与 WebUI Schema。
+    """
+
+    model_config = ConfigDict(validate_assignment=True, extra="ignore")
+
+    __ui_label__: ClassVar[str] = ""
+    __ui_icon__: ClassVar[str] = ""
+    __ui_order__: ClassVar[int] = 0
+
+
+def is_plugin_config_class(candidate: Any) -> bool:
+    """判断对象是否为插件配置模型类。"""
+    return bool(inspect.isclass(candidate) and issubclass(candidate, PluginConfigBase))
+
+
+def build_plugin_default_config(config_class: type[PluginConfigT]) -> dict[str, Any]:
+    """根据配置模型构造默认配置字典。"""
+    try:
+        instance = config_class()
+    except Exception as exc:
+        raise ValueError(
+            f"插件配置模型 {config_class.__name__} 需要为所有字段提供默认值"
+        ) from exc
+    return instance.model_dump(mode="python")
+
+
+def validate_plugin_config(
+    config_class: type[PluginConfigT],
+    config_data: Mapping[str, Any],
+) -> PluginConfigT:
+    """校验并构造强类型配置实例。"""
+    return config_class.model_validate(dict(config_data))
+
+
+def merge_plugin_config_data(
+    default_config: Mapping[str, Any],
+    raw_config: Mapping[str, Any],
+) -> tuple[dict[str, Any], bool]:
+    """将用户配置递归合并到默认配置之上。"""
+    changed = False
+    merged: dict[str, Any] = dict(default_config)
+
+    for key, value in raw_config.items():
+        base_value = merged.get(key)
+        if isinstance(base_value, Mapping) and isinstance(value, Mapping):
+            nested, nested_changed = merge_plugin_config_data(base_value, value)
+            merged[key] = nested
+            changed = changed or nested_changed or nested != dict(base_value)
+        elif base_value != value:
+            merged[key] = value
+            changed = True
+
+    return merged, changed

provider_sdk-0.1.0/provider_sdk/context.py

@@ -0,0 +1,78 @@
+"""插件运行时上下文。"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+import aiohttp
+
+from provider_sdk.capabilities import ConfigCapability, HttpCapability, LoggingCapability
+
+__all__ = ["HostServices", "PluginContext", "create_plugin_context"]
+
+
+@dataclass
+class HostServices:
+    """Host 注入给 SDK 的运行时服务集合。"""
+
+    session: aiohttp.ClientSession
+    plugin_id: str
+    plugin_dir: str = ""
+    get_plugin_config: Any = None
+    get_global_config: Any = None
+    logger: Optional[logging.Logger] = None
+
+
+class PluginContext:
+    """插件运行时上下文。
+
+    插件通过 ``self.ctx`` 访问日志、配置与 HTTP 会话。
+    """
+
+    def __init__(
+        self,
+        *,
+        plugin_id: str,
+        plugin_dir: str,
+        logger: logging.Logger,
+        config: ConfigCapability,
+        http: HttpCapability,
+    ) -> None:
+        self.plugin_id = plugin_id
+        self.plugin_dir = plugin_dir
+        self.logger = logger
+        self.config = config
+        self.http = http
+
+    @property
+    def paths(self) -> Mapping[str, str]:
+        """插件相关路径。"""
+        return {"plugin_dir": self.plugin_dir}
+
+
+def create_plugin_context(services: HostServices) -> PluginContext:
+    """根据 Host 服务构造插件上下文。"""
+    plugin_id = services.plugin_id
+    logger = services.logger or logging.getLogger(f"provider_sdk.plugin.{plugin_id}")
+
+    def _plugin_config() -> Mapping[str, Any]:
+        if callable(services.get_plugin_config):
+            raw = services.get_plugin_config()
+            return dict(raw) if isinstance(raw, Mapping) else {}
+        return {}
+
+    config_cap = ConfigCapability(
+        get_plugin_config=_plugin_config,
+        get_global_config=services.get_global_config if callable(services.get_global_config) else None,
+    )
+    http_cap = HttpCapability(services.session)
+    return PluginContext(
+        plugin_id=plugin_id,
+        plugin_dir=services.plugin_dir,
+        logger=logger,
+        config=config_cap,
+        http=http_cap,
+    )

provider_sdk-0.1.0/provider_sdk/integrate.py

@@ -0,0 +1,51 @@
+"""与 Provider Host 注册表集成的辅助函数。"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Callable, Mapping, Optional, Sequence
+
+import aiohttp
+
+from provider_sdk.runtime.loader import LoadedPlugin, PluginLoader
+
+__all__ = ["load_platform_plugins", "register_loaded_plugins"]
+
+
+async def load_platform_plugins(
+    plugins_root: Path,
+    session: aiohttp.ClientSession,
+    *,
+    host_version: str = "",
+    get_plugin_config: Optional[Callable[[str], Mapping[str, Any]]] = None,
+    get_global_config: Optional[Callable[[], Mapping[str, Any]]] = None,
+    whitelist: Optional[Sequence[str]] = None,
+    blacklist: Optional[Sequence[str]] = None,
+) -> list[LoadedPlugin]:
+    """发现并加载 ``plugins/`` 目录下的平台插件。"""
+    loader = PluginLoader(host_version=host_version, plugin_type_filter="platform")
+    return await loader.discover_and_load(
+        plugins_root,
+        session,
+        get_plugin_config=get_plugin_config,
+        get_global_config=get_global_config,
+        whitelist=whitelist,
+        blacklist=blacklist,
+    )
+
+
+def register_loaded_plugins(registry: Any, loaded: Sequence[LoadedPlugin]) -> None:
+    """将已加载插件的适配器注册到 echotools 风格注册表。
+
+    ``registry`` 需实现 ``register(adapter)`` 或内部 ``_registry.register``。
+    """
+    for record in loaded:
+        adapter = record.adapter
+        if hasattr(registry, "register") and callable(registry.register):
+            registry.register(adapter)
+            continue
+        inner = getattr(registry, "_registry", None)
+        if inner is not None and hasattr(inner, "register"):
+            inner.register(adapter)
+            continue
+        raise TypeError("registry 不支持 register(adapter)")

provider_sdk-0.1.0/provider_sdk/platform.py

@@ -0,0 +1,140 @@
+"""平台适配器抽象接口 — 与 Provider Host 内置适配器契约一致。"""
+
+from __future__ import annotations
+
+import time
+import uuid
+from abc import ABC, abstractmethod
+from typing import Any, AsyncGenerator, Dict, List, Optional, Union
+
+import aiohttp
+
+from provider_sdk.types.candidate import Candidate
+
+__all__ = ["PlatformAdapter", "DEFAULT_CONTEXT_LENGTH"]
+
+DEFAULT_CONTEXT_LENGTH = 131072
+
+
+class PlatformAdapter(ABC):
+    """所有平台适配器的抽象基类。
+
+  设计原则（与 Host 一致）：
+
+  - ``init()`` 必须立即返回，耗时操作放后台 Task
+  - ``candidates()`` 随时反映真实状态
+  - 可选能力方法有安全默认实现
+    """
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """平台标识名（小写，建议与目录名一致）。"""
+        ...
+
+    @property
+    def supported_models(self) -> List[str]:
+        """支持的模型列表。"""
+        return []
+
+    @property
+    def default_capabilities(self) -> Dict[str, bool]:
+        """默认能力字典，用于 ``/v1/models`` 输出。"""
+        return {"chat": True}
+
+    @property
+    def context_length(self) -> Optional[int]:
+        """默认上下文长度。"""
+        return DEFAULT_CONTEXT_LENGTH
+
+    @abstractmethod
+    async def init(self, session: aiohttp.ClientSession) -> None:
+        """初始化适配器，必须立即返回。"""
+        ...
+
+    @abstractmethod
+    async def candidates(self) -> List[Candidate]:
+        """返回当前可用候选项列表。"""
+        ...
+
+    @abstractmethod
+    async def ensure_candidates(self, count: int) -> int:
+        """确保至少有 ``count`` 个候选项可用。"""
+        ...
+
+    @abstractmethod
+    async def complete(
+        self,
+        candidate: Candidate,
+        messages: List[Dict[str, Any]],
+        model: str,
+        stream: bool,
+        *,
+        thinking: bool = False,
+        search: bool = False,
+        **kw: Any,
+    ) -> AsyncGenerator[Union[str, Dict[str, Any]], None]:
+        """聊天补全，yield 文本增量或结构化事件。"""
+        ...
+
+    @abstractmethod
+    async def close(self) -> None:
+        """关闭适配器并释放资源。"""
+        ...
+
+    async def fetch_remote_models(self) -> List[str]:
+        """拉取远程模型列表。"""
+        return []
+
+    async def create_embedding(
+        self,
+        candidate: Candidate,
+        input_data: Union[str, List[str]],
+        model: str,
+        **kw: Any,
+    ) -> Dict[str, Any]:
+        inputs = [input_data] if isinstance(input_data, str) else list(input_data)
+        return {
+            "object": "list",
+            "data": [
+                {"object": "embedding", "index": i, "embedding": []}
+                for i, _ in enumerate(inputs)
+            ],
+            "model": model,
+            "usage": {"prompt_tokens": 0, "total_tokens": 0},
+        }
+
+    async def create_image(
+        self,
+        candidate: Candidate,
+        prompt: str,
+        model: str,
+        **kw: Any,
+    ) -> Dict[str, Any]:
+        return {"created": int(time.time()), "data": []}
+
+    async def create_moderation(
+        self,
+        candidate: Candidate,
+        input_data: Union[str, List[str]],
+        model: str,
+        **kw: Any,
+    ) -> Dict[str, Any]:
+        inputs = [input_data] if isinstance(input_data, str) else list(input_data)
+        return {
+            "id": f"modr-{uuid.uuid4().hex[:24]}",
+            "model": model,
+            "results": [{"flagged": False, "categories": {}, "category_scores": {}} for _ in inputs],
+        }
+
+    def set_proxy_enabled(self, enabled: bool) -> None:
+        """设置代理覆盖开关（可选）。"""
+        del enabled
+
+    def is_proxy_allowed(self) -> bool:
+        """是否允许代理切换。"""
+        return False
+
+    def is_proxy_enabled(self) -> bool:
+        """当前是否启用代理。"""
+        return False