Metadata-Version: 2.4
Name: pai-turbox
Version: 1.2
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`; it verifies the exact OSS artifact itself during the first build.

## Independent manager and business versions

`pip list` shows both distributions:

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

`pai-turbox` contains the manager and CLI and bundles the selected initial
`turbox` distribution under its own seed directory. Its normal dependency
metadata lists the business dependencies, allowing pip to install them. The
embedded business metadata is discoverable by pip. No external direct-URL
dependency is declared by the PyPI package. After a business update, `turbox`
is installed as a standalone distribution with its own payload and loader. `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. The initial bundled `turbox` lives
under `_pai_turbox_seed/`; a later standalone update owns its own
`_turbox_runtime_payload/`. The provider state prevents a bundled seed from
shadowing a standalone update. An existing native `turbox` distribution is initially shadowed by the selected
bundled build; `pai-turbox update` replaces the standalone distribution when a
new build is selected. 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 the manager removes its initial bundled seed; a standalone business
distribution installed by update remains installed. Uninstall both components
explicitly for a complete removal. 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.
