veadk-python 0.1.0__py3-none-any.whl → 0.2.1__py3-none-any.whl

veadk/cloud/cloud_agent_engine.py

@@ -40,59 +40,59 @@ class CloudAgentEngine(BaseModel):
         )
 
     def _prepare(self, path: str, name: str):
-        # VeFaaS path check
-        if "_" in name:
-            raise ValueError(
-                f"Invalid Volcengine FaaS function name `{name}`, please use lowercase letters and numbers, or replace it with a `-` char."
-            )
-
-        # project path check
+        # basic check
         assert os.path.exists(path), f"Local agent project path `{path}` not exists."
         assert os.path.isdir(path), (
             f"Local agent project path `{path}` is not a directory."
         )
 
-        assert os.path.exists(os.path.join(path, "config.py")), (
-            f"Local agent project path `{path}` does not contain `config.py` file. Please prepare it according to veadk-python/cloud/template/config.py.example"
-        )
-
-        if os.path.exists(os.path.join(path, "app.py")):
-            logger.warning(
-                f"Local agent project path `{path}` contains an `app.py` file. Use your own `app.py` file may cause unexpected behavior."
-            )
-        else:
-            logger.info(
-                f"No `app.py` detected in local agent project path `{path}`. Prepare it."
-            )
-            template_app_py = (
-                f"{Path(__file__).resolve().parent.resolve()}/template/app.py"
+        # VeFaaS application/function name check
+        if "_" in name:
+            raise ValueError(
+                f"Invalid Volcengine FaaS function name `{name}`, please use lowercase letters and numbers, or replace it with a `-` char."
             )
-            import shutil
 
-            shutil.copy(template_app_py, os.path.join(path, "app.py"))
+        # project structure check
+        assert os.path.exists(os.path.join(path, "agent.py")), (
+            f"Local agent project path `{path}` does not contain `agent.py` file. Please prepare it according to our document https://volcengine.github.io/veadk-python/deploy.html"
+        )
 
-        if os.path.exists(os.path.join(path, "run.sh")):
+        if not os.path.exists(os.path.join(path, "config.yaml")):
             logger.warning(
-                f"Local agent project path `{path}` contains a `run.sh` file. Use your own `run.sh` file may cause unexpected behavior."
-            )
-        else:
-            logger.info(
-                f"No `run.sh` detected in local agent project path `{path}`. Prepare it."
-            )
-            template_run_sh = (
-                f"{Path(__file__).resolve().parent.resolve()}/template/run.sh"
+                f"Local agent project path `{path}` does not contain `config.yaml` file. Some important config items may not be set."
             )
-            import shutil
 
-            shutil.copy(template_run_sh, os.path.join(path, "run.sh"))
+        # prepare template files if not have
+        template_files = [
+            "app.py",
+            "studio_app.py",
+            "run.sh",
+            "requirements.txt",
+            "__init__.py",
+        ]
+        for template_file in template_files:
+            if os.path.exists(os.path.join(path, template_file)):
+                logger.warning(
+                    f"Local agent project path `{path}` contains a `{template_file}` file. Use your own `{template_file}` file may cause unexpected behavior."
+                )
+            else:
+                logger.info(
+                    f"No `{template_file}` detected in local agent project path `{path}`. Prepare it."
+                )
+                template_file_path = f"{Path(__file__).resolve().parent.resolve().parent.resolve()}/cli/services/vefaas/template/src/{template_file}"
+                import shutil
+
+                shutil.copy(template_file_path, os.path.join(path, template_file))
 
     def deploy(
         self,
+        application_name: str,
         path: str,
-        name: str,
         gateway_name: str = "",
         gateway_service_name: str = "",
         gateway_upstream_name: str = "",
+        use_studio: bool = False,
+        use_adk_web: bool = False,
     ) -> CloudApp:
         """Deploy local agent project to Volcengine FaaS platform.
 
@@ -103,21 +103,46 @@ class CloudAgentEngine(BaseModel):
         Returns:
             str: Volcengine FaaS function endpoint.
         """
+        assert not (use_studio and use_adk_web), (
+            "use_studio and use_adk_web can not be True at the same time."
+        )
+
+        # prevent deepeval writing operations
+        import veadk.config
+
+        veadk.config.veadk_environments["DEEPEVAL_TELEMETRY_OPT_OUT"] = "YES"
+
+        if use_studio:
+            veadk.config.veadk_environments["USE_STUDIO"] = "True"
+        else:
+            import veadk.config
+
+            veadk.config.veadk_environments["USE_STUDIO"] = "False"
+
+        if use_adk_web:
+            import veadk.config
+
+            veadk.config.veadk_environments["USE_ADK_WEB"] = "True"
+        else:
+            import veadk.config
+
+            veadk.config.veadk_environments["USE_ADK_WEB"] = "False"
+
         # convert `path` to absolute path
         path = str(Path(path).resolve())
-        self._prepare(path, name)
+        self._prepare(path, application_name)
 
         if not gateway_name:
-            gateway_name = f"{name}-gw-{formatted_timestamp()}"
+            gateway_name = f"{application_name}-gw-{formatted_timestamp()}"
         if not gateway_service_name:
-            gateway_service_name = f"{name}-gw-svr-{formatted_timestamp()}"
+            gateway_service_name = f"{application_name}-gw-svr-{formatted_timestamp()}"
         if not gateway_upstream_name:
-            gateway_upstream_name = f"{name}-gw-us-{formatted_timestamp()}"
+            gateway_upstream_name = f"{application_name}-gw-us-{formatted_timestamp()}"
 
         try:
             vefaas_application_url, app_id, function_id = self._vefaas_service.deploy(
                 path=path,
-                name=name,
+                name=application_name,
                 gateway_name=gateway_name,
                 gateway_service_name=gateway_service_name,
                 gateway_upstream_name=gateway_upstream_name,
@@ -125,9 +150,9 @@ class CloudAgentEngine(BaseModel):
             _ = function_id  # for future use
 
             return CloudApp(
-                name=name,
-                endpoint=vefaas_application_url,
-                app_id=app_id,
+                vefaas_application_name=application_name,
+                vefaas_endpoint=vefaas_application_url,
+                vefaas_application_id=app_id,
             )
         except Exception as e:
             raise ValueError(
@@ -142,3 +167,39 @@ class CloudAgentEngine(BaseModel):
         else:
             app_id = self._vefaas_service.find_app_id_by_name(app_name)
             self._vefaas_service.delete(app_id)
+
+    def update_function_code(
+        self,
+        application_name: str,
+        path: str,
+    ) -> CloudApp:
+        """Update existing agent project code while keeping the same URL.
+
+        Args:
+            application_name (str): Existing application name to update.
+            path (str): Local agent project path.
+
+        Returns:
+            CloudApp: Updated cloud app with same endpoint.
+        """
+        # convert `path` to absolute path
+        path = str(Path(path).resolve())
+        self._prepare(path, application_name)
+
+        try:
+            vefaas_application_url, app_id, function_id = (
+                self._vefaas_service._update_function_code(
+                    application_name=application_name,
+                    path=path,
+                )
+            )
+
+            return CloudApp(
+                vefaas_application_name=application_name,
+                vefaas_endpoint=vefaas_application_url,
+                vefaas_application_id=app_id,
+            )
+        except Exception as e:
+            raise ValueError(
+                f"Failed to update agent project on Volcengine FaaS platform. Error: {e}"
+            )

veadk/cloud/cloud_app.py

@@ -15,10 +15,12 @@
 from typing import Any
 from uuid import uuid4
 
+import json
 import httpx
 from a2a.client import A2ACardResolver, A2AClient
 from a2a.types import AgentCard, Message, MessageSendParams, SendMessageRequest
 
+from veadk.config import getenv
 from veadk.utils.logger import get_logger
 
 logger = get_logger(__name__)
@@ -35,19 +37,34 @@ class CloudApp:
 
     def __init__(
         self,
-        name: str,
-        endpoint: str,
-        app_id: str,
+        vefaas_application_name: str = "",
+        vefaas_endpoint: str = "",
+        vefaas_application_id: str = "",
         use_agent_card: bool = False,
     ):
-        self.endpoint = endpoint
-        self.app_id = app_id
-        self.name = name
+        self.vefaas_endpoint = vefaas_endpoint
+        self.vefaas_application_id = vefaas_application_id
+        self.vefaas_application_name = vefaas_application_name
         self.use_agent_card = use_agent_card
 
-        if not endpoint.startswith("http") and not endpoint.startswith("https"):
+        # vefaas must be set one of three
+        if (
+            not vefaas_endpoint
+            and not vefaas_application_id
+            and not vefaas_application_name
+        ):
             raise ValueError(
-                f"Invalid endpoint: {endpoint}. The endpoint must start with `http` or `https`."
+                "VeFaaS CloudAPP must be set one of endpoint, application_id, or application_name."
+            )
+
+        if not vefaas_endpoint:
+            self.vefaas_endpoint = self._get_vefaas_endpoint()
+
+        if not self.vefaas_endpoint.startswith(
+            "http"
+        ) and not self.vefaas_endpoint.startswith("https"):
+            raise ValueError(
+                f"Invalid endpoint: {vefaas_endpoint}. The endpoint must start with `http` or `https`."
             )
 
         if use_agent_card:
@@ -57,11 +74,39 @@ class CloudApp:
 
         self.httpx_client = httpx.AsyncClient()
 
+    def _get_vefaas_endpoint(
+        self,
+        volcengine_ak: str = getenv("VOLCENGINE_ACCESS_KEY"),
+        volcengine_sk: str = getenv("VOLCENGINE_SECRET_KEY"),
+    ) -> str:
+        from veadk.cli.services.vefaas.vefaas import VeFaaS
+
+        vefaas_client = VeFaaS(access_key=volcengine_ak, secret_key=volcengine_sk)
+        app = vefaas_client.get_application_details(
+            app_id=self.vefaas_application_id,
+            app_name=self.vefaas_application_name,
+        )
+        cloud_resource = json.loads(app["CloudResource"])
+        try:
+            vefaas_endpoint = cloud_resource["framework"]["url"]["system_url"]
+        except Exception as e:
+            raise ValueError(f"VeFaaS cloudAPP could not get endpoint. Error: {e}")
+        return vefaas_endpoint
+
+    def _get_vefaas_application_id_by_name(self) -> str:
+        if not self.vefaas_application_name:
+            raise ValueError(
+                "VeFaaS CloudAPP must be set application_name to get application_id."
+            )
+        # TODO(zakahan): get application id from vefaas application name
+        vefaas_application_id = ""
+        return vefaas_application_id
+
     async def _get_a2a_client(self) -> A2AClient:
         if self.use_agent_card:
             async with self.httpx_client as httpx_client:
                 resolver = A2ACardResolver(
-                    httpx_client=httpx_client, base_url=self.endpoint
+                    httpx_client=httpx_client, base_url=self.vefaas_endpoint
                 )
 
                 final_agent_card_to_use: AgentCard | None = None
@@ -74,10 +119,32 @@ class CloudApp:
                     httpx_client=self.httpx_client, agent_card=final_agent_card_to_use
                 )
         else:
-            return A2AClient(httpx_client=self.httpx_client, url=self.endpoint)
+            return A2AClient(httpx_client=self.httpx_client, url=self.vefaas_endpoint)
+
+    def update_self(
+        self,
+        volcengine_ak: str = getenv("VOLCENGINE_ACCESS_KEY"),
+        volcengine_sk: str = getenv("VOLCENGINE_SECRET_KEY"),
+    ):
+        if not volcengine_ak or not volcengine_sk:
+            raise ValueError("Volcengine access key and secret key must be set.")
+
+        # TODO(floritange): support update cloud app
+
+    def delete_self(
+        self,
+        volcengine_ak: str = getenv("VOLCENGINE_ACCESS_KEY"),
+        volcengine_sk: str = getenv("VOLCENGINE_SECRET_KEY"),
+    ):
+        if not volcengine_ak or not volcengine_sk:
+            raise ValueError("Volcengine access key and secret key must be set.")
+
+        if not self.vefaas_application_id:
+            self.vefaas_application_id = self._get_vefaas_application_id_by_name()
 
-    def delete_self(self, volcengine_ak: str, volcengine_sk: str):
-        confirm = input(f"Confirm delete cloud app {self.app_id}? (y/N): ")
+        confirm = input(
+            f"Confirm delete cloud app {self.vefaas_application_id}? (y/N): "
+        )
         if confirm.lower() != "y":
             print("Delete cancelled.")
             return
@@ -85,8 +152,8 @@ class CloudApp:
             from veadk.cli.services.vefaas.vefaas import VeFaaS
 
             vefaas_client = VeFaaS(access_key=volcengine_ak, secret_key=volcengine_sk)
-            vefaas_client.delete(self.app_id)
-            print(f"Cloud app {self.app_id} is deleting...")
+            vefaas_client.delete(self.vefaas_application_id)
+            print(f"Cloud app {self.vefaas_application_id} is deleting...")
 
     async def message_send(
         self, message: str, session_id: str, user_id: str, timeout: float = 600.0
@@ -119,5 +186,6 @@ class CloudApp:
                 )
                 return res.root.result
             except Exception as e:
+                # TODO(floritange): show error log on VeFaaS function
                 print(e)
                 return None

veadk/database/database_adapter.py

@@ -0,0 +1,280 @@
+# 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.
+
+import re
+import time
+from typing import BinaryIO, TextIO
+from veadk.database.base_database import BaseDatabase
+
+from veadk.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class KVDatabaseAdapter:
+    def __init__(self, client):
+        from veadk.database.kv.redis_database import RedisDatabase
+
+        self.client: RedisDatabase = client
+
+    def add(self, data: list[str], index: str):
+        logger.debug(f"Adding documents to Redis database: index={index}")
+
+        try:
+            for _data in data:
+                self.client.add(key=index, value=_data)
+            logger.debug(f"Added {len(data)} texts to Redis database: index={index}")
+        except Exception as e:
+            logger.error(
+                f"Failed to add data to Redis database: index={index} error={e}"
+            )
+            raise e
+
+    def query(self, query: str, index: str, top_k: int = 0) -> list[str]:
+        logger.debug(f"Querying Redis database: index={index} query={query}")
+
+        # ignore top_k, as KV search only return one result
+        _ = top_k
+
+        try:
+            result = self.client.query(key=index, query=query)
+            return result
+        except Exception as e:
+            logger.error(f"Failed to search from Redis: index={index} error={e}")
+            raise e
+
+
+class RelationalDatabaseAdapter:
+    def __init__(self, client):
+        from veadk.database.relational.mysql_database import MysqlDatabase
+
+        self.client: MysqlDatabase = client
+
+    def create_table(self, table_name: str):
+        logger.debug(f"Creating table for SQL database: table_name={table_name}")
+
+        sql = f"""
+            CREATE TABLE `{table_name}` (
+                `id` BIGINT AUTO_INCREMENT PRIMARY KEY,
+                `data` TEXT NOT NULL,
+                `created_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+            ) ENGINE=InnoDB DEFAULT CHARSET={self.client.config.charset};
+        """
+        self.client.add(sql)
+
+    def add(self, data: list[str], index: str):
+        logger.debug(
+            f"Adding documents to SQL database: table_name={index} data_len={len(data)}"
+        )
+
+        if not self.client.table_exists(index):
+            logger.warning(f"Table {index} does not exist, creating a new table.")
+            self.create_table(index)
+
+        for _data in data:
+            sql = f"""
+                INSERT INTO `{index}` (`data`)
+                VALUES (%s);
+                """
+            self.client.add(sql, params=(_data,))
+        logger.debug(f"Added {len(data)} texts to table {index}.")
+
+    def query(self, query: str, index: str, top_k: int) -> list[str]:
+        logger.debug(
+            f"Querying SQL database: table_name={index} query={query} top_k={top_k}"
+        )
+
+        if not self.client.table_exists(index):
+            logger.warning(
+                f"Querying SQL database, but table `{index}` does not exist, returning empty list."
+            )
+            return []
+
+        sql = f"""
+            SELECT `data` FROM `{index}` ORDER BY `created_at` DESC LIMIT {top_k};
+            """
+        results = self.client.query(sql)
+
+        return [item["data"] for item in results]
+
+
+class VectorDatabaseAdapter:
+    def __init__(self, client):
+        from veadk.database.vector.opensearch_vector_database import (
+            OpenSearchVectorDatabase,
+        )
+
+        self.client: OpenSearchVectorDatabase = client
+
+    def _validate_index(self, index: str):
+        """
+        Verify whether the string conforms to the naming rules of index_name in OpenSearch.
+        https://docs.opensearch.org/2.8/api-reference/index-apis/create-index/
+        """
+        if not (
+            isinstance(index, str)
+            and not index.startswith(("_", "-"))
+            and index.islower()
+            and re.match(r"^[a-z0-9_\-.]+$", index)
+        ):
+            raise ValueError(
+                "The index name does not conform to the naming rules of OpenSearch"
+            )
+
+    def add(self, data: list[str], index: str):
+        self._validate_index(index)
+
+        logger.debug(
+            f"Adding documents to vector database: index={index} data_len={len(data)}"
+        )
+
+        self.client.add(data, collection_name=index)
+
+    def query(self, query: str, index: str, top_k: int) -> list[str]:
+        logger.debug(
+            f"Querying vector database: collection_name={index} query={query} top_k={top_k}"
+        )
+
+        return self.client.query(
+            query=query,
+            collection_name=index,
+            top_k=top_k,
+        )
+
+
+class VikingDatabaseAdapter:
+    def __init__(self, client):
+        from veadk.database.viking.viking_database import VikingDatabase
+
+        self.client: VikingDatabase = client
+
+    def _validate_index(self, index: str):
+        """
+        Only English letters, numbers, and underscores (_) are allowed.
+        It must start with an English letter and cannot be empty. Length requirement: [1, 128].
+        For details, please see: https://www.volcengine.com/docs/84313/1254542?lang=zh
+        """
+        if not (
+            isinstance(index, str)
+            and 0 < len(index) <= 128
+            and re.fullmatch(r"^[a-zA-Z][a-zA-Z0-9_]*$", index)
+        ):
+            raise ValueError(
+                "The index name does not conform to the rules: it must start with an English letter, contain only letters, numbers, and underscores, and have a length of 1-128."
+            )
+
+    def get_or_create_collection(self, collection_name: str):
+        if not self.client.collection_exists(collection_name):
+            logger.warning(
+                f"Collection {collection_name} does not exist, creating a new collection."
+            )
+            self.client.create_collection(collection_name)
+
+        # After creation, it is necessary to wait for a while.
+        count = 0
+        while not self.client.collection_exists(collection_name):
+            print("here")
+            time.sleep(1)
+            count += 1
+            if count > 60:
+                raise TimeoutError(
+                    f"Collection {collection_name} not created after 50 seconds"
+                )
+
+    def add(
+        self, data: str | list[str] | TextIO | BinaryIO | bytes, index: str, **kwargs
+    ):
+        self._validate_index(index)
+
+        logger.debug(f"Adding documents to Viking database: collection_name={index}")
+
+        self.get_or_create_collection(index)
+        self.client.add(data, collection_name=index, **kwargs)
+
+    def query(self, query: str, index: str, top_k: int) -> list[str]:
+        self._validate_index(index)
+
+        logger.debug(f"Querying Viking database: collection_name={index} query={query}")
+
+        if not self.client.collection_exists(index):
+            return []
+
+        return self.client.query(query, collection_name=index, top_k=top_k)
+
+
+class VikingMemoryDatabaseAdapter:
+    def __init__(self, client):
+        from veadk.database.viking.viking_memory_db import VikingMemoryDatabase
+
+        self.client: VikingMemoryDatabase = client
+
+    def _validate_index(self, index: str):
+        if not (
+            isinstance(index, str)
+            and 1 <= len(index) <= 128
+            and re.fullmatch(r"^[a-zA-Z][a-zA-Z0-9_]*$", index)
+        ):
+            raise ValueError(
+                "The index name does not conform to the rules: it must start with an English letter, contain only letters, numbers, and underscores, and have a length of 1-128."
+            )
+
+    def add(self, data: list[str], index: str, **kwargs):
+        self._validate_index(index)
+
+        logger.debug(
+            f"Adding documents to Viking database memory: collection_name={index} data_len={len(data)}"
+        )
+
+        self.client.add(data, collection_name=index, **kwargs)
+
+    def query(self, query: str, index: str, top_k: int, **kwargs):
+        self._validate_index(index)
+
+        logger.debug(
+            f"Querying Viking database memory: collection_name={index} query={query} top_k={top_k}"
+        )
+
+        result = self.client.query(query, collection_name=index, top_k=top_k, **kwargs)
+        return result
+
+
+class LocalDatabaseAdapter:
+    def __init__(self, client):
+        from veadk.database.local_database import LocalDataBase
+
+        self.client: LocalDataBase = client
+
+    def add(self, data: list[str], **kwargs):
+        self.client.add(data)
+
+    def query(self, query: str, **kwargs):
+        return self.client.query(query, **kwargs)
+
+
+MAPPING = {
+    "RedisDatabase": KVDatabaseAdapter,
+    "MysqlDatabase": RelationalDatabaseAdapter,
+    "LocalDataBase": LocalDatabaseAdapter,
+    "VikingDatabase": VikingDatabaseAdapter,
+    "OpenSearchVectorDatabase": VectorDatabaseAdapter,
+    "VikingMemoryDatabase": VikingMemoryDatabaseAdapter,
+}
+
+
+def get_knowledgebase_database_adapter(database_client: BaseDatabase):
+    return MAPPING[type(database_client).__name__](client=database_client)
+
+
+def get_long_term_memory_database_adapter(database_client: BaseDatabase):
+    return MAPPING[type(database_client).__name__](client=database_client)

veadk/database/database_factory.py

@@ -69,12 +69,12 @@ class DatabaseFactory:
             return VikingDatabase() if config is None else VikingDatabase(config=config)
 
         if backend == DatabaseBackend.VIKING_MEM:
-            from .viking.viking_memory_db import VikingDatabaseMemory
+            from .viking.viking_memory_db import VikingMemoryDatabase
 
             return (
-                VikingDatabaseMemory()
+                VikingMemoryDatabase()
                 if config is None
-                else VikingDatabaseMemory(config=config)
+                else VikingMemoryDatabase(config=config)
             )
         else:
             raise ValueError(f"Unsupported database type: {backend}")