computenest-agent-integrations 0.1.0__py3-none-any.whl

computenest/agents/__init__.py

@@ -0,0 +1 @@
+"""ComputeNest Agent Integrations – reusable helpers for building agents."""

computenest/agents/adk/__init__.py

@@ -0,0 +1,7 @@
+"""ADK (Agent Development Kit) integration helpers."""
+
+from .memory import BailianLongTermMemoryService
+from .tools.bailian_mcp import BailianMcpTool
+from .tools.bailian_rag import BailianRagTool
+
+__all__ = ["BailianLongTermMemoryService", "BailianRagTool", "BailianMcpTool"]

computenest/agents/adk/mcp_helpers.py

@@ -0,0 +1,8 @@
+"""MCP (Model Context Protocol) helper utilities for ADK agents."""
+
+from __future__ import annotations
+
+
+def hello() -> None:
+    """Simple hello helper – placeholder for MCP integration logic."""
+    print("Hello from computenest.agents.adk.mcp_helpers!")

computenest/agents/adk/memory/__init__.py

@@ -0,0 +1,5 @@
+"""ADK memory service integrations."""
+
+from .bailian_long_term_memory import BailianLongTermMemoryService
+
+__all__ = ["BailianLongTermMemoryService"]

computenest/agents/adk/memory/bailian_long_term_memory.py

@@ -0,0 +1,194 @@
+"""Alibaba Cloud Model Studio long-term memory service for ADK."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from datetime import timezone
+import logging
+from typing import Any
+
+import aiohttp
+from google.adk.memory.base_memory_service import BaseMemoryService
+from google.adk.memory.base_memory_service import SearchMemoryResponse
+from google.adk.memory.memory_entry import MemoryEntry
+from google.adk.sessions.session import Session
+from google.genai import types
+from typing_extensions import override
+
+DEFAULT_ENDPOINT = "https://dashscope.aliyuncs.com/api/v2/apps/memory"
+
+logger = logging.getLogger(__name__)
+
+
+class BailianLongTermMemoryService(BaseMemoryService):
+    """Store and retrieve ADK conversation memory through Bailian."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        memory_library_id: str,
+        add_project_id: str | None = None,
+        search_project_ids: list[str] | None = None,
+        top_k: int = 5,
+        min_score: float = 0.3,
+        endpoint: str = DEFAULT_ENDPOINT,
+        timeout: float = 30.0,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key must not be empty")
+        if not memory_library_id:
+            raise ValueError("memory_library_id must not be empty")
+
+        self._api_key = api_key
+        self._memory_library_id = memory_library_id
+        self._add_project_id = add_project_id
+        self._search_project_ids = search_project_ids
+        self._top_k = top_k
+        self._min_score = min_score
+        self._endpoint = endpoint.rstrip("/")
+        self._timeout = timeout
+
+    @override
+    async def add_session_to_memory(self, session: Session) -> None:
+        """Extract memories from the user and model messages in a session."""
+        try:
+            messages = _events_to_messages(session.events)
+            if not messages:
+                logger.debug(
+                    "No messages to store for session %s",
+                    session.id,
+                )
+                return
+
+            payload: dict[str, Any] = {
+                "user_id": session.user_id,
+                "messages": messages,
+                "memory_library_id": self._memory_library_id,
+                "meta_data": {
+                    "app_name": session.app_name,
+                    "session_id": session.id,
+                },
+            }
+            if self._add_project_id:
+                payload["project_id"] = self._add_project_id
+
+            result = await self._request("/add", payload)
+            logger.info(
+                "Stored %d messages for session %s "
+                "(created %d memory nodes, request_id=%s)",
+                len(messages),
+                session.id,
+                len(result.get("memory_nodes", [])),
+                result.get("request_id", ""),
+            )
+        except Exception:
+            logger.exception(
+                "Failed to add session %s to Bailian memory",
+                session.id,
+            )
+            raise
+
+    @override
+    async def search_memory(
+        self,
+        *,
+        app_name: str,
+        user_id: str,
+        query: str,
+    ) -> SearchMemoryResponse:
+        """Search the configured Bailian memory library for one ADK user."""
+        try:
+            payload: dict[str, Any] = {
+                "user_id": user_id,
+                "messages": [{"role": "user", "content": query}],
+                "memory_library_id": self._memory_library_id,
+                "top_k": self._top_k,
+                "min_score": self._min_score,
+            }
+            if self._search_project_ids:
+                payload["project_ids"] = self._search_project_ids
+
+            result = await self._request(
+                "/memory_nodes/search",
+                payload,
+            )
+            memories = [
+                MemoryEntry(
+                    id=node.get("memory_node_id"),
+                    content=types.Content(
+                        role="user",
+                        parts=[
+                            types.Part.from_text(
+                                text=str(node.get("content", ""))
+                            )
+                        ],
+                    ),
+                    author="memory",
+                    timestamp=_format_timestamp(node.get("created_at")),
+                    custom_metadata=node.get("meta_data") or {},
+                )
+                for node in result.get("memory_nodes", [])
+                if node.get("content")
+            ]
+
+            logger.info(
+                "Found %d memories for query '%s' (app=%s, user=%s)",
+                len(memories),
+                query[:50],
+                app_name,
+                user_id,
+            )
+            return SearchMemoryResponse(memories=memories)
+        except Exception:
+            logger.exception(
+                "Failed to search Bailian memories "
+                "(app=%s, user=%s)",
+                app_name,
+                user_id,
+            )
+            return SearchMemoryResponse(memories=[])
+
+    async def _request(
+        self,
+        path: str,
+        payload: dict[str, Any],
+    ) -> dict[str, Any]:
+        headers = {
+            "Authorization": f"Bearer {self._api_key}",
+            "Content-Type": "application/json",
+        }
+        timeout = aiohttp.ClientTimeout(total=self._timeout)
+        async with aiohttp.ClientSession(timeout=timeout) as session:
+            async with session.post(
+                f"{self._endpoint}{path}",
+                headers=headers,
+                json=payload,
+            ) as response:
+                response.raise_for_status()
+                return await response.json()
+
+
+def _events_to_messages(events: list[Any]) -> list[dict[str, str]]:
+    messages: list[dict[str, str]] = []
+    for event in events:
+        content = getattr(event, "content", None)
+        if not content or not content.parts:
+            continue
+
+        role = "assistant" if content.role == "model" else content.role
+        if role not in ("user", "assistant"):
+            continue
+
+        text = "\n".join(
+            part.text for part in content.parts if part.text
+        ).strip()
+        if text:
+            messages.append({"role": role, "content": text})
+    return messages
+
+
+def _format_timestamp(timestamp: int | None) -> str | None:
+    if timestamp is None:
+        return None
+    return datetime.fromtimestamp(timestamp, tz=timezone.utc).isoformat()

computenest/agents/adk/tools/bailian_mcp.py

@@ -0,0 +1,50 @@
+"""Build ADK McpToolsets from Bailian MCP configuration."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import Any
+
+from google.adk.tools.mcp_tool import McpToolset
+from google.adk.tools.mcp_tool import StreamableHTTPConnectionParams
+
+_DASHSCOPE_API_KEY = "${DASHSCOPE_API_KEY}"
+
+
+class BailianMcpTool:
+    """Build ADK McpToolsets from Bailian MCP JSON configuration."""
+
+    def __init__(
+        self,
+        mcp_config: dict[str, Any],
+        *,
+        dashscope_api_key: str,
+        **mcp_toolset_kwargs: Any,
+    ) -> None:
+        """Create toolsets from Bailian MCP JSON configuration.
+
+        ``mcp_config`` may be the full JSON (with ``mcpServers``) or just the
+        ``mcpServers`` object.
+        """
+        api_key = dashscope_api_key.strip()
+        servers = mcp_config.get("mcpServers", mcp_config)
+
+        self._toolsets = [
+            McpToolset(
+                connection_params=StreamableHTTPConnectionParams(
+                    url=cfg["baseUrl"],
+                    headers={
+                        key: value.replace(_DASHSCOPE_API_KEY, api_key)
+                        for key, value in (cfg.get("headers") or {}).items()
+                    } or None,
+                ),
+                **mcp_toolset_kwargs,
+            )
+            for cfg in servers.values()
+        ]
+
+    def __iter__(self) -> Iterator[McpToolset]:
+        return iter(self._toolsets)
+
+    def __len__(self) -> int:
+        return len(self._toolsets)

computenest/agents/adk/tools/bailian_rag.py

@@ -0,0 +1,128 @@
+"""Alibaba Cloud Model Studio knowledge-base retrieval tool for ADK."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from alibabacloud_bailian20231229 import models as bailian_models
+from alibabacloud_bailian20231229.client import Client as BailianClient
+from alibabacloud_tea_openapi.utils_models import Config
+from google.adk.tools.base_tool import BaseTool
+from google.adk.tools.tool_context import ToolContext
+from google.genai import types
+from typing_extensions import override
+
+logger = logging.getLogger(__name__)
+
+
+class BailianRagTool(BaseTool):
+    """Retrieve relevant document chunks from a Bailian knowledge base."""
+
+    def __init__(
+        self,
+        *,
+        access_key_id: str,
+        access_key_secret: str,
+        workspace_id: str,
+        index_id: str,
+        region_id: str = "cn-beijing",
+    ) -> None:
+        super().__init__(
+            name="retrieve_from_knowledge_base",
+            description=(
+                "Retrieve document chunks from the configured Bailian "
+                "knowledge base that are relevant to the user's query."
+            ),
+        )
+        self._workspace_id = workspace_id
+        self._index_id = index_id
+        self._client = BailianClient(
+            Config(
+                access_key_id=access_key_id,
+                access_key_secret=access_key_secret,
+                endpoint=f"bailian.{region_id}.aliyuncs.com",
+            )
+        )
+
+    @override
+    def _get_declaration(self) -> types.FunctionDeclaration:
+        return types.FunctionDeclaration(
+            name=self.name,
+            description=self.description,
+            parameters=types.Schema(
+                type=types.Type.OBJECT,
+                properties={
+                    "query": types.Schema(
+                        type=types.Type.STRING,
+                        description="The knowledge-base search query.",
+                    ),
+                },
+                required=["query"],
+            ),
+        )
+
+    @override
+    async def run_async(
+        self,
+        *,
+        args: dict[str, Any],
+        tool_context: ToolContext,
+    ) -> dict[str, Any]:
+        del tool_context
+
+        query = args.get("query")
+        if not isinstance(query, str) or not query.strip():
+            return {
+                "success": False,
+                "error_code": "INVALID_QUERY",
+                "message": "The query must be a non-empty string.",
+                "query": query if isinstance(query, str) else None,
+                "chunks": [],
+            }
+
+        normalized_query = query.strip()
+        try:
+            response = await self._client.retrieve_async(
+                self._workspace_id,
+                bailian_models.RetrieveRequest(
+                    index_id=self._index_id,
+                    query=normalized_query,
+                ),
+            )
+        except Exception:
+            logger.exception("Bailian knowledge-base request failed.")
+            return {
+                "success": False,
+                "error_code": "BAILIAN_REQUEST_ERROR",
+                "message": "Unable to access the Bailian knowledge base.",
+                "query": normalized_query,
+                "chunks": [],
+            }
+
+        if not response.body or not response.body.success:
+            return {
+                "success": False,
+                "error_code": "BAILIAN_API_ERROR",
+                "message": "Bailian knowledge-base retrieval failed.",
+                "query": normalized_query,
+                "chunks": [],
+            }
+
+        nodes = response.body.data.nodes if response.body.data else []
+        return {
+            "success": True,
+            "message": (
+                f"Retrieved {len(nodes)} knowledge-base chunk(s)."
+                if nodes
+                else "No relevant knowledge-base content was found."
+            ),
+            "query": normalized_query,
+            "chunks": [
+                {
+                    "text": node.text,
+                    "score": node.score,
+                }
+                for node in nodes
+            ],
+        }

computenest/agents/common/__init__.py

@@ -0,0 +1 @@
+"""Common utilities shared across agent integrations."""

computenest_agent_integrations-0.1.0.dist-info/METADATA

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: computenest-agent-integrations
+Version: 0.1.0
+Summary: ComputeNest agent integrations for Google ADK with Alibaba Cloud Bailian
+Author-email: Bali <zhaoyu.zhaoyu@alibaba-inc.com>, Yunyao <ziqiao.lzq@alibaba-inc.com>, Zhongsi <zhongsi.lz@alibaba-inc.com>
+Project-URL: Homepage, https://computenest.console.aliyun.com/welcome
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: aiohttp>=3.9.0
+Requires-Dist: alibabacloud-bailian20231229>=1.0.0
+Requires-Dist: google-adk>=2.0.0
+Requires-Dist: mcp<2.0.0,>=1.24.0
+Requires-Dist: typing-extensions>=4.12.0
+Provides-Extra: app
+Requires-Dist: circus==0.19.0; extra == "app"
+Requires-Dist: uvicorn[standard]==0.34.3; extra == "app"
+Requires-Dist: python-dotenv==1.0.1; extra == "app"
+Requires-Dist: fastapi==0.115.13; extra == "app"
+Requires-Dist: sse-starlette==2.1.3; extra == "app"
+Requires-Dist: pydantic-settings<3.0.0,>=2.2.1; extra == "app"
+
+# 详细指南
+Python部署请参考ATA文档：https://ata.atatech.org/articles/11020487205
+如有疑问，可加入“Aone Python应用部署答疑群”群 钉钉群号： 109775038267
+# 项目结构
+```tree
+├── APP-META (构建用到的文件)
+│   └── docker-config (构建镜像时的工作目录)
+│       ├── Dockerfile
+│       └── environment
+│           └── common
+│               ├── base (要使用aone启动应用，必须包含的脚本/配置)
+│               │   ├── app
+│               │   │   └── bin
+│               │   │       ├── appctl.sh
+│               │   │       ├── health.sh
+│               │   │       ├── setenv.sh
+│               │   │       ├── start.sh
+│               │   │       └── stop.sh
+│               │   └── cai
+│               │       ├── bin
+│               │       │   └── nginxctl
+│               │       └── conf
+│               │           ├── mime.types
+│               │           └── nginx-proxy.conf
+│               └── custom (项目自定义的脚本/配置)
+│                   └── app
+│                       └── bin
+│                           ├── health.sh
+│                           ├── setenv.sh
+│                           ├── start.sh
+│                           └── stop.sh
+├── README.md
+├── app
+│   ├── __init__.py
+│   ├── api (对外暴露的后端API)
+│   │   ├── __init__.py
+│   │   ├── main.py
+│   │   └── routes
+│   │       ├── __init__.py
+│   │       ├── health.py
+│   │       └── hello.py
+│   ├── config (应用配置相关)
+│   │   ├── __init__.py
+│   │   ├── env.py
+│   │   ├── diamond.py
+│   ├── lifecycle (应用生命周期相关)
+│   │   ├── __init__.py
+│   │   └── manager.py
+│   └──main.py (主文件，初始化FastAPI，设置路由并启动)
+│
+├── conf (配置文件)
+│   └── circus.ini (circus用于进程管理，Python应用的启动在此定义)
+│
+└── computenest-agent-integrations.release (构建文件)
+```
+# 自定义启动脚本
+
+## 定制启动脚本请写到APP-META/.../common/custom目录下
+
+APP-META/.../common/custom目录中存储了健康检查(health.sh)、环境变量(setenv.sh)、启动(start.sh)、停止(stop.sh)等脚本，这些脚本会在容器启动时被执行。如果项目有特殊需求，可以在custom目录下修改对应的脚本，最好不要直接修改base目录下的脚本，否则可能导致项目无法正常启动，如遇项目启动问题，请联系源码模板负责人。
+
+
+# 本地启动
+
+### 1. 安装依赖
+- 首先安装uv，最简单的是`pip install uv`，其它方法：https://docs.astral.sh/uv/getting-started/installation/
+- uv安装依赖：uv sync
+- 如果不使用uv，可以手动pip安装pyproject.toml中的依赖
+
+### 2. 启动命令
+`uv run python -m app.main`
+
+注意uv run自动激活了.venv虚拟环境，如果要直接运行python -m app.main，首先需要激活虚拟环境: `source .venv/bin/activate`
+
+注意由于main.py被放置在app目录下，所以需要使用`python -m`模块启动，这是Python工程推荐做法，如果你希望直接使用`python main.py`启动，可以将main.py移出app目录，在根目录启动。
+
+### 3. FastAPI 交互式API文档页
+[http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs)
+
+### 4. VSCode调试
+创建launch.json时，选择Python调试程序->模块->输入app.main即可 
+
+# Aone部署
+
+### 1. 部署
+
+### 2. FastAPI 交互式API文档页
+http://{host}/docs
+
+# 脚手架介绍
+
+该脚手架用于快速搭建并在Aone部署基于FastAPI的Python后端应用，也可以用于自定义部署参考，如果你希望部署其它框架或开源产品，只需删除app目录，并修改conf/circus.ini中的启动命令，但必须参考app/api/routes/health.py提供/status.taobao健康检查接口，如果你不需要VIPServer的优雅上下线，直接在/status.taobao中返回"success"即可。

computenest_agent_integrations-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+computenest/agents/__init__.py,sha256=2VdnwimZsqhNzzkpDh8TZvOLdHhzmceZDubAE1eZ5JA,79
+computenest/agents/adk/__init__.py,sha256=m47DjvuNGpBbwUdUW-gr1Cv5tC8XXXyuFhRRA5Ul7Kg,277
+computenest/agents/adk/mcp_helpers.py,sha256=Vesddn1-290bLOJFUDPPB0o8htEoEeFT6JuUp2ImAJc,260
+computenest/agents/adk/memory/__init__.py,sha256=TDFHm7FVCK7T7L3Cjq4ILKAgwuaKpQw4KDX_tMv-2S8,151
+computenest/agents/adk/memory/bailian_long_term_memory.py,sha256=RzhzAj0YiNQ0f-EqQTe8eZB8rflhGyuEf3Os5VuIr58,6495
+computenest/agents/adk/tools/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+computenest/agents/adk/tools/bailian_mcp.py,sha256=wxVYaHeO7eWPLdN-VIQNZYIQjle62SgxWxDmPlYbby4,1505
+computenest/agents/adk/tools/bailian_rag.py,sha256=bbtomRRYXdDCdQcC_JGrSO1pDDF7ZQ_cbEYY8gsTvf4,4144
+computenest/agents/common/__init__.py,sha256=OCQY0h32BorokX2fIwa7FyVlmllo_-LSmQZKh1uxDoQ,57
+computenest_agent_integrations-0.1.0.dist-info/METADATA,sha256=j-dYfBQAxh07s_2qHA0z5R0UeO9JjeK6mjrqAkk3fqI,5196
+computenest_agent_integrations-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+computenest_agent_integrations-0.1.0.dist-info/top_level.txt,sha256=YC9gq6Rtqnrt-MbnbaqEUTXYFGEC2__8Ro3t3uKrrUw,12
+computenest_agent_integrations-0.1.0.dist-info/RECORD,,

computenest_agent_integrations-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

computenest_agent_integrations-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+computenest