veadk-python 0.2.27__py3-none-any.whl

veadk/tools/builtin_tools/web_scraper.py

@@ -0,0 +1,76 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# 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 typing import Any
+
+import requests
+
+from veadk.config import getenv
+
+
+def web_scraper(query: str) -> dict[str, Any]:
+    """query a single keyword from some search engineer
+
+    Args:
+        query (str, optional): query keyword. Defaults to None.
+
+    Returns:
+        dict[str, Any]: search results
+    """
+
+    endpoint = getenv("TOOL_WEB_SCRAPER_ENDPOINT")
+    token = getenv("TOOL_WEB_SCRAPER_API_KEY")
+
+    try:
+        url = f"https://{endpoint}/v1/queries"
+        headers = {
+            "Content-Type": "application/json",
+            "X-VE-Source": "google_search",
+            "X-VE-API-Key": token,
+        }
+        data = {
+            "query": query,
+            "source": "google_search",
+            "parse": True,
+            "limit": "10",
+            "start_page": "1",
+            "pages": "1",
+            "context": [
+                {"key": "nfpr", "value": True},
+                {"key": "safe_search", "value": False},
+                {"key": "filter", "value": 1},
+            ],
+        }
+        response = requests.post(url, headers=headers, json=data, verify=False)
+
+        response.raise_for_status()
+
+        response_json = response.json() if response.content else None
+        results_dict = (
+            response_json.get("results")[0].get("content").get("results").get("organic")
+        )
+
+        results_str = ""
+        for r in results_dict:
+            dic = {
+                "url": r.get("url"),
+                "title": r.get("title"),
+                "description": r.get("desc"),
+            }
+            results_str += str(dic)
+        return results_str
+
+    except requests.exceptions.RequestException as e:
+        error_message = f"Error: {str(e)}, response: {response}"
+        raise ValueError(error_message)

veadk/tools/builtin_tools/web_search.py

@@ -0,0 +1,83 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# 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.
+
+"""
+The document of this tool see: https://www.volcengine.com/docs/85508/1650263
+"""
+
+import os
+
+from google.adk.tools import ToolContext
+
+from veadk.auth.veauth.utils import get_credential_from_vefaas_iam
+from veadk.utils.logger import get_logger
+from veadk.utils.volcengine_sign import ve_request
+
+logger = get_logger(__name__)
+
+
+def web_search(query: str, tool_context: ToolContext) -> list[str]:
+    """Search a query in websites.
+
+    Args:
+        query: The query to search.
+
+    Returns:
+        A list of result documents.
+    """
+    ak = tool_context.state.get("VOLCENGINE_ACCESS_KEY")
+    sk = tool_context.state.get("VOLCENGINE_SECRET_KEY")
+    session_token = ""
+
+    if not (ak and sk):
+        logger.debug("Get AK/SK from tool context failed.")
+        ak = os.getenv("VOLCENGINE_ACCESS_KEY")
+        sk = os.getenv("VOLCENGINE_SECRET_KEY")
+        if not (ak and sk):
+            logger.debug("Get AK/SK from environment variables failed.")
+            credential = get_credential_from_vefaas_iam()
+            ak = credential.access_key_id
+            sk = credential.secret_access_key
+            session_token = credential.session_token
+        else:
+            logger.debug("Successfully get AK/SK from environment variables.")
+    else:
+        logger.debug("Successfully get AK/SK from tool context.")
+
+    response = ve_request(
+        request_body={
+            "Query": query,
+            "SearchType": "web",
+            "Count": 5,
+            "NeedSummary": True,
+        },
+        action="WebSearch",
+        ak=ak,
+        sk=sk,
+        service="volc_torchlight_api",
+        version="2025-01-01",
+        region="cn-beijing",
+        host="mercury.volcengineapi.com",
+        header={"X-Security-Token": session_token},
+    )
+
+    try:
+        results: list = response["Result"]["WebResults"]
+        final_results = []
+        for result in results:
+            final_results.append(result["Summary"].strip())
+        return final_results
+    except Exception as e:
+        logger.error(f"Web search failed {e}, response body: {response}")
+        return [response]

veadk/tools/demo_tools.py

@@ -0,0 +1,58 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# 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.
+
+
+def get_city_weather(city: str) -> dict[str, str]:
+    """Retrieves the weather information of a given city. the args must in English"""
+    fixed_weather = {
+        "beijing": {"condition": "Sunny", "temperature": 25},
+        "shanghai": {"condition": "Cloudy", "temperature": 22},
+        "guangzhou": {"condition": "Rainy", "temperature": 28},
+        "shenzhen": {"condition": "Partly cloudy", "temperature": 29},
+        "chengdu": {"condition": "Windy", "temperature": 20},
+        "hangzhou": {"condition": "Snowy", "temperature": -2},
+        "wuhan": {"condition": "Humid", "temperature": 26},
+        "chongqing": {"condition": "Hazy", "temperature": 30},
+        "xi'an": {"condition": "Cool", "temperature": 18},
+        "nanjing": {"condition": "Hot", "temperature": 32},
+    }
+
+    city = city.lower().strip()
+    if city in fixed_weather:
+        info = fixed_weather[city]
+        return {"result": f"{info['condition']}, {info['temperature']}°C"}
+    else:
+        return {"result": f"Weather information not found for {city}"}
+
+
+def get_location_weather(city: str) -> dict[str, str]:
+    """Retrieves the weather information of a given city. the args must in English"""
+    import random
+
+    condition = random.choice(
+        [
+            "Sunny",
+            "Cloudy",
+            "Rainy",
+            "Partly cloudy",
+            "Windy",
+            "Snowy",
+            "Humid",
+            "Hazy",
+            "Cool",
+            "Hot",
+        ]
+    )
+    temperature = random.randint(-10, 40)
+    return {"result": f"{condition}, {temperature}°C"}

veadk/tools/load_knowledgebase_tool.py

@@ -0,0 +1,149 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# 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 __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import wrapt
+from google.adk.tools.function_tool import FunctionTool
+from google.adk.tools.tool_context import ToolContext
+from google.genai import types
+from pydantic import BaseModel, Field
+from typing_extensions import override
+
+from veadk.knowledgebase import KnowledgeBase
+from veadk.knowledgebase.entry import KnowledgebaseEntry
+from veadk.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+if TYPE_CHECKING:
+    from google.adk.models.llm_request import LlmRequest
+
+
+knowledgebase: KnowledgeBase | None = None
+
+
+class LoadKnowledgebaseResponse(BaseModel):
+    knowledges: list[KnowledgebaseEntry] = Field(default_factory=list)
+
+
+class SearchKnowledgebaseResponse(BaseModel):
+    """Represents the response from a knowledgebase search.
+
+    Attributes:
+        knowledges: A list of knowledgebase entries that relate to the search query.
+    """
+
+    knowledges: list[KnowledgebaseEntry] = Field(default_factory=list)
+
+
+async def search_knowledgebase(
+    self, query: str, app_name: str
+) -> SearchKnowledgebaseResponse:
+    """Searches the knowledgebase of the current user."""
+    if isinstance(knowledgebase, KnowledgeBase):
+        entry_list = knowledgebase.search(query)
+        return SearchKnowledgebaseResponse(knowledges=entry_list)
+    else:
+        return SearchKnowledgebaseResponse(knowledges=[])
+
+
+@wrapt.when_imported("google.adk.tools.tool_context")
+def on_tool_context_imported(module):
+    class_ = getattr(module, "ToolContext", None)
+    if not class_:
+        raise ImportError("Could not find ToolContext in module")
+
+    if not hasattr(class_, "search_knowledgebase"):
+        class_.search_knowledgebase = search_knowledgebase
+
+
+async def load_knowledgebase(
+    query: str, tool_context: ToolContext
+) -> LoadKnowledgebaseResponse:
+    """Loads the knowledgebase for the user.
+
+    Args:
+      query: The query to load the knowledgebase for.
+
+    Returns:
+      A list of knowledgebase results.
+    """
+
+    search_knowledgebase_response = await tool_context.search_knowledgebase(  # type: ignore[attr-defined]
+        query, tool_context._invocation_context.app_name
+    )
+    return LoadKnowledgebaseResponse(
+        knowledges=search_knowledgebase_response.knowledges
+    )
+
+
+class LoadKnowledgebaseTool(FunctionTool):
+    """A tool that loads the common knowledgebase.
+
+    In the future, we will support multiple knowledgebase based on different user.
+    """
+
+    def __init__(self):
+        super().__init__(load_knowledgebase)
+        global knowledgebase
+        if knowledgebase is None:
+            logger.info(
+                "Get global knowledgebase instance failed, failed to set knowledgebase tool backend."
+            )
+        else:
+            if not self.custom_metadata:
+                self.custom_metadata = {}
+            self.custom_metadata["backend"] = knowledgebase.backend
+
+    @override
+    def _get_declaration(self) -> types.FunctionDeclaration | None:
+        return types.FunctionDeclaration(
+            name=self.name,
+            description=self.description,
+            parameters=types.Schema(
+                type=types.Type.OBJECT,
+                properties={
+                    "query": types.Schema(
+                        type=types.Type.STRING,
+                    )
+                },
+                required=["query"],
+            ),
+        )
+
+    @override
+    async def process_llm_request(
+        self,
+        *,
+        tool_context: ToolContext,
+        llm_request: LlmRequest,
+    ) -> None:
+        await super().process_llm_request(
+            tool_context=tool_context, llm_request=llm_request
+        )
+        # Tell the model about the knowledgebase.
+        llm_request.append_instructions(
+            [
+                """
+You have a knowledgebase. You can use it to answer questions. If any questions need
+you to look up the knowledgebase, you should call load_knowledgebase function with a query.
+"""
+            ]
+        )
+
+
+load_knowledgebase_tool = LoadKnowledgebaseTool()

veadk/tools/sandbox/__init__.py

@@ -0,0 +1,13 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# 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.

veadk/tools/sandbox/browser_sandbox.py

@@ -0,0 +1,37 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# 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 google.adk.tools.mcp_tool.mcp_toolset import MCPToolset
+
+from veadk.config import getenv
+from veadk.utils.mcp_utils import get_mcp_params
+
+url = getenv("TOOL_BROWSER_SANDBOX_URL")
+
+
+browser_sandbox = MCPToolset(connection_params=get_mcp_params(url=url))
+
+# browser_sandbox = ...
+
+
+# def browser_use(prompt: str) -> str:
+#     """Using the remote browser sandbox to according to the prompt.
+
+#     Args:
+#         prompt (str): The prompt to be used.
+
+#     Returns:
+#         str: The response from the sandbox.
+#     """
+#     ...

veadk/tools/sandbox/code_sandbox.py

@@ -0,0 +1,40 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# 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 google.adk.tools.mcp_tool.mcp_toolset import MCPToolset
+
+from veadk.config import getenv
+from veadk.utils.mcp_utils import get_mcp_params
+
+url = getenv("TOOL_CODE_SANDBOX_URL")
+
+
+code_sandbox = MCPToolset(connection_params=get_mcp_params(url=url))
+
+# code_sandbox = ...
+
+
+# def code_execution(code: str, language: str) -> str:
+#     """Execute code in sandbox.
+
+#     Args:
+#         code (str): The code to be executed.
+#         language (str): The language of the code.
+
+#     Returns:
+#         str: The response from the sandbox.
+#     """
+
+#     res = code_sandbox(code, language)
+#     return res

veadk/tools/sandbox/computer_sandbox.py

@@ -0,0 +1,34 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# 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 google.adk.tools.mcp_tool.mcp_toolset import MCPToolset
+
+from veadk.config import getenv
+from veadk.utils.mcp_utils import get_mcp_params
+
+url = getenv("TOOL_COMPUTER_SANDBOX_URL")
+
+
+computer_sandbox = MCPToolset(connection_params=get_mcp_params(url=url))
+
+# def computer_use(prompt: str) -> str:
+#     """Using the remote computer sandbox to according to the prompt.
+
+#     Args:
+#         prompt (str): The prompt to be used.
+
+#     Returns:
+#         str: The response from the sandbox.
+#     """
+#     ...

veadk/tracing/__init__.py

@@ -0,0 +1,13 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# 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.

veadk/tracing/base_tracer.py

@@ -0,0 +1,58 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# 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 ABC, abstractmethod
+
+from veadk.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class BaseTracer(ABC):
+    """Abstract base class for implementing tracing functionality in VeADK agents.
+
+    BaseTracer provides the foundation for collecting, managing, and exporting
+    trace data from agent execution sessions. It defines the interface that all
+    concrete tracer implementations must follow, enabling pluggable tracing
+    backends for different observability platforms.
+
+    Attributes:
+        name: Unique identifier for this tracer instance
+        _trace_id: Internal trace identifier for current execution context
+        _trace_file_path: Path to the current trace data file
+    """
+
+    def __init__(self, name: str):
+        """Initialize a new BaseTracer instance.
+
+        Args:
+            name: Unique identifier for this tracer instance.
+        """
+        self.name = name
+        self._trace_id = "<unknown_trace_id>"
+        self._trace_file_path = "<unknown_trace_file_path>"
+
+    @abstractmethod
+    def dump(self, user_id: str, session_id: str, path: str) -> str:
+        """Dump the collected trace data to a local file.
+
+        This method must be implemented by concrete tracer classes to export
+        trace data in a format suitable for analysis or storage.
+
+        Args:
+            user_id: User identifier for trace organization and file naming
+            session_id: Session identifier for filtering and organizing spans
+            path: Directory path for the output file
+        """
+        ...

veadk/tracing/telemetry/__init__.py

@@ -0,0 +1,13 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# 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.

veadk/tracing/telemetry/attributes/attributes.py

@@ -0,0 +1,29 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# 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 veadk.tracing.telemetry.attributes.extractors.common_attributes_extractors import (
+    COMMON_ATTRIBUTES,
+)
+from veadk.tracing.telemetry.attributes.extractors.llm_attributes_extractors import (
+    LLM_ATTRIBUTES,
+)
+from veadk.tracing.telemetry.attributes.extractors.tool_attributes_extractors import (
+    TOOL_ATTRIBUTES,
+)
+
+ATTRIBUTES = {
+    "common": COMMON_ATTRIBUTES,
+    "llm": LLM_ATTRIBUTES,
+    "tool": TOOL_ATTRIBUTES,
+}