polaris-python-ai 0.0.1.dev2__py3-none-any.whl

polaris_ai/agentscope/config.py

@@ -0,0 +1,221 @@
+# Tencent is pleased to support the open source community by making polaris-python-ai available.
+#
+# Copyright (C) 2026 Tencent. All rights reserved.
+#
+# Licensed under the BSD 3-Clause License (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# https://opensource.org/licenses/BSD-3-Clause
+#
+# 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.
+
+"""Application-side configuration for Polaris AgentScope integrations."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+
+
+def _bool_env(value: str, *, default: bool) -> bool:
+    lowered = value.strip().lower()
+    if lowered in ("1", "true", "yes", "on"):
+        return True
+    if lowered in ("0", "false", "no", "off"):
+        return False
+    if not lowered:
+        return default
+    raise ValueError(f"Invalid boolean environment value: {value!r}")
+
+
+def _text_env(value: str) -> str:
+    return value.strip()
+
+
+def _list_env(value: str) -> tuple[str, ...]:
+    return tuple(item.strip() for item in value.split(",") if item.strip())
+
+
+def _int_env(value: str, name: str, default: int) -> int:
+    if not value:
+        return default
+    try:
+        return int(value)
+    except ValueError as error:
+        raise ValueError(f"{name} must be an integer") from error
+
+
+def _float_env(value: str, name: str, default: float) -> float:
+    if not value:
+        return default
+    try:
+        return float(value)
+    except ValueError as error:
+        raise ValueError(f"{name} must be a number") from error
+
+
+def _headers_env(value: str) -> tuple[tuple[str, str], ...]:
+    result = []
+    for item in _list_env(value):
+        name, separator, header_value = item.partition("=")
+        if not separator or not name.strip():
+            raise ValueError("POLARIS_AI_MCP_HEADERS items must be name=value")
+        result.append((name.strip(), header_value.strip()))
+    return tuple(result)
+
+
+@dataclass(frozen=True)
+class PolarisSkillConfig:
+    """Read-only Skill repository options."""
+
+    enabled: bool = True
+    addresses: tuple[str, ...] = ()
+    names: tuple[str, ...] = ()
+    version: str = ""
+    list_limit: int = 50
+    max_skills: int = 100
+    refresh_interval: float = 30.0
+    mounted_enabled: bool = False
+    mounted_service_name: str = ""
+    attach_to_agent: bool = True
+
+
+@dataclass(frozen=True)
+class PolarisA2ARegistryConfig:
+    enabled: bool = True
+    ttl: int = 5
+
+
+@dataclass(frozen=True)
+class PolarisA2ADiscoveryConfig:
+    enabled: bool = True
+
+
+@dataclass(frozen=True)
+class PolarisA2AConfig:
+    enabled: bool = True
+    registry: PolarisA2ARegistryConfig = field(default_factory=PolarisA2ARegistryConfig)
+    discovery: PolarisA2ADiscoveryConfig = field(default_factory=PolarisA2ADiscoveryConfig)
+
+
+@dataclass(frozen=True)
+class PolarisMCPConfig:
+    enabled: bool = False
+    protocol_version: str = ""
+    scheme: str = ""
+    timeout: float = 30.0
+    filter_contract: bool = True
+    headers: tuple[tuple[str, str], ...] = ()
+    caller_service: str = ""
+    labels: str = ""
+
+
+@dataclass(frozen=True)
+class PolarisAgentConfig:
+    """Code-first options for an application; not part of polaris.yaml."""
+
+    enabled: bool = True
+    namespace: str = "default"
+    addresses: tuple[str, ...] = ("127.0.0.1:8091",)
+    connector_token: str = ""
+    service_token: str = ""
+    skill: PolarisSkillConfig = field(default_factory=PolarisSkillConfig)
+    a2a: PolarisA2AConfig = field(default_factory=PolarisA2AConfig)
+    mcp: PolarisMCPConfig = field(default_factory=PolarisMCPConfig)
+
+    @classmethod
+    def from_env(
+        cls,
+        environ: dict[str, str] | None = None,
+        *,
+        agent_name: str = "",
+    ) -> "PolarisAgentConfig":
+        """Load application options with explicit code and SDK env fallbacks.
+
+        `POLARIS_AI_*` always takes precedence. Existing `POLARIS_*` variables are
+        read only as fallbacks so this helper can coexist with SDK examples.
+        """
+        env = os.environ if environ is None else environ
+
+        def value(name: str, fallback: str = "") -> str:
+            return env.get(name, env.get(fallback, "")).strip()
+
+        addresses = _list_env(
+            value("POLARIS_AI_ADDRESS", "POLARIS_SERVER_ADDRESS")
+            or value("POLARIS_AI_ADDRESSES", "POLARIS_SERVER_ADDRESSES")
+        ) or ("127.0.0.1:8091",)
+        skill_addresses = _list_env(
+            value("POLARIS_AI_SKILL_ADDRESS", "POLARIS_SKILL_SERVER_ADDRESS")
+        )
+
+        mounted_service = value("POLARIS_AI_MOUNTED_SKILL_SERVICE")
+        if not mounted_service:
+            mounted_service = value("POLARIS_AI_A2A_CARD_NAME")
+        if not mounted_service:
+            mounted_service = value("POLARIS_AI_AGENT_NAME") or agent_name.strip()
+
+        skill = PolarisSkillConfig(
+            enabled=_bool_env(env.get("POLARIS_AI_SKILL_ENABLED", ""), default=True),
+            addresses=skill_addresses,
+            names=_list_env(value("POLARIS_AI_SKILL_NAMES")),
+            version=value("POLARIS_AI_SKILL_VERSION"),
+            list_limit=_int_env(
+                value("POLARIS_AI_SKILL_LIST_LIMIT"), "POLARIS_AI_SKILL_LIST_LIMIT", 50
+            ),
+            max_skills=_int_env(
+                value("POLARIS_AI_SKILL_MAX_SKILLS"), "POLARIS_AI_SKILL_MAX_SKILLS", 100
+            ),
+            refresh_interval=_float_env(
+                value("POLARIS_AI_SKILL_LIST_REFRESH_INTERVAL_SECONDS"),
+                "POLARIS_AI_SKILL_LIST_REFRESH_INTERVAL_SECONDS",
+                30.0,
+            ),
+            mounted_enabled=_bool_env(
+                env.get("POLARIS_AI_MOUNTED_SKILL_ENABLED", ""), default=False
+            ),
+            mounted_service_name=mounted_service,
+            attach_to_agent=_bool_env(
+                env.get("POLARIS_AI_SKILL_ATTACH_TO_AGENT", ""), default=True
+            ),
+        )
+        a2a = PolarisA2AConfig(
+            enabled=_bool_env(env.get("POLARIS_AI_A2A_ENABLED", ""), default=True),
+            registry=PolarisA2ARegistryConfig(
+                enabled=_bool_env(
+                    env.get("POLARIS_AI_A2A_REGISTRY_ENABLED", ""), default=True
+                ),
+                ttl=_int_env(value("POLARIS_AI_A2A_TTL"), "POLARIS_AI_A2A_TTL", 5),
+            ),
+            discovery=PolarisA2ADiscoveryConfig(
+                enabled=_bool_env(
+                    env.get("POLARIS_AI_A2A_DISCOVERY_ENABLED", ""), default=True
+                ),
+            ),
+        )
+        headers = _headers_env(value("POLARIS_AI_MCP_HEADERS"))
+        mcp = PolarisMCPConfig(
+            enabled=_bool_env(env.get("POLARIS_AI_MCP_ENABLED", ""), default=False),
+            protocol_version=value("POLARIS_AI_MCP_PROTOCOL_VERSION"),
+            scheme=value("POLARIS_AI_MCP_SCHEME"),
+            timeout=_float_env(value("POLARIS_AI_MCP_TIMEOUT"), "POLARIS_AI_MCP_TIMEOUT", 30.0),
+            filter_contract=_bool_env(
+                env.get("POLARIS_AI_MCP_FILTER_CONTRACT", ""), default=True
+            ),
+            headers=headers,
+            caller_service=value("POLARIS_AI_MCP_CALLER_SERVICE"),
+            labels=value("POLARIS_AI_MCP_LABELS"),
+        )
+        return cls(
+            enabled=_bool_env(env.get("POLARIS_AI_ENABLED", ""), default=True),
+            namespace=value("POLARIS_AI_NAMESPACE", "default") or "default",
+            addresses=addresses,
+            connector_token=value("POLARIS_AI_CONNECTOR_TOKEN", "POLARIS_TOKEN"),
+            service_token=value("POLARIS_AI_SERVICE_TOKEN", "POLARIS_SERVICE_TOKEN"),
+            skill=skill,
+            a2a=a2a,
+            mcp=mcp,
+        )

polaris_ai/agentscope/context.py

@@ -0,0 +1,195 @@
+# Tencent is pleased to support the open source community by making polaris-python-ai available.
+#
+# Copyright (C) 2026 Tencent. All rights reserved.
+#
+# Licensed under the BSD 3-Clause License (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# https://opensource.org/licenses/BSD-3-Clause
+#
+# 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.
+
+"""Shared Polaris connection factory for AgentScope applications."""
+
+import asyncio
+from collections.abc import Iterable
+
+from polaris.api.config import init_context_by_config
+from polaris.api.consumer import ConsumerAPI
+from polaris.api.log import LogOptions
+from polaris.api.provider import ProviderAPI
+from polaris.api.skill import SkillAPI
+from polaris.pkg.config.api import Configuration
+
+from polaris_ai._async import await_completion
+
+DEFAULT_DISCOVERY_ADDRESS = "127.0.0.1:8091"
+SKILL_ADDRESS_PORT = 8094
+
+
+def _validate_address(address: str) -> str:
+    if not isinstance(address, str) or not address.strip():
+        raise ValueError("Polaris addresses must be nonempty host:port values")
+    address = address.strip()
+    host, separator, port_text = address.rpartition(":")
+    if not separator or not host:
+        raise ValueError(f"Invalid Polaris address {address!r}: a port is required")
+    try:
+        port = int(port_text)
+    except ValueError as error:
+        raise ValueError(f"Invalid Polaris address {address!r}: port must be an integer") from error
+    if not 0 < port < 65536:
+        raise ValueError(f"Invalid Polaris address {address!r}: port must be in [1, 65535]")
+    if host.startswith("[") and host.endswith("]"):
+        host = host[1:-1]
+        if not host:
+            raise ValueError(f"Invalid Polaris address {address!r}: empty IPv6 host")
+    elif host.count(":") > 0:
+        raise ValueError(f"Invalid Polaris address {address!r}: IPv6 hosts require brackets")
+    if not host.strip():
+        raise ValueError(f"Invalid Polaris address {address!r}: host is empty")
+    return f"[{host}]:{port}" if ":" in host else f"{host}:{port}"
+
+
+def derive_skill_addresses(addresses: Iterable[str]) -> list[str]:
+    """Map discovery endpoints to the standard Skill endpoint on each host."""
+    result = []
+    for address in addresses:
+        normalized = _validate_address(address)
+        host, _, _ = normalized.rpartition(":")
+        skill_address = f"{host}:{SKILL_ADDRESS_PORT}"
+        if skill_address not in result:
+            result.append(skill_address)
+    if not result:
+        raise ValueError("At least one discovery address is required")
+    return result
+
+
+class PolarisAgentContext:
+    """Expose shared Provider, Consumer and Skill APIs over one SDK context.
+
+    A supplied context is borrowed and is never modified or destroyed by this
+    factory. When no context is supplied, the factory owns the context it
+    creates, disables stat reporting, and derives Skill addresses from the
+    discovery addresses. Like Java's PolarisContextManager, it also disables
+    the provider lossless lifecycle for this owned context.
+    """
+
+    def __init__(
+        self,
+        namespace: str = "default",
+        *,
+        address: str | Iterable[str] = DEFAULT_DISCOVERY_ADDRESS,
+        connector_token: str = "",
+        skill_address: str | Iterable[str] = "",
+        log_options: LogOptions | None = None,
+        sdk_context=None,
+    ):
+        if sdk_context is not None:
+            if sdk_context.is_destroy():
+                raise ValueError("An active SDKContext is required")
+            self._owns_context = False
+            self._context = sdk_context
+        else:
+            if isinstance(address, str):
+                addresses = [address]
+            else:
+                addresses = list(address)
+            if not addresses:
+                raise ValueError("At least one discovery address is required")
+            addresses = [_validate_address(item) for item in addresses]
+            if isinstance(skill_address, str):
+                skill_addresses = [] if not skill_address else [skill_address]
+            else:
+                skill_addresses = list(skill_address)
+            skill_addresses = [_validate_address(item) for item in skill_addresses]
+            if not skill_addresses:
+                skill_addresses = derive_skill_addresses(addresses)
+
+            config = Configuration()
+            config.set_default()
+            config.get_global().get_server_connector().addresses = addresses
+            config.get_global().get_server_connector().token = connector_token
+            config.get_global().get_stat_reporter().enable = False
+            config.get_provider().get_lossless().enable = False
+            config.get_ai().get_skill().get_server_connector().addresses = skill_addresses
+            self._owns_context = True
+            self._context = None
+            try:
+                self._context = init_context_by_config(config, log_options=log_options)
+            except BaseException:
+                if self._context is not None:
+                    self._context.destroy()
+                raise
+
+        self.namespace = namespace.strip() or "default"
+        self._closed = False
+        try:
+            self.provider = ProviderAPI(self._context)
+            self.consumer = ConsumerAPI(self._context)
+            self.skill = SkillAPI(self._context)
+        except BaseException:
+            self.close()
+            raise
+
+    @classmethod
+    def from_address(
+        cls,
+        address: str | Iterable[str] = DEFAULT_DISCOVERY_ADDRESS,
+        namespace: str = "default",
+        *,
+        connector_token: str = "",
+        skill_address: str | Iterable[str] = "",
+        log_options: LogOptions | None = None,
+    ) -> "PolarisAgentContext":
+        return cls(
+            namespace,
+            address=address,
+            connector_token=connector_token,
+            skill_address=skill_address,
+            log_options=log_options,
+        )
+
+    @property
+    def context(self):
+        return self._context
+
+    @property
+    def owns_context(self) -> bool:
+        return self._owns_context
+
+    def _check_open(self):
+        if self._closed or self._context is None or self._context.is_destroy():
+            raise RuntimeError("PolarisAgentContext is closed")
+
+    def close(self):
+        """Close owned resources; borrowed contexts remain untouched."""
+        if self._closed:
+            return
+        self._closed = True
+        self.provider = None
+        self.consumer = None
+        self.skill = None
+        if self._owns_context and self._context is not None:
+            self._context.destroy()
+
+    async def async_close(self):
+        await await_completion(asyncio.to_thread(self.close))
+
+    def __enter__(self):
+        self._check_open()
+        return self
+
+    def __exit__(self, *_):
+        self.close()
+
+    async def __aenter__(self):
+        self._check_open()
+        return self
+
+    async def __aexit__(self, *_):
+        await self.async_close()