Metadata-Version: 2.4
Name: tsugi-kpool
Version: 0.1.0
Summary: K-Pool LoRA SDK. software analog of TsugiCinema's Infinity provisional at LoRA adapter granularity. Productized from the K-Pool LoRA provisional (US App. 64/060,315) and the Infinity provisional (US App. 64/055,093).
Project-URL: Homepage, https://tsugilabs.ai
Project-URL: Patents, https://tsugilabs.ai/patents
Project-URL: Repository, https://github.com/tsugiai/tsugi-kpool
Project-URL: Unified-SDK, https://github.com/tsugiai/tsugi
Project-URL: Companion-SDK-Patent-Independent, https://github.com/tsugiai/tsugi-mend
Author-email: Tong Liu <tong@tsugicinema.com>
License: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: distributed-training,lora,peft,plesiochronous,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: accelerate>=0.34
Requires-Dist: numpy>=1.26
Requires-Dist: peft>=0.12
Requires-Dist: torch>=2.4
Requires-Dist: transformers>=4.45
Provides-Extra: benchmark
Requires-Dist: bitsandbytes>=0.43; extra == 'benchmark'
Requires-Dist: datasets>=2.20; extra == 'benchmark'
Requires-Dist: evaluate>=0.4; extra == 'benchmark'
Requires-Dist: hf-transfer>=0.1; extra == 'benchmark'
Requires-Dist: matplotlib>=3.8; extra == 'benchmark'
Requires-Dist: protobuf>=4.25; extra == 'benchmark'
Requires-Dist: pyyaml>=6.0; extra == 'benchmark'
Requires-Dist: scipy>=1.13; extra == 'benchmark'
Requires-Dist: sentencepiece>=0.2; extra == 'benchmark'
Requires-Dist: wandb>=0.17; extra == 'benchmark'
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

# tsugi-kpool

K-Pool LoRA SDK. Software productization of TsugiCinema Inc.'s K-Pool LoRA provisional (US App. 64/060,315, filed 2026-05-07) and Infinity provisional (US App. 64/055,093, filed 2026-05-01), packaged as a drop-in extension to PyTorch + PEFT for distributed LoRA fine-tuning with measurable straggler-tax recovery on cross-rack training clusters.

## What this is

A Python package that wraps PyTorch distributed and PEFT to implement, at LoRA adapter granularity:

1. **K-out-of-N adapter routing**. K-Pool LoRA's claim element, selecting K of N adapter modules per step.
2. **Adapter-gradient elastic buffer**. software analog of Infinity claim 2, FIFO buffer of adapter gradients prior to aggregation.
3. **Buffer-convergence aggregation**. Infinity claim 4, triggers aggregation when buffer-variance falls below threshold instead of on iteration count.
4. **Phase-correction sideband**. Infinity claim 3, low-bandwidth TCP channel between training nodes carrying drift telemetry, parallel to (not displacing) the NCCL gradient data plane.

The public API stays close to `peft.LoraConfig` + `accelerate.Accelerator` so adoption friction is minimal.

## What this is not

- Not a fork of OpenDiLoCo. The architectural sibling exists but Prime Intellect's open-source orchestration layer is a separate prior-art branch; we go through `torch.distributed.ProcessGroup` directly to keep IP boundaries clean.
- Not a full-model Infinity instance. This SDK demonstrates the mechanism at adapter granularity. The transport-layer / full-model instantiation is a separate (Phase 2) productization track.
- Not yet a benchmark. The benchmark protocol is in `benchmarks/llama3_8b_lora/`.

## Install

```bash
pip install -e ".[dev,benchmark]"
```

## Minimal usage

```python
from tsugi_kpool import KPoolLoraConfig, plesio_init
from transformers import AutoModelForCausalLM
from peft import get_peft_model

model = AutoModelForCausalLM.from_pretrained("meta-llama/Meta-Llama-3-8B")

config = KPoolLoraConfig(
    r=16,                        # standard LoRA rank
    lora_alpha=32,
    target_modules=["q_proj", "v_proj"],
    n_adapters=8,                # N
    k_active=2,                  # K-out-of-N per step
    sideband_addr="tcp://0.0.0.0:51820",  # phase-correction sideband
    buffer_convergence_eps=1e-3, # buffer-variance trigger threshold
)

model = get_peft_model(model, config)
plesio_init(model, config)   # starts the sideband + aggregator threads

# from here, train as you would any peft+accelerate fine-tune
```

## License

**Apache License, Version 2.0** with its full automatic patent grant. TsugiCinema, Inc. is the Licensor. The Apache-2.0 patent 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. See `LICENSE` for the NOTICE preamble explaining the doctrine and the full Apache-2.0 license text.

The license posture aligns with TsugiCinema's 2026-05-22 strategic doctrine: hyperscaler-product revenue as primary path; patents as defensive moat (DD scaffolding plus counter-assertion insurance) rather than offensive enforcement; unified `pip install tsugi` product wrapping this SDK and the companion `tsugiai-mend-sdk` at the packaging level.

## Status

Pre-alpha. APIs will change without notice until v0.1. Repository is private and counsel-and-internal-only pending coordinated public release with the companion `tsugiai-mend-sdk` and the unified `pip install tsugi` product surface.
