veadk-python 0.2.27__py3-none-any.whl

veadk/cli/cli_kb.py

@@ -0,0 +1,110 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from pathlib import Path
+from typing import Literal
+
+import click
+
+
+@click.command()
+@click.option(
+    "--backend",
+    type=click.Choice(
+        ["local", "opensearch", "viking", "redis"],
+        case_sensitive=False,
+    ),
+    required=True,
+)
+@click.option(
+    "--app_name",
+    default="",
+    help="`app_name` for init your knowledgebase",
+)
+@click.option(
+    "--index",
+    default="",
+    help="Knowledgebase index",
+)
+@click.option(
+    "--path",
+    required=True,
+    help="Knowledge file or directory path",
+)
+def add(
+    backend: Literal["local", "opensearch", "viking", "redis"],
+    app_name: str,
+    index: str,
+    path: str,
+):
+    """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."
+
+    from veadk.knowledgebase import KnowledgeBase
+
+    knowledgebase = KnowledgeBase(backend=backend, app_name=app_name, index=index)
+
+    if _path.is_file():
+        knowledgebase.add_from_files(files=[path])
+    elif _path.is_dir():
+        knowledgebase.add_from_directory(directory=path)
+    else:
+        raise RuntimeError(
+            "Unsupported knowledgebase file type, only support a single file and a directory."
+        )
+
+
+@click.group()
+def kb():
+    """VeADK Knowledgebase management"""
+    pass
+
+
+kb.add_command(add)

veadk/cli/cli_pipeline.py

@@ -0,0 +1,285 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import warnings
+
+import click
+
+from veadk.config import getenv
+from veadk.consts import (
+    DEFAULT_CR_INSTANCE_NAME,
+    DEFAULT_CR_NAMESPACE_NAME,
+    DEFAULT_CR_REPO_NAME,
+)
+from veadk.integrations.ve_code_pipeline.ve_code_pipeline import VeCodePipeline
+from veadk.integrations.ve_cr.ve_cr import VeCR
+from veadk.integrations.ve_faas.ve_faas import VeFaaS
+from veadk.utils.logger import get_logger
+from veadk.version import VERSION
+
+logger = get_logger(__name__)
+
+
+warnings.filterwarnings(
+    "ignore", category=UserWarning, module="pydantic._internal._fields"
+)
+
+
+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"],
+        region=volcengine_settings["volcengine_region"],
+    )
+    try:
+        vecr._create_instance(cr_settings["cr_instance_name"])
+    except Exception as e:
+        click.echo(f"Failed to create CR instance: {e}")
+        raise
+
+    try:
+        vecr._create_namespace(
+            instance_name=cr_settings["cr_instance_name"],
+            namespace_name=cr_settings["cr_namespace_name"],
+        )
+    except Exception as e:
+        click.echo(f"Failed to create CR namespace: {e}")
+        raise
+
+    try:
+        vecr._create_repo(
+            instance_name=cr_settings["cr_instance_name"],
+            namespace_name=cr_settings["cr_namespace_name"],
+            repo_name=cr_settings["cr_repo_name"],
+        )
+    except Exception as e:
+        click.echo(f"Failed to create CR repo: {e}")
+        raise
+
+
+@click.command()
+@click.option(
+    "--veadk-version",
+    default=VERSION,
+    help=f"Base VeADK image tag can be 'preview', 'latest', or a specific VeADK version (e.g., {VERSION})",
+)
+@click.option(
+    "--github-url",
+    required=True,
+    help="The github url of your project",
+)
+@click.option(
+    "--github-branch",
+    required=True,
+    help="The github branch of your project",
+)
+@click.option(
+    "--github-token",
+    required=True,
+    help="The github token to manage your project",
+)
+@click.option(
+    "--volcengine-access-key",
+    default=None,
+    help="Volcengine access key, if not set, will use the value of environment variable VOLCENGINE_ACCESS_KEY",
+)
+@click.option(
+    "--volcengine-secret-key",
+    default=None,
+    help="Volcengine secret key, if not set, will use the value of environment variable VOLCENGINE_SECRET_KEY",
+)
+@click.option(
+    "--region",
+    default="cn-beijing",
+    help="Region for Volcengine VeFaaS, CR, and Pipeline. Default is cn-beijing",
+)
+@click.option(
+    "--cr-instance-name",
+    default=DEFAULT_CR_INSTANCE_NAME,
+    help="Volcengine Container Registry instance name, default is veadk-user-instance",
+)
+@click.option(
+    "--cr-namespace-name",
+    default=DEFAULT_CR_NAMESPACE_NAME,
+    help="Volcengine Container Registry namespace name, default is veadk-user-namespace",
+)
+@click.option(
+    "--cr-repo-name",
+    default=DEFAULT_CR_REPO_NAME,
+    help="Volcengine Container Registry repo name, default is veadk-user-repo",
+)
+@click.option(
+    "--vefaas-function-id",
+    default=None,
+    help="Volcengine FaaS function ID, if not set, a new function will be created automatically",
+)
+def pipeline(
+    veadk_version: str,
+    github_url: str,
+    github_branch: str,
+    github_token: str,
+    volcengine_access_key: str,
+    volcengine_secret_key: str,
+    region: str,
+    cr_instance_name: str,
+    cr_namespace_name: str,
+    cr_repo_name: str,
+    vefaas_function_id: str,
+) -> None:
+    """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."
+    )
+
+    if not volcengine_access_key:
+        volcengine_access_key = getenv("VOLCENGINE_ACCESS_KEY")
+    if not volcengine_secret_key:
+        volcengine_secret_key = getenv("VOLCENGINE_SECRET_KEY")
+
+    volcengine_settings = {
+        "volcengine_access_key": volcengine_access_key,
+        "volcengine_secret_key": volcengine_secret_key,
+        "volcengine_region": region,
+    }
+
+    cr_settings = {
+        "cr_domain": f"{cr_instance_name}-{region}.cr.volces.com",
+        "cr_instance_name": cr_instance_name,
+        "cr_namespace_name": cr_namespace_name,
+        "cr_repo_name": cr_repo_name,
+        "cr_region": region,
+    }
+
+    if not vefaas_function_id:
+        click.echo(
+            "No Function ID specified. VeADK will create one automatically. Please specify a function name:"
+        )
+        function_name = click.prompt(
+            "Function name", default="veadk-image-function", show_default=False
+        )
+
+    _create_cr(volcengine_settings, cr_settings)
+
+    if not vefaas_function_id:
+        vefaas_client = VeFaaS(
+            access_key=volcengine_settings["volcengine_access_key"],
+            secret_key=volcengine_settings["volcengine_secret_key"],
+            region=volcengine_settings["volcengine_region"],
+        )
+        _, _, function_id = vefaas_client.deploy_image(
+            name=function_name,
+            image="veadk-cn-beijing.cr.volces.com/veadk/simple-fastapi:0.1",
+            registry_name=cr_settings["cr_instance_name"],
+        )
+        logger.debug(f"Created function {function_name} with ID: {function_id}")
+
+    client = VeCodePipeline(
+        volcengine_access_key=volcengine_settings["volcengine_access_key"],
+        volcengine_secret_key=volcengine_settings["volcengine_secret_key"],
+        region=volcengine_settings["volcengine_region"],
+    )
+
+    click.echo("=====================================================")
+    click.echo("Using the following configuration to create pipeline:")
+    click.echo(f"Use VeADK version: {veadk_version}")
+    click.echo(f"Github url: {github_url}")
+    click.echo(f"Github branch: {github_branch}")
+    click.echo(f"VeFaaS function name: {function_name}")
+    click.echo(f"VeFaaS function ID: {function_id}")
+    click.echo(f"Container Registry domain: {cr_settings['cr_domain']}")
+    click.echo(f"Container Registry namespace name: {cr_settings['cr_namespace_name']}")
+    click.echo(f"Container Registry region: {region}")
+    click.echo(f"Container Registry instance name: {cr_settings['cr_instance_name']}")
+    click.echo(f"Container Registry repo name: {cr_settings['cr_repo_name']}")
+
+    client.deploy(
+        base_image_tag=veadk_version,
+        github_url=github_url,
+        github_branch=github_branch,
+        github_token=github_token,
+        cr_domain=cr_settings["cr_domain"],
+        cr_namespace_name=cr_settings["cr_namespace_name"],
+        cr_region=cr_settings["cr_region"],
+        cr_instance_name=cr_settings["cr_instance_name"],
+        cr_repo_name=cr_settings["cr_repo_name"],
+        function_id=function_id,
+    )
+
+    click.echo("Pipeline has been created successfully.")

veadk/cli/cli_prompt.py

@@ -0,0 +1,86 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import click
+
+
+@click.command()
+@click.option(
+    "--path", default=".", help="Agent file path with global variable `agent=...`"
+)
+@click.option("--feedback", default="", help="Suggestions for prompt optimization")
+@click.option("--api-key", default="", help="API Key of PromptPilot")
+@click.option("--workspace-id", default="", help="Workspace ID of PromptPilot")
+@click.option(
+    "--model-name",
+    default="doubao-1.5-pro-32k-250115",
+    help="Model name for prompt optimization",
+)
+def prompt(
+    path: str, feedback: str, api_key: str, workspace_id: str, model_name: str
+) -> None:
+    """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
+    from veadk.config import settings
+    from veadk.integrations.ve_prompt_pilot.ve_prompt_pilot import VePromptPilot
+    from veadk.utils.misc import load_module_from_file
+
+    module_name = "agents_for_prompt_pilot"
+    module_abs_path = Path(path).resolve()
+
+    module = load_module_from_file(
+        module_name=module_name, file_path=str(module_abs_path)
+    )
+
+    # get all global variables from module
+    globals_in_module = vars(module)
+
+    agents = []
+    for global_variable_name, global_variable_value in globals_in_module.items():
+        if isinstance(global_variable_value, Agent):
+            agent = global_variable_value
+            agents.append(agent)
+
+    if len(agents) > 0:
+        click.echo(f"Found {len(agents)} agents in {module_abs_path}")
+
+        if not api_key:
+            api_key = settings.prompt_pilot.api_key
+
+        if not workspace_id:
+            raise ValueError("Please provide workspace_id for PromptPilot service.")
+
+        ve_prompt_pilot = VePromptPilot(api_key=api_key, workspace_id=workspace_id)
+        ve_prompt_pilot.optimize(
+            agents=agents, feedback=feedback, model_name=model_name
+        )
+    else:
+        click.echo(f"No agents found in {module_abs_path}")

veadk/cli/cli_update.py

@@ -0,0 +1,106 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import click
+
+from veadk.cloud.cloud_agent_engine import CloudAgentEngine
+from veadk.utils.logger import get_logger
+from veadk.config import getenv
+
+logger = get_logger(__name__)
+
+
+@click.command()
+@click.option(
+    "--volcengine-access-key",
+    default=None,
+    help="Volcengine access key for authentication. Defaults to VOLCENGINE_ACCESS_KEY environment variable.",
+)
+@click.option(
+    "--volcengine-secret-key",
+    default=None,
+    help="Volcengine secret key for authentication. Defaults to VOLCENGINE_SECRET_KEY environment variable.",
+)
+@click.option(
+    "--vefaas-app-name",
+    required=True,
+    help="Name of the cloud application to update.",
+)
+@click.option(
+    "--path",
+    default=".",
+    help="Local path containing the updated code. Defaults to current directory.",
+)
+def update(
+    volcengine_access_key: str,
+    volcengine_secret_key: str,
+    vefaas_app_name: str,
+    path: str,
+) -> None:
+    """Update function code of a deployed cloud application on Volcengine FaaS.
+
+    This command updates the code of an existing cloud application without changing
+    the endpoint or other resources. It uploads the local project code to replace
+    the existing function implementation.
+
+    The update process:
+    1. Authenticates with Volcengine using provided credentials
+    2. Validates the local project path and application name
+    3. Uploads the updated code to the existing application
+    4. Preserves the existing endpoint and gateway configuration
+
+    Args:
+        volcengine_access_key: Volcengine platform access key for authentication.
+            If not provided, uses VOLCENGINE_ACCESS_KEY environment variable.
+        volcengine_secret_key: Volcengine platform secret key for authentication.
+            If not provided, uses VOLCENGINE_SECRET_KEY environment variable.
+        vefaas_app_name: Name of the existing cloud application to update.
+        path: Local directory path containing the updated agent project.
+            Defaults to current directory if not specified.
+
+    Note:
+        - Application must already exist on Volcengine FaaS
+        - Only function code is updated, endpoint remains unchanged
+        - Uses default region 'cn-beijing' for Volcengine services
+
+    Raises:
+        ValueError: If authentication fails or application not found.
+        FileNotFoundError: If local path does not exist.
+    """
+    # Set environment variables if provided
+    if not volcengine_access_key:
+        volcengine_access_key = getenv("VOLCENGINE_ACCESS_KEY")
+    if not volcengine_secret_key:
+        volcengine_secret_key = getenv("VOLCENGINE_SECRET_KEY")
+
+    # Initialize cloud agent engine
+    engine = CloudAgentEngine(
+        volcengine_access_key=volcengine_access_key,
+        volcengine_secret_key=volcengine_secret_key,
+    )
+
+    try:
+        # Update function code
+        updated_app = engine.update_function_code(
+            application_name=vefaas_app_name,
+            path=path,
+        )
+
+        logger.info(f"Successfully updated cloud application '{vefaas_app_name}'")
+        logger.info(f"Endpoint: {updated_app.vefaas_endpoint}")
+        logger.info(f"Application ID: {updated_app.vefaas_application_id}")
+
+    except Exception as e:
+        logger.error(f"Failed to update cloud application: {e}")
+        raise