Metadata-Version: 2.4
Name: pai-turbox
Version: 1.1
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
Requires-Dist: packaging>=24
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# pai-turbox

Install TurboX binary wheels for the active GPU PyTorch environment:

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

GPU PyTorch and its driver must already be installed. The manager selects a
compatible, SHA256-verified binary from the public OSS index. It never resolves
the public PyPI project named `turbox`; its dependency is an exact OSS URL.

## Independent manager and business versions

`pip list` shows both distributions:

```text
pai-turbox  1.1
turbox      0.2.17+torch2.10.0.cu130.ppu.managed1.h...
```

`pai-turbox` contains the manager and CLI. `turbox` owns the compiled payload,
original dependencies, startup loader and console commands. `import turbox` and
`ENABLE_TURBOX=1` keep their existing behavior and license checks.

The business wheel's public version and environment suffix are preserved. A
managed build identity is appended so different commits or dependency policies
with the same business version can be replaced reliably by pip. Compiled file
contents are unchanged. `turbox.__version__` retains the original business version.

## Inspect and update

```sh
pai-turbox info
pai-turbox info --json
pai-turbox --version
pai-turbox update --dry-run
pai-turbox update
```

`info` reads installed metadata and shows both versions, Torch, CUDA, device and
original wheel without importing the business binary or contacting the network.
`update` reads the latest index, probes the active environment and selects the
highest compatible stable business version, then the latest OSS LastModified
within that version. If the same managed build is installed, it does nothing.
Otherwise it verifies and installs one exact OSS wheel with pip, including its
declared dependencies. It does not force-reinstall all dependencies or upgrade
the manager. Restart Python/Notebook processes that already imported TurboX.

To pin a business version or an original build:

```sh
pai-turbox update --version 0.2.17
pai-turbox update --wheel EXACT_ORIGINAL_WHEEL_FILENAME
```

These options permit rollback as well as upgrade. Missing Torch/GPU or a missing
compatible release produces an error. Customers need no OSS credentials or
wheel-index argument. `--no-cache-dir` is used internally during updates; keep it
on manager installs to avoid cross-environment pip wheel-cache reuse.

## Migrate and uninstall

Migrate from the 1.0 combined distribution with:

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

The old manager-owned payload is removed, and the new `turbox` distribution owns
its private `_turbox_runtime_payload/`. An existing native `turbox` distribution
is replaced in the target environment by the selected OSS build. A virtualenv
will not uninstall a distribution owned by an inherited system environment.

Uninstall both components explicitly when removing TurboX completely:

```sh
python -m pip uninstall pai-turbox turbox
```

Uninstalling only the manager leaves the business distribution installed, as with
normal pip dependencies. Use `pai-turbox update` for future business releases;
`pip install -U pai-turbox` only upgrades manager releases.

## Publisher

The fixed public index is:

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

`publish_oss_index.py` scans only direct original wheels in agent/, verifies new
or changed objects and publishes deterministic managed `turbox` wheels under
index/runtime/. The JSON records exact URLs and SHA256 for both original and
managed artifacts. Unchanged managed builds are reused. No original wheel or
bucket ACL is modified; newly published objects are public-read and anonymously
verified. Index snapshots are retained.

Install requirements-publish.txt and provide TURBOX_PUBLISH_ACCESS_KEY_ID and
TURBOX_PUBLISH_ACCESS_KEY_SECRET only in the publisher environment, then run:

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

Run one publisher at a time. Artifact validation is not full runtime qualification.
Special filenames lacking CUDA remain excluded until an explicit policy mapping
is supplied. New business wheels and policy data normally require only index
publication; they do not require a new manager release.

For manager releases, increment VERSION and use release_pypi.py to build, check
and upload only the installer sdist to the official `pai-turbox` project. Do not
upload business wheels to the public PyPI `turbox` project.
