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

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/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()
         )
 
 

veadk/evaluation/adk_evaluator/adk_evaluator.py

@@ -39,16 +39,55 @@ import inspect
 
 
 def formatted_timestamp():
+    """Generates a formatted timestamp string in YYYYMMDDHHMMSS format.
+
+    This function creates a string representation of the current time.
+    It uses local time for formatting.
+
+    Returns:
+        str: Timestamp string like '20251028123045'.
+    """
     # YYYYMMDDHHMMSS
     return time.strftime("%Y%m%d%H%M%S", time.localtime())
 
 
 class ADKEvaluator(BaseEvaluator):
+    """Evaluates agents using Google ADK metrics.
+
+    This class uses Google's Agent Development Kit (ADK) to test agents.
+    It checks tool usage and response quality.
+    Runs tests multiple times for reliable results.
+
+    Attributes:
+        name (str): Name of this evaluator. Defaults to 'veadk_adk_evaluator'.
+
+    Note:
+        Works with .test.json files and folders of files.
+        Default thresholds: tool=1.0, response=0.8.
+        Runs each test multiple times (default 2) for average scores.
+
+    Examples:
+        ```python
+        agent = Agent(tools=[get_city_weather])
+        evaluator = ADKEvaluator(agent=agent)
+        results, failures = await evaluator.evaluate(eval_set_file_path="test_folder")
+        ```
+    """
+
     def __init__(
         self,
         agent,
         name: str = "veadk_adk_evaluator",
     ):
+        """Initializes the ADK evaluator with agent and name.
+
+        Args:
+            agent: The agent to evaluate.
+            name (str): Name of the evaluator. Defaults to 'veadk_adk_evaluator'.
+
+        Raises:
+            ValueError: If agent is invalid.
+        """
         super().__init__(agent=agent, name=name)
 
     @override
@@ -62,23 +101,44 @@ class ADKEvaluator(BaseEvaluator):
         num_runs: int = 2,
         print_detailed_results: bool = True,
     ):
-        """
-        End-to-end evaluation flow:
-        1) Discover test files (.test.json) or accept a single path.
-        2) Build metric criteria (metric_name -> threshold).
-        3) For each file, build in-memory eval cases via BaseEvaluator.
-        4) For each eval case, construct expected ADK Invocations from expected data.
-        5) Repeat for num_runs:
-           - Reset all session_ids to isolate state.
-           - Generate actual outputs via BaseEvaluator and convert to ADK Invocations.
-        6) Repeat expected invocations to match num_runs for 1:1 alignment.
-        7) For each metric:
-           - Create EvalMetric and get the evaluator from ADK's registry.
-           - Call evaluate_invocations (await if async) to get EvaluationResult with:
-             overall_score/overall_eval_status + per_invocation_results.
-           - Optionally pretty print via AgentEvaluator._print_details.
-           - Record failure if overall status != PASSED.
-        8) Return (all evaluation_result objects, failures) to the caller.
+        """Tests agent using ADK metrics on test cases.
+
+        This method does these steps:
+        1. Finds test files in folder or single file
+        2. Sets up scoring rules with thresholds
+        3. Runs agent multiple times for each test
+        4. Converts data to ADK format
+        5. Scores tool usage and response quality
+        6. Collects results and failures
+
+        Args:
+            eval_set: Test cases in memory. If given, used first.
+            eval_set_file_path: Path to test file or folder. Used if no eval_set.
+            eval_id: Unique name for this test run.
+            tool_score_threshold: Minimum score for tool usage. 1.0 means perfect.
+            response_match_score_threshold: Minimum score for response match.
+                Uses text similarity. 0.8 is default.
+            num_runs: How many times to run each test. More runs = more reliable.
+            print_detailed_results: If True, shows detailed scores for each test.
+
+        Returns:
+            tuple[list, list]: Two lists:
+                - List of evaluation results with scores
+                - List of failure messages if tests failed
+
+        Raises:
+            ValueError: If no test cases found or thresholds wrong.
+            FileNotFoundError: If test file not found.
+            EvaluationError: If agent fails or scoring fails.
+
+        Examples:
+            ```python
+            results, failures = await evaluator.evaluate(
+                 eval_set_file_path="tests/",
+                 tool_score_threshold=0.9,
+                 num_runs=3)
+            print(f"Results: {len(results)}, Failures: {len(failures)}")
+            ```
         """
 
         # Resolve eval files: accept a directory (scan *.test.json) or a single file