veadk-python 0.2.27__py3-none-any.whl

veadk/auth/veauth/prompt_pilot_veauth.py

@@ -0,0 +1,60 @@
+# 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 os
+
+from typing_extensions import override
+
+from veadk.auth.veauth.base_veauth import BaseVeAuth
+from veadk.utils.logger import get_logger
+from veadk.utils.volcengine_sign import ve_request
+
+logger = get_logger(__name__)
+
+
+class PromptPilotVeAuth(BaseVeAuth):
+    def __init__(
+        self,
+        access_key: str = os.getenv("VOLCENGINE_ACCESS_KEY", ""),
+        secret_key: str = os.getenv("VOLCENGINE_SECRET_KEY", ""),
+    ) -> None:
+        super().__init__(access_key, secret_key)
+
+        self._token: str = ""
+
+    @override
+    def _fetch_token(self) -> None:
+        logger.info("Fetching Prompt Pilot token...")
+
+        res = ve_request(
+            request_body={},
+            action="GetOrCreatePromptPilotAPIKeys",
+            ak=self.access_key,
+            sk=self.secret_key,
+            service="ark",
+            version="2024-01-01",
+            region="cn-beijing",
+            host="open.volcengineapi.com",
+        )
+        try:
+            self._token = res["Result"]["APIKeys"][0]["APIKey"]
+        except KeyError:
+            raise ValueError(f"Failed to get Prompt Pilot token: {res}")
+
+    @property
+    def token(self) -> str:
+        if self._token:
+            return self._token
+        self._fetch_token()
+        return self._token

veadk/auth/veauth/speech_veauth.py

@@ -0,0 +1,54 @@
+# 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 os
+
+from veadk.auth.veauth.utils import get_credential_from_vefaas_iam
+from veadk.utils.logger import get_logger
+from veadk.utils.volcengine_sign import ve_request
+
+logger = get_logger(__name__)
+
+
+def get_speech_token(region: str = "cn-beijing") -> str:
+    logger.info("Fetching speech token...")
+
+    access_key = os.getenv("VOLCENGINE_ACCESS_KEY")
+    secret_key = os.getenv("VOLCENGINE_SECRET_KEY")
+    session_token = ""
+
+    if not (access_key and secret_key):
+        # try to get from vefaas iam
+        cred = get_credential_from_vefaas_iam()
+        access_key = cred.access_key_id
+        secret_key = cred.secret_access_key
+        session_token = cred.session_token
+
+    res = ve_request(
+        request_body={"ProjectName": "default", "OnlyAvailable": True},
+        header={"X-Security-Token": session_token},
+        action="ListAPIKeys",
+        ak=access_key,
+        sk=secret_key,
+        service="speech_saas_prod",
+        version="2025-05-20",
+        region=region,
+        host="open.volcengineapi.com",
+    )
+    try:
+        first_api_key_id = res["Result"]["APIKeys"][0]["APIKey"]
+        logger.info("Successfully fetching speech API Key.")
+        return first_api_key_id
+    except KeyError:
+        raise ValueError(f"Failed to get speech api key list: {res}")

veadk/auth/veauth/utils.py

@@ -0,0 +1,69 @@
+# 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 json
+from pathlib import Path
+
+from pydantic import BaseModel
+
+from veadk.consts import VEFAAS_IAM_CRIDENTIAL_PATH
+from veadk.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class VeIAMCredential(BaseModel):
+    access_key_id: str
+    secret_access_key: str
+    session_token: str
+
+
+def get_credential_from_vefaas_iam() -> VeIAMCredential:
+    """Get credential from VeFaaS IAM file"""
+    logger.info(
+        f"Get Volcegnine access key or secret key from environment variables failed, try to get from VeFaaS IAM file (path={VEFAAS_IAM_CRIDENTIAL_PATH})."
+    )
+
+    path = Path(VEFAAS_IAM_CRIDENTIAL_PATH)
+
+    if not path.exists():
+        logger.error(
+            f"Get Volcegnine access key or secret key from environment variables failed, and VeFaaS IAM file (path={VEFAAS_IAM_CRIDENTIAL_PATH}) not exists. Please check your configuration."
+        )
+        raise FileNotFoundError(
+            f"Get Volcegnine access key or secret key from environment variables failed, and VeFaaS IAM file (path={VEFAAS_IAM_CRIDENTIAL_PATH}) not exists. Please check your configuration."
+        )
+
+    with open(VEFAAS_IAM_CRIDENTIAL_PATH, "r") as f:
+        cred_dict = json.load(f)
+        access_key = cred_dict["access_key_id"]
+        secret_key = cred_dict["secret_access_key"]
+        session_token = cred_dict["session_token"]
+
+        logger.info("Get credential from IAM file successfully.")
+
+        return VeIAMCredential(
+            access_key_id=access_key,
+            secret_access_key=secret_key,
+            session_token=session_token,
+        )
+
+
+def refresh_ak_sk(access_key: str, secret_key: str) -> VeIAMCredential:
+    if access_key and secret_key:
+        return VeIAMCredential(
+            access_key_id=access_key, secret_access_key=secret_key, session_token=""
+        )
+
+    return get_credential_from_vefaas_iam()

veadk/auth/veauth/vesearch_veauth.py

@@ -0,0 +1,62 @@
+# 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 os
+
+from typing_extensions import override
+
+from veadk.auth.veauth.base_veauth import BaseVeAuth
+from veadk.utils.logger import get_logger
+from veadk.utils.volcengine_sign import ve_request
+
+logger = get_logger(__name__)
+
+
+class VesearchVeAuth(BaseVeAuth):
+    def __init__(
+        self,
+        access_key: str = os.getenv("VOLCENGINE_ACCESS_KEY", ""),
+        secret_key: str = os.getenv("VOLCENGINE_SECRET_KEY", ""),
+    ) -> None:
+        super().__init__(access_key, secret_key)
+
+        self._token: str = ""
+
+    @override
+    def _fetch_token(self):
+        logger.info("Fetching VeSearch token ...")
+
+        res = ve_request(
+            request_body={"biz_scene": "search_agent", "page": 1, "rows": 10},
+            action="ListAPIKeys",
+            ak=self.access_key,
+            sk=self.secret_key,
+            service="content_customization",
+            version="2025-01-01",
+            region="cn-beijing",
+            host="open.volcengineapi.com",
+        )
+        try:
+            self._token = res["Result"]["api_key_vos"][0]["api_key"]
+
+            logger.info("Fetching VeSearch token done.")
+        except KeyError:
+            raise ValueError(f"Failed to get VeSearch token: {res}")
+
+    @property
+    def token(self) -> str:
+        if self._token:
+            return self._token
+        self._fetch_token()
+        return self._token

veadk/auth/veauth/viking_mem0_veauth.py

@@ -0,0 +1,91 @@
+# 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 os
+
+from veadk.auth.veauth.utils import get_credential_from_vefaas_iam
+from veadk.utils.logger import get_logger
+from veadk.utils.volcengine_sign import ve_request
+
+logger = get_logger(__name__)
+
+
+def _get_api_key_id_by_project_id(
+    project_id: str, access_key: str, secret_key: str, session_token: str, region: str
+):
+    res = ve_request(
+        request_body={"MemoryProjectId": project_id},
+        header={"X-Security-Token": session_token},
+        action="DescribeMemoryProjectDetail",
+        ak=access_key,
+        sk=secret_key,
+        service="mem0",
+        version="2025-10-10",
+        region=region,
+        host="open.volcengineapi.com",
+    )
+    try:
+        api_key_id = res["Result"]["APIKeyInfos"]["APIKeyId"]
+    except KeyError:
+        raise ValueError(f"Failed to get mem0 api key id: {res}")
+
+    return api_key_id
+
+
+def _get_api_key_by_api_key_id(
+    api_key_id: str, access_key: str, secret_key: str, session_token: str, region: str
+) -> str:
+    res = ve_request(
+        request_body={"APIKeyId": api_key_id},
+        header={"X-Security-Token": session_token},
+        action="DescribeAPIKeyDetail",
+        ak=access_key,
+        sk=secret_key,
+        service="mem0",
+        version="2025-10-10",
+        region=region,
+        host="open.volcengineapi.com",
+    )
+    try:
+        api_key = res["Result"]["APIKeyValue"]
+    except KeyError:
+        raise ValueError(f"Failed to get mem0 api key: {res}")
+
+    return api_key
+
+
+def get_viking_mem0_token(
+    api_key_id: str, memory_project_id: str, region: str = "cn-beijing"
+) -> str:
+    logger.info("Fetching Viking mem0 token...")
+
+    access_key = os.getenv("VOLCENGINE_ACCESS_KEY")
+    secret_key = os.getenv("VOLCENGINE_SECRET_KEY")
+    session_token = ""
+
+    if not (access_key and secret_key):
+        # try to get from vefaas iam
+        cred = get_credential_from_vefaas_iam()
+        access_key = cred.access_key_id
+        secret_key = cred.secret_access_key
+        session_token = cred.session_token
+
+    if not api_key_id:
+        api_key_id = _get_api_key_id_by_project_id(
+            memory_project_id, access_key, secret_key, session_token, region
+        )
+
+    return _get_api_key_by_api_key_id(
+        api_key_id, access_key, secret_key, session_token, region
+    )

veadk/cli/__init__.py

@@ -0,0 +1,13 @@
+# 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.

veadk/cli/cli.py

@@ -0,0 +1,58 @@
+# 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.cli.cli_deploy import deploy
+from veadk.cli.cli_eval import eval
+from veadk.cli.cli_init import init
+from veadk.cli.cli_create import create
+from veadk.cli.cli_kb import kb
+from veadk.cli.cli_pipeline import pipeline
+from veadk.cli.cli_prompt import prompt
+from veadk.cli.cli_web import web
+from veadk.cli.cli_uploadevalset import uploadevalset
+from veadk.cli.cli_update import update
+from veadk.cli.cli_clean import clean
+from veadk.version import VERSION
+
+
+@click.group()
+@click.version_option(
+    version=VERSION, prog_name="Volcengine Agent Development Kit (VeADK)"
+)
+def veadk():
+    """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.add_command(deploy)
+veadk.add_command(init)
+veadk.add_command(create)
+veadk.add_command(prompt)
+veadk.add_command(web)
+veadk.add_command(pipeline)
+veadk.add_command(eval)
+veadk.add_command(kb)
+veadk.add_command(uploadevalset)
+veadk.add_command(update)
+veadk.add_command(clean)
+
+if __name__ == "__main__":
+    veadk()

veadk/cli/cli_clean.py

@@ -0,0 +1,87 @@
+# 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 time
+import click
+
+from veadk.config import getenv
+from veadk.integrations.ve_faas.ve_faas import VeFaaS
+from veadk.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+@click.command()
+@click.option(
+    "--vefaas-app-name",
+    required=True,
+    help="VeFaaS application name to clean",
+)
+@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",
+)
+def clean(
+    vefaas_app_name: str, volcengine_access_key: str, volcengine_secret_key: str
+) -> None:
+    """
+    Clean and delete a VeFaaS application from the cloud.
+
+    This command deletes a specified VeFaaS application after user confirmation.
+    It will prompt the user for confirmation before proceeding with the deletion
+    and monitor the deletion process until completion.
+
+    Args:
+        vefaas_app_name (str): The name of the VeFaaS application to delete
+        volcengine_access_key (str): Volcengine access key for authentication.
+            If None, will use VOLCENGINE_ACCESS_KEY environment variable
+        volcengine_secret_key (str): Volcengine secret key for authentication.
+            If None, will use VOLCENGINE_SECRET_KEY environment variable
+
+    Returns:
+        None
+    """
+    if not volcengine_access_key:
+        volcengine_access_key = getenv("VOLCENGINE_ACCESS_KEY")
+    if not volcengine_secret_key:
+        volcengine_secret_key = getenv("VOLCENGINE_SECRET_KEY")
+
+    confirm = input(f"Confirm delete cloud app {vefaas_app_name}? (y/N): ")
+    if confirm.lower() != "y":
+        click.echo("Delete cancelled.")
+        return
+    else:
+        vefaas_client = VeFaaS(
+            access_key=volcengine_access_key, secret_key=volcengine_secret_key
+        )
+        vefaas_application_id = vefaas_client.find_app_id_by_name(vefaas_app_name)
+        vefaas_client.delete(vefaas_application_id)
+        click.echo(
+            f"Cloud app {vefaas_app_name} delete request has been sent to VeFaaS"
+        )
+        while True:
+            try:
+                id = vefaas_client.find_app_id_by_name(vefaas_app_name)
+                if not id:
+                    break
+                time.sleep(3)
+            except Exception as _:
+                break
+        click.echo("Delete application done.")

veadk/cli/cli_create.py

@@ -0,0 +1,163 @@
+# 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
+import shutil
+from pathlib import Path
+
+_ENV_TEMPLATE = """\
+MODEL_AGENT_API_KEY={ark_api_key}
+"""
+
+_INIT_PY_TEMPLATE = """\
+from . import agent
+"""
+
+_AGENT_PY_TEMPLATE = """\
+from veadk import Agent
+
+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 created in {agent_folder}:
+- .env
+- __init__.py
+- agent.py
+
+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 .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 .env file later.", fg="yellow")
+        return ""
+
+
+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_folder=target_dir_path),
+        fg="green",
+    )
+
+
+@click.command()
+@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:
+    """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:
+        ark_api_key = _prompt_for_ark_api_key()
+
+    cwd = Path.cwd()
+    target_dir_path = cwd / agent_name
+
+    if target_dir_path.exists() and any(target_dir_path.iterdir()):
+        if not click.confirm(
+            f"Directory '{target_dir_path}' already exists and is not empty. Do you want to overwrite it?"
+        ):
+            click.secho("Operation cancelled.", fg="red")
+            return
+        shutil.rmtree(target_dir_path)
+
+    _generate_files(ark_api_key, target_dir_path)