veadk-python 0.2.15__py3-none-any.whl → 0.2.17__py3-none-any.whl

veadk/cloud/cloud_agent_engine.py

@@ -22,7 +22,7 @@ from typing import Any
 from pydantic import BaseModel
 
 from veadk.cloud.cloud_app import CloudApp
-from veadk.config import getenv
+from veadk.config import getenv, veadk_environments
 from veadk.integrations.ve_faas.ve_faas import VeFaaS
 from veadk.utils.logger import get_logger
 from veadk.utils.misc import formatted_timestamp
@@ -31,11 +31,51 @@ logger = get_logger(__name__)
 
 
 class CloudAgentEngine(BaseModel):
+    """Manages cloud agent deployment and operations on Volcengine FaaS platform.
+
+    This class handles authentication with Volcengine, deploys local projects to FaaS,
+    updates function code, removes applications, and supports local testing.
+
+    Attributes:
+        volcengine_access_key (str): Access key for Volcengine authentication.
+            Defaults to VOLCENGINE_ACCESS_KEY environment variable.
+        volcengine_secret_key (str): Secret key for Volcengine authentication.
+            Defaults to VOLCENGINE_SECRET_KEY environment variable.
+        region (str): Region for Volcengine services. Defaults to "cn-beijing".
+        _vefaas_service (VeFaaS): Internal VeFaaS client instance, initialized post-creation.
+
+    Note:
+        Credentials must be set via environment variables for default behavior.
+        This class performs interactive confirmations for destructive operations like removal.
+
+    Examples:
+        ```python
+        from veadk.cloud.cloud_agent_engine import CloudAgentEngine
+        engine = CloudAgentEngine()
+        app = engine.deploy("test-app", "/path/to/local/project")
+        print(app.vefaas_endpoint)
+        ```
+    """
+
     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:
+        """Initializes the internal VeFaaS service after Pydantic model validation.
+
+        Creates a VeFaaS instance using the configured access key, secret key, and region.
+
+        Args:
+            self: The CloudAgentEngine instance.
+            context: Pydantic post-init context parameter (not used).
+
+        Returns:
+            None
+
+        Note:
+            This is a Pydantic lifecycle method, ensuring service readiness after init.
+        """
         self._vefaas_service = VeFaaS(
             access_key=self.volcengine_access_key,
             secret_key=self.volcengine_secret_key,
@@ -43,6 +83,25 @@ class CloudAgentEngine(BaseModel):
         )
 
     def _prepare(self, path: str, name: str):
+        """Prepares the local project for deployment by validating path and name.
+
+        Checks if the path exists and is a directory, validates application name format.
+
+        Args:
+            path (str): Full or relative path to the local agent project directory.
+            name (str): Intended VeFaaS application name.
+
+        Returns:
+            None
+
+        Raises:
+            AssertionError: If path does not exist or is not a directory.
+            ValueError: If name contains invalid characters like underscores.
+
+        Note:
+            Includes commented code for handling requirements.txt; not executed currently.
+            Called internally by deploy and update methods.
+        """
         # basic check
         assert os.path.exists(path), f"Local agent project path `{path}` not exists."
         assert os.path.isdir(path), (
@@ -73,10 +132,23 @@ class CloudAgentEngine(BaseModel):
         #     )
 
     def _try_launch_fastapi_server(self, path: str):
-        """Try to launch a fastapi server for tests according to user's configuration.
+        """Tries to start a FastAPI server locally for testing deployment readiness.
+
+        Runs the project's run.sh script and checks connectivity on port 8000.
 
         Args:
-            path (str): Local agent project path.
+            path (str): Path to the local project containing run.sh.
+
+        Returns:
+            None
+
+        Raises:
+            RuntimeError: If server startup times out after 30 seconds.
+
+        Note:
+            Sets _FAAS_FUNC_TIMEOUT environment to 900 seconds.
+            Streams output to console and terminates process after successful check.
+            Assumes run.sh launches server on 0.0.0.0:8000.
         """
         RUN_SH = f"{path}/run.sh"
 
@@ -128,33 +200,42 @@ class CloudAgentEngine(BaseModel):
         use_adk_web: bool = False,
         local_test: bool = False,
     ) -> CloudApp:
-        """Deploy local agent project to Volcengine FaaS platform.
+        """Deploys a local agent project to Volcengine FaaS, creating necessary resources.
+
+        Prepares project, optionally tests locally, deploys via VeFaaS, and returns app instance.
 
         Args:
-            application_name (str): Expected VeFaaS application name.
-            path (str): Local agent project path.
-            gateway_name (str): Gateway name.
-            gateway_service_name (str): Gateway service name.
-            gateway_upstream_name (str): Gateway upstream name.
-            use_adk_web (bool): Whether to use ADK Web.
-            local_test (bool): Whether to run local test for FastAPI Server.
+            application_name (str): Unique name for the VeFaaS application.
+            path (str): Local directory path of the agent project.
+            gateway_name (str, optional): Custom gateway resource name. Defaults to timestamped.
+            gateway_service_name (str, optional): Custom service name. Defaults to timestamped.
+            gateway_upstream_name (str, optional): Custom upstream name. Defaults to timestamped.
+            use_adk_web (bool): Enable ADK Web configuration. Defaults to False.
+            local_test (bool): Perform FastAPI server test before deploy. Defaults to False.
 
         Returns:
-            CloudApp: The deployed cloud application instance.
+            CloudApp: Deployed application with endpoint, name, and ID.
+
+        Raises:
+            ValueError: On deployment failure, such as invalid config or VeFaaS errors.
+
+        Note:
+            Converts path to absolute; sets telemetry opt-out and ADK Web env vars.
+            Generates default gateway names if not specified.
+
+        Examples:
+            ```python
+            app = engine.deploy("my-agent", "./agent-project", local_test=True)
+            print(f"Deployed at: {app.vefaas_endpoint}")
+            ```
         """
         # prevent deepeval writing operations
-        import veadk.config
-
-        veadk.config.veadk_environments["DEEPEVAL_TELEMETRY_OPT_OUT"] = "YES"
+        veadk_environments["DEEPEVAL_TELEMETRY_OPT_OUT"] = "YES"
 
         if use_adk_web:
-            import veadk.config
-
-            veadk.config.veadk_environments["USE_ADK_WEB"] = "True"
+            veadk_environments["USE_ADK_WEB"] = "True"
         else:
-            import veadk.config
-
-            veadk.config.veadk_environments["USE_ADK_WEB"] = "False"
+            veadk_environments["USE_ADK_WEB"] = "False"
 
         # convert `path` to absolute path
         path = str(Path(path).resolve())
@@ -191,6 +272,28 @@ class CloudAgentEngine(BaseModel):
             )
 
     def remove(self, app_name: str):
+        """Deletes a deployed cloud application after user confirmation.
+
+        Locates app by name, confirms, and issues delete via VeFaaS.
+
+        Args:
+            app_name (str): Name of the application to remove.
+
+        Returns:
+            None
+
+        Raises:
+            ValueError: If application not found by name.
+
+        Note:
+            Interactive prompt required; cancels on non-'y' input.
+            Deletion is processed asynchronously by VeFaaS.
+
+        Examples:
+            ```python
+            engine.remove("my-agent")
+            ```
+        """
         confirm = input(f"Confirm delete cloud app {app_name}? (y/N): ")
         if confirm.lower() != "y":
             print("Delete cancelled.")
@@ -208,14 +311,28 @@ class CloudAgentEngine(BaseModel):
         application_name: str,
         path: str,
     ) -> CloudApp:
-        """Update existing agent project code while keeping the same URL.
+        """Updates the code in an existing VeFaaS application without changing endpoint.
+
+        Prepares new code from local path and updates function via VeFaaS.
 
         Args:
-            application_name (str): Existing application name to update.
-            path (str): Local agent project path.
+            application_name (str): Name of the existing application to update.
+            path (str): Local path containing updated project files.
 
         Returns:
-            CloudApp: Updated cloud app with same endpoint.
+            CloudApp: Updated application instance with same endpoint.
+
+        Raises:
+            ValueError: If update fails due to preparation or VeFaaS issues.
+
+        Note:
+            Preserves gateway and other resources; only function code is updated.
+            Path is resolved to absolute before processing.
+
+        Examples:
+            ```python
+            updated_app = engine.update_function_code("my-agent", "./updated-project")
+            ```
         """
         # convert `path` to absolute path
         path = str(Path(path).resolve())

veadk/cloud/cloud_app.py

@@ -23,17 +23,37 @@ from a2a.types import AgentCard, Message, MessageSendParams, SendMessageRequest
 
 from veadk.config import getenv
 from veadk.utils.logger import get_logger
+from veadk.integrations.ve_faas.ve_faas import VeFaaS
 
 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).
+    """Represents a deployed cloud agent application on Volcengine FaaS platform.
+
+    This class facilitates interaction with the deployed agent via A2A protocol,
+    supports self-management like update and delete, and handles endpoint resolution.
+
+    It uses HTTP client for async communications.
+
+    Attributes:
+        vefaas_application_name (str): Name of the VeFaaS application. Defaults to "".
+        vefaas_endpoint (str): URL for accessing the application. Resolved if not provided.
+        vefaas_application_id (str): Unique identifier of the application. Defaults to "".
+        use_agent_card (bool): Flag to resolve endpoint via agent card. Defaults to False.
+        httpx_client (httpx.AsyncClient): Async HTTP client for requests.
+
+    Note:
+        At least one of name, endpoint, or ID must be provided during init.
+        Agent card mode fetches card from the endpoint's public path.
+
+    Examples:
+        ```python
+        from veadk.cloud.cloud_app import CloudApp
+        app = CloudApp(vefaas_endpoint="https://my-agent.volcengine.com")
+        response = await app.message_send("Query", "session-1", "user-123")
+        print(response.message_id)
+        ```
     """
 
     def __init__(
@@ -43,6 +63,31 @@ class CloudApp:
         vefaas_application_id: str = "",
         use_agent_card: bool = False,
     ):
+        """Initializes the CloudApp with VeFaaS application details.
+
+        Sets attributes, validates inputs, resolves endpoint if missing, and creates HTTP client.
+
+        Args:
+            vefaas_application_name (str, optional): Application name for lookup. Defaults to "".
+            vefaas_endpoint (str, optional): Direct endpoint URL. Defaults to "".
+            vefaas_application_id (str, optional): Application ID for lookup. Defaults to "".
+            use_agent_card (bool): Use agent card to determine invocation URL. Defaults to False.
+
+        Returns:
+            None
+
+        Raises:
+            ValueError: If no app identifiers provided or endpoint lacks http/https prefix.
+
+        Note:
+            Logs info if agent card mode enabled.
+            Endpoint is fetched via _get_vefaas_endpoint if not set.
+
+        Examples:
+            ```python
+            app = CloudApp(vefaas_application_id="app-123", use_agent_card=True)
+            ```
+        """
         self.vefaas_endpoint = vefaas_endpoint
         self.vefaas_application_id = vefaas_application_id
         self.vefaas_application_name = vefaas_application_name
@@ -82,6 +127,29 @@ class CloudApp:
         volcengine_ak: str = getenv("VOLCENGINE_ACCESS_KEY"),
         volcengine_sk: str = getenv("VOLCENGINE_SECRET_KEY"),
     ) -> str:
+        """Fetches the application endpoint from VeFaaS details if not directly provided.
+
+        Uses VeFaaS client to get app info and parse CloudResource JSON for URL.
+
+        Args:
+            volcengine_ak (str, optional): Volcengine access key. Defaults to env var.
+            volcengine_sk (str, optional): Volcengine secret key. Defaults to env var.
+
+        Returns:
+            str: The system URL from CloudResource or empty string on failure.
+
+        Raises:
+            ValueError: If application not found by ID or name.
+
+        Note:
+            Logs warning if JSON parsing fails; returns empty on error.
+            Called during init if endpoint missing.
+
+        Examples:
+            ```python
+            endpoint = app._get_vefaas_endpoint("custom-ak", "custom-sk")
+            ```
+        """
         from veadk.integrations.ve_faas.ve_faas import VeFaaS
 
         vefaas_client = VeFaaS(access_key=volcengine_ak, secret_key=volcengine_sk)
@@ -105,6 +173,26 @@ class CloudApp:
         return vefaas_endpoint
 
     def _get_vefaas_application_id_by_name(self) -> str:
+        """Retrieves the application ID using the configured name.
+
+        Instantiates VeFaaS client and queries by name.
+
+        Returns:
+            str: The found application ID.
+
+        Raises:
+            ValueError: If vefaas_application_name is not set.
+
+        Note:
+            Uses default environment credentials.
+            Internal method for ID resolution.
+
+        Examples:
+            ```python
+            app.vefaas_application_name = "my-app"
+            id = app._get_vefaas_application_id_by_name()
+            ```
+        """
         if not self.vefaas_application_name:
             raise ValueError(
                 "VeFaaS CloudAPP must be set application_name to get application_id."
@@ -121,6 +209,20 @@ class CloudApp:
         return vefaas_application_id
 
     async def _get_a2a_client(self) -> A2AClient:
+        """Constructs an A2A client configured for this cloud app.
+
+        If use_agent_card, resolves agent card and uses its URL; otherwise uses direct endpoint.
+
+        Args:
+            self: The CloudApp instance.
+
+        Returns:
+            A2AClient: Ready-to-use A2A client.
+
+        Note:
+            Manages httpx_client context.
+            For card mode, fetches from base_url/ (public card).
+        """
         if self.use_agent_card:
             async with self.httpx_client as httpx_client:
                 resolver = A2ACardResolver(
@@ -141,19 +243,81 @@ class CloudApp:
 
     def update_self(
         self,
+        path: str,
         volcengine_ak: str = getenv("VOLCENGINE_ACCESS_KEY"),
         volcengine_sk: str = getenv("VOLCENGINE_SECRET_KEY"),
     ):
+        """Updates the configuration of this cloud application.
+
+        Currently a placeholder; implementation pending.
+
+        Args:
+            volcengine_ak (str, optional): Access key for VeFaaS. Defaults to env var.
+            volcengine_sk (str, optional): Secret key for VeFaaS. Defaults to env var.
+
+        Returns:
+            None
+
+        Raises:
+            ValueError: If access key or secret key missing.
+
+        Examples:
+            ```python
+            app.update_self("ak", "sk")
+            ```
+        """
         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
+        if not self.vefaas_application_id:
+            self.vefaas_application_id = self._get_vefaas_application_id_by_name()
+
+        vefaas_client = VeFaaS(access_key=volcengine_ak, secret_key=volcengine_sk)
+
+        try:
+            vefaas_application_url, app_id, function_id = (
+                vefaas_client._update_function_code(
+                    application_name=self.vefaas_application_name,
+                    path=path,
+                )
+            )
+            self.vefaas_endpoint = vefaas_application_url
+            self.vefaas_application_id = app_id
+            logger.info(
+                f"Cloud app {self.vefaas_application_name} updated successfully."
+            )
+        except Exception as e:
+            raise ValueError(f"Failed to update cloud app. Error: {e}")
 
     def delete_self(
         self,
         volcengine_ak: str = getenv("VOLCENGINE_ACCESS_KEY"),
         volcengine_sk: str = getenv("VOLCENGINE_SECRET_KEY"),
     ):
+        """Deletes this cloud application after interactive confirmation.
+
+        Issues delete to VeFaaS and polls for completion.
+
+        Args:
+            volcengine_ak (str, optional): Access key. Defaults to env var.
+            volcengine_sk (str, optional): Secret key. Defaults to env var.
+
+        Returns:
+            None
+
+        Raises:
+            ValueError: If credentials not provided.
+
+        Note:
+            Fetches ID if not set using name.
+            Polls every 3 seconds until app no longer exists.
+            Prints status messages.
+
+        Examples:
+            ```python
+            app.delete_self()
+            ```
+        """
         if not volcengine_ak or not volcengine_sk:
             raise ValueError("Volcengine access key and secret key must be set.")
 
@@ -187,8 +351,33 @@ class CloudApp:
     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)
+        """Sends a user message to the cloud agent and retrieves the response.
+
+        Constructs A2A SendMessageRequest and executes via client.
+
+        Args:
+            message (str): Text content of the user message.
+            session_id (str): Identifier for the conversation session.
+            user_id (str): Identifier for the user.
+            timeout (float): Maximum wait time in seconds. Defaults to 600.0.
+
+        Returns:
+            Message | None: Assistant response message or None if error occurs.
+
+        Raises:
+            Exception: Communication or processing errors; error is printed.
+
+        Note:
+            Uses UUID for message and request IDs.
+            Payload includes role 'user' and text part.
+            Debug logs the full response.
+            Ignores type checks for result as it may not be Task.
+
+        Examples:
+            ```python
+            response = await app.message_send("What is AI?", "chat-1", "user-1", timeout=300)
+            print(response.content)
+            ```
         """
         a2a_client = await self._get_a2a_client()
 
@@ -223,13 +412,31 @@ class CloudApp:
                 # from CloudApp will not be `Task` type
                 return res.root.result  # type: ignore
             except Exception as e:
-                # TODO(floritange): show error log on VeFaaS function
-                print(e)
+                logger.error(f"Failed to send message to cloud app. Error: {e}")
                 return None
 
 
 def get_message_id(message: Message):
-    """Get the messageId of the a2a message"""
+    """Extracts the unique ID from an A2A Message object.
+
+    Checks for both legacy 'messageId' and current 'message_id' attributes.
+
+    Args:
+        message (Message): The A2A message instance.
+
+    Returns:
+        str: The message identifier.
+
+    Note:
+        Ensures compatibility with a2a-python versions before and after 0.3.0.
+        Prefers 'message_id' if available, falls back to 'messageId'.
+
+    Examples:
+        ```python
+        mid = get_message_id(response_message)
+        print(mid)
+        ```
+    """
     if getattr(message, "messageId", None):
         # Compatible with the messageId of the old a2a-python version (<0.3.0) in cloud app
         return message.messageId  # type: ignore

veadk/config.py

@@ -15,7 +15,7 @@
 import os
 from typing import Any
 
-from dotenv import find_dotenv
+from dotenv import find_dotenv, load_dotenv
 from pydantic import BaseModel, Field
 
 from veadk.configs.database_configs import (
@@ -33,8 +33,16 @@ from veadk.configs.tracing_configs import (
     PrometheusConfig,
     TLSConfig,
 )
+from veadk.utils.logger import get_logger
 from veadk.utils.misc import set_envs
 
+logger = get_logger(__name__)
+
+if load_dotenv(find_dotenv(usecwd=True)):
+    logger.info(f"Find `.env` file in {find_dotenv(usecwd=True)}, load envs.")
+else:
+    logger.info("No env file found.")
+
 
 class VeADKConfig(BaseModel):
     model: ModelConfig = Field(default_factory=ModelConfig)
@@ -89,7 +97,10 @@ config_yaml_path = find_dotenv(filename="config.yaml", usecwd=True)
 veadk_environments = {}
 
 if config_yaml_path:
+    logger.info(f"Find `config.yaml` file in {config_yaml_path}")
     config_dict, _veadk_environments = set_envs(config_yaml_path=config_yaml_path)
     veadk_environments.update(_veadk_environments)
+else:
+    logger.warning("No `config.yaml` file found.")
 
 settings = VeADKConfig()

veadk/configs/database_configs.py

@@ -89,6 +89,10 @@ class Mem0Config(BaseSettings):
     api_key: str = ""
     """Mem0 API key"""
 
+    api_key_id: str = ""
+
+    project_id: str = ""
+
     base_url: str = ""  # "https://api.mem0.ai/v1"
 
 

veadk/configs/model_configs.py

@@ -56,7 +56,11 @@ class EmbeddingModelConfig(BaseSettings):
 
     @cached_property
     def api_key(self) -> str:
-        return os.getenv("MODEL_EMBEDDING_API_KEY") or get_ark_token()
+        return (
+            os.getenv("MODEL_EMBEDDING_API_KEY")
+            or os.getenv("MODEL_AGENT_API_KEY")  # try to use agent's model api key
+            or get_ark_token()
+        )
 
 
 class NormalEmbeddingModelConfig(BaseSettings):

veadk/configs/tracing_configs.py

@@ -18,7 +18,7 @@ from functools import cached_property
 from pydantic import Field
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
-from veadk.auth.veauth.apmplus_veauth import APMPlusVeAuth
+from veadk.auth.veauth.apmplus_veauth import get_apmplus_token
 from veadk.consts import (
     DEFAULT_APMPLUS_OTEL_EXPORTER_ENDPOINT,
     DEFAULT_APMPLUS_OTEL_EXPORTER_SERVICE_NAME,
@@ -46,7 +46,7 @@ class APMPlusConfig(BaseSettings):
     def otel_exporter_api_key(self) -> str:
         return (
             os.getenv("OBSERVABILITY_OPENTELEMETRY_APMPLUS_API_KEY")
-            or APMPlusVeAuth().token
+            or get_apmplus_token()
         )