arkruntime 0.1.0__py3-none-any.whl

arkruntime/_compat.py

@@ -0,0 +1,265 @@
+# Copyright (c) 2025 ByteDance Ltd. and/or its affiliates.
+# SPDX-License-Identifier: Apache-2.0
+# License text: https://github.com/volcengine/ark-runtime-python/blob/main/LICENSE
+
+from __future__ import annotations
+
+from datetime import date, datetime
+from typing import TYPE_CHECKING, Any, Callable, Generic, TypeVar, Union, cast, overload
+
+import pydantic
+from pydantic.fields import FieldInfo
+from typing_extensions import Literal, Self
+
+from ._types import IncEx
+
+_T = TypeVar("_T")
+_ModelT = TypeVar("_ModelT", bound=pydantic.BaseModel)
+StrBytesIntFloat = Union[str, bytes, int, float]
+
+# --------------- Pydantic v2 compatibility ---------------
+
+# Pyright incorrectly reports some of our functions as overriding a method when they don't
+# pyright: reportIncompatibleMethodOverride=false
+
+PYDANTIC_V2 = pydantic.VERSION.startswith("2.")
+
+# v1 re-exports
+if TYPE_CHECKING:
+
+    def parse_date(value: date | StrBytesIntFloat) -> date:  # noqa: ARG001
+        ...
+
+    def parse_datetime(value: Union[datetime, StrBytesIntFloat]) -> datetime:  # noqa: ARG001
+        ...
+
+    def get_args(t: type[Any]) -> tuple[Any, ...]:  # noqa: ARG001
+        ...
+
+    def is_union(tp: type[Any] | None) -> bool:  # noqa: ARG001
+        ...
+
+    def get_origin(t: type[Any]) -> type[Any] | None:  # noqa: ARG001
+        ...
+
+    def is_literal_type(type_: type[Any]) -> bool:  # noqa: ARG001
+        ...
+
+    def is_typeddict(type_: type[Any]) -> bool:  # noqa: ARG001
+        ...
+
+else:
+    if PYDANTIC_V2:
+        from pydantic.v1.datetime_parse import (
+            parse_date as parse_date,
+        )
+        from pydantic.v1.datetime_parse import (
+            parse_datetime as parse_datetime,
+        )
+        from pydantic.v1.typing import (
+            get_args as get_args,
+        )
+        from pydantic.v1.typing import (
+            get_origin as get_origin,
+        )
+        from pydantic.v1.typing import (
+            is_literal_type as is_literal_type,
+        )
+        from pydantic.v1.typing import (
+            is_typeddict as is_typeddict,
+        )
+        from pydantic.v1.typing import (
+            is_union as is_union,
+        )
+    else:
+        from pydantic.datetime_parse import (
+            parse_date as parse_date,
+        )
+        from pydantic.datetime_parse import (
+            parse_datetime as parse_datetime,
+        )
+        from pydantic.typing import (
+            get_args as get_args,
+        )
+        from pydantic.typing import (
+            get_origin as get_origin,
+        )
+        from pydantic.typing import (
+            is_literal_type as is_literal_type,
+        )
+        from pydantic.typing import (
+            is_typeddict as is_typeddict,
+        )
+        from pydantic.typing import (
+            is_union as is_union,
+        )
+
+# refactored config
+if TYPE_CHECKING:
+    from pydantic import ConfigDict as ConfigDict
+else:
+    if PYDANTIC_V2:
+        from pydantic import ConfigDict
+    else:
+        # TODO: provide an error message here?
+        ConfigDict = None
+
+
+# renamed methods / properties
+def parse_obj(model: type[_ModelT], value: object) -> _ModelT:
+    if PYDANTIC_V2:
+        return model.model_validate(value)
+    else:
+        return cast(_ModelT, model.parse_obj(value))  # pyright: ignore[reportDeprecated, reportUnnecessaryCast]
+
+
+def field_is_required(field: FieldInfo) -> bool:
+    if PYDANTIC_V2:
+        return field.is_required()
+    return field.required  # type: ignore
+
+
+def field_get_default(field: FieldInfo) -> Any:
+    value = field.get_default()
+    if PYDANTIC_V2:
+        from pydantic_core import PydanticUndefined
+
+        if value == PydanticUndefined:
+            return None
+        return value
+    return value
+
+
+def field_outer_type(field: FieldInfo) -> Any:
+    if PYDANTIC_V2:
+        return field.annotation
+    return field.outer_type_  # type: ignore
+
+
+def get_model_config(model: type[pydantic.BaseModel]) -> Any:
+    if PYDANTIC_V2:
+        return model.model_config
+    return model.__config__  # type: ignore
+
+
+def get_model_fields(model: type[pydantic.BaseModel]) -> dict[str, FieldInfo]:
+    if PYDANTIC_V2:
+        return model.model_fields
+    return model.__fields__  # type: ignore
+
+
+def model_copy(model: _ModelT) -> _ModelT:
+    if PYDANTIC_V2:
+        return model.model_copy()
+    return model.copy()  # type: ignore
+
+
+def model_json(model: pydantic.BaseModel, *, indent: int | None = None) -> str:
+    if PYDANTIC_V2:
+        return model.model_dump_json(indent=indent)
+    return model.json(indent=indent)  # type: ignore
+
+
+def model_dump(
+    model: pydantic.BaseModel,
+    *,
+    exclude: IncEx | None = None,
+    exclude_unset: bool = False,
+    exclude_defaults: bool = False,
+    warnings: bool = True,
+    mode: Literal["json", "python"] = "python",
+) -> dict[str, Any]:
+    if PYDANTIC_V2 or hasattr(model, "model_dump"):
+        return model.model_dump(
+            mode=mode,
+            exclude=exclude,
+            exclude_unset=exclude_unset,
+            exclude_defaults=exclude_defaults,
+            # warnings are not supported in Pydantic v1
+            warnings=warnings if PYDANTIC_V2 else True,
+        )
+    return cast(
+        "dict[str, Any]",
+        model.dict(  # pyright: ignore[reportDeprecated, reportUnnecessaryCast]
+            exclude=exclude,
+            exclude_unset=exclude_unset,
+            exclude_defaults=exclude_defaults,
+        ),
+    )
+
+
+def model_parse(model: type[_ModelT], data: Any) -> _ModelT:
+    if PYDANTIC_V2:
+        return model.model_validate(data)
+    return model.parse_obj(data)  # pyright: ignore[reportDeprecated]
+
+
+def model_parse_json(model: type[_ModelT], data: str | bytes) -> _ModelT:
+    if PYDANTIC_V2:
+        return model.model_validate_json(data)
+    return model.parse_raw(data)  # pyright: ignore[reportDeprecated]
+
+
+def model_json_schema(model: type[_ModelT]) -> dict[str, Any]:
+    if PYDANTIC_V2:
+        return model.model_json_schema()
+    return model.schema()  # pyrigh
+
+
+# generic models
+if TYPE_CHECKING:
+
+    class GenericModel(pydantic.BaseModel): ...
+
+else:
+    if PYDANTIC_V2:
+        # there no longer needs to be a distinction in v2 but
+        # we still have to create our own subclass to avoid
+        # inconsistent MRO ordering errors
+        class GenericModel(pydantic.BaseModel): ...
+
+    else:
+        import pydantic.generics
+
+        class GenericModel(pydantic.generics.GenericModel, pydantic.BaseModel): ...
+
+
+# cached properties
+if TYPE_CHECKING:
+    cached_property = property
+
+    # we define a separate type (copied from typeshed)
+    # that represents that `cached_property` is `set`able
+    # at runtime, which differs from `@property`.
+    #
+    # this is a separate type as editors likely special case
+    # `@property` and we don't want to cause issues just to have
+    # more helpful internal types.
+
+    class typed_cached_property(Generic[_T]):
+        func: Callable[[Any], _T]
+        attrname: str | None
+
+        def __init__(self, func: Callable[[Any], _T]) -> None: ...
+
+        @overload
+        def __get__(self, instance: None, owner: type[Any] | None = None) -> Self: ...
+
+        @overload
+        def __get__(self, instance: object, owner: type[Any] | None = None) -> _T: ...
+
+        def __get__(self, instance: object, owner: type[Any] | None = None) -> _T | Self:
+            raise NotImplementedError()
+
+        def __set_name__(self, owner: type[Any], name: str) -> None: ...
+
+        # __set__ is not defined at runtime, but @cached_property is designed to be settable
+        def __set__(self, instance: object, value: _T) -> None: ...
+
+else:
+    try:
+        from functools import cached_property as cached_property
+    except ImportError:
+        from cached_property import cached_property as cached_property
+
+    typed_cached_property = cached_property

arkruntime/_constants.py

@@ -0,0 +1,55 @@
+# Copyright (c) 2025 ByteDance Ltd. and/or its affiliates.
+# SPDX-License-Identifier: Apache-2.0
+# License text: https://github.com/volcengine/ark-runtime-python/blob/main/LICENSE
+
+import httpx
+
+VERSION = "1.0.0"
+BASE_URL = "https://ark.cn-beijing.volces.com/api/v3"
+
+
+# Cloud presets. ``ARK_API_KEY`` is shared across clouds; AK/SK env-var names
+# differ. Use ``Ark.volc(...)`` / ``Ark.byteplus(...)`` to pick a preset.
+class Cloud(str):
+    VOLC = "volc"
+    BYTEPLUS = "byteplus"
+
+
+_CLOUD_PRESETS = {
+    Cloud.VOLC: {
+        "base_url": "https://ark.cn-beijing.volces.com/api/v3",
+        "region": "cn-beijing",
+        "ak_env": "VOLC_ACCESSKEY",
+        "sk_env": "VOLC_SECRETKEY",
+    },
+    Cloud.BYTEPLUS: {
+        "base_url": "https://ark.ap-southeast.bytepluses.com/api/v3",
+        "region": "ap-southeast-1",
+        "ak_env": "BYTEPLUS_ACCESSKEY",
+        "sk_env": "BYTEPLUS_SECRETKEY",
+    },
+}
+
+RAW_RESPONSE_HEADER = "X-Stainless-Raw-Response"
+CLIENT_REQUEST_HEADER = "X-Client-Request-Id"
+SERVER_REQUEST_HEADER = "X-Request-Id"
+ARK_E2E_ENCRYPTION_HEADER = "x-is-encrypted"
+ARK_APIKEY_PROJECT_NAME = "X-Project-Name"
+
+DEFAULT_TIMEOUT_SECONDS = 600.0
+DEFAULT_CONNECT_TIMEOUT_SECONDS = 60.0
+# default timeout is 1 minutes
+DEFAULT_TIMEOUT = httpx.Timeout(timeout=DEFAULT_TIMEOUT_SECONDS, connect=DEFAULT_CONNECT_TIMEOUT_SECONDS)
+
+DEFAULT_MAX_RETRIES = 2
+DEFAULT_CONNECTION_LIMITS = httpx.Limits(max_connections=1000, max_keepalive_connections=100)
+
+INITIAL_RETRY_DELAY = 0.5
+MAX_RETRY_DELAY = 8.0
+
+_DEFAULT_MANDATORY_REFRESH_TIMEOUT = 10 * 60  # 10 min
+_DEFAULT_ADVISORY_REFRESH_TIMEOUT = 30 * 60  # 30 min
+_DEFAULT_STS_TIMEOUT = 7 * 24 * 60 * 60  # 7 days
+
+_DEFAULT_RESOURCE_TYPE = "endpoint"
+_PRESETENDPOINT_RESOURCE_TYPE = "presetendpoint"

arkruntime/_exceptions.py

@@ -0,0 +1,188 @@
+# Copyright (c) 2025 ByteDance Ltd. and/or its affiliates.
+# SPDX-License-Identifier: Apache-2.0
+# License text: https://github.com/volcengine/ark-runtime-python/blob/main/LICENSE
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Optional
+
+import httpx
+from typing_extensions import Literal
+
+if TYPE_CHECKING:
+    from .types.chat import ChatCompletion
+
+__all__ = [
+    "ArkBadRequestError",
+    "ArkAuthenticationError",
+    "ArkPermissionDeniedError",
+    "ArkNotFoundError",
+    "ArkConflictError",
+    "ArkUnprocessableEntityError",
+    "ArkRateLimitError",
+    "ArkInternalServerError",
+]
+
+
+class ArkError(Exception):
+    pass
+
+
+class ArkAPIError(ArkError):
+    message: str
+    request: Optional[httpx.Request] = None
+    body: Optional[object] = None
+    request_id: Optional[str] = None
+    """The API response body.
+
+    If the API responded with a valid JSON structure then this property will be the
+    decoded result.
+
+    If it isn't a valid JSON structure then this will be the raw response.
+
+    If there was no response associated with this error then it will be `None`.
+    """
+
+    code: Optional[str] = None
+    param: Optional[str] = None
+    type: Optional[str]
+
+    def __init__(
+        self,
+        message: str,
+        request: Optional[httpx.Request] = None,
+        *,
+        body: Optional[object] = None,
+        request_id: Optional[str] = None,
+    ) -> None:
+        super().__init__(message)
+        self.request = request
+        self.message = message
+        self.body = body
+        self.request_id = request_id
+
+        if isinstance(body, dict):
+            self.code = body.get("code")
+            self.param = body.get("param")
+            self.type = body.get("type")
+        else:
+            self.code = None
+            self.param = None
+            self.type = None
+
+    def __str__(self):
+        return f"{self.message}, request_id: {self.request_id}"
+
+
+class ArkAPIResponseValidationError(ArkAPIError):
+    response: httpx.Response
+    status_code: int
+
+    def __init__(
+        self,
+        response: httpx.Response,
+        body: object | None,
+        *,
+        message: str | None = None,
+        request_id: str,
+    ) -> None:
+        super().__init__(
+            message or "Data returned by API invalid for expected schema.",
+            response.request,
+            body=body,
+        )
+        self.response = response
+        self.status_code = response.status_code
+        self.request_id = request_id
+
+
+class ArkAPIStatusError(ArkAPIError):
+    """Raised when an API response has a status code of 4xx or 5xx."""
+
+    response: httpx.Response
+    status_code: int
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        response: httpx.Response,
+        body: object | None,
+        request_id: str,
+    ) -> None:
+        super().__init__(message, response.request, body=body, request_id=request_id)
+        self.response = response
+        self.status_code = response.status_code
+        self.request_id = request_id
+
+
+class ArkAPIConnectionError(ArkAPIError):
+    def __init__(
+        self,
+        *,
+        message: str = "Connection error.",
+        request: httpx.Request,
+        request_id: str,
+    ) -> None:
+        super().__init__(message, request, body=None, request_id=request_id)
+
+
+class ArkAPITimeoutError(ArkAPIConnectionError):
+    def __init__(self, request: httpx.Request, request_id: str) -> None:
+        super().__init__(message="Request timed out.", request=request, request_id=request_id)
+
+
+class ArkBadRequestError(ArkAPIStatusError):
+    status_code: Literal[400] = 400  # pyright: ignore[reportIncompatibleVariableOverride]
+
+
+class ArkAuthenticationError(ArkAPIStatusError):
+    status_code: Literal[401] = 401  # pyright: ignore[reportIncompatibleVariableOverride]
+
+
+class ArkPermissionDeniedError(ArkAPIStatusError):
+    status_code: Literal[403] = 403  # pyright: ignore[reportIncompatibleVariableOverride]
+
+
+class ArkNotFoundError(ArkAPIStatusError):
+    status_code: Literal[404] = 404  # pyright: ignore[reportIncompatibleVariableOverride]
+
+
+class ArkConflictError(ArkAPIStatusError):
+    status_code: Literal[409] = 409  # pyright: ignore[reportIncompatibleVariableOverride]
+
+
+class ArkUnprocessableEntityError(ArkAPIStatusError):
+    status_code: Literal[422] = 422  # pyright: ignore[reportIncompatibleVariableOverride]
+
+
+class ArkRateLimitError(ArkAPIStatusError):
+    status_code: Literal[429] = 429  # pyright: ignore[reportIncompatibleVariableOverride]
+
+
+class ArkInternalServerError(ArkAPIStatusError):
+    pass
+
+
+class ArkLengthFinishReasonError(ArkError):
+    completion: ChatCompletion
+    """The completion that caused this error.
+
+    Note: this will *not* be a complete `ChatCompletion` object when streaming as `usage`
+          will not be included.
+    """
+
+    def __init__(self, *, completion: ChatCompletion) -> None:
+        msg = "Could not parse response content as the length limit was reached"
+        if completion.usage:
+            msg += f" - {completion.usage}"
+
+        super().__init__(msg)
+        self.completion = completion
+
+
+class ArkContentFilterFinishReasonError(ArkError):
+    def __init__(self) -> None:
+        super().__init__(
+            "Could not parse response content as the request was rejected by the content filter",
+        )

arkruntime/_files.py

@@ -0,0 +1,122 @@
+# Copyright (c) 2025 ByteDance Ltd. and/or its affiliates.
+# SPDX-License-Identifier: Apache-2.0
+# License text: https://github.com/volcengine/ark-runtime-python/blob/main/LICENSE
+
+from __future__ import annotations
+
+import io
+import os
+import pathlib
+from typing import overload
+
+import anyio
+from typing_extensions import TypeGuard
+
+from ._types import (
+    FileContent,
+    FileTypes,
+    HttpxFileContent,
+    HttpxFileTypes,
+    HttpxRequestFiles,
+    RequestFiles,
+)
+from ._utils import is_mapping_t, is_sequence_t, is_tuple_t
+
+
+def is_file_content(obj: object) -> TypeGuard[FileContent]:
+    return (
+        isinstance(obj, bytes) or isinstance(obj, tuple) or isinstance(obj, io.IOBase) or isinstance(obj, os.PathLike)
+    )
+
+
+def assert_is_file_content(obj: object, *, key: str | None = None) -> None:
+    if not is_file_content(obj):
+        prefix = f"Expected entry at `{key}`" if key is not None else f"Expected file input `{obj!r}`"
+        raise RuntimeError(
+            f"{prefix} to be bytes, an io.IOBase instance, PathLike or a tuple but received {type(obj)} instead. "
+        ) from None
+
+
+@overload
+def to_httpx_files(files: None) -> None: ...
+
+
+@overload
+def to_httpx_files(files: RequestFiles) -> HttpxRequestFiles: ...
+
+
+def to_httpx_files(files: RequestFiles | None) -> HttpxRequestFiles | None:
+    if files is None:
+        return None
+
+    if is_mapping_t(files):
+        files = {key: _transform_file(file) for key, file in files.items()}
+    elif is_sequence_t(files):
+        files = [(key, _transform_file(file)) for key, file in files]
+    else:
+        raise TypeError(f"Unexpected file type input {type(files)}, expected mapping or sequence")
+
+    return files
+
+
+def _transform_file(file: FileTypes) -> HttpxFileTypes:
+    if is_file_content(file):
+        if isinstance(file, os.PathLike):
+            path = pathlib.Path(file)
+            return (path.name, path.read_bytes())
+
+        return file
+
+    if is_tuple_t(file):
+        return (file[0], _read_file_content(file[1]), *file[2:])
+
+    raise TypeError("Expected file types input to be a FileContent type or to be a tuple")
+
+
+def _read_file_content(file: FileContent) -> HttpxFileContent:
+    if isinstance(file, os.PathLike):
+        return pathlib.Path(file).read_bytes()
+    return file
+
+
+@overload
+async def async_to_httpx_files(files: None) -> None: ...
+
+
+@overload
+async def async_to_httpx_files(files: RequestFiles) -> HttpxRequestFiles: ...
+
+
+async def async_to_httpx_files(files: RequestFiles | None) -> HttpxRequestFiles | None:
+    if files is None:
+        return None
+
+    if is_mapping_t(files):
+        files = {key: await _async_transform_file(file) for key, file in files.items()}
+    elif is_sequence_t(files):
+        files = [(key, await _async_transform_file(file)) for key, file in files]
+    else:
+        raise TypeError("Unexpected file type input {type(files)}, expected mapping or sequence")
+
+    return files
+
+
+async def _async_transform_file(file: FileTypes) -> HttpxFileTypes:
+    if is_file_content(file):
+        if isinstance(file, os.PathLike):
+            path = anyio.Path(file)
+            return (path.name, await path.read_bytes())
+
+        return file
+
+    if is_tuple_t(file):
+        return (file[0], await _async_read_file_content(file[1]), *file[2:])
+
+    raise TypeError("Expected file types input to be a FileContent type or to be a tuple")
+
+
+async def _async_read_file_content(file: FileContent) -> HttpxFileContent:
+    if isinstance(file, os.PathLike):
+        return await anyio.Path(file).read_bytes()
+
+    return file