agentrun-inner-test 0.0.62__py3-none-any.whl

agentrun/utils/exception.py

@@ -0,0 +1,151 @@
+"""异常定义"""
+
+from typing import Optional
+
+
+class AgentRunError(Exception):
+    """AgentRun SDK 基础异常类"""
+
+    def __init__(
+        self,
+        message: str,
+        **kwargs,
+    ):
+        """初始化异常
+
+        Args:
+            message: 错误消息
+            details: 详细信息
+        """
+        msg = message or ""
+        if kwargs is not None:
+            msg += self.kwargs_str(**kwargs)
+
+        super().__init__(msg)
+        self.message = message
+        self.details = kwargs
+
+    @classmethod
+    def kwargs_str(cls, **kwargs) -> str:
+        """获取详细信息字符串
+
+        Returns:
+            str: 详细信息字符串
+        """
+        if not kwargs:
+            return ""
+        # return ", ".join([f"{key}={value!s}" for key, value in kwargs.items()])
+        import json
+
+        return json.dumps(
+            kwargs,
+            ensure_ascii=False,
+            default=lambda x: x.__dict__,
+        )
+
+    def details_str(self) -> str:
+        return self.kwargs_str(**self.details)
+
+    def __str__(self) -> str:
+        return self.message
+
+
+class HTTPError(AgentRunError):
+    """HTTP 异常类"""
+
+    def __init__(
+        self,
+        status_code: int,
+        message: str,
+        request_id: Optional[str] = None,
+        **kwargs,
+    ):
+        self.status_code = status_code
+        self.request_id = request_id
+        self.details = kwargs
+        super().__init__(message, **kwargs)
+
+    def __str__(self) -> str:
+        return (
+            f"HTTP {self.status_code}: {self.message}. Request ID:"
+            f" {self.request_id}. Details: {self.details_str()}"
+        )
+
+    def to_resource_error(
+        self, resource_type: str, resource_id: Optional[str] = ""
+    ):
+        if self.status_code == 404 and (
+            "does not exist" in self.message or "not found" in self.message
+        ):
+            return ResourceNotExistError(resource_type, resource_id)
+        elif (
+            self.status_code == 400
+            or self.status_code == 409
+            or self.status_code == 500
+        ) and ("already exists" in self.message):
+            # TODO: ModelProxy already exists returns 500
+            return ResourceAlreadyExistError(resource_type, resource_id)
+        else:
+            return self
+
+
+class ClientError(HTTPError):
+    """客户端异常类"""
+
+    def __init__(
+        self,
+        status_code: int,
+        message: str,
+        request_id: Optional[str] = None,
+        **kwargs,
+    ):
+        super().__init__(status_code, message, request_id=request_id, **kwargs)
+
+
+class ServerError(HTTPError):
+    """服务端异常类"""
+
+    def __init__(
+        self, status_code: int, message: str, request_id: Optional[str] = None
+    ):
+        super().__init__(status_code, message, request_id=request_id)
+
+
+class ResourceNotExistError(AgentRunError):
+    """资源不存在异常"""
+
+    def __init__(
+        self,
+        resource_type: str,
+        resource_id: Optional[str] = "",
+    ):
+        super().__init__(
+            f"Resource {resource_type}({resource_id}) does not exist."
+        )
+
+
+class ResourceAlreadyExistError(AgentRunError):
+    """资源已存在异常"""
+
+    def __init__(
+        self,
+        resource_type: str,
+        resource_id: Optional[str] = "",
+    ):
+        super().__init__(
+            f"Resource {resource_type}({resource_id}) already exists."
+        )
+
+
+class DeleteResourceError(AgentRunError):
+    """删除资源异常"""
+
+    def __init__(
+        self,
+        message: Optional[str] = None,
+    ):
+        msg = "Failed to delete resource."
+        if message:
+            msg += f" Reason: {message}"
+
+        super().__init__(msg)

agentrun/utils/helper.py

@@ -0,0 +1,108 @@
+"""辅助工具模块 / Helper Utilities Module
+
+此模块提供一些通用的辅助函数。
+This module provides general utility functions.
+"""
+
+from typing import Any, Optional
+
+from typing_extensions import NotRequired, TypedDict, Unpack
+
+
+def mask_password(password: Optional[str]) -> str:
+    """遮蔽密码用于日志记录 / Mask password for logging purposes
+
+    将密码部分字符替换为星号,用于安全地记录日志。
+    Replaces part of the password characters with asterisks for safe logging.
+
+    Args:
+        password: 原始密码,可选 / Original password, optional
+
+    Returns:
+        str: 遮蔽后的密码 / Masked password
+
+    Examples:
+        >>> mask_password("password123")
+        'pa******23'
+        >>> mask_password("abc")
+        'a*c'
+    """
+    if not password:
+        return ""
+    if len(password) <= 2:
+        return "*" * len(password)
+    if len(password) <= 4:
+        return password[0] + "*" * (len(password) - 2) + password[-1]
+    return password[0:2] + "*" * (len(password) - 4) + password[-2:]
+
+
+class MergeOptions(TypedDict):
+    concat_list: NotRequired[bool]
+    no_new_field: NotRequired[bool]
+    ignore_empty_list: NotRequired[bool]
+
+
+def merge(a: Any, b: Any, **args: Unpack[MergeOptions]) -> Any:
+    """通用合并函数 / Generic deep merge helper.
+
+    合并规则概览:
+    - 若 ``b`` 为 ``None``: 返回 ``a``
+    - 若 ``a`` 为 ``None``: 返回 ``b``
+    - ``dict``: 递归按 key 深度合并
+    - ``list``: 连接列表 ``a + b``
+    - ``tuple``: 连接元组 ``a + b``
+    - ``set``/``frozenset``: 取并集
+    - 具有 ``__dict__`` 的同类型对象: 按属性字典递归合并后构造新实例
+    - 其他类型: 直接返回 ``b`` (视为覆盖)
+    """
+
+    # None 合并: 保留非 None 一方
+    if b is None:
+        return a
+    if a is None:
+        return b
+
+    # dict 深度合并
+    if isinstance(a, dict) and isinstance(b, dict):
+        result: dict[Any, Any] = dict(a)
+        for key, value in b.items():
+            if key in result:
+                result[key] = merge(result[key], value, **args)
+            else:
+                if args.get("no_new_field", False):
+                    continue
+                result[key] = value
+        return result
+
+    # list 合并: 连接
+    if isinstance(a, list) and isinstance(b, list):
+        if args.get("concat_list", False):
+            return [*a, *b]
+        if args.get("ignore_empty_list", False):
+            if len(b) == 0:
+                return a
+        return b
+
+    # tuple 合并: 连接
+    if isinstance(a, tuple) and isinstance(b, tuple):
+        return (*a, *b)
+
+    # set / frozenset: 并集
+    if isinstance(a, set) and isinstance(b, set):
+        return a | b
+    if isinstance(a, frozenset) and isinstance(b, frozenset):
+        return a | b
+
+    # 同类型且具备 __dict__ 的对象: 按属性递归合并, 就地更新 a
+    if type(a) is type(b) and hasattr(a, "__dict__") and hasattr(b, "__dict__"):
+        for key, value in b.__dict__.items():
+            if key in a.__dict__:
+                setattr(a, key, merge(getattr(a, key), value, **args))
+            else:
+                if args.get("no_new_field", False):
+                    continue
+                setattr(a, key, value)
+        return a
+
+    # 其他情况: 视为覆盖, 返回 b
+    return b

agentrun/utils/log.py

@@ -0,0 +1,77 @@
+"""日志模块 / Logging Module
+
+此模块配置 AgentRun SDK 的日志系统。
+This module configures the logging system for AgentRun SDK.
+"""
+
+import logging
+import os
+
+from dotenv import load_dotenv
+
+load_dotenv()
+
+
+class CustomFormatter(logging.Formatter):
+    """自定义日志格式化器 / Custom Log Formatter
+
+    提供带颜色的日志输出格式。
+    Provides colorful log output format.
+    """
+
+    FORMATS = {
+        "DEBUG": (
+            "\n\x1b[1;36m%(levelname)s\x1b[0m \x1b[36m[%(name)s] %(asctime)s"
+            " \x1b[2;3m%(pathname)s:%(lineno)s\x1b[0m\n\x1b[2m%(message)s\x1b[0m\n"
+        ),
+        "INFO": (
+            "\n\x1b[1;34m%(levelname)s\x1b[0m \x1b[34m[%(name)s] %(asctime)s"
+            " \x1b[2;3m%(pathname)s:%(lineno)s\x1b[0m\n%(message)s\n"
+        ),
+        "WARNING": (
+            "\n\x1b[1;33m%(levelname)s\x1b[0m \x1b[33m[%(name)s] %(asctime)s"
+            " \x1b[2;3m%(pathname)s:%(lineno)s\x1b[0m\n%(message)s\n"
+        ),
+        "ERROR": (
+            "\n\x1b[1;31m%(levelname)s\x1b[0m \x1b[31m[%(name)s] %(asctime)s"
+            " \x1b[2;3m%(pathname)s:%(lineno)s\x1b[0m\n%(message)s\n"
+        ),
+        "CRITICAL": (
+            "\n\x1b[1;31m%(levelname)s\x1b[0m \x1b[31m[%(name)s] %(asctime)s"
+            " \x1b[2;3m%(pathname)s:%(lineno)s\x1b[0m\n%(message)s\n"
+        ),
+        "DEFAULT": (
+            "\n%(levelname)s [%(name)s] %(asctime)s"
+            " \x1b[2;3m%(pathname)s:%(lineno)s\x1b[0m\n%(message)s\n"
+        ),
+    }
+
+    def format(self, record):
+        formatter = logging.Formatter(
+            self.FORMATS.get(record.levelname, self.FORMATS["DEFAULT"])
+        )
+        return formatter.format(record)
+
+
+logger = logging.getLogger("agentrun-logger")
+
+logger.setLevel(level=logging.INFO)
+handler = logging.StreamHandler()
+handler.setFormatter(CustomFormatter())
+logger.addHandler(handler)
+
+
+if os.getenv("AGENTRUN_SDK_DEBUG") not in [
+    None,
+    "",
+    "False",
+    "FALSE",
+    "false",
+    "0",
+]:
+    logger.setLevel(logging.DEBUG)
+    logger.warning(
+        "启用 AgentRun SDK 调试日志， 移除 AGENTRUN_SDK_DEBUG 环境变量以关闭"
+    )
+else:
+    logger.setLevel(logging.INFO)

agentrun/utils/model.py

@@ -0,0 +1,168 @@
+"""数据模型基类模块 / Data Model Base Module
+
+此模块定义所有数据模型的基类和通用配置。
+This module defines base classes and common configurations for all data models.
+"""
+
+from enum import Enum
+from typing import List, Optional, Union
+
+from darabonba.model import DaraModel
+from pydantic import AliasGenerator
+from pydantic import BaseModel as PydanticModel
+from pydantic import ConfigDict, Field, ValidationError
+from Tea.model import TeaModel
+from typing_extensions import Self
+
+from agentrun.utils.log import logger
+
+
+def to_camel_case(field_name: str) -> str:
+    """将下划线命名转换为驼峰命名 / Convert snake_case to camelCase
+
+    Args:
+        field_name: 下划线命名的字段名 / Field name in snake_case
+
+    Returns:
+        str: 驼峰命名的字段名 / Field name in camelCase
+
+    Examples:
+        >>> to_camel_case("hello_world")
+        'helloWorld'
+        >>> to_camel_case("access_key_id")
+        'accessKeyId'
+    """
+    if "_" not in field_name:
+        return field_name
+    parts = field_name.split("_")
+    return parts[0] + "".join(word.capitalize() for word in parts[1:])
+
+
+class BaseModel(PydanticModel):
+    model_config = ConfigDict(
+        use_attribute_docstrings=True,
+        validate_by_name=True,
+        validate_by_alias=False,
+        serialize_by_alias=True,
+        use_enum_values=True,
+        extra="allow",
+        arbitrary_types_allowed=True,
+        alias_generator=AliasGenerator(
+            validation_alias=to_camel_case,
+            serialization_alias=to_camel_case,
+        ),
+    )
+
+    @classmethod
+    def from_inner_object(
+        cls, obj: Union[DaraModel, TeaModel], extra: Optional[dict] = None
+    ) -> Self:
+        """从 Darabonba 模型对象创建 Pydantic 模型对象，可选地合并额外的字段"""
+        logger.debug(
+            "before parse object obj=%s, extra=%s", obj.to_map(), extra
+        )
+
+        d = {**extra, **obj.to_map()} if extra else obj.to_map()  # type: ignore
+        try:
+            result = cls.model_validate(d, by_alias=True)
+        except ValidationError as e:
+            logger.warning("validate type failed, %s", e)
+            result = cls.model_construct(None, **d)  # type: ignore
+        return result
+
+    def update_self(self, other: Optional["BaseModel"]) -> Self:
+        """更新自身属性 / Update self attributes
+
+        用另一个模型对象的属性更新当前对象。
+        Update current object with attributes from another model object.
+
+        Args:
+            other: 另一个模型对象,可选 / Another model object, optional
+
+        Returns:
+            Self: 更新后的自身 / Updated self
+        """
+        if other is not None:
+            self.__dict__.update(other.__dict__)
+
+        return self
+
+
+class NetworkMode(str, Enum):
+    """网络访问模式 / Network Access Mode
+
+    定义 Agent Runtime 的网络访问模式。
+    Defines network access modes for Agent Runtime.
+    """
+
+    PUBLIC = "PUBLIC"
+    """公网模式 / Public network mode"""
+    PRIVATE = "PRIVATE"
+    """私网模式 / Private network mode"""
+    PUBLIC_AND_PRIVATE = "PUBLIC_AND_PRIVATE"
+    """公私网混合模式 / Public and private network mode"""
+
+
+class NetworkConfig(BaseModel):
+    """网络配置 / Network Configuration
+
+    定义 Agent Runtime 的网络配置。
+    Defines network configuration for Agent Runtime.
+    """
+
+    network_mode: NetworkMode = Field(
+        alias="networkMode", default=NetworkMode.PUBLIC
+    )
+    """网络访问模式 / Network access mode"""
+    security_group_id: Optional[str] = Field(
+        alias="securityGroupId", default=None
+    )
+    """安全组 ID"""
+    vpc_id: Optional[str] = Field(alias="vpcId", default=None)
+    """私有网络 ID"""
+    vswitch_ids: Optional[List[str]] = Field(alias="vswitchIds", default=None)
+    """私有网络交换机 ID 列表"""
+
+
+class PageableInput(BaseModel):
+    page_number: Optional[int] = None
+    """页码"""
+    page_size: Optional[int] = None
+    """页大小"""
+
+
+class Status(str, Enum):
+    """Agent Runtime 状态"""
+
+    CREATING = "CREATING"
+    CREATE_FAILED = "CREATE_FAILED"
+    UPDATING = "UPDATING"
+    UPDATE_FAILED = "UPDATE_FAILED"
+    READY = "READY"
+    DELETING = "DELETING"
+    DELETE_FAILED = "DELETE_FAILED"
+
+    @staticmethod
+    def is_final_status(status: Optional["Status"] = None) -> bool:
+        """判断状态是否为最终状态"""
+        return status in {
+            None,
+            Status.READY,
+            Status.CREATE_FAILED,
+            Status.UPDATE_FAILED,
+            Status.DELETE_FAILED,
+        }
+
+    def is_final(self) -> bool:
+        """判断状态是否为最终状态"""
+        return Status.is_final_status(self)
+
+
+__all__ = [
+    "BaseModel",
+    "Field",
+    "NetworkMode",
+    "NetworkConfig",
+    "PageableInput",
+    "Status",
+]