chore: add docstrings for cli and tracing module

Author: BhAem

veadk/cli/cli.py

@@ -32,7 +32,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_create.py

@@ -46,6 +46,16 @@
 
 
 def _prompt_for_ark_api_key() -> str:
+    """Prompt user to enter ARK API key with guidance and options.
+
+    Displays instructions for obtaining an ARK API key and provides the user
+    with two options: enter the key immediately or configure it later in the
+    generated .env file. Includes helpful documentation links and clear choices.
+
+    Returns:
+        str: The ARK API key entered by the user, or empty string if they
+            choose to configure it later
+    """
     click.secho(
         "An API key is required to run the agent. See https://www.volcengine.com/docs/82379/1541594 for details.",
         fg="green",
@@ -62,6 +72,30 @@ def _prompt_for_ark_api_key() -> str:
 
 
 def _generate_files(ark_api_key: str, target_dir_path: Path) -> None:
+    """Generate agent project files from templates in the target directory.
+
+    Creates the essential files for a new VeADK agent project including
+    environment configuration, Python package initialization, and the main
+    agent definition file. Uses predefined templates to ensure consistent
+    project structure and proper configuration.
+
+    Args:
+        ark_api_key: ARK API key to be written to the .env file for
+            model authentication. Can be empty string if not provided
+        target_dir_path: Path object pointing to the target directory
+            where files should be created
+
+    Files Created:
+        - .env: Environment file with ARK API key configuration
+        - __init__.py: Python package initialization file
+        - agent.py: Main agent definition with default configuration
+
+    Note:
+        - Creates target directory if it doesn't exist
+        - Overwrites existing files without warning
+        - Uses template formatting to inject API key into .env file
+        - Displays success message with project location after completion
+    """
     target_dir_path.mkdir(exist_ok=True)
     env_path = target_dir_path / ".env"
     init_file_path = target_dir_path / "__init__.py"
@@ -82,7 +116,34 @@ def _generate_files(ark_api_key: str, target_dir_path: Path) -> None:
 @click.argument("agent_name", required=False)
 @click.option("--ark-api-key", help="The ARK API key.")
 def create(agent_name: str, ark_api_key: str) -> None:
-    """Creates a new agent in the current folder with prepopulated agent template."""
+    """Create a new VeADK agent project with prepopulated template files.
+
+    This command creates a new agent project directory with all necessary
+    files to get started with VeADK agent development. It sets up a complete
+    project structure including environment configuration, agent definition,
+    and package initialization.
+
+    The command handles interactive prompts for missing parameters and provides
+    safety checks for existing directories to prevent accidental overwrites.
+
+    Project Structure Created:
+        agent_name/
+        ├── .env                 # Environment configuration with API key
+        ├── __init__.py         # Python package initialization
+        └── agent.py            # Main agent definition with default settings
+
+    Args:
+        agent_name: Name of the agent and directory to create. If not provided
+            as an argument, the user will be prompted to enter it interactively
+        ark_api_key: ARK API key for model authentication. If not provided,
+            the user will be prompted with options to enter it or configure later
+
+    Note:
+        - Agent name becomes both the directory name and project identifier
+        - API key can be configured later by editing the .env file
+        - Generated agent is immediately runnable with 'veadk web' command
+        - Template includes comments guiding users to customize model settings
+    """
     if not agent_name:
         agent_name = click.prompt("Enter the agent name")
     if not ark_api_key:

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."