arkruntime 0.4.0__tar.gz → 0.6.0__tar.gz

arkruntime-0.6.0/MANIFEST.in

@@ -0,0 +1 @@
+prune tests

{arkruntime-0.4.0 → arkruntime-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arkruntime
-Version: 0.4.0
+Version: 0.6.0
 Summary: Ark runtime SDK for Python
 Author: Volcengine
 License: Apache-2.0
@@ -8,6 +8,7 @@ Project-URL: Homepage, https://github.com/volcengine/ark-runtime-python
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
+License-File: THIRD_PARTY_NOTICES.md
 Requires-Dist: httpx>=0.23.0
 Requires-Dist: pydantic>=2.0
 Requires-Dist: anyio<5,>=3.5.0
@@ -19,7 +20,7 @@ Dynamic: license-file
 
 # Ark Runtime Python SDK
 
-The official Python library for the Volcengine Ark runtime API. It provides convenient access to the Ark REST API from any Python 3.8+ application, with both synchronous and asynchronous clients.
+The official Python library for accessing ModelArk on Volcengine and BytePlus. It provides synchronous and asynchronous clients, typed models, streaming, authentication, retries, and timeout configuration.
 
 ## Installation
 
@@ -27,39 +28,64 @@ The official Python library for the Volcengine Ark runtime API. It provides conv
 pip install arkruntime
 ```
 
-## Usage
+## Choose Volcengine or BytePlus
+
+Set `ARK_API_KEY`, then choose the client factory for the service you use. The factory configures the correct base URL and region; request construction and all subsequent SDK calls are the same.
+
+### Volcengine (China)
+
+```python
+from arkruntime import Ark
+
+client = Ark.volc()
+# or explicitly: Ark.volc(api_key="your-api-key")
+```
 
-Create a client by setting the `ARK_API_KEY` environment variable:
+### BytePlus (BP)
 
 ```python
 from arkruntime import Ark
 
-client = Ark()
-# or explicitly: Ark(api_key="your-api-key")
+client = Ark.byteplus()
+# or explicitly: Ark.byteplus(api_key="your-api-key")
 ```
 
+Use a model ID available in the corresponding Volcengine or BytePlus account. Model IDs can differ between the two services; the examples use `doubao-seed-2-1-pro-260628` for Volcengine and `seed-2-0-lite-260428` for BytePlus. Override either default with `ARK_MODEL`.
+
+The async client provides the same factories: `AsyncArk.volc()` and `AsyncArk.byteplus()`.
+
+## Quick start
+
 ### Responses API
 
 ```python
 import os
 from arkruntime import Ark
 
-client = Ark()
+client = Ark.volc()
 
 response = client.responses.create(
     model=os.environ.get("ARK_MODEL", "doubao-seed-2-1-pro-260628"),
     input="Explain how large language models work in three sentences.",
 )
-print(response.output_text)
+for item in response.output or []:
+    if item.type == "message":
+        for content in item.content:
+            if content.type == "output_text":
+                print(content.text)
 ```
 
+For BytePlus, change only the client line to `client = Ark.byteplus()` and set `ARK_MODEL` to a BytePlus model ID.
+
+## Usage
+
 ### Chat Completions
 
 ```python
 import os
 from arkruntime import Ark
 
-client = Ark()
+client = Ark.volc()
 
 completion = client.chat.completions.create(
     model=os.environ.get("ARK_MODEL", "doubao-seed-2-1-pro-260628"),
@@ -81,7 +107,7 @@ Both the Responses and Chat Completions APIs support streaming via `stream=True`
 import os
 from arkruntime import Ark
 
-client = Ark()
+client = Ark.volc()
 
 stream = client.responses.create(
     model=os.environ.get("ARK_MODEL", "doubao-seed-2-1-pro-260628"),
@@ -98,7 +124,7 @@ for event in stream:
 import os
 from arkruntime import Ark
 
-client = Ark()
+client = Ark.volc()
 
 stream = client.chat.completions.create(
     model=os.environ.get("ARK_MODEL", "doubao-seed-2-1-pro-260628"),
@@ -119,14 +145,18 @@ import asyncio
 import os
 from arkruntime import AsyncArk
 
-client = AsyncArk()
+client = AsyncArk.volc()
 
 async def main():
     response = await client.responses.create(
         model=os.environ.get("ARK_MODEL", "doubao-seed-2-1-pro-260628"),
         input="Explain quantum computing briefly.",
     )
-    print(response.output_text)
+    for item in response.output or []:
+        if item.type == "message":
+            for content in item.content:
+                if content.type == "output_text":
+                    print(content.text)
 
 asyncio.run(main())
 ```
@@ -139,7 +169,7 @@ Pass images alongside text using multimodal content blocks.
 import os
 from arkruntime import Ark
 
-client = Ark()
+client = Ark.volc()
 
 completion = client.chat.completions.create(
     model=os.environ.get("ARK_MODEL", "doubao-seed-2-1-pro-260628"),
@@ -163,7 +193,7 @@ import json
 import os
 from arkruntime import Ark
 
-client = Ark()
+client = Ark.volc()
 
 tools = [
     {
@@ -198,7 +228,7 @@ print(f"Arguments: {tool_call.function.arguments}")
 ```python
 from arkruntime import Ark
 
-client = Ark()
+client = Ark.volc()
 
 # Upload a file
 file = client.files.create(file=open("data.jsonl", "rb"), purpose="batch")
@@ -220,7 +250,7 @@ The SDK raises typed exceptions for API errors.
 from arkruntime import Ark
 from arkruntime._exceptions import ArkAPIError, ArkRateLimitError, ArkAuthenticationError
 
-client = Ark()
+client = Ark.volc()
 
 try:
     client.chat.completions.create(
@@ -262,7 +292,7 @@ The client automatically retries failed requests (default: 2 retries) with backo
 from arkruntime import Ark
 
 # Customize retries and timeout
-client = Ark(
+client = Ark.volc(
     max_retries=5,
     timeout=120.0,  # seconds
 )
@@ -285,7 +315,7 @@ client.chat.completions.create(
 ```python
 from arkruntime import Ark
 
-client = Ark(timeout=24 * 3600)
+client = Ark.volc(timeout=24 * 3600)
 
 result = client.batch.chat.completions.create(
     model="doubao-seed-2-1-pro-260628",
@@ -294,50 +324,18 @@ result = client.batch.chat.completions.create(
 print(result)
 ```
 
-## API coverage
-
-| API | Client path |
-|---|---|
-| Responses | `client.responses.create()` |
-| Chat Completions | `client.chat.completions.create()` |
-| Embeddings | `client.embeddings.create()` |
-| Multimodal Embeddings | `client.multimodal_embeddings.create()` |
-| Content Generation | `client.content_generation.tasks.create()` |
-| Images | `client.images.generate()` |
-| Files | `client.files.create()` / `.list()` / `.delete()` |
-| Tokenization | `client.tokenization.create()` |
-| Batch | `client.batch.chat.completions.create()` etc. |
-
 ## Examples
 
-See the [examples/](./examples) directory for runnable scripts:
-
-- `responses/` -- Responses API: multi-turn chat, function calling, structured output, video streaming
-- `chat/` -- Chat Completions: basic, function calling, reasoning, structured output, vision
-- `batch/` -- Batch inference: chat completions, embeddings, multimodal embeddings (sync + async)
-- `files/` -- Files API: upload, wait for processing, list, delete
-- `embeddings.py` -- Text embeddings
-- `multimodal_embeddings.py` -- Multimodal embeddings with image input
-- `content_generation_tasks.py` -- Video generation task lifecycle
-- `image_generations.py` -- Image generation
-- `tokenization.py` -- Tokenization API
+For detailed usage guidance and legacy migration, see
+[`docs/README.md`](docs/README.md) and
+[`docs/migration.md`](docs/migration.md).
 
-## Development
-
-This repo uses [uv](https://docs.astral.sh/uv/) for dependency management.
-
-```bash
-uv sync                       # create venv + install runtime + dev deps
-uv run pytest                 # run tests
-uv run ruff check src/        # lint
-uv run ruff format src/       # format
-```
+See the [examples/](./examples) directory for runnable scripts:
 
-A pre-commit hook runs the same linting as CI:
+- `volc/` -- Volcengine China examples for Chat, Responses, images, video generation, embeddings, files, tokenization, batch APIs, and resource APIs
+- `byteplus/` -- supported BytePlus counterparts using the BytePlus client and regional model IDs
 
-```bash
-uv run pre-commit install     # one-time setup
-```
+MCP examples are provided for both clouds and explicitly send `ark-beta-mcp: true`. Other built-in-tool examples are CN-only and show their required beta headers.
 
 ## Requirements
 
@@ -345,3 +343,9 @@ uv run pre-commit install     # one-time setup
 - httpx >= 0.23.0
 - pydantic >= 2.0
 - typing-extensions >= 4.7
+
+## License
+
+This project is licensed under the Apache License 2.0. See [LICENSE](./LICENSE).
+For third-party open-source software notices, see
+[THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md).

{arkruntime-0.4.0 → arkruntime-0.6.0}/README.md

@@ -1,6 +1,6 @@
 # Ark Runtime Python SDK
 
-The official Python library for the Volcengine Ark runtime API. It provides convenient access to the Ark REST API from any Python 3.8+ application, with both synchronous and asynchronous clients.
+The official Python library for accessing ModelArk on Volcengine and BytePlus. It provides synchronous and asynchronous clients, typed models, streaming, authentication, retries, and timeout configuration.
 
 ## Installation
 
@@ -8,39 +8,64 @@ The official Python library for the Volcengine Ark runtime API. It provides conv
 pip install arkruntime
 ```
 
-## Usage
+## Choose Volcengine or BytePlus
+
+Set `ARK_API_KEY`, then choose the client factory for the service you use. The factory configures the correct base URL and region; request construction and all subsequent SDK calls are the same.
+
+### Volcengine (China)
+
+```python
+from arkruntime import Ark
+
+client = Ark.volc()
+# or explicitly: Ark.volc(api_key="your-api-key")
+```
 
-Create a client by setting the `ARK_API_KEY` environment variable:
+### BytePlus (BP)
 
 ```python
 from arkruntime import Ark
 
-client = Ark()
-# or explicitly: Ark(api_key="your-api-key")
+client = Ark.byteplus()
+# or explicitly: Ark.byteplus(api_key="your-api-key")
 ```
 
+Use a model ID available in the corresponding Volcengine or BytePlus account. Model IDs can differ between the two services; the examples use `doubao-seed-2-1-pro-260628` for Volcengine and `seed-2-0-lite-260428` for BytePlus. Override either default with `ARK_MODEL`.
+
+The async client provides the same factories: `AsyncArk.volc()` and `AsyncArk.byteplus()`.
+
+## Quick start
+
 ### Responses API
 
 ```python
 import os
 from arkruntime import Ark
 
-client = Ark()
+client = Ark.volc()
 
 response = client.responses.create(
     model=os.environ.get("ARK_MODEL", "doubao-seed-2-1-pro-260628"),
     input="Explain how large language models work in three sentences.",
 )
-print(response.output_text)
+for item in response.output or []:
+    if item.type == "message":
+        for content in item.content:
+            if content.type == "output_text":
+                print(content.text)
 ```
 
+For BytePlus, change only the client line to `client = Ark.byteplus()` and set `ARK_MODEL` to a BytePlus model ID.
+
+## Usage
+
 ### Chat Completions
 
 ```python
 import os
 from arkruntime import Ark
 
-client = Ark()
+client = Ark.volc()
 
 completion = client.chat.completions.create(
     model=os.environ.get("ARK_MODEL", "doubao-seed-2-1-pro-260628"),
@@ -62,7 +87,7 @@ Both the Responses and Chat Completions APIs support streaming via `stream=True`
 import os
 from arkruntime import Ark
 
-client = Ark()
+client = Ark.volc()
 
 stream = client.responses.create(
     model=os.environ.get("ARK_MODEL", "doubao-seed-2-1-pro-260628"),
@@ -79,7 +104,7 @@ for event in stream:
 import os
 from arkruntime import Ark
 
-client = Ark()
+client = Ark.volc()
 
 stream = client.chat.completions.create(
     model=os.environ.get("ARK_MODEL", "doubao-seed-2-1-pro-260628"),
@@ -100,14 +125,18 @@ import asyncio
 import os
 from arkruntime import AsyncArk
 
-client = AsyncArk()
+client = AsyncArk.volc()
 
 async def main():
     response = await client.responses.create(
         model=os.environ.get("ARK_MODEL", "doubao-seed-2-1-pro-260628"),
         input="Explain quantum computing briefly.",
     )
-    print(response.output_text)
+    for item in response.output or []:
+        if item.type == "message":
+            for content in item.content:
+                if content.type == "output_text":
+                    print(content.text)
 
 asyncio.run(main())
 ```
@@ -120,7 +149,7 @@ Pass images alongside text using multimodal content blocks.
 import os
 from arkruntime import Ark
 
-client = Ark()
+client = Ark.volc()
 
 completion = client.chat.completions.create(
     model=os.environ.get("ARK_MODEL", "doubao-seed-2-1-pro-260628"),
@@ -144,7 +173,7 @@ import json
 import os
 from arkruntime import Ark
 
-client = Ark()
+client = Ark.volc()
 
 tools = [
     {
@@ -179,7 +208,7 @@ print(f"Arguments: {tool_call.function.arguments}")
 ```python
 from arkruntime import Ark
 
-client = Ark()
+client = Ark.volc()
 
 # Upload a file
 file = client.files.create(file=open("data.jsonl", "rb"), purpose="batch")
@@ -201,7 +230,7 @@ The SDK raises typed exceptions for API errors.
 from arkruntime import Ark
 from arkruntime._exceptions import ArkAPIError, ArkRateLimitError, ArkAuthenticationError
 
-client = Ark()
+client = Ark.volc()
 
 try:
     client.chat.completions.create(
@@ -243,7 +272,7 @@ The client automatically retries failed requests (default: 2 retries) with backo
 from arkruntime import Ark
 
 # Customize retries and timeout
-client = Ark(
+client = Ark.volc(
     max_retries=5,
     timeout=120.0,  # seconds
 )
@@ -266,7 +295,7 @@ client.chat.completions.create(
 ```python
 from arkruntime import Ark
 
-client = Ark(timeout=24 * 3600)
+client = Ark.volc(timeout=24 * 3600)
 
 result = client.batch.chat.completions.create(
     model="doubao-seed-2-1-pro-260628",
@@ -275,50 +304,18 @@ result = client.batch.chat.completions.create(
 print(result)
 ```
 
-## API coverage
-
-| API | Client path |
-|---|---|
-| Responses | `client.responses.create()` |
-| Chat Completions | `client.chat.completions.create()` |
-| Embeddings | `client.embeddings.create()` |
-| Multimodal Embeddings | `client.multimodal_embeddings.create()` |
-| Content Generation | `client.content_generation.tasks.create()` |
-| Images | `client.images.generate()` |
-| Files | `client.files.create()` / `.list()` / `.delete()` |
-| Tokenization | `client.tokenization.create()` |
-| Batch | `client.batch.chat.completions.create()` etc. |
-
 ## Examples
 
-See the [examples/](./examples) directory for runnable scripts:
-
-- `responses/` -- Responses API: multi-turn chat, function calling, structured output, video streaming
-- `chat/` -- Chat Completions: basic, function calling, reasoning, structured output, vision
-- `batch/` -- Batch inference: chat completions, embeddings, multimodal embeddings (sync + async)
-- `files/` -- Files API: upload, wait for processing, list, delete
-- `embeddings.py` -- Text embeddings
-- `multimodal_embeddings.py` -- Multimodal embeddings with image input
-- `content_generation_tasks.py` -- Video generation task lifecycle
-- `image_generations.py` -- Image generation
-- `tokenization.py` -- Tokenization API
+For detailed usage guidance and legacy migration, see
+[`docs/README.md`](docs/README.md) and
+[`docs/migration.md`](docs/migration.md).
 
-## Development
-
-This repo uses [uv](https://docs.astral.sh/uv/) for dependency management.
-
-```bash
-uv sync                       # create venv + install runtime + dev deps
-uv run pytest                 # run tests
-uv run ruff check src/        # lint
-uv run ruff format src/       # format
-```
+See the [examples/](./examples) directory for runnable scripts:
 
-A pre-commit hook runs the same linting as CI:
+- `volc/` -- Volcengine China examples for Chat, Responses, images, video generation, embeddings, files, tokenization, batch APIs, and resource APIs
+- `byteplus/` -- supported BytePlus counterparts using the BytePlus client and regional model IDs
 
-```bash
-uv run pre-commit install     # one-time setup
-```
+MCP examples are provided for both clouds and explicitly send `ark-beta-mcp: true`. Other built-in-tool examples are CN-only and show their required beta headers.
 
 ## Requirements
 
@@ -326,3 +323,9 @@ uv run pre-commit install     # one-time setup
 - httpx >= 0.23.0
 - pydantic >= 2.0
 - typing-extensions >= 4.7
+
+## License
+
+This project is licensed under the Apache License 2.0. See [LICENSE](./LICENSE).
+For third-party open-source software notices, see
+[THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md).

arkruntime-0.6.0/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,38 @@
+# Third-Party Notices
+
+This repository contains code that is derived from or structurally adapted
+from third-party open-source projects.
+
+## Anthropic self-hosted worker SDK
+
+Portions of the self-hosted worker lifecycle and local agent tool
+implementations under `src/arkruntime/selfhosted` are structurally adapted
+from Anthropic's self-hosted worker SDK implementations:
+
+- https://github.com/anthropics/anthropic-sdk-python
+- https://github.com/anthropics/anthropic-sdk-go
+
+The upstream projects are licensed under the MIT License. The MIT copyright
+and permission notice is preserved below as required by that license.
+
+```text
+Copyright 2023 Anthropic, PBC.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```

{arkruntime-0.4.0 → arkruntime-0.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "arkruntime"
-version = "0.4.0"
+version = "0.6.0"
 description = "Ark runtime SDK for Python"
 readme = "README.md"
 requires-python = ">=3.8"
@@ -44,6 +44,9 @@ dev = [
     "respx>=0.21",
 ]
 
+[tool.setuptools]
+license-files = ["LICENSE", "THIRD_PARTY_NOTICES.md"]
+
 [tool.setuptools.packages.find]
 where = ["src"]
 include = ["arkruntime*"]

{arkruntime-0.4.0 → arkruntime-0.6.0}/src/arkruntime/_base_client.py

@@ -184,7 +184,7 @@ class BaseClient(Generic[_HttpxClientT]):
 
     @property
     def user_agent(self) -> str:
-        return "volc-sdk-python/" + VERSION
+        return "ark-runtime-python/" + VERSION
 
     def default_headers(self) -> Dict[str, str]:
         return {

{arkruntime-0.4.0 → arkruntime-0.6.0}/src/arkruntime/_constants.py

@@ -4,7 +4,8 @@
 
 import httpx
 
-VERSION = "1.0.0"
+from ._version import VERSION as VERSION
+
 BASE_URL = "https://ark.cn-beijing.volces.com/api/v3"
 
 

{arkruntime-0.4.0 → arkruntime-0.6.0}/src/arkruntime/_utils/_transform.py

@@ -272,9 +272,10 @@ def _transform_typeddict(
     result: dict[str, object] = {}
     annotations = get_type_hints(expected_type, include_extras=True)
     for key, value in data.items():
-        if not is_given(value):
-            # we don't need to include `NotGiven` values here as they'll
-            # be stripped out before the request is sent anyway
+        if value is None or not is_given(value):
+            # Optional request parameters default to None in generated methods.
+            # Omit both None and NotGiven values so the wire payload contains
+            # only fields the caller actually supplied.
             continue
 
         type_ = annotations.get(key)
@@ -439,9 +440,10 @@ async def _async_transform_typeddict(
     result: dict[str, object] = {}
     annotations = get_type_hints(expected_type, include_extras=True)
     for key, value in data.items():
-        if not is_given(value):
-            # we don't need to include `NotGiven` values here as they'll
-            # be stripped out before the request is sent anyway
+        if value is None or not is_given(value):
+            # Optional request parameters default to None in generated methods.
+            # Omit both None and NotGiven values so the wire payload contains
+            # only fields the caller actually supplied.
             continue
 
         type_ = annotations.get(key)

arkruntime-0.6.0/src/arkruntime/_version.py

@@ -0,0 +1,27 @@
+# Copyright (c) 2026 ByteDance Ltd. and/or its affiliates.
+# SPDX-License-Identifier: Apache-2.0
+
+import re
+from importlib.metadata import version
+from pathlib import Path
+
+
+def _get_version() -> str:
+    # Source and editable imports must use this checkout, even if another
+    # arkruntime distribution is installed. Releases use wheel metadata,
+    # which setuptools derives from the same pyproject.toml project.version.
+    source_root = Path(__file__).resolve().parent.parent
+    pyproject = source_root.parent / "pyproject.toml"
+    if source_root.name == "src" and pyproject.is_file():
+        # The project declares a static, single-line version. Read only the
+        # [project] table without requiring a TOML dependency on Python 3.8.
+        project = re.search(r"(?ms)^\[project\][ \t]*\n(.*?)(?=^\[|\Z)", pyproject.read_text(encoding="utf-8"))
+        if project is not None:
+            declared = re.search(r"""(?m)^version\s*=\s*["']([^"'\r\n]+)["'][ \t]*(?:#.*)?$""", project[1])
+            if declared is not None:
+                return declared[1]
+        raise RuntimeError("Expected a static project.version in " + str(pyproject))
+    return version("arkruntime")
+
+
+VERSION = _get_version()

{arkruntime-0.4.0 → arkruntime-0.6.0}/src/arkruntime/resources/__init__.py

@@ -7,7 +7,7 @@ from .batch import AsyncBatch, Batch
 from .chat import AsyncChat, Chat
 from .content_generation import AsyncContentGeneration, ContentGeneration
 from .embeddings import AsyncEmbeddings, Embeddings
-from .environments import AsyncEnvironments, Environments
+from .environments import AsyncEnvironments, AsyncEnvironmentWork, Environments, EnvironmentWork
 from .files import AsyncFiles, Files
 from .images import AsyncImages, Images
 from .memory_stores import (
@@ -56,6 +56,8 @@ __all__ = [
     "AsyncAgents",
     "Environments",
     "AsyncEnvironments",
+    "EnvironmentWork",
+    "AsyncEnvironmentWork",
     "MemoryStores",
     "AsyncMemoryStores",
     "Memories",

arkruntime-0.6.0/src/arkruntime/resources/environments/__init__.py

@@ -0,0 +1,4 @@
+from arkruntime.resources.environments.environments import AsyncEnvironments, Environments
+from arkruntime.resources.environments.work import AsyncEnvironmentWork, EnvironmentWork
+
+__all__ = ["Environments", "AsyncEnvironments", "EnvironmentWork", "AsyncEnvironmentWork"]