veadk-python 0.2.12__py3-none-any.whl → 0.2.14__py3-none-any.whl

veadk/cli/cli.py

@@ -18,6 +18,7 @@ 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
@@ -37,6 +38,7 @@ def veadk():
 
 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/cli/cli_create.py

@@ -0,0 +1,122 @@
+# 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
+
+_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
+"""
+
+_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",
+)
+"""
+
+_SUCCESS_MSG = """\
+Agent '{agent_name}' created successfully at '{agent_folder}':
+- config.yaml
+- {agent_name}/__init__.py
+- {agent_name}/agent.py
+
+You can run the agent by executing: cd {agent_name} && veadk web
+"""
+
+
+def _prompt_for_ark_api_key() -> str:
+    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.")
+    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"
+        )
+        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)
+    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),
+        fg="green",
+    )
+
+
+@click.command()
+@click.option("--agent-name", help="The name of the agent.")
+@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."""
+    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(agent_name, ark_api_key, target_dir_path)

veadk/consts.py

@@ -62,9 +62,6 @@ DEFAULT_TOS_BUCKET_NAME = "ark-tutorial"
 
 DEFAULT_COZELOOP_SPACE_NAME = "VeADK Space"
 
-DEFAULT_TEXT_TO_IMAGE_MODEL_NAME = "doubao-seedream-3-0-t2i-250415"
-DEFAULT_TEXT_TO_IMAGE_MODEL_API_BASE = "https://ark.cn-beijing.volces.com/api/v3/"
-
 DEFAULT_IMAGE_EDIT_MODEL_NAME = "doubao-seededit-3-0-i2i-250628"
 DEFAULT_IMAGE_EDIT_MODEL_API_BASE = "https://ark.cn-beijing.volces.com/api/v3/"
 

veadk/integrations/ve_tos/ve_tos.py

@@ -36,11 +36,14 @@ class VeTOS:
         self,
         ak: str = "",
         sk: str = "",
+        session_token: str = "",
         region: str = "cn-beijing",
         bucket_name: str = DEFAULT_TOS_BUCKET_NAME,
     ) -> None:
         self.ak = ak if ak else os.getenv("VOLCENGINE_ACCESS_KEY", "")
         self.sk = sk if sk else os.getenv("VOLCENGINE_SECRET_KEY", "")
+        self.session_token = session_token
+
         # Add empty value validation
         if not self.ak or not self.sk:
             raise ValueError(
@@ -71,6 +74,7 @@ class VeTOS:
             self._client = self._tos_module.TosClientV2(
                 ak=self.ak,
                 sk=self.sk,
+                security_token=self.session_token,
                 endpoint=f"tos-{self.region}.volces.com",
                 region=self.region,
             )
@@ -85,6 +89,7 @@ class VeTOS:
             self._client = self._tos_module.TosClientV2(
                 self.ak,
                 self.sk,
+                security_token=self.session_token,
                 endpoint=f"tos-{self.region}.volces.com",
                 region=self.region,
             )

veadk/knowledgebase/backends/utils.py

@@ -46,6 +46,7 @@ def build_vikingdb_knowledgebase_request(
     path: str,
     volcengine_access_key: str,
     volcengine_secret_key: str,
+    session_token: str = "",
     method: Literal["GET", "POST", "PUT", "DELETE"] = "POST",
     region: str = "cn-beijing",
     params=None,
@@ -85,7 +86,7 @@ def build_vikingdb_knowledgebase_request(
         r.set_body(json.dumps(data))
 
     credentials = Credentials(
-        volcengine_access_key, volcengine_secret_key, "air", region
+        volcengine_access_key, volcengine_secret_key, "air", region, session_token
     )
     SignerV4.sign(r, credentials)
     return r

veadk/knowledgebase/backends/vikingdb_knowledge_backend.py

@@ -14,6 +14,7 @@
 
 import asyncio
 import json
+import os
 import re
 from pathlib import Path
 from typing import Any, Literal
@@ -23,7 +24,7 @@ from pydantic import Field
 from typing_extensions import override
 
 import veadk.config  # noqa E401
-from veadk.config import getenv
+from veadk.auth.veauth.utils import get_credential_from_vefaas_iam
 from veadk.configs.database_configs import NormalTOSConfig, TOSConfig
 from veadk.knowledgebase.backends.base_backend import BaseKnowledgebaseBackend
 from veadk.knowledgebase.backends.utils import build_vikingdb_knowledgebase_request
@@ -58,14 +59,16 @@ def get_files_in_directory(directory: str):
 
 
 class VikingDBKnowledgeBackend(BaseKnowledgebaseBackend):
-    volcengine_access_key: str = Field(
-        default_factory=lambda: getenv("VOLCENGINE_ACCESS_KEY")
+    volcengine_access_key: str | None = Field(
+        default_factory=lambda: os.getenv("VOLCENGINE_ACCESS_KEY")
     )
 
-    volcengine_secret_key: str = Field(
-        default_factory=lambda: getenv("VOLCENGINE_SECRET_KEY")
+    volcengine_secret_key: str | None = Field(
+        default_factory=lambda: os.getenv("VOLCENGINE_SECRET_KEY")
     )
 
+    session_token: str = ""
+
     volcengine_project: str = "default"
     """VikingDB knowledgebase project in Volcengine console platform. Default by `default`"""
 
@@ -75,6 +78,15 @@ class VikingDBKnowledgeBackend(BaseKnowledgebaseBackend):
     tos_config: TOSConfig | NormalTOSConfig = Field(default_factory=TOSConfig)
     """TOS config, used to upload files to TOS"""
 
+    def model_post_init(self, __context: Any) -> None:
+        self.precheck_index_naming()
+
+        # check whether collection exist, if not, create it
+        if not self.collection_status()["existed"]:
+            logger.warning(
+                f"VikingDB knowledgebase collection {self.index} does not exist, please create it first..."
+            )
+
     def precheck_index_naming(self):
         if not (
             isinstance(self.index, str)
@@ -86,18 +98,21 @@ class VikingDBKnowledgeBackend(BaseKnowledgebaseBackend):
                 "it must start with an English letter, contain only letters, numbers, and underscores, and have a length of 1-128."
             )
 
-    def model_post_init(self, __context: Any) -> None:
-        self.precheck_index_naming()
-
-        # check whether collection exist, if not, create it
-        if not self.collection_status()["existed"]:
-            logger.warning(
-                f"VikingDB knowledgebase collection {self.index} does not exist, please create it first..."
-            )
-
-        self._tos_client = VeTOS(
-            ak=self.volcengine_access_key,
-            sk=self.volcengine_secret_key,
+    def _get_tos_client(self) -> VeTOS:
+        volcengine_access_key = self.volcengine_access_key
+        volcengine_secret_key = self.volcengine_secret_key
+        session_token = self.session_token
+
+        if not (volcengine_access_key and volcengine_secret_key):
+            cred = get_credential_from_vefaas_iam()
+            volcengine_access_key = cred.access_key_id
+            volcengine_secret_key = cred.secret_access_key
+            session_token = cred.session_token
+
+        return VeTOS(
+            ak=volcengine_access_key,
+            sk=volcengine_secret_key,
+            session_token=session_token,
             region=self.tos_config.region,
             bucket_name=self.tos_config.bucket,
         )
@@ -404,6 +419,8 @@ class VikingDBKnowledgeBackend(BaseKnowledgebaseBackend):
         metadata: dict | None = None,
     ) -> str:
         # Here, we set the metadata via the TOS object, ref: https://www.volcengine.com/docs/84313/1254624
+        self._tos_client = self._get_tos_client()
+
         self._tos_client.bucket_name = tos_bucket_name
         coro = self._tos_client.upload(
             object_key=object_key,
@@ -504,10 +521,21 @@ class VikingDBKnowledgeBackend(BaseKnowledgebaseBackend):
     ) -> dict:
         VIKINGDB_KNOWLEDGEBASE_BASE_URL = "api-knowledgebase.mlp.cn-beijing.volces.com"
 
+        volcengine_access_key = self.volcengine_access_key
+        volcengine_secret_key = self.volcengine_secret_key
+        session_token = self.session_token
+
+        if not (volcengine_access_key and volcengine_secret_key):
+            cred = get_credential_from_vefaas_iam()
+            volcengine_access_key = cred.access_key_id
+            volcengine_secret_key = cred.secret_access_key
+            session_token = cred.session_token
+
         request = build_vikingdb_knowledgebase_request(
             path=path,
-            volcengine_access_key=self.volcengine_access_key,
-            volcengine_secret_key=self.volcengine_secret_key,
+            volcengine_access_key=volcengine_access_key,
+            volcengine_secret_key=volcengine_secret_key,
+            session_token=session_token,
             method=method,
             data=body,
         )

veadk/memory/long_term_memory.py

@@ -104,6 +104,15 @@ class LongTermMemory(BaseMemoryService, BaseModel):
 
         # Once user define backend config, use it directly
         if self.backend_config:
+            if "index" not in self.backend_config:
+                logger.warning(
+                    "Attribute `index` not provided in backend_config, use `index` or `app_name` instead."
+                )
+                self.backend_config["index"] = self.index or self.app_name
+
+            logger.debug(
+                f"Init {self.backend}, Use provided backend config: {self.backend_config}"
+            )
             self._backend = _get_backend_cls(self.backend)(**self.backend_config)
             return
 

veadk/memory/long_term_memory_backends/vikingdb_memory_backend.py

@@ -49,7 +49,23 @@ class VikingDBLTMBackend(BaseLongTermMemoryBackend):
     region: str = "cn-beijing"
     """VikingDB memory region"""
 
+    memory_type: list[str] = Field(default_factory=list)
+
     def model_post_init(self, __context: Any) -> None:
+        # We get memory type from:
+        # 1. user input
+        # 2. environment variable
+        # 3. default value
+        if not self.memory_type:
+            env_memory_type = os.getenv("DATABASE_VIKINGMEM_MEMORY_TYPE")
+            if env_memory_type:
+                # "event_1, event_2" -> ["event_1", "event_2"]
+                self.memory_type = [x.strip() for x in env_memory_type.split(",")]
+            else:
+                self.memory_type = ["sys_event_v1", "event_v1"]
+
+        logger.info(f"Using memory type: {self.memory_type}")
+
         # check whether collection exist, if not, create it
         if not self._collection_exist():
             self._create_collection()
@@ -68,17 +84,23 @@ class VikingDBLTMBackend(BaseLongTermMemoryBackend):
         try:
             client = self._get_client()
             client.get_collection(collection_name=self.index)
+            logger.info(f"Collection {self.index} exist.")
             return True
         except Exception:
+            logger.info(f"Collection {self.index} not exist.")
             return False
 
     def _create_collection(self) -> None:
+        logger.info(
+            f"Create collection with collection_name={self.index}, builtin_event_types={self.memory_type}"
+        )
         client = self._get_client()
         response = client.create_collection(
             collection_name=self.index,
             description="Created by Volcengine Agent Development Kit VeADK",
-            builtin_event_types=["sys_event_v1"],
+            builtin_event_types=self.memory_type,
         )
+        logger.debug(f"Create collection with response {response}")
         return response
 
     def _get_client(self) -> VikingDBMemoryClient:
@@ -135,10 +157,7 @@ class VikingDBLTMBackend(BaseLongTermMemoryBackend):
     def search_memory(
         self, user_id: str, query: str, top_k: int, **kwargs
     ) -> list[str]:
-        filter = {
-            "user_id": user_id,
-            "memory_type": ["sys_event_v1", "event_v1"],
-        }
+        filter = {"user_id": user_id, "memory_type": self.memory_type}
 
         logger.debug(
             f"Request for search memory in VikingDB: filter={filter}, collection_name={self.index}, query={query}, limit={top_k}"