polyllm-core 0.1.0__tar.gz

polyllm_core-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PolyLLM 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.

polyllm_core-0.1.0/PKG-INFO

@@ -0,0 +1,43 @@
+Metadata-Version: 2.4
+Name: polyllm-core
+Version: 0.1.0
+Summary: PolyLLM Python core: unified protocol, registry, and parameter policy.
+Author: PolyLLM contributors
+License-Expression: MIT
+Project-URL: Homepage, https://polyllm.raingpt.top
+Project-URL: Repository, https://github.com/you-want/PolyLLM
+Project-URL: Issues, https://github.com/you-want/PolyLLM/issues
+Keywords: llm,polyllm,plugins
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# PolyLLM Core for Python
+
+PolyLLM Python 版核心包提供统一请求/响应协议、模型注册表、别名解析、参数策略和插件客户端。核心不内置任何厂商逻辑，所有供应商能力都由独立插件提供。
+
+```python
+from polyllm_core import create_llm
+from polyllm_openai import OpenAIPlugin
+
+llm = create_llm(
+    plugins=[OpenAIPlugin()],
+    providers={"openai": {"api_key": "..."}},
+)
+
+response = await llm.chat(
+    "openai:gpt-4o-mini",
+    messages=[{"role": "user", "content": "你好"}],
+)
+```

polyllm_core-0.1.0/README.md

@@ -0,0 +1,18 @@
+# PolyLLM Core for Python
+
+PolyLLM Python 版核心包提供统一请求/响应协议、模型注册表、别名解析、参数策略和插件客户端。核心不内置任何厂商逻辑，所有供应商能力都由独立插件提供。
+
+```python
+from polyllm_core import create_llm
+from polyllm_openai import OpenAIPlugin
+
+llm = create_llm(
+    plugins=[OpenAIPlugin()],
+    providers={"openai": {"api_key": "..."}},
+)
+
+response = await llm.chat(
+    "openai:gpt-4o-mini",
+    messages=[{"role": "user", "content": "你好"}],
+)
+```

polyllm_core-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "polyllm-core"
+version = "0.1.0"
+description = "PolyLLM Python core: unified protocol, registry, and parameter policy."
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = []
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "PolyLLM contributors" }]
+keywords = ["llm", "polyllm", "plugins"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.urls]
+Homepage = "https://polyllm.raingpt.top"
+Repository = "https://github.com/you-want/PolyLLM"
+Issues = "https://github.com/you-want/PolyLLM/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+polyllm_core = ["py.typed"]

polyllm_core-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

polyllm_core-0.1.0/src/polyllm_core/__init__.py

@@ -0,0 +1,18 @@
+from .config import resolve_provider_runtime
+from .client import PolyLLM, create_llm
+from .errors import AmbiguousModelError, PolyLLMError, UnknownModelError
+from .params import ParamValidationResult, validate_and_map_params
+from .registry import ModelRegistry
+from .types import *
+
+__all__ = [
+    "AmbiguousModelError",
+    "ModelRegistry",
+    "ParamValidationResult",
+    "PolyLLM",
+    "PolyLLMError",
+    "UnknownModelError",
+    "create_llm",
+    "resolve_provider_runtime",
+    "validate_and_map_params",
+]

polyllm_core-0.1.0/src/polyllm_core/client.py

@@ -0,0 +1,239 @@
+from __future__ import annotations
+
+from typing import Any, AsyncIterator, Mapping
+
+from .config import resolve_provider_runtime
+from .errors import PolyLLMError, UnknownModelError
+from .params import validate_and_map_params
+from .registry import ModelRegistry
+from .types import (
+    ChatContext,
+    ClientConfig,
+    LLMClient,
+    LLMPlugin,
+    ModelSpec,
+    ProviderConfig,
+    UnifiedContentPart,
+    UnifiedMessage,
+    UnifiedRequest,
+    UnifiedResponse,
+    UnifiedStreamChunk,
+    UnifiedTool,
+    UnifiedToolCall,
+)
+
+
+class PolyLLM(LLMClient):
+    def __init__(self, config: ClientConfig):
+        self._config = config
+        self._plugins: dict[str, LLMPlugin] = {}
+        self._registry = ModelRegistry()
+
+        for plugin in config.plugins:
+            if plugin.provider in self._plugins:
+                raise PolyLLMError(
+                    "DUPLICATE_PROVIDER",
+                    f"供应商插件重复注册: {plugin.provider}",
+                    {"provider": plugin.provider},
+                )
+            if plugin.provider not in config.providers:
+                raise PolyLLMError(
+                    "MISSING_PROVIDER_CONFIG",
+                    f"缺少供应商配置: {plugin.provider}",
+                    {"provider": plugin.provider},
+                )
+            self._plugins[plugin.provider] = plugin
+            for spec in plugin.models:
+                self._registry.register(spec)
+
+    async def chat(
+        self,
+        model: str,
+        request: Mapping[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> UnifiedResponse:
+        request = _merge_request(request, kwargs)
+        plugin, spec, prepared = self._prepare(model, request)
+        return await plugin.chat(
+            prepared,
+            self._config.providers[plugin.provider],
+            ChatContext(model=spec),
+        )
+
+    async def chat_stream(
+        self,
+        model: str,
+        request: Mapping[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> AsyncIterator[UnifiedStreamChunk]:
+        payload = _merge_request(request, kwargs)
+        payload["stream"] = True
+        plugin, spec, prepared = self._prepare(model, payload)
+        try:
+            stream = plugin.chat_stream(
+                prepared,
+                self._config.providers[plugin.provider],
+                ChatContext(model=spec),
+            )
+        except NotImplementedError as error:
+            raise PolyLLMError(
+                "UNSUPPORTED_PARAMETER",
+                f"插件 {plugin.provider} 不支持流式输出",
+                {"provider": plugin.provider},
+            ) from error
+
+        async for chunk in stream:
+            yield chunk
+
+    def list_models(self) -> list[ModelSpec]:
+        return self._registry.list()
+
+    def get_model_info(self, model: str) -> ModelSpec | None:
+        try:
+            return self._registry.resolve(model)
+        except UnknownModelError:
+            if not self._config.allow_unlisted_models:
+                return None
+            return self._create_dynamic_model(model)
+
+    def _prepare(
+        self,
+        model: str,
+        request: Mapping[str, Any],
+    ) -> tuple[LLMPlugin, ModelSpec, UnifiedRequest]:
+        try:
+            spec = self._registry.resolve(model)
+        except UnknownModelError as error:
+            if not self._config.allow_unlisted_models:
+                raise error
+            dynamic_spec = self._create_dynamic_model(model)
+            if dynamic_spec is None:
+                raise error
+            spec = dynamic_spec
+
+        plugin = self._plugins.get(spec.provider)
+        if plugin is None:
+            raise PolyLLMError(
+                "MISSING_PROVIDER_CONFIG",
+                f"模型 {model} 对应的插件未注册",
+                {"provider": spec.provider},
+            )
+
+        unified = normalize_unified_request({**dict(request), "model": spec.id})
+        validated = validate_and_map_params(spec, unified, self._config.param_policy)
+        return plugin, spec, validated.request
+
+    def _create_dynamic_model(self, model: str) -> ModelSpec | None:
+        separator = model.find(":")
+        if separator <= 0:
+            return None
+        provider = model[:separator]
+        model_id = model[separator + 1 :]
+        plugin = self._plugins.get(provider)
+        if plugin is None or not model_id:
+            return None
+        try:
+            return plugin.create_model_spec(model_id)
+        except NotImplementedError:
+            return None
+
+
+def create_llm(config: ClientConfig | Mapping[str, Any] | None = None, **kwargs: Any) -> PolyLLM:
+    if config is None:
+        config = dict(kwargs)
+    elif kwargs:
+        raise PolyLLMError("INVALID_CONFIG", "create_llm 不能同时传入 config 对象和关键字参数")
+    if isinstance(config, Mapping):
+        config = ClientConfig(**config)
+    if not isinstance(config, ClientConfig):
+        raise PolyLLMError("INVALID_CONFIG", "create_llm 配置必须是 ClientConfig 或 dict")
+    config = replace_provider_configs(config)
+    resolve_runtime_configs(config)
+    return PolyLLM(config)
+
+
+def _merge_request(
+    request: Mapping[str, Any] | None,
+    kwargs: dict[str, Any],
+) -> dict[str, Any]:
+    payload = dict(request or {})
+    payload.update(kwargs)
+    return payload
+
+
+def replace_provider_configs(config: ClientConfig) -> ClientConfig:
+    from dataclasses import replace
+
+    providers = {
+        provider: value if isinstance(value, ProviderConfig) else ProviderConfig(**value)
+        for provider, value in config.providers.items()
+    }
+    return replace(config, providers=providers)
+
+
+def normalize_unified_request(payload: dict[str, Any]) -> UnifiedRequest:
+    payload = dict(payload)
+    payload["messages"] = [normalize_message(message) for message in payload.get("messages", [])]
+    if payload.get("tools") is not None:
+        payload["tools"] = [normalize_tool(tool) for tool in payload["tools"]]
+    return UnifiedRequest(**payload)
+
+
+def normalize_message(value: Any) -> UnifiedMessage:
+    if isinstance(value, UnifiedMessage):
+        return value
+    if not isinstance(value, dict):
+        raise PolyLLMError("INVALID_CONFIG", "messages 必须是 UnifiedMessage 或 dict", {"message": value})
+    content = value.get("content", "")
+    if isinstance(content, list):
+        content = [normalize_content_part(part) for part in content]
+    tool_calls = value.get("tool_calls") or []
+    return UnifiedMessage(
+        role=value["role"],
+        content=content,
+        name=value.get("name"),
+        tool_call_id=value.get("tool_call_id"),
+        tool_calls=tuple(normalize_tool_call(call) for call in tool_calls),
+    )
+
+
+def normalize_content_part(value: Any) -> UnifiedContentPart:
+    if isinstance(value, UnifiedContentPart):
+        return value
+    if not isinstance(value, dict):
+        raise PolyLLMError("INVALID_CONFIG", "content parts 必须是 UnifiedContentPart 或 dict", {"part": value})
+    return UnifiedContentPart(
+        type=value["type"],
+        text=value.get("text"),
+        image_url=value.get("image_url") or value.get("imageUrl"),
+    )
+
+
+def normalize_tool(value: Any) -> UnifiedTool:
+    if isinstance(value, UnifiedTool):
+        return value
+    if not isinstance(value, dict):
+        raise PolyLLMError("INVALID_CONFIG", "tools 必须是 UnifiedTool 或 dict", {"tool": value})
+    return UnifiedTool(type="function", function=value["function"])
+
+
+def normalize_tool_call(value: Any) -> UnifiedToolCall:
+    if isinstance(value, UnifiedToolCall):
+        return value
+    if not isinstance(value, dict):
+        raise PolyLLMError("INVALID_CONFIG", "tool_calls 必须是 UnifiedToolCall 或 dict", {"toolCall": value})
+    return UnifiedToolCall(id=value["id"], type="function", function=value["function"])
+
+
+def resolve_runtime_configs(config: ClientConfig) -> dict[str, ProviderConfig]:
+    resolved: dict[str, ProviderConfig] = {}
+    for provider, provider_config in config.providers.items():
+        runtime = resolve_provider_runtime(provider, provider_config)
+        resolved[provider] = ProviderConfig(
+            api_key=runtime.api_key,
+            api_key_env=None,
+            base_url=provider_config.base_url,
+            headers=provider_config.headers,
+            extra=provider_config.extra,
+        )
+    return resolved

polyllm_core-0.1.0/src/polyllm_core/config.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+import os
+from typing import Mapping
+
+from .errors import PolyLLMError
+from .types import ProviderConfig, ProviderRuntime
+
+
+def resolve_provider_runtime(
+    provider: str,
+    config: ProviderConfig,
+    environment: Mapping[str, str] | None = None,
+) -> ProviderRuntime:
+    environment = os.environ if environment is None else environment
+    api_key = config.api_key or (environment.get(config.api_key_env) if config.api_key_env else None)
+    if not api_key or not api_key.strip():
+        source = (
+            "providers[].api_key"
+            if config.api_key
+            else f"环境变量 {config.api_key_env}"
+            if config.api_key_env
+            else f"{provider} 配置"
+        )
+        raise PolyLLMError(
+            "MISSING_API_KEY",
+            f"PolyLLM 无法解析 {provider} 的 API key，来源: {source}",
+            {"provider": provider, "source": source},
+        )
+
+    return ProviderRuntime(
+        api_key=api_key.strip(),
+        base_url=config.base_url or "",
+        headers=dict(config.headers),
+        extra=dict(config.extra),
+    )

polyllm_core-0.1.0/src/polyllm_core/errors.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from typing import Any, Literal
+
+ErrorCode = Literal[
+    "AMBIGUOUS_MODEL",
+    "INVALID_CONFIG",
+    "DUPLICATE_MODEL",
+    "DUPLICATE_PROVIDER",
+    "MISSING_PROVIDER_CONFIG",
+    "MISSING_API_KEY",
+    "PROVIDER_ERROR",
+    "UNKNOWN_MODEL",
+    "UNSUPPORTED_PARAMETER",
+]
+
+
+class PolyLLMError(Exception):
+    def __init__(self, code: ErrorCode, message: str, details: dict[str, Any] | None = None):
+        super().__init__(message)
+        self.code = code
+        self.details = details or {}
+
+
+class UnknownModelError(PolyLLMError):
+    def __init__(self, model: str, available_models: list[str]):
+        super().__init__(
+            "UNKNOWN_MODEL",
+            f"未知模型: {model}。可用模型: {', '.join(available_models)}",
+            {"model": model, "availableModels": available_models},
+        )
+
+
+class AmbiguousModelError(PolyLLMError):
+    def __init__(self, model: str, candidates: list[str]):
+        super().__init__(
+            "AMBIGUOUS_MODEL",
+            f"模型标识有歧义: {model}。请使用 provider:model，候选: {', '.join(candidates)}",
+            {"model": model, "candidates": candidates},
+        )

polyllm_core-0.1.0/src/polyllm_core/params.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+from dataclasses import replace
+from typing import Any, Mapping
+
+from .errors import PolyLLMError
+from .types import ModelSpec, ParamPolicy, UnifiedMessage, UnifiedRequest
+
+
+class ParamValidationResult:
+    def __init__(self, request: UnifiedRequest, warnings: list[str]):
+        self.request = request
+        self.warnings = warnings
+
+
+def validate_and_map_params(
+    model: ModelSpec,
+    request: UnifiedRequest,
+    policy: ParamPolicy = "strict",
+) -> ParamValidationResult:
+    warnings: list[str] = []
+
+    def unsupported(name: str, reason: str) -> bool:
+        if policy == "strict":
+            raise PolyLLMError(
+                "UNSUPPORTED_PARAMETER",
+                f"参数不被目标模型支持: {name}。{reason}",
+                {"parameter": name, "reason": reason, "policy": policy},
+            )
+        warnings.append(f"{name} 已忽略: {reason}")
+        return False
+
+    def clamp_number(name: str, value: float, minimum: float, maximum: float) -> float:
+        if minimum <= value <= maximum:
+            return value
+        bounded = min(maximum, max(minimum, value))
+        if policy == "auto":
+            warnings.append(f"{name}={value} 超出范围 [{minimum}, {maximum}]，已调整为 {bounded}")
+            return bounded
+        if policy == "lenient":
+            warnings.append(f"{name}={value} 超出范围 [{minimum}, {maximum}]，已忽略")
+            return minimum
+        raise PolyLLMError(
+            "UNSUPPORTED_PARAMETER",
+            f"{name}={value} 超出范围 [{minimum}, {maximum}]",
+            {"parameter": name, "value": value, "min": minimum, "max": maximum},
+        )
+
+    stream = request.stream
+    if stream and not model.capabilities.streaming:
+        stream = unsupported("stream", "该模型不支持流式输出")
+
+    json_mode = request.json_mode
+    if json_mode and not model.capabilities.json_mode:
+        json_mode = unsupported("jsonMode", "该模型不支持 JSON mode")
+
+    tools = list(request.tools)
+    if tools and not model.capabilities.function_calling:
+        tools = [] if unsupported("tools", "该模型不支持 function calling") else tools
+
+    messages = list(request.messages)
+    if not model.capabilities.system_prompt and any(message.role == "system" for message in messages):
+        keep_system = unsupported("messages[role=system]", "该模型不支持 system prompt")
+        messages = [message for message in messages if keep_system or message.role != "system"]
+
+    if not model.capabilities.vision:
+        has_image = any(
+            not isinstance(message.content, str) and any(part.type == "image_url" for part in message.content)
+            for message in messages
+        )
+        if has_image:
+            keep_images = unsupported("messages[content=image_url]", "该模型不支持视觉输入")
+            messages = [
+                message
+                if isinstance(message.content, str) or keep_images
+                else replace(message, content=[part for part in message.content if part.type != "image_url"])
+                for message in messages
+            ]
+
+    temperature = request.temperature
+    temperature_range = model.params.get("temperature")
+    if temperature is not None and temperature_range:
+        temperature = clamp_number("temperature", temperature, temperature_range.min, temperature_range.max)
+
+    top_p = request.top_p
+    top_p_range = model.params.get("top_p")
+    if top_p is not None and top_p_range:
+        top_p = clamp_number("topP", top_p, top_p_range.min, top_p_range.max)
+
+    max_tokens = request.max_tokens
+    if max_tokens is not None:
+        max_tokens_range = model.params.get("max_tokens")
+        maximum = max_tokens_range.max if max_tokens_range else model.max_output
+        max_tokens = int(clamp_number("maxTokens", max_tokens, 1, maximum))
+
+    prepared = replace(
+        request,
+        model=model.id,
+        messages=messages,
+        stream=stream,
+        json_mode=json_mode,
+        tools=tools,
+        temperature=temperature,
+        top_p=top_p,
+        max_tokens=max_tokens,
+    )
+    return ParamValidationResult(prepared, warnings)

polyllm_core-0.1.0/src/polyllm_core/registry.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+import re
+from typing import List
+
+from .errors import AmbiguousModelError, PolyLLMError, UnknownModelError
+from .types import ModelSpec
+
+
+def _normalize(value: str) -> str:
+    return re.sub(r"[-\s_]", "", value.strip().lower())
+
+
+class ModelRegistry:
+    def __init__(self) -> None:
+        self._models: dict[str, ModelSpec] = {}
+        self._snapshots: dict[str, ModelSpec] = {}
+        self._aliases: dict[str, ModelSpec] = {}
+
+    def register(self, spec: ModelSpec) -> None:
+        if not spec.id or not spec.provider:
+            raise PolyLLMError("DUPLICATE_MODEL", "ModelSpec.id 和 ModelSpec.provider 不能为空", {"spec": spec})
+
+        key = f"{spec.provider}:{spec.id}"
+        if key in self._models:
+            raise PolyLLMError("DUPLICATE_MODEL", f"模型重复注册: {key}", {"model": key})
+        if spec.snapshot:
+            snapshot_key = f"{spec.provider}:{spec.snapshot}"
+            if snapshot_key in self._snapshots:
+                raise PolyLLMError("DUPLICATE_MODEL", f"模型快照重复注册: {snapshot_key}", {"model": snapshot_key})
+            self._snapshots[snapshot_key] = spec
+
+        self._models[key] = spec
+        for alias in spec.aliases:
+            alias_key = f"{spec.provider}:{alias}"
+            if alias_key in self._aliases:
+                raise PolyLLMError("DUPLICATE_MODEL", f"模型别名重复注册: {alias_key}", {"alias": alias_key})
+            self._aliases[alias_key] = spec
+
+    def resolve(self, model: str) -> ModelSpec:
+        trimmed = model.strip()
+        separator = trimmed.find(":")
+        explicit_provider = separator > 0 and trimmed[:separator]
+        model_name = trimmed[separator + 1 :] if separator > 0 else trimmed
+        if not model_name:
+            raise UnknownModelError(model, self.list_ids())
+
+        if explicit_provider:
+            provider = explicit_provider.lower()
+            candidates = [
+                self._snapshots.get(f"{provider}:{model_name}"),
+                self._models.get(f"{provider}:{model_name}"),
+                self._aliases.get(f"{provider}:{model_name}"),
+            ]
+            exact = next((item for item in candidates if item is not None), None)
+            if exact:
+                return exact
+
+            normalized = self._find_normalized(f"{provider}:{model_name}")
+            if len(normalized) == 1:
+                return normalized[0]
+            if len(normalized) > 1:
+                raise AmbiguousModelError(model, [self._model_id(item) for item in normalized])
+            raise UnknownModelError(model, self.list_ids())
+
+        for predicate in (
+            lambda spec: spec.snapshot == model_name,
+            lambda spec: spec.id == model_name,
+            lambda spec: model_name in spec.aliases,
+        ):
+            matches = [spec for spec in self._models.values() if predicate(spec)]
+            if len(matches) == 1:
+                return matches[0]
+            if len(matches) > 1:
+                raise AmbiguousModelError(model, [self._model_id(spec) for spec in matches])
+
+        normalized = self._find_normalized(model_name)
+        if len(normalized) == 1:
+            return normalized[0]
+        if len(normalized) > 1:
+            raise AmbiguousModelError(model, [self._model_id(spec) for spec in normalized])
+        raise UnknownModelError(model, self.list_ids())
+
+    def list(self) -> List[ModelSpec]:
+        return list(self._models.values())
+
+    def list_ids(self) -> List[str]:
+        return [self._model_id(spec) for spec in self._models.values()]
+
+    def _find_normalized(self, value: str) -> List[ModelSpec]:
+        normalized = _normalize(value)
+        return [spec for spec in self._models.values() if _normalize(f"{spec.provider}:{spec.id}") == normalized]
+
+    @staticmethod
+    def _model_id(spec: ModelSpec) -> str:
+        return f"{spec.provider}:{spec.id}"

polyllm_core-0.1.0/src/polyllm_core/types.py

@@ -0,0 +1,212 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any, AsyncIterator, Literal, Mapping, Optional
+
+JsonRecord = dict[str, Any]
+Role = Literal["system", "user", "assistant", "tool"]
+FinishReason = Literal["stop", "length", "tool_calls", "content_filter", "other"]
+ParamPolicy = Literal["strict", "lenient", "auto"]
+
+
+@dataclass(frozen=True)
+class UnifiedContentPart:
+    type: Literal["text", "image_url"]
+    text: Optional[str] = None
+    image_url: Optional[dict[str, Any]] = None
+
+
+@dataclass(frozen=True)
+class UnifiedToolCall:
+    id: str
+    type: Literal["function"]
+    function: dict[str, str]
+
+
+@dataclass(frozen=True)
+class UnifiedMessage:
+    role: Role
+    content: str | tuple[UnifiedContentPart, ...] | list[UnifiedContentPart]
+    name: Optional[str] = None
+    tool_call_id: Optional[str] = None
+    tool_calls: tuple[UnifiedToolCall, ...] = ()
+
+
+@dataclass(frozen=True)
+class UnifiedTool:
+    type: Literal["function"]
+    function: dict[str, Any]
+
+
+@dataclass(frozen=True)
+class UnifiedRequest:
+    model: str
+    messages: tuple[UnifiedMessage, ...] | list[UnifiedMessage]
+    temperature: Optional[float] = None
+    max_tokens: Optional[int] = None
+    top_p: Optional[float] = None
+    stream: bool = False
+    json_mode: bool = False
+    tools: tuple[UnifiedTool, ...] | list[UnifiedTool] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class UnifiedUsage:
+    prompt_tokens: int
+    completion_tokens: int
+    total_tokens: int
+
+
+@dataclass(frozen=True)
+class UnifiedChoice:
+    index: int
+    message: UnifiedMessage
+    finish_reason: FinishReason
+
+
+@dataclass(frozen=True)
+class UnifiedResponse:
+    id: str
+    model: str
+    choices: tuple[UnifiedChoice, ...] | list[UnifiedChoice]
+    usage: UnifiedUsage
+    provider_metadata: Optional[JsonRecord] = None
+
+
+@dataclass(frozen=True)
+class UnifiedStreamChunk:
+    id: str
+    model: str
+    delta: dict[str, Any]
+    usage: Optional[UnifiedUsage] = None
+    finish_reason: Optional[FinishReason] = None
+    provider_metadata: Optional[JsonRecord] = None
+
+
+@dataclass(frozen=True)
+class NumericParamRange:
+    min: float
+    max: float
+    default: float
+    field: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class ModelCapabilities:
+    streaming: bool
+    vision: bool
+    function_calling: bool
+    json_mode: bool
+    system_prompt: bool
+
+
+@dataclass(frozen=True)
+class ModelSpec:
+    id: str
+    provider: str
+    capabilities: ModelCapabilities
+    context_window: int
+    max_output: int
+    aliases: tuple[str, ...] = ()
+    version: Optional[str] = None
+    snapshot: Optional[str] = None
+    is_latest: bool = False
+    deprecated: bool = False
+    params: Mapping[str, NumericParamRange] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class ProviderConfig:
+    api_key: Optional[str] = None
+    api_key_env: Optional[str] = None
+    base_url: Optional[str] = None
+    headers: Mapping[str, str] = field(default_factory=dict)
+    extra: JsonRecord = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class ProviderRuntime:
+    api_key: str
+    base_url: str
+    headers: dict[str, str]
+    extra: JsonRecord
+
+
+@dataclass(frozen=True)
+class ProviderModelInfo:
+    id: str
+    display_name: Optional[str] = None
+    owned_by: Optional[str] = None
+    created_at: Optional[str | int] = None
+    metadata: Optional[JsonRecord] = None
+
+
+@dataclass(frozen=True)
+class ChatContext:
+    model: ModelSpec
+    timeout_ms: Optional[int] = None
+
+
+class LLMPlugin(ABC):
+    provider: str
+    models: tuple[ModelSpec, ...]
+
+    @abstractmethod
+    async def chat(
+        self,
+        request: UnifiedRequest,
+        config: ProviderConfig,
+        context: ChatContext,
+    ) -> UnifiedResponse:
+        raise NotImplementedError
+
+    def chat_stream(
+        self,
+        request: UnifiedRequest,
+        config: ProviderConfig,
+        context: ChatContext,
+    ) -> AsyncIterator[UnifiedStreamChunk]:
+        raise NotImplementedError
+
+    async def list_models(self, config: ProviderConfig) -> list[ProviderModelInfo]:
+        raise NotImplementedError
+
+    def create_model_spec(self, model_id: str) -> ModelSpec:
+        raise NotImplementedError
+
+
+@dataclass(frozen=True)
+class ClientConfig:
+    plugins: list[LLMPlugin]
+    providers: dict[str, ProviderConfig]
+    param_policy: ParamPolicy = "strict"
+    allow_unlisted_models: bool = False
+
+
+class LLMClient(ABC):
+    @abstractmethod
+    async def chat(
+        self,
+        model: str,
+        request: Mapping[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> UnifiedResponse:
+        raise NotImplementedError
+
+    @abstractmethod
+    def chat_stream(
+        self,
+        model: str,
+        request: Mapping[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> AsyncIterator[UnifiedStreamChunk]:
+        raise NotImplementedError
+
+    @abstractmethod
+    def list_models(self) -> list[ModelSpec]:
+        raise NotImplementedError
+
+    @abstractmethod
+    def get_model_info(self, model: str) -> Optional[ModelSpec]:
+        raise NotImplementedError

polyllm_core-0.1.0/src/polyllm_core.egg-info/PKG-INFO

@@ -0,0 +1,43 @@
+Metadata-Version: 2.4
+Name: polyllm-core
+Version: 0.1.0
+Summary: PolyLLM Python core: unified protocol, registry, and parameter policy.
+Author: PolyLLM contributors
+License-Expression: MIT
+Project-URL: Homepage, https://polyllm.raingpt.top
+Project-URL: Repository, https://github.com/you-want/PolyLLM
+Project-URL: Issues, https://github.com/you-want/PolyLLM/issues
+Keywords: llm,polyllm,plugins
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# PolyLLM Core for Python
+
+PolyLLM Python 版核心包提供统一请求/响应协议、模型注册表、别名解析、参数策略和插件客户端。核心不内置任何厂商逻辑，所有供应商能力都由独立插件提供。
+
+```python
+from polyllm_core import create_llm
+from polyllm_openai import OpenAIPlugin
+
+llm = create_llm(
+    plugins=[OpenAIPlugin()],
+    providers={"openai": {"api_key": "..."}},
+)
+
+response = await llm.chat(
+    "openai:gpt-4o-mini",
+    messages=[{"role": "user", "content": "你好"}],
+)
+```

polyllm_core-0.1.0/src/polyllm_core.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+pyproject.toml
+src/polyllm_core/__init__.py
+src/polyllm_core/client.py
+src/polyllm_core/config.py
+src/polyllm_core/errors.py
+src/polyllm_core/params.py
+src/polyllm_core/py.typed
+src/polyllm_core/registry.py
+src/polyllm_core/types.py
+src/polyllm_core.egg-info/PKG-INFO
+src/polyllm_core.egg-info/SOURCES.txt
+src/polyllm_core.egg-info/dependency_links.txt
+src/polyllm_core.egg-info/top_level.txt
+tests/test_core.py

polyllm_core-0.1.0/src/polyllm_core.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

polyllm_core-0.1.0/src/polyllm_core.egg-info/top_level.txt

@@ -0,0 +1 @@
+polyllm_core

polyllm_core-0.1.0/tests/test_core.py

@@ -0,0 +1,158 @@
+import asyncio
+import unittest
+
+from polyllm_core import (
+    AmbiguousModelError,
+    ModelRegistry,
+    PolyLLMError,
+    UnknownModelError,
+    create_llm,
+    validate_and_map_params,
+)
+from polyllm_core.types import (
+    ChatContext,
+    LLMPlugin,
+    ModelCapabilities,
+    ModelSpec,
+    NumericParamRange,
+    ProviderConfig,
+    UnifiedContentPart,
+    UnifiedMessage,
+    UnifiedRequest,
+    UnifiedResponse,
+    UnifiedUsage,
+)
+
+
+def make_spec(provider="test") -> ModelSpec:
+    return ModelSpec(
+        id="test-model",
+        provider=provider,
+        aliases=("test", "mini"),
+        snapshot="test-model-v1",
+        capabilities=ModelCapabilities(
+            streaming=True,
+            vision=False,
+            function_calling=True,
+            json_mode=True,
+            system_prompt=True,
+        ),
+        params={
+            "temperature": NumericParamRange(0, 1, 1),
+            "max_tokens": NumericParamRange(16, 128, 64, field="max_tokens"),
+        },
+        context_window=4096,
+        max_output=128,
+    )
+
+
+class TestPlugin(LLMPlugin):
+    provider = "test"
+    models = (make_spec(),)
+    received: UnifiedRequest | None = None
+
+    async def chat(self, request, config, context):
+        self.received = request
+        return UnifiedResponse(
+            id="test-response",
+            model=request.model,
+            choices=[],
+            usage=UnifiedUsage(1, 1, 2),
+        )
+
+    def create_model_spec(self, model_id):
+        return ModelSpec(
+            id=model_id,
+            provider="test",
+            capabilities=self.models[0].capabilities,
+            context_window=self.models[0].context_window,
+            max_output=self.models[0].max_output,
+        )
+
+
+class CoreTests(unittest.TestCase):
+    def test_registry_resolution(self):
+        registry = ModelRegistry()
+        registry.register(make_spec())
+        self.assertEqual(registry.resolve("test:test-model").id, "test-model")
+        self.assertEqual(registry.resolve("test:test").id, "test-model")
+        self.assertEqual(registry.resolve("test:test-model-v1").id, "test-model")
+        self.assertEqual(registry.resolve("test:testmodel").id, "test-model")
+
+    def test_registry_errors(self):
+        registry = ModelRegistry()
+        registry.register(make_spec())
+        registry.register(make_spec("other"))
+        with self.assertRaises(UnknownModelError):
+            registry.resolve("test:missing")
+        with self.assertRaises(AmbiguousModelError):
+            registry.resolve("test-model")
+
+    def test_auto_policy_clamps(self):
+        result = validate_and_map_params(
+            make_spec(),
+            UnifiedRequest(
+                model="test-model",
+                messages=[UnifiedMessage(role="user", content="hi")],
+                temperature=2,
+                max_tokens=999,
+            ),
+            "auto",
+        )
+        self.assertEqual(result.request.temperature, 1)
+        self.assertEqual(result.request.max_tokens, 128)
+        self.assertEqual(len(result.warnings), 2)
+
+    def test_strict_policy_rejects_vision(self):
+        with self.assertRaises(PolyLLMError):
+            validate_and_map_params(
+                make_spec(),
+                UnifiedRequest(
+                    model="test-model",
+                    messages=[
+                        UnifiedMessage(
+                            role="user",
+                            content=[
+                                UnifiedContentPart(
+                                    type="image_url",
+                                    image_url={"url": "https://example.com/a.png"},
+                                )
+                            ],
+                        )
+                    ],
+                ),
+                "strict",
+            )
+
+    def test_client_routes_chat(self):
+        plugin = TestPlugin()
+        client = create_llm(
+            plugins=[plugin],
+            providers={"test": ProviderConfig(api_key="k")},
+        )
+        response = asyncio.run(client.chat("test:mini", {"messages": [UnifiedMessage(role="user", content="hi")]}))
+        self.assertEqual(response.model, "test-model")
+        self.assertEqual(plugin.received.messages[0].content, "hi")
+
+    def test_client_accepts_pythonic_dicts(self):
+        client = create_llm(
+            plugins=[TestPlugin()],
+            providers={"test": {"api_key": "k"}},
+        )
+        response = asyncio.run(client.chat("test:mini", messages=[{"role": "user", "content": "hi"}]))
+        self.assertEqual(response.model, "test-model")
+
+    def test_unlisted_model_resolution(self):
+        client = create_llm(
+            plugins=[TestPlugin()],
+            providers={"test": ProviderConfig(api_key="k")},
+            allow_unlisted_models=True,
+        )
+        response = asyncio.run(
+            client.chat("test:remote-only", {"messages": [UnifiedMessage(role="user", content="hi")]})
+        )
+        self.assertEqual(response.model, "remote-only")
+
+
+if __name__ == "__main__":
+    unittest.main()