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

polaris_ai/a2a/server.py

@@ -0,0 +1,92 @@
+# 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.
+
+"""Lifecycle glue between an already started A2A server and Polaris."""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+
+from polaris_ai._async import await_completion
+
+
+class PolarisA2AServerRegistration:
+    """Register an A2A endpoint after its server becomes ready.
+
+    ``server_ready`` accepts an ``asyncio.Event``, an awaitable, or a callable
+    returning an awaitable. Closing the registration closes the registrar, so
+    normal exceptions and cancellation unwind through the context manager and
+    trigger deregistration.
+    """
+
+    def __init__(self, registrar, agent_card, transports, *, server_ready=None):
+        if registrar is None:
+            raise ValueError("A PolarisA2ARegistrar is required")
+        if agent_card is None:
+            raise ValueError("An AgentCard is required")
+        self._registrar = registrar
+        self._agent_card = agent_card
+        self._transports = tuple(transports)
+        self._server_ready = server_ready
+        self._lock = asyncio.Lock()
+        self._registered = False
+        self._closed = False
+
+    @property
+    def registered(self) -> bool:
+        return self._registered
+
+    async def _wait_for_server(self):
+        ready = self._server_ready
+        if ready is None:
+            return
+        if isinstance(ready, asyncio.Event):
+            await ready.wait()
+            return
+        if inspect.isawaitable(ready):
+            await ready
+            return
+        if callable(ready):
+            result = ready()
+            if inspect.isawaitable(result):
+                await result
+            return
+        raise TypeError("server_ready must be an asyncio.Event, awaitable, or callable")
+
+    async def async_start(self):
+        async with self._lock:
+            if self._closed:
+                raise RuntimeError("Polaris A2A server registration is closed")
+            if self._registered:
+                return self
+            await self._wait_for_server()
+            await self._registrar.async_register(self._agent_card, self._transports)
+            self._registered = True
+            return self
+
+    async def async_close(self):
+        async with self._lock:
+            self._closed = True
+            await await_completion(self._registrar.async_close())
+            if not self._registrar.registered:
+                self._registered = False
+
+    async def __aenter__(self):
+        return await self.async_start()
+
+    async def __aexit__(self, *_):
+        await self.async_close()

polaris_ai/agentscope/__init__.py

@@ -0,0 +1,76 @@
+# 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.
+
+"""AgentScope integrations; optional dependencies load only when requested."""
+
+from importlib import import_module
+
+from polaris_ai._version import __version__
+
+__all__ = [
+    "PolarisSkillLoader",
+    "PolarisAgentContext",
+    "PolarisA2AAgent",
+    "PolarisAgentConfig",
+    "PolarisAgentRuntime",
+    "PolarisDynamicSkillMiddleware",
+    "PolarisMCPResolver",
+    "PolarisMCPClientPool",
+    "PolarisAgentCardTemplate",
+    "build_agent_card",
+    "PolarisA2ARegistrar",
+    "PolarisA2AResolver",
+    "PolarisA2AServerRegistration",
+    "A2ATransport",
+    "AgentCardNotFoundError",
+    "RegisteredInstance",
+    "PolarisSkillNotFoundError",
+    "PolarisSkillRepositoryInfo",
+    "PolarisAILogOptions",
+    "PolarisAILogger",
+    "__version__",
+]
+
+
+def __getattr__(name: str):
+    if name not in __all__:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    if name == "PolarisSkillLoader":
+        module = ".skill"
+    elif name == "PolarisAgentContext":
+        module = ".context"
+    elif name == "PolarisA2AAgent":
+        module = ".a2a"
+    elif name in ("PolarisAgentConfig",):
+        module = ".config"
+    elif name in ("PolarisAgentRuntime",):
+        module = ".runtime"
+    elif name in ("PolarisDynamicSkillMiddleware",):
+        module = ".middleware"
+    elif name in ("PolarisMCPResolver", "PolarisMCPClientPool"):
+        module = ".mcp"
+    elif name in ("PolarisAgentCardTemplate", "build_agent_card"):
+        module = ".cards"
+    elif name == "PolarisA2AServerRegistration":
+        module = "polaris_ai.a2a.server"
+    elif name in ("PolarisSkillNotFoundError", "PolarisSkillRepositoryInfo"):
+        module = ".skill"
+    elif name in ("PolarisAILogOptions", "PolarisAILogger"):
+        module = "polaris_ai.log"
+    else:
+        module = "polaris_ai.a2a"
+    value = getattr(import_module(module, __name__), name)
+    globals()[name] = value
+    return value

polaris_ai/agentscope/a2a.py

@@ -0,0 +1,276 @@
+# 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.
+
+"""A resilient wrapper around AgentScope's native A2A client."""
+
+import asyncio
+import time
+
+from polaris.pkg.model.service import InstanceType
+
+from polaris_ai._async import await_completion
+from polaris_ai.log import get_ai_logger
+from polaris_ai.metrics import PolarisCallReporter
+
+
+class PolarisA2AAgent:
+    """Resolve once, then rebuild the native A2A client only when needed.
+
+    A card is resolved before the first call. Later calls reuse the native
+    AgentScope ``A2AAgent`` unless the caller invalidates it or a network
+    failure occurs before any response event has been delivered. Business
+    errors are propagated without switching instances. The wrapper owns the
+    supplied resolver and closes it together with the current client.
+    """
+
+    def __init__(self, resolver, agent_name: str, *, agent_factory=None, reporter=None,
+                 caller_service: str = "", labels: str = "", logger=None):
+        if resolver is None:
+            raise ValueError("A PolarisA2AResolver is required")
+        if not isinstance(agent_name, str) or not agent_name.strip():
+            raise ValueError("agent_name is required")
+        if agent_factory is None:
+            from agentscope.agent import A2AAgent
+
+            agent_factory = A2AAgent
+        self._resolver = resolver
+        self._agent_name = agent_name.strip()
+        self._agent_factory = agent_factory
+        self._reporter = reporter
+        self.logger = logger if logger is not None else get_ai_logger("a2a")
+        if self._reporter is None and getattr(resolver, "consumer", None) is not None:
+            self._reporter = PolarisCallReporter(
+                resolver.consumer,
+                getattr(resolver, "namespace", "default"),
+                caller_service=caller_service,
+                labels=labels,
+            )
+        self._agent = None
+        self._card = None
+        self._lock = asyncio.Lock()
+        self._closed = False
+
+    @property
+    def name(self) -> str:
+        return self._agent_name
+
+    @property
+    def card(self):
+        return self._card
+
+    @property
+    def agent(self):
+        return self._agent
+
+    def _check_open(self):
+        if self._closed:
+            raise RuntimeError("Polaris A2A agent is closed")
+
+    @staticmethod
+    def _is_timeout(error: BaseException) -> bool:
+        if isinstance(error, (asyncio.TimeoutError, TimeoutError)):
+            return True
+        try:
+            from a2a.client.errors import A2AClientTimeoutError
+        except ImportError:
+            return False
+        return isinstance(error, A2AClientTimeoutError)
+
+    @staticmethod
+    def _is_retryable(error: BaseException) -> bool:
+        if PolarisA2AAgent._is_timeout(error) or isinstance(error, OSError):
+            return True
+        try:
+            from a2a.client.errors import A2AClientTimeoutError
+        except ImportError:
+            return False
+        if isinstance(error, A2AClientTimeoutError):
+            return True
+        try:
+            from a2a.client.errors import A2AClientError
+        except ImportError:
+            return False
+        return isinstance(error, A2AClientError) and str(error).startswith("Network communication error")
+
+    async def _ensure_agent(self):
+        self._check_open()
+        if self._agent is None:
+            self.logger.debug("Resolving A2A agent client: name=%s", self._agent_name)
+            self._card = await self._resolver.async_resolve(self._agent_name)
+            self._agent = self._agent_factory(self._card)
+            await self._agent.__aenter__()
+            self.logger.debug("Created A2A agent client: name=%s", self._agent_name)
+        return self._agent
+
+    async def _close_agent(self):
+        agent = self._agent
+        if agent is None:
+            return
+        self.logger.debug("Closing A2A agent client: name=%s", self._agent_name)
+        await await_completion(agent.aclose())
+        if self._agent is agent:
+            self._agent = None
+            self._card = None
+
+    async def _replace_agent(self):
+        self.logger.warning_throttled(
+            ("rebuild", self._agent_name),
+            "Rebuilding A2A agent client after network failure: name=%s",
+            self._agent_name,
+        )
+        await self._close_agent()
+        await self._ensure_agent()
+
+    async def reply(self, inputs):
+        async with self._lock:
+            self.logger.debug("Sending non-streaming A2A request: name=%s", self._agent_name)
+            agent = await self._ensure_agent()
+            started_at = time.monotonic()
+            final_message = None
+            saw_remote_event = False
+            try:
+                async for event in agent.reply_stream(inputs, yield_final_msg=True):
+                    if not _is_local_reply_start_event(event):
+                        saw_remote_event = True
+                    if isinstance(event, _message_type()):
+                        final_message = event
+                if final_message is None:
+                    raise RuntimeError("A2A agent did not produce a final message")
+                await self._report_call(started_at, success=True)
+                self.logger.debug("Completed non-streaming A2A request: name=%s",
+                                  self._agent_name)
+                return final_message
+            except BaseException as error:
+                await self._report_call(
+                    started_at, success=False,
+                    timeout=self._is_timeout(error),
+                )
+                if saw_remote_event or not self._is_retryable(error):
+                    self.logger.debug(
+                        "A2A request failed without retry: name=%s error=%r",
+                        self._agent_name, error,
+                    )
+                    raise
+                await self._replace_agent()
+                retry_started = time.monotonic()
+                try:
+                    self.logger.debug("Retrying A2A request: name=%s", self._agent_name)
+                    reply = await self._agent.reply(inputs)
+                except BaseException as retry_error:
+                    await self._report_call(
+                        retry_started, success=False,
+                        timeout=self._is_timeout(retry_error),
+                    )
+                    raise
+                await self._report_call(retry_started, success=True)
+                self.logger.debug("Retried A2A request succeeded: name=%s", self._agent_name)
+                return reply
+
+    async def reply_stream(self, inputs, *, yield_final_msg: bool = False):
+        async with self._lock:
+            self.logger.debug("Sending streaming A2A request: name=%s", self._agent_name)
+            agent = await self._ensure_agent()
+            started_at = time.monotonic()
+            yielded = False
+            succeeded = False
+            try:
+                async for event in agent.reply_stream(inputs, yield_final_msg=yield_final_msg):
+                    yielded = True
+                    yield event
+                succeeded = True
+            except BaseException as error:
+                await self._report_call(
+                    started_at, success=False,
+                    timeout=self._is_timeout(error),
+                )
+                if yielded or not self._is_retryable(error):
+                    self.logger.debug(
+                        "A2A stream failed without retry: name=%s yielded=%s error=%r",
+                        self._agent_name, yielded, error,
+                    )
+                    raise
+                await self._replace_agent()
+                async for event in self._agent.reply_stream(inputs, yield_final_msg=yield_final_msg):
+                    yield event
+                succeeded = True
+            finally:
+                if succeeded:
+                    await self._report_call(started_at, success=True)
+                    self.logger.debug("Completed streaming A2A request: name=%s",
+                                      self._agent_name)
+
+    async def _report_call(self, started_at, *, success, timeout=False):
+        if self._reporter is None:
+            return
+        endpoint = self._resolver.selected_endpoint(self._agent_name)
+        if endpoint is None:
+            return
+        host, port = endpoint
+        await self._reporter.report(
+            service=self._agent_name,
+            host=host,
+            port=port,
+            method="message/send",
+            instance_type=InstanceType.A2A,
+            started_at=started_at,
+            success=success,
+            timeout=timeout,
+        )
+
+    async def observe(self, msgs):
+        async with self._lock:
+            agent = await self._ensure_agent()
+            await agent.observe(msgs)
+
+    async def invalidate(self):
+        """Close the current client and make the next call resolve again."""
+        async with self._lock:
+            self._check_open()
+            self.logger.debug("Invalidating A2A agent client: name=%s", self._agent_name)
+            await self._close_agent()
+            self._resolver.invalidate(self._agent_name)
+
+    async def aclose(self):
+        self._closed = True
+        self.logger.debug("Closing A2A agent wrapper: name=%s", self._agent_name)
+        await await_completion(self._close_all())
+
+    async def _close_all(self):
+        async with self._lock:
+            try:
+                await self._close_agent()
+            finally:
+                await self._resolver.async_close()
+
+    async def __aenter__(self):
+        self._check_open()
+        return self
+
+    async def __aexit__(self, *_):
+        await self.aclose()
+
+
+def _message_type():
+    from agentscope.message import Msg
+
+    return Msg
+
+
+def _is_local_reply_start_event(event):
+    try:
+        from agentscope.event import ReplyStartEvent
+    except ImportError:
+        return False
+    return isinstance(event, ReplyStartEvent)

polaris_ai/agentscope/cards.py

@@ -0,0 +1,106 @@
+# 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.
+
+"""Reusable native AgentCard construction for AgentScope applications."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+
+try:
+    from a2a.types import (
+        AgentCapabilities,
+        AgentCard,
+        AgentInterface,
+        AgentSkill,
+    )
+except ImportError as error:
+    raise ImportError(
+        "AgentCard construction requires pip install 'polaris-python-ai[a2a]'."
+    ) from error
+
+
+def _agent_skill(skill) -> AgentSkill:
+    if isinstance(skill, AgentSkill):
+        return skill
+    name = getattr(skill, "name", "")
+    description = getattr(skill, "description", "")
+    if not name:
+        raise ValueError("Agent Skill requires a name")
+    return AgentSkill(id=name, name=name, description=description, tags=["polaris"])
+
+
+def build_agent_card(
+    *,
+    name: str,
+    url: str,
+    description: str = "",
+    version: str = "1.0.0",
+    protocol_binding: str = "JSONRPC",
+    protocol_version: str = "1.0",
+    skills: Sequence = (),
+    input_modes: Sequence[str] = ("text/plain",),
+    output_modes: Sequence[str] = ("text/plain",),
+    streaming: bool = True,
+) -> AgentCard:
+    """Build a native A2A card while preserving framework-owned types."""
+    if not isinstance(name, str) or not name.strip():
+        raise ValueError("Agent name is required")
+    if not isinstance(url, str) or not url.strip():
+        raise ValueError("Agent URL is required")
+    return AgentCard(
+        name=name.strip(),
+        description=description,
+        version=version,
+        supported_interfaces=[AgentInterface(
+            url=url,
+            protocol_binding=protocol_binding,
+            protocol_version=protocol_version,
+        )],
+        capabilities=AgentCapabilities(streaming=streaming),
+        default_input_modes=list(input_modes),
+        default_output_modes=list(output_modes),
+        skills=[_agent_skill(skill) for skill in skills],
+    )
+
+
+@dataclass(frozen=True)
+class PolarisAgentCardTemplate:
+    """Reusable card defaults; only endpoint and runtime Skills vary per Agent."""
+
+    description: str = ""
+    version: str = "1.0.0"
+    protocol_binding: str = "JSONRPC"
+    protocol_version: str = "1.0"
+    input_modes: tuple[str, ...] = ("text/plain",)
+    output_modes: tuple[str, ...] = ("text/plain",)
+    streaming: bool = True
+    skills: tuple = field(default_factory=tuple)
+
+    def build(self, name: str, url: str, *, skills: Sequence = ()) -> AgentCard:
+        selected = tuple(skills) if skills else self.skills
+        return build_agent_card(
+            name=name,
+            url=url,
+            description=self.description,
+            version=self.version,
+            protocol_binding=self.protocol_binding,
+            protocol_version=self.protocol_version,
+            skills=selected,
+            input_modes=self.input_modes,
+            output_modes=self.output_modes,
+            streaming=self.streaming,
+        )