Metadata-Version: 2.4
Name: tsugi
Version: 0.1.0
Summary: Unified developer surface for TsugiCinema's open-source distributed-training SDKs. pip install tsugi pulls tsugi-mend (Apache-2.0; patent-independent) and tsugi-kpool (Apache-2.0; patent-aligned) and re-exports both under one namespace.
Project-URL: Homepage, https://tsugilabs.ai
Project-URL: Repository, https://github.com/tsugiai/tsugi
Project-URL: Companion-SDK-Mend, https://github.com/tsugiai/tsugi-mend
Project-URL: Companion-SDK-KPool, https://github.com/tsugiai/tsugi-kpool
Author-email: Tong Liu <tong@tsugicinema.com>
License: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: cross-rack,decoupled-diloco,distributed-training,infinity,k-pool-lora,lora,peft,pytorch
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: tsugi-kpool==0.1.0
Requires-Dist: tsugi-mend==0.1.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

# tsugi

Unified developer surface for TsugiCinema's open-source distributed-training SDKs.

```bash
pip install tsugi
```

`tsugi` is a thin packaging-level wrapper that depends on and re-exports two physically separate Apache-2.0 SDKs published by TsugiCinema, Inc.

| Sub-SDK | PyPI package | Imports as | Patent posture |
|---|---|---|---|
| Cross-rack reducer (Decoupled DiLoCo + DES-LOC + async-TP + FALCON) | `tsugi-mend` | `tsugi.mend` | Patent-independent by deliberate construction |
| K-Pool LoRA / Infinity software analog | `tsugi-kpool` | `tsugi.kpool` | Patent-aligned (US App. 64/060,315 + US App. 64/055,093) |

The two sub-SDKs share zero code. This meta-package exposes them under a unified import namespace for developer convenience. Both sub-SDKs and this meta-package are licensed under the Apache License, Version 2.0.

## Status

**Pre-Alpha (0.1.0).** APIs are stabilizing. Cross-SDK integration patterns may evolve. The two sub-SDK packages are also at 0.1.0 and are pinned by exact version in this meta-package's dependencies.

## Quickstart

```python
import tsugi

tsugi.about()
# tsugi 0.1.0  unified developer surface
#   tsugi-mend  0.1.0  Apache-2.0  patent-independent (Decoupled DiLoCo + DES-LOC + async-TP + FALCON)
#   tsugi-kpool 0.1.0  Apache-2.0  patent-aligned (US App. 64/060,315 K-Pool LoRA + US App. 64/055,093 Infinity)
```

### Cross-rack reducer (`tsugi.mend`)

```python
from tsugi.mend import MendConfig, mend_init, mend_shutdown

# After your model is wrapped (FSDP, TP, etc.):
config = MendConfig(quorum_min_learners=2, grace_window_ms=2000)
mend_init(model, config)

# ... train ...

mend_shutdown(model)
```

See [`tsugi-mend`](https://github.com/tsugiai/tsugi-mend) for benchmark protocols, the multi-stage validation record (Stage A through Stage E-prime), and the Phase 2 sprint plan.

### K-Pool LoRA / Infinity (`tsugi.kpool`)

```python
from tsugi.kpool import KPoolLoraConfig, plesio_init, plesio_shutdown

config = KPoolLoraConfig(
    r=16,
    lora_alpha=32,
    n_adapters=8,
    k_active=4,
    sideband_enabled=True,
    aggregation_mode="buffer_convergence",
)
plesio_init(model, config)

# ... train with K-of-N adapter routing ...

plesio_shutdown(model)
```

See [`tsugi-kpool`](https://github.com/tsugiai/tsugi-kpool) for the buffer-convergence trigger characterization and the K-of-N routing semantics.

## Architecture

`tsugi` itself is a torch-free import: `import tsugi` resolves only to configuration dataclasses on each sub-SDK. The runtime functions (`mend_init`, `plesio_init`, etc.) lazy-import torch via each sub-SDK's facade on first call. This keeps documentation builds and torch-free CI environments working.

When you actually call a runtime function, that sub-SDK loads torch and its own runtime machinery. The two sub-SDKs never cross-reference each other; they can be installed and used independently of this meta-package.

## License and IP posture

Apache-2.0 with full automatic patent grant. See [`LICENSE`](LICENSE) for the preamble that distinguishes this meta-package's grant scope from each sub-SDK's grant scope, and [`NOTICE`](NOTICE) for the attribution chain to the upstream sub-SDKs.

The patent posture, in brief:

- This meta-package itself contains no patent-exercising code. Its Apache-2.0 patent grant covers only the thin wrapper code in this repository.
- `tsugi-mend` is patent-independent. Its Apache-2.0 grant does not extend to TsugiCinema's K-Pool LoRA or Infinity patent estates.
- `tsugi-kpool` is patent-aligned. Its Apache-2.0 grant in Section 3 extends to TsugiCinema's K-Pool LoRA (US App. 64/060,315) and Infinity (US App. 64/055,093) patent estates AS PRACTICED BY THE SDK CODE AS DISTRIBUTED. Apache-2.0 Section 3's "necessarily infringed by their Contribution" language bounds the patent license to the specific embodiment present in the SDK code, not the broader scope of the patent claims as filed.

## Links

- Homepage: https://tsugilabs.ai
- Companion SDK (Mend): https://github.com/tsugiai/tsugi-mend
- Companion SDK (KPool): https://github.com/tsugiai/tsugi-kpool
