update(docstring): update docstring (evaluation and cloud)

Author: floritange

veadk/cloud/cloud_agent_engine.py

@@ -48,11 +48,13 @@ class CloudAgentEngine(BaseModel):
         Credentials must be set via environment variables for default behavior.
         This class performs interactive confirmations for destructive operations like removal.
 
-    Example:
-        >>> from veadk.cloud.cloud_agent_engine import CloudAgentEngine
-        >>> engine = CloudAgentEngine()
-        >>> app = engine.deploy("test-app", "/path/to/local/project")
-        >>> print(app.vefaas_endpoint)
+    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")
@@ -221,9 +223,11 @@ def deploy(
             Converts path to absolute; sets telemetry opt-out and ADK Web env vars.
             Generates default gateway names if not specified.
 
-        Example:
-            >>> app = engine.deploy("my-agent", "./agent-project", local_test=True)
-            >>> print(f"Deployed at: {app.vefaas_endpoint}")
+        Examples:
+            ```python
+            app = engine.deploy("my-agent", "./agent-project", local_test=True)
+            print(f"Deployed at: {app.vefaas_endpoint}")
+            ```
         """
         # prevent deepeval writing operations
         veadk_environments["DEEPEVAL_TELEMETRY_OPT_OUT"] = "YES"
@@ -285,9 +289,10 @@ def remove(self, app_name: str):
             Interactive prompt required; cancels on non-'y' input.
             Deletion is processed asynchronously by VeFaaS.
 
-        Example:
-            >>> engine.remove("my-agent")
-            Confirm delete cloud app my-agent? (y/N): y
+        Examples:
+            ```python
+            engine.remove("my-agent")
+            ```
         """
         confirm = input(f"Confirm delete cloud app {app_name}? (y/N): ")
         if confirm.lower() != "y":
@@ -324,9 +329,10 @@ def update_function_code(
             Preserves gateway and other resources; only function code is updated.
             Path is resolved to absolute before processing.
 
-        Example:
-            >>> updated_app = engine.update_function_code("my-agent", "./updated-project")
-            >>> assert updated_app.vefaas_endpoint == old_endpoint
+        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

@@ -46,11 +46,13 @@ class CloudApp:
         At least one of name, endpoint, or ID must be provided during init.
         Agent card mode fetches card from the endpoint's public path.
 
-    Example:
-        >>> 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)
+    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__(
@@ -80,8 +82,10 @@ def __init__(
             Logs info if agent card mode enabled.
             Endpoint is fetched via _get_vefaas_endpoint if not set.
 
-        Example:
-            >>> app = CloudApp(vefaas_application_id="app-123", use_agent_card=True)
+        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
@@ -140,8 +144,10 @@ def _get_vefaas_endpoint(
             Logs warning if JSON parsing fails; returns empty on error.
             Called during init if endpoint missing.
 
-        Example:
-            >>> endpoint = app._get_vefaas_endpoint("custom-ak", "custom-sk")
+        Examples:
+            ```python
+            endpoint = app._get_vefaas_endpoint("custom-ak", "custom-sk")
+            ```
         """
         from veadk.integrations.ve_faas.ve_faas import VeFaaS
 
@@ -180,9 +186,11 @@ def _get_vefaas_application_id_by_name(self) -> str:
             Uses default environment credentials.
             Internal method for ID resolution.
 
-        Example:
-            >>> app.vefaas_application_name = "my-app"
-            >>> id = app._get_vefaas_application_id_by_name()
+        Examples:
+            ```python
+            app.vefaas_application_name = "my-app"
+            id = app._get_vefaas_application_id_by_name()
+            ```
         """
         if not self.vefaas_application_name:
             raise ValueError(
@@ -251,8 +259,10 @@ def update_self(
         Raises:
             ValueError: If access key or secret key missing.
 
-        Example:
-            >>> app.update_self("ak", "sk")
+        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.")
@@ -283,10 +293,10 @@ def delete_self(
             Polls every 3 seconds until app no longer exists.
             Prints status messages.
 
-        Example:
-            >>> app.delete_self()
-            Confirm delete cloud app app-123? (y/N): y
-            Delete application done.
+        Examples:
+            ```python
+            app.delete_self()
+            ```
         """
         if not volcengine_ak or not volcengine_sk:
             raise ValueError("Volcengine access key and secret key must be set.")
@@ -343,9 +353,11 @@ async def message_send(
             Debug logs the full response.
             Ignores type checks for result as it may not be Task.
 
-        Example:
-            >>> response = await app.message_send("What is AI?", "chat-1", "user-1", timeout=300)
-            >>> print(response.content)
+        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()
 
@@ -400,9 +412,11 @@ def get_message_id(message: Message):
         Ensures compatibility with a2a-python versions before and after 0.3.0.
         Prefers 'message_id' if available, falls back to 'messageId'.
 
-    Example:
-        >>> mid = get_message_id(response_message)
-        >>> print(mid)
+    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

veadk/evaluation/adk_evaluator/adk_evaluator.py

@@ -66,12 +66,12 @@ class ADKEvaluator(BaseEvaluator):
         Default thresholds: tool=1.0, response=0.8.
         Runs each test multiple times (default 2) for average scores.
 
-    Example:
-        >>> agent = Agent(tools=[get_city_weather])
-        >>> evaluator = ADKEvaluator(agent=agent)
-        >>> results, failures = await evaluator.evaluate(
-        ...     eval_set_file_path="test_folder"
-        ... )
+    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__(
@@ -131,13 +131,14 @@ async def evaluate(
             FileNotFoundError: If test file not found.
             EvaluationError: If agent fails or scoring fails.
 
-        Example:
-            >>> 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)}")
+        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

veadk/evaluation/deepeval_evaluator/deepeval_evaluator.py

@@ -66,11 +66,13 @@ class DeepevalEvaluator(BaseEvaluator):
         Needs judge model credentials from environment if not given.
         Turns off cache to get fresh results each time.
 
-    Example:
-        >>> agent = Agent(tools=[get_city_weather])
-        >>> evaluator = DeepevalEvaluator(agent=agent)
-        >>> metrics = [GEval(threshold=0.8)]
-        >>> results = await evaluator.evaluate(metrics, eval_set_file_path="test.json")
+    Examples:
+        ```python
+        agent = Agent(tools=[get_city_weather])
+        evaluator = DeepevalEvaluator(agent=agent)
+        metrics = [GEval(threshold=0.8)]
+        results = await evaluator.evaluate(metrics, eval_set_file_path="test.json")
+        ```
     """
 
     def __init__(
@@ -100,12 +102,13 @@ def __init__(
             ValueError: If model settings are wrong.
             EnvironmentError: If environment variables are missing.
 
-        Example:
-            >>> evaluator = DeepevalEvaluator(
-            ...     agent=my_agent,
-            ...     judge_model_api_key="sk-...",
-            ...     prometheus_config=prometheus_config
-            ... )
+        Examples:
+            ```python
+            evaluator = DeepevalEvaluator(
+                agent=my_agent,
+                judge_model_api_key="sk-...",
+                prometheus_config=prometheus_config)
+            ```
         """
         super().__init__(agent=agent, name=name)
 
@@ -162,13 +165,14 @@ async def evaluate(
             FileNotFoundError: If test file not found.
             EvaluationError: If agent fails or metrics fail.
 
-        Example:
-            >>> metrics = [GEval(threshold=0.8), ToolCorrectnessMetric(threshold=0.5)]
-            >>> results = await evaluator.evaluate(
-            ...     metrics=metrics,
-            ...     eval_set_file_path="test_cases.json"
-            ... )
-            >>> print(f"Test cases run: {len(results.test_results)}")
+        Examples:
+            ```python
+            metrics = [GEval(threshold=0.8), ToolCorrectnessMetric(threshold=0.5)]
+            results = await evaluator.evaluate(
+                metrics=metrics,
+                eval_set_file_path="test_cases.json")
+            print(f"Test cases run: {len(results.test_results)}")
+            ```
         """
         # Get evaluation data by parsing eval set file
         self.build_eval_set(eval_set, eval_set_file_path)
@@ -268,9 +272,10 @@ def export_results(self, eval_id: str, test_results: EvaluationResult):
             Uses fixed thresholds for now: case_threshold=0.5, diff_threshold=0.2.
             These may change later.
 
-        Example:
-            >>> evaluator.export_results("test_20240101", test_results)
-            # Results sent to Prometheus
+        Examples:
+            ```python
+            evaluator.export_results("test_20240101", test_results)
+            ```
         """
         # fixed attributions
         test_name = eval_id

veadk/evaluation/eval_set_file_loader.py

@@ -33,9 +33,11 @@ def load_eval_set_from_file(eval_set_file_path: str) -> EvalSet:
     Raises:
         Exception: If file loading or parsing fails, with details.
 
-    Example:
-        >>> eval_set = load_eval_set_from_file("my_eval.json")
-        >>> print(len(eval_set.eval_cases))
+    Examples:
+        ```python
+        eval_set = load_eval_set_from_file("my_eval.json")
+        print(len(eval_set.eval_cases))
+        ```
     """
     try:
         eval_set = adk_load_eval_set_from_file(eval_set_file_path, eval_set_file_path)