polaris-python 0.0.1.dev3__py3-none-any.whl

polaris/api/lossless.py

@@ -0,0 +1,73 @@
+# Tencent is pleased to support the open source community by making polaris-python available.
+#
+# Copyright (C) 2021 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.
+
+"""Public API for Java-compatible lossless online/offline."""
+
+from polaris.api.config import SDKContext
+from polaris.pkg.model.error import SDKError, ErrorCode
+from polaris.pkg.model.lossless import LosslessActionProvider, LosslessInstance
+
+
+class LosslessAPI:
+    """Drive lossless lifecycle with user-supplied register/deregister callbacks."""
+
+    def __init__(self, context: SDKContext):
+        self.context = context
+
+    def check_available(self):
+        if not self.context:
+            raise SDKError(ErrorCode.ErrCodeAPIInvalidArgument, "losslessAPI can not be None")
+        if self.context.is_destroy():
+            raise SDKError(ErrorCode.ErrCodeInvalidStateError, "losslessAPI: api instance has been destroyed")
+
+    def _manager(self):
+        manager = self.context.get_engine().lossless_manager
+        if manager is None:
+            raise SDKError(ErrorCode.ErrCodeInvalidStateError, "losslessAPI: engine has no lossless manager")
+        return manager
+
+    def set_lossless_action_provider(self, instance: LosslessInstance,
+                                     provider: LosslessActionProvider) -> None:
+        """Bind the callbacks used by lossless register/deregister for one instance."""
+        self.check_available()
+        if not isinstance(provider, LosslessActionProvider):
+            raise SDKError(ErrorCode.ErrCodeAPIInvalidArgument,
+                           "losslessAPI: provider must implement LosslessActionProvider")
+        self._manager().set_action_provider(instance, provider)
+
+    def lossless_register(self, instance: LosslessInstance) -> None:
+        """Synchronously start lossless online for one instance."""
+        self.check_available()
+        engine = self.context.get_engine()
+        engine._run_sync(self._manager().lossless_register(instance))
+
+    async def async_lossless_register(self, instance: LosslessInstance) -> None:
+        """Asynchronously start lossless online for one instance."""
+        self.check_available()
+        engine = self.context.get_engine()
+        await engine._run_async(self._manager().lossless_register(instance))
+
+    def lossless_deregister(self, instance: LosslessInstance) -> None:
+        """Synchronously trigger lossless offline for one instance."""
+        self.check_available()
+        engine = self.context.get_engine()
+        engine._run_sync(self._manager().lossless_deregister(instance))
+
+    async def async_lossless_deregister(self, instance: LosslessInstance) -> None:
+        """Asynchronously trigger lossless offline for one instance."""
+        self.check_available()
+        engine = self.context.get_engine()
+        await engine._run_async(self._manager().lossless_deregister(instance))

polaris/api/provider.py

@@ -0,0 +1,152 @@
+# Tencent is pleased to support the open source community by making polaris-python available.
+#
+# Copyright (C) 2021 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.
+
+from polaris.pkg.model.server import (
+    InstanceDeRegisterRequest,
+    InstanceHeartbeatRequest,
+    InstanceRegisterRequest,
+    InstanceRegisterResponse,
+)
+from polaris.pkg.config.api import Configuration
+from polaris.pkg.model.error import SDKError, ErrorCode
+from polaris.api.config import SDKContext, init_context_by_config, init_context_by_file
+from polaris.api.log import LogOptions
+
+
+class ProviderAPI:
+    """Register instances and manage their heartbeats through a shared SDK context."""
+
+    def __init__(self, context: SDKContext):
+        self.context = context
+
+    def check_available(self):
+        if not self.context:
+            raise SDKError(ErrorCode.ErrCodeAPIInvalidArgument, "providerAPI can not be None")
+        if self.context.is_destroy():
+            raise SDKError(ErrorCode.ErrCodeInvalidStateError, "providerAPI: api instance has been destroyed")
+
+    def register(self, request: InstanceRegisterRequest) -> InstanceRegisterResponse:
+        """Register synchronously, using the request's automatic-heartbeat setting."""
+        self.check_available()
+        request.validate()
+        return self.context.get_engine().sync_register(request)
+
+    def register_instance(self, request: InstanceRegisterRequest) -> InstanceRegisterResponse:
+        """Register synchronously and let the SDK maintain instance heartbeats."""
+        self.check_available()
+        request.validate()
+        request.auto_heartbeat = True
+        return self.context.get_engine().sync_register(request)
+
+    def deregister(self, request: InstanceDeRegisterRequest) -> None:
+        """Stop automatic heartbeats and synchronously deregister the instance."""
+        self.check_available()
+        request.validate()
+        return self.context.get_engine().sync_deregister(request)
+
+    def heartbeat(self, request: InstanceHeartbeatRequest) -> None:
+        """Synchronously send one explicit instance heartbeat."""
+        self.check_available()
+        request.validate()
+        return self.context.get_engine().sync_heartbeat(request)
+
+    def deregister_instance(self, request: InstanceDeRegisterRequest) -> None:
+        """Stop automatic heartbeats and synchronously deregister an instance."""
+        return self.deregister(request)
+
+    def lossless_register(self, request: InstanceRegisterRequest) -> None:
+        """Delay or health-check gate registration for lossless online."""
+        self.check_available()
+        request.validate()
+        return self.context.get_engine().sync_lossless_register(request)
+
+    def lossless_deregister(self, request) -> None:
+        """Deregister immediately so consumers stop routing to the instance."""
+        self.check_available()
+        request.validate()
+        return self.context.get_engine().sync_lossless_deregister(request)
+
+    async def async_register(self, request: InstanceRegisterRequest) -> InstanceRegisterResponse:
+        """Asynchronously register with the request's automatic-heartbeat setting."""
+        self.check_available()
+        request.validate()
+        return await self.context.get_engine().async_register(request)
+
+    async def async_register_instance(self, request: InstanceRegisterRequest) -> InstanceRegisterResponse:
+        """Asynchronously register and let the SDK maintain instance heartbeats."""
+        self.check_available()
+        request.validate()
+        request.auto_heartbeat = True
+        return await self.context.get_engine().async_register(request)
+
+    async def async_deregister(self, request: InstanceDeRegisterRequest) -> None:
+        """Stop automatic heartbeats and asynchronously deregister the instance."""
+        self.check_available()
+        request.validate()
+        return await self.context.get_engine().async_deregister(request)
+
+    async def async_heartbeat(self, request: InstanceHeartbeatRequest) -> None:
+        """Asynchronously send one explicit instance heartbeat."""
+        self.check_available()
+        request.validate()
+        return await self.context.get_engine().async_heartbeat(request)
+
+    async def async_deregister_instance(self, request: InstanceDeRegisterRequest) -> None:
+        """Stop automatic heartbeats and asynchronously deregister an instance."""
+        return await self.async_deregister(request)
+
+    async def async_lossless_register(self, request: InstanceRegisterRequest) -> None:
+        """Asynchronously delay or health-check gate registration."""
+        self.check_available()
+        request.validate()
+        return await self.context.get_engine().async_lossless_register(request)
+
+    async def async_lossless_deregister(self, request) -> None:
+        """Asynchronously deregister immediately for lossless offline."""
+        self.check_available()
+        request.validate()
+        return await self.context.get_engine().async_lossless_deregister(request)
+
+    def report_service_contract(self, request):
+        """Synchronously report tools, resources, prompts and handler descriptors."""
+        self.check_available()
+        request.validate()
+        return self.context.get_engine().sync_contract_call("report_service_contract", request)
+
+    async def async_report_service_contract(self, request):
+        """Asynchronously report a service contract."""
+        self.check_available()
+        request.validate()
+        return await self.context.get_engine().async_contract_call("report_service_contract", request)
+
+    def destroy(self) -> None:
+        """Destroy the shared context and stop all of its heartbeat tasks."""
+        if self.context:
+            self.context.destroy()
+
+
+def create_provider_by_file(path: str, *, log_options: LogOptions | None = None) -> ProviderAPI:
+    context = init_context_by_file(path=path, log_options=log_options)
+    return ProviderAPI(context=context)
+
+
+def create_provider_by_config(config: Configuration, *, log_options: LogOptions | None = None) -> ProviderAPI:
+    context = init_context_by_config(config=config, log_options=log_options)
+    return ProviderAPI(context=context)
+
+
+def create_provider_by_default_config_file(*, log_options: LogOptions | None = None) -> ProviderAPI:
+    from polaris.api.config import init_context
+    return ProviderAPI(context=init_context(log_options=log_options))

polaris/api/skill.py

@@ -0,0 +1,162 @@
+# Tencent is pleased to support the open source community by making polaris-python available.
+#
+# Copyright (C) 2021 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.
+
+"""Read-only published Skill APIs with synchronous and asynchronous entry points."""
+
+from polaris.api.config import init_context_by_config, init_context_by_file
+from polaris.pkg.model.error import ErrorCode, SDKError
+from polaris.pkg.model.service import ExtendedMetadata, ServiceInstances
+from polaris.pkg.model.skill import SkillDownloadRequest, SkillGetRequest, SkillListRequest
+
+
+class SkillAPI:
+    """Query and download published skills through a shared SDK context."""
+
+    def __init__(self, context, *, owns_context=False):
+        self.context = context
+        self._owns_context = owns_context
+        self._closed = False
+
+    def _check(self, request):
+        if self._closed or self.context is None or self.context.is_destroy():
+            raise SDKError(ErrorCode.ErrCodeInvalidStateError, "Skill API or context has been destroyed")
+        request.validate()
+
+    def resolve_mounted_skill_request(self, service_snapshot, *, skill_name: str = "",
+                                      requested_version: str = "", timeout: int = 0) -> SkillGetRequest:
+        """Resolve one mounted skill, preferring its recorded version over the caller version."""
+        if self._closed or self.context is None or self.context.is_destroy():
+            raise SDKError(ErrorCode.ErrCodeInvalidStateError, "Skill API or context has been destroyed")
+        if not isinstance(service_snapshot, ServiceInstances):
+            raise SDKError(ErrorCode.ErrCodeAPIInvalidArgument, "service_snapshot must be a ServiceInstances")
+        if not isinstance(skill_name, str) or not isinstance(requested_version, str) or type(timeout) is not int:
+            raise SDKError(ErrorCode.ErrCodeAPIInvalidArgument,
+                           "skill_name and requested_version must be strings and timeout must be an integer")
+
+        mounts = [item.agent_skill for item in service_snapshot.get_extended_metadata()
+                  if item.type == ExtendedMetadata.SKILL and item.agent_skill is not None]
+        if skill_name:
+            mounts = [mount for mount in mounts if mount.name == skill_name]
+        elif len(mounts) > 1:
+            raise SDKError(ErrorCode.ErrCodeAPIInvalidArgument,
+                           "service has multiple mounted skills; specify skill_name")
+        if not mounts:
+            raise SDKError(ErrorCode.ErrCodeAPIInvalidArgument, "service has no matching mounted skill")
+
+        mount = mounts[0]
+        if not mount.name:
+            raise SDKError(ErrorCode.ErrCodeAPIInvalidArgument, "mounted skill name is empty")
+        version = mount.version or requested_version
+        request = SkillGetRequest(service_snapshot.get_namespace(), mount.name, version, timeout)
+        request.validate()
+        return request
+
+    def get_skill(self, request: SkillGetRequest):
+        """Synchronously fetch published content with network-error fallback."""
+        self._check(request)
+        return self.context.engine.sync_skill_call("get_skill", request)
+
+    async def async_get_skill(self, request: SkillGetRequest):
+        """Asynchronously fetch published content with network-error fallback."""
+        self._check(request)
+        return await self.context.engine.async_skill_call("get_skill", request)
+
+    def list_skills(self, request: SkillListRequest):
+        """Synchronously search published skills on the remote server."""
+        self._check(request)
+        return self.context.engine.sync_skill_call("list_skills", request)
+
+    async def async_list_skills(self, request: SkillListRequest):
+        """Asynchronously search published skills on the remote server."""
+        self._check(request)
+        return await self.context.engine.async_skill_call("list_skills", request)
+
+    def download_skill(self, request: SkillDownloadRequest):
+        """Synchronously download a complete markdown or ZIP payload."""
+        self._check(request)
+        return self.context.engine.sync_skill_call("download_skill", request)
+
+    def get_mounted_skill(self, service_snapshot, *, skill_name: str = "", requested_version: str = "",
+                          timeout: int = 0):
+        """Synchronously fetch the skill mounted on a discovered service."""
+        request = self.resolve_mounted_skill_request(
+            service_snapshot, skill_name=skill_name, requested_version=requested_version, timeout=timeout)
+        return self.get_skill(request)
+
+    async def async_get_mounted_skill(self, service_snapshot, *, skill_name: str = "",
+                                      requested_version: str = "", timeout: int = 0):
+        """Asynchronously fetch the skill mounted on a discovered service."""
+        request = self.resolve_mounted_skill_request(
+            service_snapshot, skill_name=skill_name, requested_version=requested_version, timeout=timeout)
+        return await self.async_get_skill(request)
+
+    def download_mounted_skill(self, service_snapshot, *, skill_name: str = "", requested_version: str = "",
+                               timeout: int = 0, format: str = "markdown"):
+        """Synchronously download the skill mounted on a discovered service."""
+        request = self.resolve_mounted_skill_request(
+            service_snapshot, skill_name=skill_name, requested_version=requested_version, timeout=timeout)
+        download = SkillDownloadRequest(request.namespace, request.name, request.version, timeout, format=format)
+        return self.download_skill(download)
+
+    async def async_download_mounted_skill(self, service_snapshot, *, skill_name: str = "",
+                                           requested_version: str = "", timeout: int = 0,
+                                           format: str = "markdown"):
+        """Asynchronously download the skill mounted on a discovered service."""
+        request = self.resolve_mounted_skill_request(
+            service_snapshot, skill_name=skill_name, requested_version=requested_version, timeout=timeout)
+        download = SkillDownloadRequest(request.namespace, request.name, request.version, timeout, format=format)
+        return await self.async_download_skill(download)
+
+    async def async_download_skill(self, request: SkillDownloadRequest):
+        """Asynchronously download a complete markdown or ZIP payload."""
+        self._check(request)
+        return await self.context.engine.async_skill_call("download_skill", request)
+
+    def destroy(self):
+        """Close this API and its context only when the factory created that context."""
+        self._closed = True
+        if self._owns_context and self.context is not None:
+            self.context.destroy()
+
+    def close(self):
+        """Java AutoCloseable-compatible alias for destroy()."""
+        self.destroy()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *_):
+        self.close()
+
+
+def create_skill_by_config(config, *, log_options=None):
+    """Create a Skill API owning an independently configured context."""
+    return SkillAPI(init_context_by_config(config, log_options=log_options), owns_context=True)
+
+
+def create_skill_by_file(path, *, log_options=None):
+    """Create a Skill API owning a context loaded from polaris.yaml."""
+    return SkillAPI(init_context_by_file(path, log_options=log_options), owns_context=True)
+
+
+def create_skill_by_context(context):
+    """Create a Skill API that shares a caller-owned SDK context."""
+    return SkillAPI(context)
+
+
+def create_skill_by_default_config_file(*, log_options=None):
+    """Create a Skill API from the default polaris.yaml or environment."""
+    from polaris.api.config import init_context
+    return SkillAPI(init_context(log_options=log_options), owns_context=True)

polaris/pkg/__init__.py

@@ -0,0 +1,15 @@
+# Tencent is pleased to support the open source community by making polaris-python available.
+#
+# Copyright (C) 2021 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.
+

polaris/pkg/common/__init__.py

@@ -0,0 +1,15 @@
+# Tencent is pleased to support the open source community by making polaris-python available.
+#
+# Copyright (C) 2021 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.
+

polaris/pkg/common/plugin.py

@@ -0,0 +1,33 @@
+# Tencent is pleased to support the open source community by making polaris-python available.
+#
+# Copyright (C) 2021 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.
+
+from abc import abstractmethod
+
+from polaris.pkg.config import api
+from polaris.plugin_manager import PluginType
+
+
+class Supplier:
+    @abstractmethod
+    def get_plugin(cls, type: PluginType, name: str):
+        pass
+
+
+class InitContext:
+    def __init__(self, config: api.Configuration, plugins: Supplier, value_ctx, conn_manager):
+        self.config = config
+        self.plugins = plugins
+        self.value_ctx = value_ctx
+        self.conn_manager = conn_manager

polaris/pkg/config/__init__.py

@@ -0,0 +1,15 @@
+# Tencent is pleased to support the open source community by making polaris-python available.
+#
+# Copyright (C) 2021 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.
+