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

veadk/cli/cli_create.py

@@ -16,26 +16,8 @@ import click
 import shutil
 from pathlib import Path
 
-_CONFIG_YAML_TEMPLATE = """\
-model:
-  agent:
-    name: doubao-seed-1-6-251015
-    api_key: {ark_api_key}
-  video:
-    name: doubao-seedance-1-0-pro-250528
-    # if you want to use different api_key, just uncomment following line and complete api_key
-    # api_key: 
-  image:
-    name: doubao-seedream-4-0-250828
-    # if you want to use different api_key, just uncomment following line and complete api_key
-    # api_key: 
-
-logging:
-  # ERROR
-  # WARNING
-  # INFO
-  # DEBUG
-  level: DEBUG
+_ENV_TEMPLATE = """\
+MODEL_AGENT_API_KEY={ark_api_key}
 """
 
 _INIT_PY_TEMPLATE = """\
@@ -49,60 +31,119 @@ root_agent = Agent(
     name="root_agent",
     description="A helpful assistant for user questions.",
     instruction="Answer user questions to the best of your knowledge",
+    model_name="doubao-seed-1-6-251015", # <---- you can change your model here
 )
 """
 
 _SUCCESS_MSG = """\
-Agent '{agent_name}' created successfully at '{agent_folder}':
-- config.yaml
-- {agent_name}/__init__.py
-- {agent_name}/agent.py
+Agent created in {agent_folder}:
+- .env
+- __init__.py
+- agent.py
 
-You can run the agent by executing: cd {agent_name} && veadk web
+You can run the agent by executing: veadk web
 """
 
 
 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",
     )
     click.echo("You have two options:")
     click.echo("  1. Enter the API key now.")
-    click.echo("  2. Configure it later in the generated config.yaml file.")
+    click.echo("  2. Configure it later in the generated .env file.")
     choice = click.prompt("Please select an option", type=click.Choice(["1", "2"]))
     if choice == "1":
         return click.prompt("Please enter your ARK API key")
     else:
-        click.secho(
-            "You can set the `api_key` in the config.yaml file later.", fg="yellow"
-        )
+        click.secho("You can set the `api_key` in the .env file later.", fg="yellow")
         return ""
 
 
-def _generate_files(agent_name: str, ark_api_key: str, target_dir_path: Path) -> None:
-    agent_dir_path = target_dir_path / agent_name
-    agent_dir_path.mkdir(parents=True, exist_ok=True)
-    config_yaml_path = target_dir_path / "config.yaml"
-    init_file_path = agent_dir_path / "__init__.py"
-    agent_file_path = agent_dir_path / "agent.py"
-
-    config_yaml_content = _CONFIG_YAML_TEMPLATE.format(ark_api_key=ark_api_key)
-    config_yaml_path.write_text(config_yaml_content)
+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"
+    agent_file_path = target_dir_path / "agent.py"
+
+    env_content = _ENV_TEMPLATE.format(ark_api_key=ark_api_key)
+    env_path.write_text(env_content)
     init_file_path.write_text(_INIT_PY_TEMPLATE)
     agent_file_path.write_text(_AGENT_PY_TEMPLATE)
 
     click.secho(
-        _SUCCESS_MSG.format(agent_name=agent_name, agent_folder=target_dir_path),
+        _SUCCESS_MSG.format(agent_folder=target_dir_path),
         fg="green",
     )
 
 
 @click.command()
-@click.option("--agent-name", help="The name of the agent.")
+@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:
@@ -119,4 +160,4 @@ def create(agent_name: str, ark_api_key: str) -> None:
             return
         shutil.rmtree(target_dir_path)
 
-    _generate_files(agent_name, ark_api_key, target_dir_path)
+    _generate_files(ark_api_key, target_dir_path)

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 @@ warnings.filterwarnings(
 
 
 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 @@ warnings.filterwarnings(
 
 
 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 @@ import click
 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(

veadk/cli/cli_web.py

@@ -23,7 +23,14 @@ logger = get_logger(__name__)
 
 def patch_adkwebserver_disable_openapi():
     """
-    Monkey patch AdkWebServer.get_fast_api to remove openapi.json route.
+    Monkey patch AdkWebServer to disable OpenAPI documentation endpoints.
+
+    This function patches the AdkWebServer.get_fast_api_app method to remove
+    OpenAPI-related routes (/openapi.json, /docs, /redoc) from the FastAPI
+    application for security and simplicity purposes.
+
+    The patch is applied by replacing the original method with a wrapped version
+    that filters out the unwanted routes after the FastAPI app is created.
     """
     import google.adk.cli.adk_web_server
     from fastapi.routing import APIRoute
@@ -52,7 +59,25 @@ def patch_adkwebserver_disable_openapi():
 )
 @click.pass_context
 def web(ctx, *args, **kwargs) -> None:
-    """Launch web with long term and short term memory."""
+    """
+    Launch a web server with VeADK agent support and memory integration.
+
+    This command starts a web server that can serve VeADK agents with both
+    short-term and long-term memory capabilities. It automatically detects
+    the type of agent being loaded and configures the appropriate memory
+    services accordingly.
+
+    The function patches the ADK web server to integrate VeADK-specific
+    functionality, including memory service configuration and workflow
+    agent detection.
+
+    Args:
+        ctx: Click context object containing command line arguments
+
+    Note:
+        For workflow agents (Sequential, Loop, Parallel), individual sub-agent
+        memory configurations are not utilized as warned in the logs.
+    """
     from google.adk.cli import adk_web_server
     from google.adk.runners import Runner as ADKRunner
 
@@ -107,6 +132,12 @@ def web(ctx, *args, **kwargs) -> None:
 
     from google.adk.cli.cli_tools_click import cli_web
 
-    extra_args = ctx.args
-    logger.debug(f"User args: {ctx.args}")
+    extra_args: list = ctx.args
+    logger.debug(f"User args: {extra_args}")
+
+    # set a default log level to avoid unnecessary outputs
+    # from Google ADK and Litellm
+    if "--log_level" not in extra_args:
+        extra_args.extend(["--log_level", "ERROR"])
+
     cli_web.main(args=extra_args, standalone_mode=False)