Metadata-Version: 2.4
Name: pai-turbox
Version: 1.0
Summary: Environment-aware installation entry for TurboX binary wheels
Author: TurboX Team
Classifier: Operating System :: POSIX :: Linux
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: requires-python
Dynamic: summary
Dynamic: Requires-Dist

# pai-turbox pip installation and OSS release index

The package name is `pai-turbox`; usage remains `import turbox`, existing console
commands and `ENABLE_TURBOX=1`. Installation finishes through pip, without a
second script or first-import binary download. Supported GPU PyTorch must already
be installed in the active environment.

## Customer installation

```sh
python -m pip install --no-cache-dir pai-turbox
```

Install into the active GPU PyTorch environment. The archive contains installation
code only. Customers do not supply wheel-index or OSS credentials. Its embedded
public index is:

https://turbox-wlcb.oss-cn-wulanchabu.aliyuncs.com/release/dist/agent/index/releases.json

The installer version is independent of the selected TurboX binary version.
Existing same-version installations are not automatically replaced when the
external index changes; see the update and cache rules below.

## Build and installation

The PEP 517 backend inspects the target interpreter's Torch/CUDA/device, reads the
public index and selects an existing wheel. It verifies the original archive's
SHA256 and metadata, then builds a pai-turbox wheel owning that binary payload.
The compiled files stay unchanged under `_pai_turbox_payload/`. A lightweight
loader exposes them as `turbox` and preserves original startup and license
checks, without sharing files with an existing native turbox distribution.

Public METADATA, dist-info and wheel filename use pai-turbox and VERSION.
Original dependencies are resolved alongside exact target Torch and index policy
constraints. There is no separate turbox distribution dependency. Source metadata
marks Requires-Dist dynamic. RECORD is rebuilt for all owned files. Selection is
frozen between metadata generation and wheel generation.

## Publishing an index

Install publisher dependencies from `requirements-publish.txt`, set
`TURBOX_PUBLISH_ACCESS_KEY_ID` and `TURBOX_PUBLISH_ACCESS_KEY_SECRET` in the release
job environment, then run:

```sh
python publish_oss_index.py --output releases.json --publish
```

The script lists `release/dist/agent/` using a slash delimiter and an additional
relative-path check. It ignores all subdirectories. New or changed wheels are
streamed, hashed and checked for ZIP integrity and matching metadata. An anonymous
HEAD verifies the download address. Unchanged ETag/size/LastModified entries reuse
previous hashes after public availability is checked. It publishes a versioned
snapshot and updates releases.json, explicitly sets object public-read ACLs, and
verifies anonymous readback. It never changes bucket or original wheel ACLs.

`approved` means these index checks passed; it does not claim every runtime
combination has been qualified. Missing CUDA information is not guessed: special
filenames remain in the inventory with review_required until explicit mappings
are supplied through release-policy.json. Dependency constraints and disabled
artifacts are also policy data, not hardcoded installer version branches.

Run one publishing job at a time. Transport/integrity errors fail the publication
instead of replacing the working index with a transient partial result. Index
writes happen only after generation finishes; retain snapshots for rollback.
Credentials are environment-only and are absent from JSON, tar and normal logs.

To publish a new installation entry after building it:

```sh
python -m build --sdist
python publish_oss_index.py --output releases.json --publish \
  --installer dist/pai_turbox-VERSION.tar.gz
```

The publisher checks name/version, the embedded default index and absence of
credentials or business payloads before uploading the source entry. Immutable
artifact names cannot be overwritten with different bytes. It also writes the
trailing-slash Simple Index project object that pip actually requests from OSS.
Increment VERSION for a changed installer release; index-only updates do not need
a new installer artifact.

## Selection, updates and cache

Match Python/ABI/platform, Torch/CUDA and device; select the highest compatible
approved stable version, then the latest OSS LastModified within that version.
Times are normalized to UTC. Pin a version with
`--config-settings turbox-version=0.2.11`, or an exact build with
`--config-settings wheel-filename=EXACT_WHEEL_FILENAME`.

Keep `--no-cache-dir` when reselecting an environment-dependent wheel. Standard
wheel tags do not encode Torch/CUDA/device. A runtime guard rejects a mismatched
cached binary, but rejection is not automatic cache invalidation. An existing
same-version pai-turbox is not automatically updated by bare `pip install` merely
because the JSON changed. Publish new installer release versions for normal
package-name upgrades. Explicit same-version rebuilds can download/extract the
source tar and pip-install the local tar, as covered by development verification;
there is no separate installer script.

References: [OSS object ACL](https://www.alibabacloud.com/help/en/oss/developer-reference/manage-object-acls-1),
[pip build interface](https://pip.pypa.io/en/stable/reference/build-system/),
[pip caching](https://pip.pypa.io/en/stable/topics/caching/).
