chore: add docstrings for cli and tracing module

Author: BhAem

veadk/cli/cli.py

@@ -31,7 +31,11 @@
     version=VERSION, prog_name="Volcengine Agent Development Kit (VeADK)"
 )
 def veadk():
-    """Volcengine ADK command line tools"""
+    """Volcengine Agent Development Kit (VeADK) command line interface.
+
+    This is the main entry point for all VeADK CLI commands. VeADK provides
+    tools for developing, deploying, and managing AI agents on the Volcengine platform.
+    """
     pass
 
 

veadk/cli/cli_deploy.py

@@ -62,7 +62,42 @@ def deploy(
     use_adk_web: bool,
     path: str,
 ) -> None:
-    """Deploy a user project to Volcengine FaaS application."""
+    """Deploy a user project to Volcengine FaaS application.
+
+    This command deploys a VeADK agent project to Volcengine's Function as a Service (FaaS)
+    platform. It creates a deployment package from the local project, configures the necessary
+    cloud resources, and manages the deployment process including template generation,
+    file copying, and cloud resource provisioning.
+
+    The deployment process includes:
+    1. Creating a temporary deployment package using cookiecutter templates
+    2. Copying the user's project files to the deployment structure
+    3. Processing configuration files and requirements
+    4. Executing the deployment to Volcengine FaaS
+    5. Cleaning up temporary files
+
+    Args:
+        access_key: Volcengine access key for API authentication. If not provided,
+            will use VOLCENGINE_ACCESS_KEY environment variable
+        secret_key: Volcengine secret key for API authentication. If not provided,
+            will use VOLCENGINE_SECRET_KEY environment variable
+        vefaas_app_name: Name of the target Volcengine FaaS application where the
+            project will be deployed
+        veapig_instance_name: Optional Volcengine API Gateway instance name for
+            external API access configuration
+        veapig_service_name: Optional Volcengine API Gateway service name
+        veapig_upstream_name: Optional Volcengine API Gateway upstream name
+        short_term_memory_backend: Backend type for short-term memory storage.
+            Choices are 'local' or 'mysql'
+        use_adk_web: Flag to enable ADK Web interface for the deployed agent
+        path: Local directory path containing the VeADK project to deploy
+
+    Note:
+        - The function automatically processes and copies requirements.txt if present in the project
+        - config.yaml files are excluded from deployment for security reasons
+        - Temporary files are created in /tmp and cleaned up after deployment
+        - The deployment uses cookiecutter templates for standardized project structure
+    """
     import asyncio
     import shutil
     from pathlib import Path

veadk/cli/cli_eval.py

@@ -64,6 +64,61 @@ def eval(
     volcengine_access_key: str,
     volcengine_secret_key: str,
 ) -> None:
+    """Evaluate an agent using specified evaluation datasets and metrics.
+
+    This command provides comprehensive agent evaluation capabilities using either Google ADK
+    or DeepEval frameworks. It supports both local agent evaluation (from source code) and
+    remote agent evaluation (via A2A deployment URLs), making it flexible for different
+    development and deployment scenarios.
+
+    The evaluation process includes:
+    1. Loading the target agent from local directory or remote A2A endpoint
+    2. Configuring the evaluation environment and credentials
+    3. Setting up the chosen evaluator with appropriate metrics
+    4. Running evaluation tests against the provided dataset
+    5. Generating detailed performance reports and scores
+
+    Evaluation Modes:
+    - Local Evaluation: Loads agent code from a local directory containing 'agent.py'
+      with exported 'root_agent' variable. Suitable for development and testing.
+    - Remote Evaluation: Connects to a deployed agent via A2A (Agent-to-Agent) URL.
+      Ideal for evaluating production deployments or distributed agents.
+
+    Evaluator Options:
+    - ADK Evaluator: Uses Google's Agent Development Kit evaluation framework.
+      Provides standardized metrics and comprehensive evaluation reports.
+    - DeepEval: Advanced evaluation framework with customizable metrics including
+      GEval for general performance and ToolCorrectnessMetric for tool usage accuracy.
+
+    Args:
+        agent_dir: Local directory path containing the agent implementation.
+            Must include an 'agent.py' file with exported 'root_agent' variable.
+            Defaults to current directory if not specified
+        agent_a2a_url: Complete URL of the deployed agent in A2A mode.
+            If provided alongside agent_dir, this URL takes precedence
+        evalset_file: Path to the evaluation dataset file in Google ADK format.
+            Should contain test cases with inputs, expected outputs, and metadata
+        evaluator: Evaluation framework to use. Available options:
+            - 'adk': Google ADK evaluator with built-in metrics
+            - 'deepeval': Advanced evaluator with customizable metrics and thresholds
+        judge_model_name: Name of the language model used for evaluation judgment.
+            Defaults to 'doubao-1-5-pro-256k-250115'. Only applicable for DeepEval;
+            ignored when using ADK evaluator
+        volcengine_access_key: Volcengine platform access key for model authentication.
+            If not provided, uses VOLCENGINE_ACCESS_KEY environment variable
+        volcengine_secret_key: Volcengine platform secret key for model authentication.
+            If not provided, uses VOLCENGINE_SECRET_KEY environment variable
+
+    Note:
+        - At least one of --agent-dir or --agent-a2a-url must be provided
+        - If both are provided, --agent-a2a-url takes precedence
+        - Judge model name is ignored when using ADK evaluator
+        - Evaluation results are logged and may be saved to output files
+
+    Raises:
+        ImportError: If DeepEval dependencies are not installed when using DeepEval evaluator.
+        ValueError: If neither agent_dir nor agent_a2a_url is provided.
+    """
     import asyncio
     import os
     from pathlib import Path

veadk/cli/cli_init.py

@@ -25,6 +25,14 @@
 
 
 def _render_prompts() -> dict[str, Any]:
+    """Render interactive prompts to collect user configuration for project initialization.
+
+    This function prompts the user for various configuration options including
+    Volcengine FaaS application name, API Gateway settings, and deployment mode.
+
+    Returns:
+        dict[str, Any]: A dictionary containing all the collected configuration values
+    """
     vefaas_application_name = click.prompt(
         "Volcengine FaaS application name", default="veadk-cloud-agent"
     )
@@ -71,9 +79,42 @@ def _render_prompts() -> dict[str, Any]:
 def init(
     vefaas_template_type: str,
 ) -> None:
-    """Init a veadk project that can be deployed to Volcengine VeFaaS.
-
-    `template` is A2A/MCP/Web server template, `web_template` is for web applications (i.e., a simple blog).
+    """Initialize a new VeADK project that can be deployed to Volcengine FaaS.
+
+    This command creates a new VeADK project from predefined templates using an interactive
+    setup process. It generates a complete project structure with all necessary files,
+    configurations, and deployment scripts ready for Volcengine cloud deployment.
+
+    The initialization process includes:
+    1. Interactive prompts for collecting deployment configuration
+    2. Template selection based on the specified template type
+    3. Project directory creation with proper structure
+    4. Configuration file generation with user preferences
+    5. Ready-to-use deployment scripts and source code structure
+
+    Available template types:
+    - 'template' (default): Creates an A2A/MCP/Web server template with a weather-reporter
+      example application. Suitable for most agent development scenarios.
+    - 'web_template': Creates a web application template with a simple-blog example.
+      Designed for web-based agent applications with UI components.
+
+    The generated project structure includes:
+    - src/ directory containing agent source code
+    - deploy.py script for cloud deployment
+    - Configuration files for various deployment scenarios
+    - Example implementations based on the selected template
+
+    Args:
+        vefaas_template_type: The type of template to use for project initialization.
+            Defaults to 'template'. Valid options are:
+            - 'template': Standard agent template (weather-reporter example)
+            - 'web_template': Web application template (simple-blog example)
+
+    Note:
+        - If the target directory already exists, you will be prompted to confirm overwrite
+        - The generated project includes example code that can be modified for your use case
+        - All deployment configurations can be customized after project creation
+        - The deploy.py script provides automated deployment to Volcengine FaaS platform
     """
     import shutil
     from pathlib import Path

veadk/cli/cli_kb.py

@@ -48,7 +48,42 @@ def add(
     index: str,
     path: str,
 ):
-    """Add files to knowledgebase"""
+    """Add files to knowledgebase.
+
+    This command adds files or directories to a specified knowledgebase backend.
+    It supports various backend types including local storage, OpenSearch, Viking,
+    and Redis for storing and indexing knowledge content.
+
+    Args:
+        backend: The knowledgebase backend type to use for storing and indexing documents.
+            Available options:
+            - 'local': Local file-based storage using SQLite. Suitable for development
+              and small-scale deployments. No external dependencies required.
+            - 'opensearch': Elasticsearch-compatible search engine with advanced
+              full-text search and vector similarity capabilities. Recommended for
+              production environments with large document collections.
+            - 'viking': Volcengine's managed vector database service optimized for
+              semantic search and RAG applications. Provides high performance and
+              automatic scaling on Volcengine cloud platform.
+            - 'redis': In-memory data structure store with vector search capabilities.
+              Fast retrieval but limited by memory capacity. Good for frequently
+              accessed, smaller knowledge bases.
+        app_name: Application identifier for organizing and isolating knowledgebase
+            data. Used to create logical separation between different applications
+            or environments. Must be consistent across operations for the same knowledge base.
+        index: Knowledgebase index identifier within the application namespace.
+            Acts as a unique name for this specific knowledge collection. Multiple
+            indexes can exist under the same app_name for different knowledge domains.
+            Index names should be descriptive and follow naming conventions of the chosen backend.
+        path: File system path to the knowledge content to be added to the knowledge base.
+            Supported formats:
+            - Single file: Path to a specific document (PDF, TXT, MD, DOCX, etc.)
+            - Directory: Path to a folder containing multiple documents. All supported
+              files in the directory will be processed recursively.
+
+    Raises:
+        RuntimeError: If the file type is not supported
+    """
     _path = Path(path)
     assert _path.exists(), f"Path {path} not exists. Please check your input."
 

veadk/cli/cli_pipeline.py

@@ -37,6 +37,18 @@
 
 
 def _create_cr(volcengine_settings: dict[str, str], cr_settings: dict[str, str]):
+    """Create Container Registry (CR) resources including instance, namespace, and repository.
+
+    This helper function creates the necessary Container Registry infrastructure
+    on Volcengine cloud platform for storing Docker images used in the CI/CD pipeline.
+
+    Args:
+        volcengine_settings: Dictionary containing Volcengine credentials and region
+        cr_settings: Dictionary containing CR instance, namespace, and repo configuration
+
+    Raises:
+        Exception: If any of the CR resource creation operations fail
+    """
     vecr = VeCR(
         access_key=volcengine_settings["volcengine_access_key"],
         secret_key=volcengine_settings["volcengine_secret_key"],
@@ -137,7 +149,60 @@ def pipeline(
     cr_repo_name: str,
     vefaas_function_id: str,
 ) -> None:
-    """Integrate a veadk project to volcengine pipeline for CI/CD"""
+    """Integrate a VeADK project with Volcengine pipeline for automated CI/CD deployment.
+
+    This command sets up a complete CI/CD pipeline that automatically builds, containerizes,
+    and deploys your VeADK agent project whenever changes are pushed to the specified GitHub
+    repository. It creates all necessary cloud infrastructure including Container Registry
+    resources, FaaS functions, and pipeline configurations.
+
+    The pipeline integration process includes:
+    1. Creating Container Registry (CR) infrastructure (instance, namespace, repository)
+    2. Setting up or using existing VeFaaS function for deployment target
+    3. Configuring Volcengine Code Pipeline with GitHub integration
+    4. Establishing automated build and deployment workflows
+    5. Linking all components for seamless CI/CD operation
+
+    Pipeline Workflow:
+    - Code changes pushed to GitHub trigger the pipeline
+    - Source code is automatically pulled from the specified branch
+    - Docker image is built using the specified VeADK base image
+    - Built image is pushed to Volcengine Container Registry
+    - VeFaaS function is updated with the new container image
+    - Deployment completion notifications are provided
+
+    Args:
+        veadk_version: Base VeADK image version for containerization. Can be:
+            - 'preview': Latest preview/development version
+            - 'latest': Latest stable release
+            - Specific version (e.g., '1.0.0'): Pinned version for consistency
+        github_url: Complete GitHub repository URL containing your VeADK project.
+            Must be accessible with the provided GitHub token
+        github_branch: Target branch to monitor for changes and deploy from.
+            Typically 'main', 'master', or your preferred deployment branch
+        github_token: GitHub personal access token with repository access permissions.
+            Required for pipeline to access and monitor your repository
+        volcengine_access_key: Volcengine cloud platform access key for authentication.
+            If not provided, uses VOLCENGINE_ACCESS_KEY environment variable
+        volcengine_secret_key: Volcengine cloud platform secret key for authentication.
+            If not provided, uses VOLCENGINE_SECRET_KEY environment variable
+        region: Volcengine cloud region for all resources (VeFaaS, CR, Pipeline).
+            Defaults to 'cn-beijing'. Choose region closest to your users
+        cr_instance_name: Name for the Container Registry instance that will store
+            your Docker images. Defaults to 'veadk-user-instance'
+        cr_namespace_name: Namespace within the Container Registry for organizing
+            repositories. Defaults to 'veadk-user-namespace'
+        cr_repo_name: Repository name within the Container Registry namespace
+            for storing your project images. Defaults to 'veadk-user-repo'
+        vefaas_function_id: Existing VeFaaS function ID to update with new deployments.
+            If not provided, a new function will be created automatically
+
+    Note:
+        - GitHub token must have appropriate permissions for repository access
+        - All Volcengine resources will be created in the specified region
+        - The pipeline will be triggered immediately upon creation for initial deployment
+        - Subsequent deployments occur automatically when code is pushed to the monitored branch
+    """
 
     click.echo(
         "Welcome use VeADK to integrate your project to volcengine pipeline for CI/CD."

veadk/cli/cli_prompt.py

@@ -30,7 +30,22 @@
 def prompt(
     path: str, feedback: str, api_key: str, workspace_id: str, model_name: str
 ) -> None:
-    """Optimize agent system prompt from a local file."""
+    """Optimize agent system prompt from a local file.
+
+    This command uses Volcengine PromptPilot service to optimize agent system prompts
+    based on feedback and best practices. It loads agents from a specified file and
+    applies intelligent prompt optimization using the specified model.
+
+    Args:
+        path: Path to the agent file containing global variable `agent=...`
+        feedback: User feedback and suggestions for prompt optimization
+        api_key: API key for accessing PromptPilot service
+        workspace_id: Workspace ID in PromptPilot for organizing prompts
+        model_name: Name of the model to use for prompt optimization
+
+    Raises:
+        ValueError: If workspace_id is not provided when required
+    """
     from pathlib import Path
 
     from veadk.agent import Agent

veadk/cli/cli_uploadevalset.py

@@ -37,7 +37,21 @@ def uploadevalset(
     cozeloop_evalset_id: str,
     cozeloop_api_key: str,
 ) -> None:
-    """Upload dataset items to CozeLoop evaluation set."""
+    """Upload dataset items to CozeLoop evaluation set.
+
+    This command uploads evaluation dataset items from a JSON file to the CozeLoop
+    platform for agent evaluation and testing. It processes Google ADK formatted
+    evaluation cases and converts them to CozeLoop's expected format.
+
+    Args:
+        file: Path to the JSON file containing dataset items in Google ADK format.
+        cozeloop_workspace_id: CozeLoop workspace identifier for organizing evaluation sets.
+            If not provided, uses OBSERVABILITY_OPENTELEMETRY_COZELOOP_SERVICE_NAME environment variable.
+        cozeloop_evalset_id: Specific evaluation set ID where items will be uploaded.
+            If not provided, uses OBSERVABILITY_OPENTELEMETRY_COZELOOP_EVALSET_ID environment variable.
+        cozeloop_api_key: API key for authenticating with CozeLoop services.
+            If not provided, uses OBSERVABILITY_OPENTELEMETRY_COZELOOP_API_KEY environment variable.
+    """
 
     if not cozeloop_workspace_id:
         cozeloop_workspace_id = getenv(