veadk-python 0.1.0__py3-none-any.whl

veadk/cloud/cloud_agent_engine.py

@@ -0,0 +1,144 @@
+# 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 os
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel
+
+from veadk.cli.services.vefaas import VeFaaS
+from veadk.cloud.cloud_app import CloudApp
+from veadk.config import getenv
+from veadk.utils.logger import get_logger
+from veadk.utils.misc import formatted_timestamp
+
+logger = get_logger(__name__)
+
+
+class CloudAgentEngine(BaseModel):
+    volcengine_access_key: str = getenv("VOLCENGINE_ACCESS_KEY")
+    volcengine_secret_key: str = getenv("VOLCENGINE_SECRET_KEY")
+    region: str = "cn-beijing"
+
+    def model_post_init(self, context: Any, /) -> None:
+        self._vefaas_service = VeFaaS(
+            access_key=self.volcengine_access_key,
+            secret_key=self.volcengine_secret_key,
+            region=self.region,
+        )
+
+    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
+        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"
+            )
+            import shutil
+
+            shutil.copy(template_app_py, os.path.join(path, "app.py"))
+
+        if os.path.exists(os.path.join(path, "run.sh")):
+            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"
+            )
+            import shutil
+
+            shutil.copy(template_run_sh, os.path.join(path, "run.sh"))
+
+    def deploy(
+        self,
+        path: str,
+        name: str,
+        gateway_name: str = "",
+        gateway_service_name: str = "",
+        gateway_upstream_name: str = "",
+    ) -> CloudApp:
+        """Deploy local agent project to Volcengine FaaS platform.
+
+        Args:
+            path (str): Local agent project path.
+            name (str): Volcengine FaaS function name.
+
+        Returns:
+            str: Volcengine FaaS function endpoint.
+        """
+        # convert `path` to absolute path
+        path = str(Path(path).resolve())
+        self._prepare(path, name)
+
+        if not gateway_name:
+            gateway_name = f"{name}-gw-{formatted_timestamp()}"
+        if not gateway_service_name:
+            gateway_service_name = f"{name}-gw-svr-{formatted_timestamp()}"
+        if not gateway_upstream_name:
+            gateway_upstream_name = f"{name}-gw-us-{formatted_timestamp()}"
+
+        try:
+            vefaas_application_url, app_id, function_id = self._vefaas_service.deploy(
+                path=path,
+                name=name,
+                gateway_name=gateway_name,
+                gateway_service_name=gateway_service_name,
+                gateway_upstream_name=gateway_upstream_name,
+            )
+            _ = function_id  # for future use
+
+            return CloudApp(
+                name=name,
+                endpoint=vefaas_application_url,
+                app_id=app_id,
+            )
+        except Exception as e:
+            raise ValueError(
+                f"Failed to deploy local agent project to Volcengine FaaS platform. Error: {e}"
+            )
+
+    def remove(self, app_name: str):
+        confirm = input(f"Confirm delete cloud app {app_name}? (y/N): ")
+        if confirm.lower() != "y":
+            print("Delete cancelled.")
+            return
+        else:
+            app_id = self._vefaas_service.find_app_id_by_name(app_name)
+            self._vefaas_service.delete(app_id)

veadk/cloud/cloud_app.py

@@ -0,0 +1,123 @@
+# 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
+from uuid import uuid4
+
+import httpx
+from a2a.client import A2ACardResolver, A2AClient
+from a2a.types import AgentCard, Message, MessageSendParams, SendMessageRequest
+
+from veadk.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class CloudApp:
+    """CloudApp class.
+
+    Args:
+        name (str): The name of the cloud app.
+        endpoint (str): The endpoint of the cloud app.
+        use_agent_card (bool): Whether to use agent card to invoke agent. If True, the client will post to the url in agent card. Otherwise, the client will post to the endpoint directly. Default False (cause the agent card and agent usually use the same endpoint).
+    """
+
+    def __init__(
+        self,
+        name: str,
+        endpoint: str,
+        app_id: str,
+        use_agent_card: bool = False,
+    ):
+        self.endpoint = endpoint
+        self.app_id = app_id
+        self.name = name
+        self.use_agent_card = use_agent_card
+
+        if not endpoint.startswith("http") and not endpoint.startswith("https"):
+            raise ValueError(
+                f"Invalid endpoint: {endpoint}. The endpoint must start with `http` or `https`."
+            )
+
+        if use_agent_card:
+            logger.info(
+                "Use agent card to invoke agent. The agent endpoint will use the `url` in agent card."
+            )
+
+        self.httpx_client = httpx.AsyncClient()
+
+    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
+                )
+
+                final_agent_card_to_use: AgentCard | None = None
+                _public_card = (
+                    await resolver.get_agent_card()
+                )  # Fetches from default public path
+                final_agent_card_to_use = _public_card
+
+                return A2AClient(
+                    httpx_client=self.httpx_client, agent_card=final_agent_card_to_use
+                )
+        else:
+            return A2AClient(httpx_client=self.httpx_client, url=self.endpoint)
+
+    def delete_self(self, volcengine_ak: str, volcengine_sk: str):
+        confirm = input(f"Confirm delete cloud app {self.app_id}? (y/N): ")
+        if confirm.lower() != "y":
+            print("Delete cancelled.")
+            return
+        else:
+            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...")
+
+    async def message_send(
+        self, message: str, session_id: str, user_id: str, timeout: float = 600.0
+    ) -> Message | None:
+        """
+        timeout is in seconds, default 600s (10 minutes)
+        """
+        a2a_client = await self._get_a2a_client()
+
+        async with self.httpx_client:
+            send_message_payload: dict[str, Any] = {
+                "message": {
+                    "role": "user",
+                    "parts": [{"type": "text", "text": message}],
+                    "messageId": uuid4().hex,
+                },
+                "metadata": {
+                    "user_id": user_id,
+                    "session_id": session_id,
+                },
+            }
+            try:
+                message_send_request = SendMessageRequest(
+                    id=uuid4().hex,
+                    params=MessageSendParams(**send_message_payload),
+                )
+                res = await a2a_client.send_message(
+                    message_send_request,
+                    http_kwargs={"timeout": httpx.Timeout(timeout)},
+                )
+                return res.root.result
+            except Exception as e:
+                print(e)
+                return None

veadk/cloud/template/app.py

@@ -0,0 +1,30 @@
+# 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 os
+
+from config import AGENT, APP_NAME, SHORT_TERM_MEMORY, TRACERS
+
+from veadk.a2a.ve_a2a_server import init_app
+
+SERVER_HOST = os.getenv("SERVER_HOST")
+
+AGENT.tracers = TRACERS
+
+app = init_app(
+    server_url=SERVER_HOST,
+    app_name=APP_NAME,
+    agent=AGENT,
+    short_term_memory=SHORT_TERM_MEMORY,
+)

veadk/cloud/template/config.py

@@ -0,0 +1,55 @@
+# 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 os
+
+from veadk import Agent
+from veadk.memory.short_term_memory import ShortTermMemory
+from veadk.tracing.base_tracer import BaseTracer
+from veadk.tracing.telemetry.opentelemetry_tracer import OpentelemetryTracer
+
+# =============
+# Generated by VeADK, do not edit!!!
+# =============
+TRACERS: list[BaseTracer] = []
+
+exporters = []
+if os.getenv("VEADK_TRACER_APMPLUS") == "true":
+    from veadk.tracing.telemetry.exporters.apmplus_exporter import APMPlusExporter
+
+    exporters.append(APMPlusExporter())
+
+if os.getenv("VEADK_TRACER_COZELOOP") == "true":
+    from veadk.tracing.telemetry.exporters.cozeloop_exporter import CozeloopExporter
+
+    exporters.append(CozeloopExporter())
+
+if os.getenv("VEADK_TRACER_TLS") == "true":
+    from veadk.tracing.telemetry.exporters.tls_exporter import TLSExporter
+
+    exporters.append(TLSExporter())
+
+TRACERS.append(OpentelemetryTracer(exporters=exporters))
+
+# =============
+# Required [you can edit here]
+# =============
+APP_NAME: str = ...  # <--- export your app name
+AGENT: Agent = ...  # <--- export your agent
+SHORT_TERM_MEMORY: ShortTermMemory = ...  # <--- export your short term memory
+
+# =============
+# Optional
+# =============
+# Other global variables

veadk/config.py

@@ -0,0 +1,131 @@
+# 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 os
+from typing import Any, Dict, List, MutableMapping, Tuple
+
+from dotenv import find_dotenv
+from pydantic_settings import (
+    BaseSettings,
+    InitSettingsSource,
+    PydanticBaseSettingsSource,
+    SettingsConfigDict,
+    YamlConfigSettingsSource,
+)
+
+settings = None
+veadk_environments = {}
+
+
+def flatten_dict(
+    d: MutableMapping[str, Any], parent_key: str = "", sep: str = "_"
+) -> Dict[str, Any]:
+    """Flatten a nested dictionary, using a separator in the keys.
+    Useful for pydantic_v1 models with nested fields -- first use
+        dct = mdl.model_dump()
+    to get a nested dictionary, then use this function to flatten it.
+    """
+    items: List[Tuple[str, Any]] = []
+    for k, v in d.items():
+        new_key = f"{parent_key}{sep}{k}" if parent_key else k
+        if isinstance(v, MutableMapping):
+            items.extend(flatten_dict(v, new_key, sep=sep).items())
+        else:
+            items.append((new_key, v))
+    return dict(items)
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        yaml_file=find_dotenv(filename="config.yaml", usecwd=True), extra="allow"
+    )
+
+    @classmethod
+    def settings_customise_sources(
+        cls,
+        settings_cls: type[BaseSettings],
+        init_settings: PydanticBaseSettingsSource,
+        env_settings: PydanticBaseSettingsSource,
+        dotenv_settings: PydanticBaseSettingsSource,
+        file_secret_settings: PydanticBaseSettingsSource,
+    ) -> tuple[PydanticBaseSettingsSource, ...]:
+        yaml_source = YamlConfigSettingsSource(settings_cls)
+        raw_data = yaml_source()
+        flat_data = flatten_dict(raw_data)
+
+        init_source = InitSettingsSource(settings_cls, flat_data)
+        return (
+            init_source,
+            env_settings,
+            dotenv_settings,
+            file_secret_settings,
+        )
+
+
+def prepare_settings():
+    path = find_dotenv(filename="config.yaml", usecwd=True)
+
+    if path == "" or path is None or not os.path.exists(path):
+        # logger.warning(
+        #     "Default and recommanded config file `config.yaml` not found. Please put it in the root directory of your project."
+        # )
+        pass
+    else:
+        # logger.info(f"Loading config file from {path}")
+        global settings
+        settings = Settings()
+
+        for k, v in settings.model_dump().items():
+            global veadk_environments
+
+            k = k.upper()
+            if k in os.environ:
+                veadk_environments[k] = os.environ[k]
+                continue
+            veadk_environments[k] = str(v)
+            os.environ[k] = str(v)
+
+
+prepare_settings()
+
+
+def get_envlist():
+    return os.environ.keys()
+
+
+def getenv(
+    env_name: str, default_value: Any = "", allow_false_values: bool = False
+) -> str:
+    """
+    Get environment variable.
+
+    Args:
+        env_name (str): The name of the environment variable.
+        default_value (str): The default value of the environment variable.
+        allow_false_values (bool, optional): Whether to allow the environment variable to be None or false values. Defaults to False.
+
+    Returns:
+        str: The value of the environment variable.
+    """
+    value = os.getenv(env_name, default_value)
+
+    if allow_false_values:
+        return value
+
+    if value:
+        return value
+    else:
+        raise ValueError(
+            f"The environment variable `{env_name}` not exists. Please set this in your environment variable or config.yaml."
+        )

veadk/consts.py

@@ -0,0 +1,17 @@
+# 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.
+
+DEFAULT_MODEL_AGENT_NAME = "doubao-seed-1-6-250615"
+DEFALUT_MODEL_AGENT_PROVIDER = "openai"
+DEFAULT_MODEL_AGENT_API_BASE = "https://ark.cn-beijing.volces.com/api/v3/"

veadk/database/__init__.py

@@ -0,0 +1,17 @@
+# 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 .database_factory import DatabaseFactory
+
+__all__ = ["DatabaseFactory"]

veadk/database/base_database.py

@@ -0,0 +1,45 @@
+# 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 typing import Any
+
+
+class DatabaseType:
+    LOCAL = "local"
+    RELATIONAL = "relational"
+    VECTOR = "vector"
+    KV = "kv"
+
+
+class BaseDatabase(ABC):
+    """Base class for database.
+
+    Args:
+        type: type of the database
+
+    Note:
+        No `update` function support currently.
+    """
+
+    def __init__(self):
+        pass
+
+    def add(self, texts: list[Any], **kwargs: Any): ...
+
+    @abstractmethod
+    def delete(self, **kwargs: Any): ...
+
+    @abstractmethod
+    def query(self, query: str, **kwargs: Any) -> list[str]: ...

veadk/database/database_factory.py

@@ -0,0 +1,80 @@
+# 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.utils.logger import get_logger
+
+from .base_database import BaseDatabase
+
+logger = get_logger(__name__)
+
+
+class DatabaseBackend:
+    OPENSEARCH = "opensearch"
+    LOCAL = "local"
+    MYSQL = "mysql"
+    REDIS = "redis"
+    VIKING = "viking"
+    VIKING_MEM = "viking_mem"
+
+    @classmethod
+    def get_attr(cls) -> set[str]:
+        return {
+            value
+            for attr, value in cls.__dict__.items()
+            if not attr.startswith("__") and attr != "get_attr"
+        }
+
+
+class DatabaseFactory:
+    @staticmethod
+    def create(backend: str, config=None) -> BaseDatabase:
+        if backend not in DatabaseBackend.get_attr():
+            logger.warning(f"Unknown backend: {backend}), change backend to `local`")
+            backend = "local"
+
+        if backend == DatabaseBackend.LOCAL:
+            from .local_database import LocalDataBase
+
+            return LocalDataBase()
+        if backend == DatabaseBackend.OPENSEARCH:
+            from .vector.opensearch_vector_database import OpenSearchVectorDatabase
+
+            return (
+                OpenSearchVectorDatabase()
+                if config is None
+                else OpenSearchVectorDatabase(config=config)
+            )
+        if backend == DatabaseBackend.MYSQL:
+            from .relational.mysql_database import MysqlDatabase
+
+            return MysqlDatabase() if config is None else MysqlDatabase(config=config)
+        if backend == DatabaseBackend.REDIS:
+            from .kv.redis_database import RedisDatabase
+
+            return RedisDatabase() if config is None else RedisDatabase(config=config)
+        if backend == DatabaseBackend.VIKING:
+            from .viking.viking_database import VikingDatabase
+
+            return VikingDatabase() if config is None else VikingDatabase(config=config)
+
+        if backend == DatabaseBackend.VIKING_MEM:
+            from .viking.viking_memory_db import VikingDatabaseMemory
+
+            return (
+                VikingDatabaseMemory()
+                if config is None
+                else VikingDatabaseMemory(config=config)
+            )
+        else:
+            raise ValueError(f"Unsupported database type: {backend}")

veadk/database/kv/__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.