veadk-python 0.2.27__py3-none-any.whl

veadk/configs/auth_configs.py

@@ -0,0 +1,133 @@
+# 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 typing import TYPE_CHECKING, Optional, Any
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+if TYPE_CHECKING:
+    from veadk.integrations.ve_identity.identity_client import IdentityClient
+else:
+    # For runtime, use Any to avoid circular import issues
+    IdentityClient = Any
+
+
+class VeIdentityConfig(BaseSettings):
+    """Configuration for VolcEngine Identity Service.
+
+    This configuration class manages settings for Agent Identity service,
+    including region and endpoint information.
+
+    It also provides a global singleton IdentityClient instance to ensure:
+    - Credential caching is shared across the application
+    - HTTP connection pooling is reused
+    - Consistent configuration throughout the application
+
+    Attributes:
+        region: The VolcEngine region for Identity service.
+        endpoint: The endpoint URL for Identity service API.
+                  If not provided, will be auto-generated based on region.
+    """
+
+    model_config = SettingsConfigDict(env_prefix="VEIDENTITY_")
+
+    region: str = "cn-beijing"
+    """The VolcEngine region for Identity service.
+    """
+
+    endpoint: str = ""
+    """The endpoint URL for Identity service API.
+
+    If not provided, the endpoint will be auto-generated based on the region.
+    """
+
+    role_session_name: str = "veadk_default_assume_role_session"
+    """Role session name, used to distinguish different sessions in audit logs.
+    """
+
+    # Global singleton IdentityClient instance
+    _identity_client: Optional["IdentityClient"] = None
+
+    def get_endpoint(self) -> str:
+        """Get the endpoint URL for Identity service.
+
+        Returns the configured endpoint if provided, otherwise generates
+        the endpoint based on the region.
+
+        Returns:
+            The endpoint URL for Identity service API.
+
+        Raises:
+            ValueError: If region is not supported.
+        """
+        if self.endpoint:
+            return self.endpoint
+
+        return f"id.{self.region}.volces.com"
+
+    def get_identity_client(
+        self,
+        access_key: Optional[str] = None,
+        secret_key: Optional[str] = None,
+        session_token: Optional[str] = None,
+    ) -> IdentityClient:
+        """Get or create the global IdentityClient instance.
+
+        This method implements a singleton pattern to ensure only one IdentityClient
+        instance is created per configuration. This allows:
+        - Credential caching to be shared across the application
+        - HTTP connection pooling to be reused
+        - Consistent configuration throughout the application
+
+        Args:
+            access_key: Optional VolcEngine access key. If not provided, uses env vars.
+            secret_key: Optional VolcEngine secret key. If not provided, uses env vars.
+            session_token: Optional VolcEngine session token. If not provided, uses env vars.
+
+        Returns:
+            The global IdentityClient instance.
+
+        Examples:
+            ```python
+            from veadk.config import settings
+
+            # Get the global identity client
+            identity_client = settings.veidentity.get_identity_client()
+
+            # Use it to get workload tokens
+            token = identity_client.get_workload_access_token(
+                workload_name="my_workload",
+                user_id="user123"
+            )
+            ```
+        """
+        # Lazy initialization: create client only when first requested
+        if self._identity_client is None:
+            from veadk.integrations.ve_identity import IdentityClient
+
+            self._identity_client = IdentityClient(
+                access_key=access_key,
+                secret_key=secret_key,
+                session_token=session_token,
+                region=self.region,
+            )
+
+        return self._identity_client
+
+    def reset_identity_client(self) -> None:
+        """Reset the global IdentityClient instance.
+
+        This forces the next call to get_identity_client() to create a new instance.
+        Useful for testing or when credentials need to be refreshed.
+        """
+        self._identity_client = None

veadk/configs/database_configs.py

@@ -0,0 +1,132 @@
+# 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 functools import cached_property
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from veadk.consts import DEFAULT_TOS_BUCKET_NAME
+from veadk.integrations.ve_tos.ve_tos import VeTOS
+
+
+class OpensearchConfig(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="DATABASE_OPENSEARCH_")
+
+    host: str = ""
+
+    port: int = 9200
+
+    username: str = ""
+
+    password: str = ""
+
+    secret_token: str = ""
+
+
+class MysqlConfig(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="DATABASE_MYSQL_")
+
+    host: str = ""
+
+    user: str = ""
+
+    password: str = ""
+
+    database: str = ""
+
+    charset: str = "utf8"
+
+    secret_token: str = ""
+    """STS token for MySQL auth, not supported yet."""
+
+
+class PostgreSqlConfig(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="DATABASE_POSTGRESQL_")
+
+    host: str = ""
+
+    port: int = 5432
+
+    user: str = ""
+
+    password: str = ""
+
+    database: str = ""
+
+    secret_token: str = ""
+
+
+class RedisConfig(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="DATABASE_REDIS_")
+
+    host: str = ""
+
+    port: int = 6379
+
+    username: str | None = None
+
+    password: str = ""
+
+    db: int = 0
+
+    secret_token: str = ""
+    """STS token for Redis auth, not supported yet."""
+
+
+class Mem0Config(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="DATABASE_MEM0_")
+
+    api_key: str = ""
+    """Mem0 API key"""
+
+    api_key_id: str = ""
+
+    project_id: str = ""
+
+    base_url: str = ""  # "https://api.mem0.ai/v1"
+
+
+class VikingKnowledgebaseConfig(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="DATABASE_VIKING_")
+
+    project: str = "default"
+    """User project in Volcengine console web."""
+
+    region: str = "cn-beijing"
+
+
+class TOSConfig(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="DATABASE_TOS_")
+
+    endpoint: str = "tos-cn-beijing.volces.com"
+
+    region: str = "cn-beijing"
+
+    @cached_property
+    def bucket(self) -> str:
+        _bucket = os.getenv("DATABASE_TOS_BUCKET") or DEFAULT_TOS_BUCKET_NAME
+
+        VeTOS(bucket_name=_bucket).create_bucket()
+        return _bucket
+
+
+class NormalTOSConfig(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="DATABASE_TOS_")
+
+    endpoint: str = "tos-cn-beijing.volces.com"
+
+    region: str = "cn-beijing"
+
+    bucket: str

veadk/configs/model_configs.py

@@ -0,0 +1,78 @@
+# 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 functools import cached_property
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from veadk.auth.veauth.ark_veauth import get_ark_token
+from veadk.consts import (
+    DEFAULT_MODEL_AGENT_API_BASE,
+    DEFAULT_MODEL_AGENT_NAME,
+    DEFAULT_MODEL_AGENT_PROVIDER,
+)
+
+
+class ModelConfig(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="MODEL_AGENT_")
+
+    name: str = DEFAULT_MODEL_AGENT_NAME
+    """Model name for agent reasoning."""
+
+    provider: str = DEFAULT_MODEL_AGENT_PROVIDER
+    """Model provider for LiteLLM initialization."""
+
+    api_base: str = DEFAULT_MODEL_AGENT_API_BASE
+    """The api base of the model for agent reasoning."""
+
+    @cached_property
+    def api_key(self) -> str:
+        return os.getenv("MODEL_AGENT_API_KEY") or get_ark_token()
+
+
+class EmbeddingModelConfig(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="MODEL_EMBEDDING_")
+
+    name: str = "doubao-embedding-text-240715"
+    """Model name for embedding."""
+
+    dim: int = 2560
+    """Embedding dim is different from different models."""
+
+    api_base: str = "https://ark.cn-beijing.volces.com/api/v3/"
+    """The api base of the model for embedding."""
+
+    @cached_property
+    def api_key(self) -> str:
+        return (
+            os.getenv("MODEL_EMBEDDING_API_KEY")
+            or os.getenv("MODEL_AGENT_API_KEY")  # try to use agent's model api key
+            or get_ark_token()
+        )
+
+
+class NormalEmbeddingModelConfig(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="MODEL_EMBEDDING_")
+
+    name: str = "doubao-embedding-text-240715"
+    """Model name for embedding."""
+
+    dim: int = 2560
+    """Embedding dim is different from different models."""
+
+    api_base: str = "https://ark.cn-beijing.volces.com/api/v3/"
+    """The api base of the model for embedding."""
+
+    api_key: str

veadk/configs/tool_configs.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 functools import cached_property
+
+from pydantic import BaseModel, Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from veadk.auth.veauth.prompt_pilot_veauth import PromptPilotVeAuth
+from veadk.auth.veauth.vesearch_veauth import VesearchVeAuth
+from veadk.auth.veauth.speech_veauth import get_speech_token
+
+
+class PromptPilotConfig(BaseModel):
+    @cached_property
+    def api_key(self) -> str:
+        return os.getenv("PROMPT_PILOT_API_KEY") or PromptPilotVeAuth().token
+
+
+class VeSearchConfig(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="TOOL_VESEARCH_")
+
+    endpoint: int | str = ""
+
+    @cached_property
+    def api_key(self) -> str:
+        return os.getenv("TOOL_VESEARCH_API_KEY") or VesearchVeAuth().token
+
+
+class VeSpeechConfig(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="TOOL_VESPEECH_")
+
+    endpoint: int | str = ""
+
+    @cached_property
+    def api_key(self) -> str:
+        return os.getenv("TOOL_VESPEECH_API_KEY") or get_speech_token()
+
+
+class BuiltinToolConfigs(BaseModel):
+    vesearch: VeSearchConfig = Field(default_factory=VeSearchConfig)
+    vespeech: VeSpeechConfig = Field(default_factory=VeSpeechConfig)

veadk/configs/tracing_configs.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.
+
+import os
+from functools import cached_property
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from veadk.auth.veauth.apmplus_veauth import get_apmplus_token
+from veadk.consts import (
+    DEFAULT_APMPLUS_OTEL_EXPORTER_ENDPOINT,
+    DEFAULT_APMPLUS_OTEL_EXPORTER_SERVICE_NAME,
+    DEFAULT_COZELOOP_OTEL_EXPORTER_ENDPOINT,
+    DEFAULT_COZELOOP_SPACE_NAME,
+    DEFAULT_TLS_OTEL_EXPORTER_ENDPOINT,
+    DEFAULT_TLS_OTEL_EXPORTER_REGION,
+)
+from veadk.integrations.ve_cozeloop.ve_cozeloop import VeCozeloop
+from veadk.integrations.ve_tls.ve_tls import VeTLS
+
+
+class APMPlusConfig(BaseSettings):
+    otel_exporter_endpoint: str = Field(
+        default=DEFAULT_APMPLUS_OTEL_EXPORTER_ENDPOINT,
+        alias="OBSERVABILITY_OPENTELEMETRY_APMPLUS_ENDPOINT",
+    )
+
+    otel_exporter_service_name: str = Field(
+        default=DEFAULT_APMPLUS_OTEL_EXPORTER_SERVICE_NAME,
+        alias="OBSERVABILITY_OPENTELEMETRY_APMPLUS_SERVICE_NAME",
+    )
+
+    @cached_property
+    def otel_exporter_api_key(self) -> str:
+        return (
+            os.getenv("OBSERVABILITY_OPENTELEMETRY_APMPLUS_API_KEY")
+            or get_apmplus_token()
+        )
+
+
+class CozeloopConfig(BaseSettings):
+    otel_exporter_endpoint: str = Field(
+        default=DEFAULT_COZELOOP_OTEL_EXPORTER_ENDPOINT,
+        alias="OBSERVABILITY_OPENTELEMETRY_COZELOOP_ENDPOINT",
+    )
+
+    otel_exporter_api_key: str = Field(
+        default="", alias="OBSERVABILITY_OPENTELEMETRY_COZELOOP_API_KEY"
+    )
+
+    # TODO: auto fetching via AK/SK pair
+    # @cached_property
+    # def otel_exporter_api_key(self) -> str:
+    #     pass
+
+    @cached_property
+    def otel_exporter_space_id(self) -> str:
+        workspace_id = os.getenv(
+            "OBSERVABILITY_OPENTELEMETRY_COZELOOP_SERVICE_NAME", ""
+        )
+
+        if not workspace_id:
+            # create a default one
+            workspace_id = VeCozeloop(self.otel_exporter_api_key).create_workspace(
+                workspace_name=DEFAULT_COZELOOP_SPACE_NAME
+            )
+
+        return workspace_id
+
+
+class TLSConfig(BaseSettings):
+    otel_exporter_endpoint: str = Field(
+        default=DEFAULT_TLS_OTEL_EXPORTER_ENDPOINT,
+        alias="OBSERVABILITY_OPENTELEMETRY_TLS_ENDPOINT",
+    )
+
+    otel_exporter_region: str = Field(
+        default=DEFAULT_TLS_OTEL_EXPORTER_REGION,
+        alias="OBSERVABILITY_OPENTELEMETRY_TLS_REGION",
+    )
+
+    @cached_property
+    def otel_exporter_topic_id(self) -> str:
+        _topic_id = (
+            os.getenv("OBSERVABILITY_OPENTELEMETRY_TLS_SERVICE_NAME")
+            or VeTLS().get_trace_topic_id()
+        )
+        return _topic_id
+
+
+class PrometheusConfig(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="OBSERVABILITY_PROMETHEUS_")
+
+    pushgateway_url: str = ""
+
+    pushgateway_username: str = ""
+
+    pushgateway_password: str = ""

veadk/consts.py

@@ -0,0 +1,74 @@
+# 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
+
+from veadk.utils.misc import getenv
+from veadk.version import VERSION
+
+DEFAULT_AGENT_NAME = "veAgent"
+
+DEFAULT_MODEL_AGENT_NAME = "doubao-seed-1-6-250615"
+DEFAULT_MODEL_AGENT_PROVIDER = "openai"
+DEFAULT_MODEL_AGENT_API_BASE = "https://ark.cn-beijing.volces.com/api/v3/"
+DEFAULT_MODEL_EXTRA_CONFIG = {
+    "extra_headers": {
+        "x-is-encrypted": getenv("MODEL_AGENT_ENCRYPTED", "true"),
+        "veadk-source": "veadk",
+        "veadk-version": VERSION,
+        "User-Agent": f"VeADK/{VERSION}",
+        "X-Client-Request-Id": f"veadk/{VERSION}",
+    },
+    "extra_body": {
+        "caching": {
+            "type": getenv("MODEL_AGENT_CACHING", "enabled"),
+        },
+        # "thinking": {
+        #     "type": "disabled"
+        # },
+        "expire_at": int(time.time()) + 3600,  # expire after 1 hour
+    },
+}
+
+DEFAULT_APMPLUS_OTEL_EXPORTER_ENDPOINT = "http://apmplus-cn-beijing.volces.com:4317"
+DEFAULT_APMPLUS_OTEL_EXPORTER_SERVICE_NAME = "veadk_tracing"
+
+DEFAULT_COZELOOP_OTEL_EXPORTER_ENDPOINT = (
+    "https://api.coze.cn/v1/loop/opentelemetry/v1/traces"
+)
+
+DEFAULT_TLS_OTEL_EXPORTER_ENDPOINT = "https://tls-cn-beijing.volces.com:4318/v1/traces"
+DEFAULT_TLS_OTEL_EXPORTER_REGION = "cn-beijing"
+
+DEFAULT_CR_INSTANCE_NAME = "veadk-user-instance"
+DEFAULT_CR_NAMESPACE_NAME = "veadk-user-namespace"
+DEFAULT_CR_REPO_NAME = "veadk-user-repo"
+
+DEFAULT_TLS_LOG_PROJECT_NAME = "veadk-logs"
+DEFAULT_TLS_TRACING_INSTANCE_NAME = "veadk-tracing"
+
+DEFAULT_TOS_BUCKET_NAME = "ark-tutorial"
+
+DEFAULT_COZELOOP_SPACE_NAME = "VeADK Space"
+
+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/"
+
+DEFAULT_VIDEO_MODEL_NAME = "doubao-seedance-1-0-pro-250528"
+DEFAULT_VIDEO_MODEL_API_BASE = "https://ark.cn-beijing.volces.com/api/v3/"
+
+DEFAULT_IMAGE_GENERATE_MODEL_NAME = "doubao-seedream-4-0-250828"
+DEFAULT_IMAGE_GENERATE_MODEL_API_BASE = "https://ark.cn-beijing.volces.com/api/v3/"
+
+VEFAAS_IAM_CRIDENTIAL_PATH = "/var/run/secrets/iam/credential"

veadk/evaluation/__init__.py

@@ -0,0 +1,17 @@
+# 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 .eval_set_recorder import EvalSetRecorder
+
+__all__ = ["EvalSetRecorder"]

veadk/evaluation/adk_evaluator/__init__.py

@@ -0,0 +1,17 @@
+# 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 .adk_evaluator import ADKEvaluator
+
+__all__ = ["ADKEvaluator"]