current-data-py 0.1.9__tar.gz → 0.1.11__tar.gz

{current_data_py-0.1.9 → current_data_py-0.1.11}/MANIFEST.in

@@ -3,3 +3,4 @@ include tests/check_environment.py
 include tests/check_remote.py
 include tests/check_management.py
 include tests/check_oss.py
+include tests/check_labeling.py

{current_data_py-0.1.9/current_data_py.egg-info → current_data_py-0.1.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: current-data-py
-Version: 0.1.9
+Version: 0.1.11
 Summary: Current Data protobuf messages and schema metadata
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
@@ -83,6 +83,97 @@ SDK. Registration only saves metadata; it does not upload files. Credential
 calls return fresh credentials without caching. Calls accept `timeout=` and
 `metadata=` for gRPC headers.
 
+For uploads that distinguish raw and converted data, use V2 with both arguments:
+
+```python
+with ManagementClient(address=os.environ["MANAGEMENT_ADDRESS"]) as client:
+    raw = client.get_upload_credentials_v2(data_type="YAM", data_kind="RAW")
+    converted = client.get_upload_credentials_v2(
+        data_type="YAM", data_kind="CONVERTED", use_internal_endpoint=True,
+    )
+```
+
+V2 accepts `EGOSUITE`, `YAM`, and `CURRENT_V2` data types and `RAW` or `CONVERTED`
+data kinds. Each argument also accepts its full enum name (`DATA_TYPE_YAM`,
+`DATA_KIND_RAW`) or integer value. `DataKind` is exported from
+`current_data_py.management`; data type constants are in `metadata_pb2`.
+Unspecified or unknown enum values are rejected. `RAW` is not a V2 data type.
+The server must have the selected environment/type/kind destination configured;
+unfilled placeholders return `FAILED_PRECONDITION`. V2 requires a deployed
+`GetUploadCredentialsV2` RPC and never falls back to the old RPC on failure.
+The existing `get_upload_credentials()` API and its defaults remain unchanged.
+V2 responses include the selected destination's `oss_endpoint` and `region`,
+along with its bucket and prefix; raw and converted destinations may use different
+OSS regions. The server derives the standard Alibaba Cloud endpoint from `region`:
+`https://oss-<region>.aliyuncs.com` by default, or
+`https://oss-<region>-internal.aliyuncs.com` with `use_internal_endpoint=True`.
+Use the internal endpoint from Alibaba Cloud resources in the same region.
+See the [Alibaba Cloud endpoint reference](https://www.alibabacloud.com/help/en/oss/user-guide/regions-and-endpoints).
+`OSSClient` accepts the same option for V2 uploads and retains it when refreshing
+credentials. It uses the returned endpoint and region for connections and signing.
+An explicit `region=` must match the returned region. If the endpoint or
+region changes during credential refresh, create a new `OSSClient`.
+
+For reads in the bucket's own region, use the new read V2 RPC:
+
+```python
+with ManagementClient(address=os.environ["MANAGEMENT_ADDRESS"]) as client:
+    read = client.get_read_credentials_v2(
+        bucket=os.environ["READ_BUCKET"], use_internal_endpoint=False,
+    )
+```
+
+The bucket is required and must appear in the service's environment-specific
+bucket-to-region map, shared with V2 uploads. Reads grant whole-bucket `GetObject`
+access bounded by the read RAM role. Public networking is the default; set
+`use_internal_endpoint=True` for internal networking. Unconfigured buckets return
+`FAILED_PRECONDITION`; empty or malformed buckets return `INVALID_ARGUMENT`.
+The existing `get_read_credentials()` API keeps its configured default endpoint,
+region and scope. V2 calls never fall back to it on failure.
+
+### Multi-cloud credentials (V3)
+
+Use V3 to explicitly choose OSS or native TOS. `StorageProvider` and
+`StorageCredentials` are exported from `current_data_py.management`.
+
+```python
+from current_data_py.management import ManagementClient
+
+with ManagementClient() as client:
+    upload = client.get_upload_credentials_v3(
+        provider="TOS", data_type="YAM", data_kind="RAW",
+        use_internal_endpoint=False,
+    )
+    read = client.get_read_credentials_v3(
+        provider="TOS", bucket=upload.bucket,
+        use_internal_endpoint=False,
+    )
+    print(upload.provider, upload.bucket, upload.endpoint, upload.region)
+```
+
+`provider` is required and accepts `OSS`/`TOS`, full enum names such as
+`STORAGE_PROVIDER_TOS`, or enum integer values. Unspecified/unknown providers
+are rejected. Uploads require the same explicit type/kind as V2; reads require
+an explicitly configured bucket on the selected provider. OSS V3 uses the same
+routes and roles as OSS V2. TOS configuration and IAM preparation are described
+in the [service deployment guide](../management_service/README.md#tos-preparation-for-v3).
+
+Both calls return `provider`, `endpoint`, `region`, `bucket`, `object_prefix`,
+`access_key_id`, `access_key_secret`, `security_token`, and `expires_at`.
+`object_prefix` is empty for whole-bucket reads. Use `endpoint` instead of V2's
+`oss_endpoint`. TOS public endpoints use `tos-<region>.volces.com`; internal
+endpoints use `tos-<region>.ivolces.com`. Internal networking requires access to
+the destination cloud and region's private network.
+
+V3 calls accept `timeout` and `metadata`, do not cache credentials, and never
+retry or fall back to earlier RPC versions. Old servers return `UNIMPLEMENTED`;
+unconfigured destinations return `FAILED_PRECONDITION`. A response whose
+provider differs from the request raises `ValueError`.
+
+These methods only fetch credentials. Pass TOS credentials to a native TOS
+client and refresh them before expiration. `OSSClient`, `DataClient`, metadata
+registration and signed URLs have not been extended to TOS by this change.
+
 ## Remote TD reads
 
 ### Payload decoding
@@ -183,10 +274,12 @@ to each call.
 
 `DataClient.open_td()` accepts an optional `bucket` argument. Without it, reads
 use the management service's `OSS_READ_BUCKET` and `OSS_READ_PREFIX` defaults.
-With it, the SDK requests whole-bucket read credentials, limited by the server's
-RAM role, and selects the first matching storage in the reference. An explicit
-bucket does not inherit the default prefix. Default and per-bucket credentials
-are cached separately and refreshed automatically.
+With it, the SDK uses `GetReadCredentialsV2` for whole-bucket credentials in the
+bucket's region, limited by the server's RAM role, and selects the first matching
+storage in the reference. An explicit bucket does not inherit the default prefix.
+Set `use_internal_endpoint=True` with an explicit bucket to use internal networking.
+Credentials are cached separately for each `(bucket, use_internal_endpoint)` pair,
+apart from the legacy default scope, and refreshed automatically.
 
 ```python
 import os
@@ -204,8 +297,10 @@ with DataClient(address=os.environ["MANAGEMENT_ADDRESS"]) as client:
             print(reader.summary())
 ```
 
-The explicit bucket must contain a storage listed in the reference. This uses
-the existing bucket-aware management API; no protocol changes are required.
+The explicit bucket must contain a storage listed in the reference and have a
+configured region on the server. Deploy `GetReadCredentialsV2` before upgrading
+clients that use explicit buckets; older servers return `UNIMPLEMENTED` and the
+SDK does not fall back to a potentially incorrect legacy endpoint.
 
 ## OSS
 
@@ -220,20 +315,67 @@ with ManagementClient(address=os.environ["MANAGEMENT_ADDRESS"]) as management:
         source.download_file(os.environ["SOURCE_OBJECT_KEY"], "/tmp/input.h5")
 
     # Convert the input into /tmp/output.td before uploading.
-    with OSSClient(management, permission="upload", data_type=int(os.environ["UPLOAD_DATA_TYPE"])) as destination:
+    with OSSClient(management, permission="upload", data_type=int(os.environ["UPLOAD_DATA_TYPE"]),
+                   data_kind="CONVERTED") as destination:
         key = destination.object_prefix + "recording/output.td"
         destination.upload_file(key, "/tmp/output.td")
         print(destination.bucket, key)  # Use these values when registering metadata.
 ```
 
-- Read access covers the requested bucket, subject to server permissions.
-  The server chooses the upload bucket and prefix based on the requested data type.
+- Read access uses V2 and covers the requested bucket, subject to server permissions.
+  The server chooses the upload bucket and prefix based on the requested data type
+  and kind. Supplying `data_kind` selects V2 and requires `data_type`; omit
+  `data_kind` to retain the legacy upload API. Read clients reject both arguments.
+- Reads and V2 uploads use the public endpoint by default. Set `use_internal_endpoint=True`
+  on `OSSClient` to select internal networking. Legacy uploads reject this option.
 - Credentials refresh automatically. Expired tokens trigger one refresh and retry.
 - Uploads reject overwrites by default; set `forbid_overwrite=False` to replace.
   Downloads replace the local file only on success; its parent directory must exist.
 - Uploads use a single PutObject request ([maximum 5 GiB](https://www.alibabacloud.com/help/en/oss/developer-reference/upload-files-using-oss-sdk-for-python-v2/)); multipart upload is not supported.
-- Supply `region=` for custom upload endpoints. Deploy the current management
-  credential API before using the new bucket and data-type arguments.
+- Supply `region=` for legacy custom upload endpoints; V2 returns its own region.
+  Deploy the V2 credential APIs and configure bucket regions before using reads
+  or the upload `data_kind` option.
+
+## Pre-annotation
+
+`current_data_py.labeling.LabelingClient` wraps the pre-annotation RPCs
+`CreateTask`, `ListTasks`, `ListItems`, `WriteResult`, and `UpdatePreAnnotation` with
+ManagementClient's TLS, package default address, caller-owned channel, per-call
+`timeout` (30 seconds by default, `None` disables it), and `metadata` conventions.
+Errors propagate without retries. Protobuf types are available through
+`service_pb2`, `task_pb2`, and `DataSelection` in the same module.
+
+```python
+from current_data_py.labeling import LabelingClient, service_pb2, task_pb2
+
+with LabelingClient() as labeling:
+    task = labeling.create_task(
+        "template-id", name="Pre-annotation",
+        input_sources=[task_pb2.InputSource(td_file=task_pb2.TdFileSource(data_id="data-id"))],
+        start_pre_annotation=True,
+    )
+    for item in labeling.list_items(task.task_id):
+        # Match question keys and option keys to the existing built-in template.
+        labeling.write_result(item.item_id, task_pb2.Result(question_results=[
+            task_pb2.QuestionResult(
+                question_key="quality",
+                choice=task_pb2.ChoiceResult(selected_option_keys=["ok"]),
+            ),
+        ]))
+        # On inference failure instead: write_result(item.item_id, pre_annotation_error="reason")
+    labeling.update_pre_annotation(
+        task.task_id, service_pb2.UpdatePreAnnotationRequest.ACTION_OPEN_HUMAN_REVIEW,
+    )
+```
+
+Alternatively, pass `data_selection=DataSelection(...)` when creating a task.
+Use `ACTION_ACCEPT_ALL_AND_COMPLETE` to accept all pre-annotations as final labels.
+Use an existing built-in template; custom templates do not support pre-annotation.
+The server validates inputs and task transitions.
+
+`list_tasks` and `list_items` return repeated protobuf collections.
+`create_task` and `update_pre_annotation` return full protobuf responses
+(including item count and task ID, or status). `write_result` returns `None`.
 
 ## 打包
 
@@ -254,6 +396,7 @@ python -m pip install --force-reinstall dist/*.whl
 python -I tests/check_package.py
 python -I tests/check_environment.py
 python -I tests/check_management.py
+python -I tests/check_labeling.py
 python -I tests/check_remote.py
 python -I tests/check_oss.py
 ```

{current_data_py-0.1.9 → current_data_py-0.1.11}/README.md

@@ -69,6 +69,97 @@ SDK. Registration only saves metadata; it does not upload files. Credential
 calls return fresh credentials without caching. Calls accept `timeout=` and
 `metadata=` for gRPC headers.
 
+For uploads that distinguish raw and converted data, use V2 with both arguments:
+
+```python
+with ManagementClient(address=os.environ["MANAGEMENT_ADDRESS"]) as client:
+    raw = client.get_upload_credentials_v2(data_type="YAM", data_kind="RAW")
+    converted = client.get_upload_credentials_v2(
+        data_type="YAM", data_kind="CONVERTED", use_internal_endpoint=True,
+    )
+```
+
+V2 accepts `EGOSUITE`, `YAM`, and `CURRENT_V2` data types and `RAW` or `CONVERTED`
+data kinds. Each argument also accepts its full enum name (`DATA_TYPE_YAM`,
+`DATA_KIND_RAW`) or integer value. `DataKind` is exported from
+`current_data_py.management`; data type constants are in `metadata_pb2`.
+Unspecified or unknown enum values are rejected. `RAW` is not a V2 data type.
+The server must have the selected environment/type/kind destination configured;
+unfilled placeholders return `FAILED_PRECONDITION`. V2 requires a deployed
+`GetUploadCredentialsV2` RPC and never falls back to the old RPC on failure.
+The existing `get_upload_credentials()` API and its defaults remain unchanged.
+V2 responses include the selected destination's `oss_endpoint` and `region`,
+along with its bucket and prefix; raw and converted destinations may use different
+OSS regions. The server derives the standard Alibaba Cloud endpoint from `region`:
+`https://oss-<region>.aliyuncs.com` by default, or
+`https://oss-<region>-internal.aliyuncs.com` with `use_internal_endpoint=True`.
+Use the internal endpoint from Alibaba Cloud resources in the same region.
+See the [Alibaba Cloud endpoint reference](https://www.alibabacloud.com/help/en/oss/user-guide/regions-and-endpoints).
+`OSSClient` accepts the same option for V2 uploads and retains it when refreshing
+credentials. It uses the returned endpoint and region for connections and signing.
+An explicit `region=` must match the returned region. If the endpoint or
+region changes during credential refresh, create a new `OSSClient`.
+
+For reads in the bucket's own region, use the new read V2 RPC:
+
+```python
+with ManagementClient(address=os.environ["MANAGEMENT_ADDRESS"]) as client:
+    read = client.get_read_credentials_v2(
+        bucket=os.environ["READ_BUCKET"], use_internal_endpoint=False,
+    )
+```
+
+The bucket is required and must appear in the service's environment-specific
+bucket-to-region map, shared with V2 uploads. Reads grant whole-bucket `GetObject`
+access bounded by the read RAM role. Public networking is the default; set
+`use_internal_endpoint=True` for internal networking. Unconfigured buckets return
+`FAILED_PRECONDITION`; empty or malformed buckets return `INVALID_ARGUMENT`.
+The existing `get_read_credentials()` API keeps its configured default endpoint,
+region and scope. V2 calls never fall back to it on failure.
+
+### Multi-cloud credentials (V3)
+
+Use V3 to explicitly choose OSS or native TOS. `StorageProvider` and
+`StorageCredentials` are exported from `current_data_py.management`.
+
+```python
+from current_data_py.management import ManagementClient
+
+with ManagementClient() as client:
+    upload = client.get_upload_credentials_v3(
+        provider="TOS", data_type="YAM", data_kind="RAW",
+        use_internal_endpoint=False,
+    )
+    read = client.get_read_credentials_v3(
+        provider="TOS", bucket=upload.bucket,
+        use_internal_endpoint=False,
+    )
+    print(upload.provider, upload.bucket, upload.endpoint, upload.region)
+```
+
+`provider` is required and accepts `OSS`/`TOS`, full enum names such as
+`STORAGE_PROVIDER_TOS`, or enum integer values. Unspecified/unknown providers
+are rejected. Uploads require the same explicit type/kind as V2; reads require
+an explicitly configured bucket on the selected provider. OSS V3 uses the same
+routes and roles as OSS V2. TOS configuration and IAM preparation are described
+in the [service deployment guide](../management_service/README.md#tos-preparation-for-v3).
+
+Both calls return `provider`, `endpoint`, `region`, `bucket`, `object_prefix`,
+`access_key_id`, `access_key_secret`, `security_token`, and `expires_at`.
+`object_prefix` is empty for whole-bucket reads. Use `endpoint` instead of V2's
+`oss_endpoint`. TOS public endpoints use `tos-<region>.volces.com`; internal
+endpoints use `tos-<region>.ivolces.com`. Internal networking requires access to
+the destination cloud and region's private network.
+
+V3 calls accept `timeout` and `metadata`, do not cache credentials, and never
+retry or fall back to earlier RPC versions. Old servers return `UNIMPLEMENTED`;
+unconfigured destinations return `FAILED_PRECONDITION`. A response whose
+provider differs from the request raises `ValueError`.
+
+These methods only fetch credentials. Pass TOS credentials to a native TOS
+client and refresh them before expiration. `OSSClient`, `DataClient`, metadata
+registration and signed URLs have not been extended to TOS by this change.
+
 ## Remote TD reads
 
 ### Payload decoding
@@ -169,10 +260,12 @@ to each call.
 
 `DataClient.open_td()` accepts an optional `bucket` argument. Without it, reads
 use the management service's `OSS_READ_BUCKET` and `OSS_READ_PREFIX` defaults.
-With it, the SDK requests whole-bucket read credentials, limited by the server's
-RAM role, and selects the first matching storage in the reference. An explicit
-bucket does not inherit the default prefix. Default and per-bucket credentials
-are cached separately and refreshed automatically.
+With it, the SDK uses `GetReadCredentialsV2` for whole-bucket credentials in the
+bucket's region, limited by the server's RAM role, and selects the first matching
+storage in the reference. An explicit bucket does not inherit the default prefix.
+Set `use_internal_endpoint=True` with an explicit bucket to use internal networking.
+Credentials are cached separately for each `(bucket, use_internal_endpoint)` pair,
+apart from the legacy default scope, and refreshed automatically.
 
 ```python
 import os
@@ -190,8 +283,10 @@ with DataClient(address=os.environ["MANAGEMENT_ADDRESS"]) as client:
             print(reader.summary())
 ```
 
-The explicit bucket must contain a storage listed in the reference. This uses
-the existing bucket-aware management API; no protocol changes are required.
+The explicit bucket must contain a storage listed in the reference and have a
+configured region on the server. Deploy `GetReadCredentialsV2` before upgrading
+clients that use explicit buckets; older servers return `UNIMPLEMENTED` and the
+SDK does not fall back to a potentially incorrect legacy endpoint.
 
 ## OSS
 
@@ -206,20 +301,67 @@ with ManagementClient(address=os.environ["MANAGEMENT_ADDRESS"]) as management:
         source.download_file(os.environ["SOURCE_OBJECT_KEY"], "/tmp/input.h5")
 
     # Convert the input into /tmp/output.td before uploading.
-    with OSSClient(management, permission="upload", data_type=int(os.environ["UPLOAD_DATA_TYPE"])) as destination:
+    with OSSClient(management, permission="upload", data_type=int(os.environ["UPLOAD_DATA_TYPE"]),
+                   data_kind="CONVERTED") as destination:
         key = destination.object_prefix + "recording/output.td"
         destination.upload_file(key, "/tmp/output.td")
         print(destination.bucket, key)  # Use these values when registering metadata.
 ```
 
-- Read access covers the requested bucket, subject to server permissions.
-  The server chooses the upload bucket and prefix based on the requested data type.
+- Read access uses V2 and covers the requested bucket, subject to server permissions.
+  The server chooses the upload bucket and prefix based on the requested data type
+  and kind. Supplying `data_kind` selects V2 and requires `data_type`; omit
+  `data_kind` to retain the legacy upload API. Read clients reject both arguments.
+- Reads and V2 uploads use the public endpoint by default. Set `use_internal_endpoint=True`
+  on `OSSClient` to select internal networking. Legacy uploads reject this option.
 - Credentials refresh automatically. Expired tokens trigger one refresh and retry.
 - Uploads reject overwrites by default; set `forbid_overwrite=False` to replace.
   Downloads replace the local file only on success; its parent directory must exist.
 - Uploads use a single PutObject request ([maximum 5 GiB](https://www.alibabacloud.com/help/en/oss/developer-reference/upload-files-using-oss-sdk-for-python-v2/)); multipart upload is not supported.
-- Supply `region=` for custom upload endpoints. Deploy the current management
-  credential API before using the new bucket and data-type arguments.
+- Supply `region=` for legacy custom upload endpoints; V2 returns its own region.
+  Deploy the V2 credential APIs and configure bucket regions before using reads
+  or the upload `data_kind` option.
+
+## Pre-annotation
+
+`current_data_py.labeling.LabelingClient` wraps the pre-annotation RPCs
+`CreateTask`, `ListTasks`, `ListItems`, `WriteResult`, and `UpdatePreAnnotation` with
+ManagementClient's TLS, package default address, caller-owned channel, per-call
+`timeout` (30 seconds by default, `None` disables it), and `metadata` conventions.
+Errors propagate without retries. Protobuf types are available through
+`service_pb2`, `task_pb2`, and `DataSelection` in the same module.
+
+```python
+from current_data_py.labeling import LabelingClient, service_pb2, task_pb2
+
+with LabelingClient() as labeling:
+    task = labeling.create_task(
+        "template-id", name="Pre-annotation",
+        input_sources=[task_pb2.InputSource(td_file=task_pb2.TdFileSource(data_id="data-id"))],
+        start_pre_annotation=True,
+    )
+    for item in labeling.list_items(task.task_id):
+        # Match question keys and option keys to the existing built-in template.
+        labeling.write_result(item.item_id, task_pb2.Result(question_results=[
+            task_pb2.QuestionResult(
+                question_key="quality",
+                choice=task_pb2.ChoiceResult(selected_option_keys=["ok"]),
+            ),
+        ]))
+        # On inference failure instead: write_result(item.item_id, pre_annotation_error="reason")
+    labeling.update_pre_annotation(
+        task.task_id, service_pb2.UpdatePreAnnotationRequest.ACTION_OPEN_HUMAN_REVIEW,
+    )
+```
+
+Alternatively, pass `data_selection=DataSelection(...)` when creating a task.
+Use `ACTION_ACCEPT_ALL_AND_COMPLETE` to accept all pre-annotations as final labels.
+Use an existing built-in template; custom templates do not support pre-annotation.
+The server validates inputs and task transitions.
+
+`list_tasks` and `list_items` return repeated protobuf collections.
+`create_task` and `update_pre_annotation` return full protobuf responses
+(including item count and task ID, or status). `write_result` returns `None`.
 
 ## 打包
 
@@ -240,6 +382,7 @@ python -m pip install --force-reinstall dist/*.whl
 python -I tests/check_package.py
 python -I tests/check_environment.py
 python -I tests/check_management.py
+python -I tests/check_labeling.py
 python -I tests/check_remote.py
 python -I tests/check_oss.py
 ```

{current_data_py-0.1.9 → current_data_py-0.1.11/current_data_py.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: current-data-py
-Version: 0.1.9
+Version: 0.1.11
 Summary: Current Data protobuf messages and schema metadata
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
@@ -83,6 +83,97 @@ SDK. Registration only saves metadata; it does not upload files. Credential
 calls return fresh credentials without caching. Calls accept `timeout=` and
 `metadata=` for gRPC headers.
 
+For uploads that distinguish raw and converted data, use V2 with both arguments:
+
+```python
+with ManagementClient(address=os.environ["MANAGEMENT_ADDRESS"]) as client:
+    raw = client.get_upload_credentials_v2(data_type="YAM", data_kind="RAW")
+    converted = client.get_upload_credentials_v2(
+        data_type="YAM", data_kind="CONVERTED", use_internal_endpoint=True,
+    )
+```
+
+V2 accepts `EGOSUITE`, `YAM`, and `CURRENT_V2` data types and `RAW` or `CONVERTED`
+data kinds. Each argument also accepts its full enum name (`DATA_TYPE_YAM`,
+`DATA_KIND_RAW`) or integer value. `DataKind` is exported from
+`current_data_py.management`; data type constants are in `metadata_pb2`.
+Unspecified or unknown enum values are rejected. `RAW` is not a V2 data type.
+The server must have the selected environment/type/kind destination configured;
+unfilled placeholders return `FAILED_PRECONDITION`. V2 requires a deployed
+`GetUploadCredentialsV2` RPC and never falls back to the old RPC on failure.
+The existing `get_upload_credentials()` API and its defaults remain unchanged.
+V2 responses include the selected destination's `oss_endpoint` and `region`,
+along with its bucket and prefix; raw and converted destinations may use different
+OSS regions. The server derives the standard Alibaba Cloud endpoint from `region`:
+`https://oss-<region>.aliyuncs.com` by default, or
+`https://oss-<region>-internal.aliyuncs.com` with `use_internal_endpoint=True`.
+Use the internal endpoint from Alibaba Cloud resources in the same region.
+See the [Alibaba Cloud endpoint reference](https://www.alibabacloud.com/help/en/oss/user-guide/regions-and-endpoints).
+`OSSClient` accepts the same option for V2 uploads and retains it when refreshing
+credentials. It uses the returned endpoint and region for connections and signing.
+An explicit `region=` must match the returned region. If the endpoint or
+region changes during credential refresh, create a new `OSSClient`.
+
+For reads in the bucket's own region, use the new read V2 RPC:
+
+```python
+with ManagementClient(address=os.environ["MANAGEMENT_ADDRESS"]) as client:
+    read = client.get_read_credentials_v2(
+        bucket=os.environ["READ_BUCKET"], use_internal_endpoint=False,
+    )
+```
+
+The bucket is required and must appear in the service's environment-specific
+bucket-to-region map, shared with V2 uploads. Reads grant whole-bucket `GetObject`
+access bounded by the read RAM role. Public networking is the default; set
+`use_internal_endpoint=True` for internal networking. Unconfigured buckets return
+`FAILED_PRECONDITION`; empty or malformed buckets return `INVALID_ARGUMENT`.
+The existing `get_read_credentials()` API keeps its configured default endpoint,
+region and scope. V2 calls never fall back to it on failure.
+
+### Multi-cloud credentials (V3)
+
+Use V3 to explicitly choose OSS or native TOS. `StorageProvider` and
+`StorageCredentials` are exported from `current_data_py.management`.
+
+```python
+from current_data_py.management import ManagementClient
+
+with ManagementClient() as client:
+    upload = client.get_upload_credentials_v3(
+        provider="TOS", data_type="YAM", data_kind="RAW",
+        use_internal_endpoint=False,
+    )
+    read = client.get_read_credentials_v3(
+        provider="TOS", bucket=upload.bucket,
+        use_internal_endpoint=False,
+    )
+    print(upload.provider, upload.bucket, upload.endpoint, upload.region)
+```
+
+`provider` is required and accepts `OSS`/`TOS`, full enum names such as
+`STORAGE_PROVIDER_TOS`, or enum integer values. Unspecified/unknown providers
+are rejected. Uploads require the same explicit type/kind as V2; reads require
+an explicitly configured bucket on the selected provider. OSS V3 uses the same
+routes and roles as OSS V2. TOS configuration and IAM preparation are described
+in the [service deployment guide](../management_service/README.md#tos-preparation-for-v3).
+
+Both calls return `provider`, `endpoint`, `region`, `bucket`, `object_prefix`,
+`access_key_id`, `access_key_secret`, `security_token`, and `expires_at`.
+`object_prefix` is empty for whole-bucket reads. Use `endpoint` instead of V2's
+`oss_endpoint`. TOS public endpoints use `tos-<region>.volces.com`; internal
+endpoints use `tos-<region>.ivolces.com`. Internal networking requires access to
+the destination cloud and region's private network.
+
+V3 calls accept `timeout` and `metadata`, do not cache credentials, and never
+retry or fall back to earlier RPC versions. Old servers return `UNIMPLEMENTED`;
+unconfigured destinations return `FAILED_PRECONDITION`. A response whose
+provider differs from the request raises `ValueError`.
+
+These methods only fetch credentials. Pass TOS credentials to a native TOS
+client and refresh them before expiration. `OSSClient`, `DataClient`, metadata
+registration and signed URLs have not been extended to TOS by this change.
+
 ## Remote TD reads
 
 ### Payload decoding
@@ -183,10 +274,12 @@ to each call.
 
 `DataClient.open_td()` accepts an optional `bucket` argument. Without it, reads
 use the management service's `OSS_READ_BUCKET` and `OSS_READ_PREFIX` defaults.
-With it, the SDK requests whole-bucket read credentials, limited by the server's
-RAM role, and selects the first matching storage in the reference. An explicit
-bucket does not inherit the default prefix. Default and per-bucket credentials
-are cached separately and refreshed automatically.
+With it, the SDK uses `GetReadCredentialsV2` for whole-bucket credentials in the
+bucket's region, limited by the server's RAM role, and selects the first matching
+storage in the reference. An explicit bucket does not inherit the default prefix.
+Set `use_internal_endpoint=True` with an explicit bucket to use internal networking.
+Credentials are cached separately for each `(bucket, use_internal_endpoint)` pair,
+apart from the legacy default scope, and refreshed automatically.
 
 ```python
 import os
@@ -204,8 +297,10 @@ with DataClient(address=os.environ["MANAGEMENT_ADDRESS"]) as client:
             print(reader.summary())
 ```
 
-The explicit bucket must contain a storage listed in the reference. This uses
-the existing bucket-aware management API; no protocol changes are required.
+The explicit bucket must contain a storage listed in the reference and have a
+configured region on the server. Deploy `GetReadCredentialsV2` before upgrading
+clients that use explicit buckets; older servers return `UNIMPLEMENTED` and the
+SDK does not fall back to a potentially incorrect legacy endpoint.
 
 ## OSS
 
@@ -220,20 +315,67 @@ with ManagementClient(address=os.environ["MANAGEMENT_ADDRESS"]) as management:
         source.download_file(os.environ["SOURCE_OBJECT_KEY"], "/tmp/input.h5")
 
     # Convert the input into /tmp/output.td before uploading.
-    with OSSClient(management, permission="upload", data_type=int(os.environ["UPLOAD_DATA_TYPE"])) as destination:
+    with OSSClient(management, permission="upload", data_type=int(os.environ["UPLOAD_DATA_TYPE"]),
+                   data_kind="CONVERTED") as destination:
         key = destination.object_prefix + "recording/output.td"
         destination.upload_file(key, "/tmp/output.td")
         print(destination.bucket, key)  # Use these values when registering metadata.
 ```
 
-- Read access covers the requested bucket, subject to server permissions.
-  The server chooses the upload bucket and prefix based on the requested data type.
+- Read access uses V2 and covers the requested bucket, subject to server permissions.
+  The server chooses the upload bucket and prefix based on the requested data type
+  and kind. Supplying `data_kind` selects V2 and requires `data_type`; omit
+  `data_kind` to retain the legacy upload API. Read clients reject both arguments.
+- Reads and V2 uploads use the public endpoint by default. Set `use_internal_endpoint=True`
+  on `OSSClient` to select internal networking. Legacy uploads reject this option.
 - Credentials refresh automatically. Expired tokens trigger one refresh and retry.
 - Uploads reject overwrites by default; set `forbid_overwrite=False` to replace.
   Downloads replace the local file only on success; its parent directory must exist.
 - Uploads use a single PutObject request ([maximum 5 GiB](https://www.alibabacloud.com/help/en/oss/developer-reference/upload-files-using-oss-sdk-for-python-v2/)); multipart upload is not supported.
-- Supply `region=` for custom upload endpoints. Deploy the current management
-  credential API before using the new bucket and data-type arguments.
+- Supply `region=` for legacy custom upload endpoints; V2 returns its own region.
+  Deploy the V2 credential APIs and configure bucket regions before using reads
+  or the upload `data_kind` option.
+
+## Pre-annotation
+
+`current_data_py.labeling.LabelingClient` wraps the pre-annotation RPCs
+`CreateTask`, `ListTasks`, `ListItems`, `WriteResult`, and `UpdatePreAnnotation` with
+ManagementClient's TLS, package default address, caller-owned channel, per-call
+`timeout` (30 seconds by default, `None` disables it), and `metadata` conventions.
+Errors propagate without retries. Protobuf types are available through
+`service_pb2`, `task_pb2`, and `DataSelection` in the same module.
+
+```python
+from current_data_py.labeling import LabelingClient, service_pb2, task_pb2
+
+with LabelingClient() as labeling:
+    task = labeling.create_task(
+        "template-id", name="Pre-annotation",
+        input_sources=[task_pb2.InputSource(td_file=task_pb2.TdFileSource(data_id="data-id"))],
+        start_pre_annotation=True,
+    )
+    for item in labeling.list_items(task.task_id):
+        # Match question keys and option keys to the existing built-in template.
+        labeling.write_result(item.item_id, task_pb2.Result(question_results=[
+            task_pb2.QuestionResult(
+                question_key="quality",
+                choice=task_pb2.ChoiceResult(selected_option_keys=["ok"]),
+            ),
+        ]))
+        # On inference failure instead: write_result(item.item_id, pre_annotation_error="reason")
+    labeling.update_pre_annotation(
+        task.task_id, service_pb2.UpdatePreAnnotationRequest.ACTION_OPEN_HUMAN_REVIEW,
+    )
+```
+
+Alternatively, pass `data_selection=DataSelection(...)` when creating a task.
+Use `ACTION_ACCEPT_ALL_AND_COMPLETE` to accept all pre-annotations as final labels.
+Use an existing built-in template; custom templates do not support pre-annotation.
+The server validates inputs and task transitions.
+
+`list_tasks` and `list_items` return repeated protobuf collections.
+`create_task` and `update_pre_annotation` return full protobuf responses
+(including item count and task ID, or status). `write_result` returns `None`.
 
 ## 打包
 
@@ -254,6 +396,7 @@ python -m pip install --force-reinstall dist/*.whl
 python -I tests/check_package.py
 python -I tests/check_environment.py
 python -I tests/check_management.py
+python -I tests/check_labeling.py
 python -I tests/check_remote.py
 python -I tests/check_oss.py
 ```