Metadata-Version: 2.4
Name: heddura
Version: 0.1.0rc15
Summary: Trellis GPU acceleration platform — probe, budget, validate, run
Project-URL: Homepage, https://github.com/KanakMalpani/Trellis
Project-URL: Repository, https://github.com/KanakMalpani/Trellis
Project-URL: Issues, https://github.com/KanakMalpani/Trellis/issues
Project-URL: Changelog, https://github.com/KanakMalpani/Trellis/blob/main/CHANGELOG.md
Project-URL: Documentation, https://github.com/KanakMalpani/Trellis/blob/main/docs/V0_1_RC.md
Author: Trellis Contributors
License: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: autotune,csm,cuda,gpu,hip,stencil,trellis
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.10
Provides-Extra: cuda
Requires-Dist: cupy-cuda12x; (platform_system != 'Darwin') and extra == 'cuda'
Requires-Dist: numpy>=1.24; extra == 'cuda'
Provides-Extra: cuda12
Requires-Dist: cupy-cuda12x; (platform_system != 'Darwin') and extra == 'cuda12'
Requires-Dist: numpy>=1.24; extra == 'cuda12'
Provides-Extra: cuda13
Requires-Dist: numpy>=1.24; extra == 'cuda13'
Provides-Extra: dev
Requires-Dist: numpy>=1.24; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff~=0.14.0; extra == 'dev'
Provides-Extra: interop
Requires-Dist: numpy>=1.24; extra == 'interop'
Provides-Extra: native
Requires-Dist: cmake>=3.20; extra == 'native'
Requires-Dist: ninja; extra == 'native'
Requires-Dist: pybind11>=2.12; extra == 'native'
Requires-Dist: scikit-build-core>=0.9; extra == 'native'
Provides-Extra: sim
Requires-Dist: numpy>=1.24; extra == 'sim'
Description-Content-Type: text/markdown

# Trellis

[![CI](https://github.com/KanakMalpani/Trellis/actions/workflows/ci.yml/badge.svg)](https://github.com/KanakMalpani/Trellis/actions/workflows/ci.yml)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10%7C3.11%7C3.12%7C3.13-blue.svg)](pyproject.toml)

**GPU acceleration that stays honest:** probe the machine → budget memory → validate the launch → run — with coded errors, a doctor, and no silent “CPU as GPU peak.”

> Research codename was **Lattice**. Product / import / CLI: **`trellis`** ([ADR D01](docs/adr/D01-public-name-trellis.md)). PyPI distribution: **`heddura`** (`pip install heddura` → `import trellis`).

## What Trellis is / is not

| **Is** | **Is not** |
|--------|------------|
| Intent→Structure→Schedule→Resource→ISA conductor + MemoryBudget + CSM | A new general-purpose language |
| Multi-vendor **doors** with honest L0–L5 outcomes | Peak-everywhere |
| Stock → cache → generate → escape | A replacement for cuBLAS / FlashAttention / NCCL |
| Spark-class CUDA **software bar** + exceed via all compute sources | ZLUDA-class CUDA translation |
| Beachhead: sim + PyTorch interop | A game engine / graphics middleware |

## Architecture (one screen)

```text
Intent (map/stencil/…)
   → Structure (components/packs)
   → Schedule (tile/fuse/…)
   → Resource (MemoryBudget, streams, parallel_map plans)
   → Conductor: stock → cache → generate → escape
   → ISA / door (CUDA · CPU · HIP scaffold · WebGPU floors)
CSM/doctor probes sparse capabilities (no invented warp/TMEM)
```

## Why Trellis

- **Safety modes** (`strict` / `balanced` / `expert`) bound MemoryBudget headroom
- **`validate()`** rejects illegal / zero-occupancy launches before you ship a kernel
- **Conductor** prefers stock libraries (cuBLAS) when available — and only then may label `gpu_peak=true`
- **One native CUDA door** backs Python, C, C++, and Rust (no dual-stack drift)
- **Doctor / CSM** read real device props (`warp_size` from the GPU — never hardcoded)

Gold-standard checklist: **[docs/GOLD_STANDARD.md](docs/GOLD_STANDARD.md)** · Authority: **[ROADMAP.md](ROADMAP.md)** §A · Queue: **§C**.

## Status

**Φ0 complete** · **Φ1 advancing** · **Φ2 draft** (legal-only Peak). Product **`0.1.0rc15`**. **Not** bare `v0.1.0` — public CUDA 2-SKU wheels / multi-GPU CI (§8.6) still open.

## Door × outcome (honest matrix)

| Door | Typical outcome | Notes |
|------|-----------------|-------|
| CUDA | L2–L4 when toolkit+driver | Spark software bar = CTK 13+; see [SPARK.md](docs/targets/SPARK.md) |
| CPU | Always L2 oracle | Never `gpu_peak` |
| HIP | Scaffold / refuse | Instinct-first checklist |
| WebGPU | Floors only | Never peak |
| NPU peers | Detect-only | No fake SIMT |

Full taxonomy: [WORLD_GPU_COMPATIBILITY.md](WORLD_GPU_COMPATIBILITY.md).

## Quickstart — Python

From PyPI (import stays `trellis`):

```powershell
python -m pip install heddura
```

From a clone (editable / extras):

```powershell
python -m pip install -e ".[dev,interop]"
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build
$env:TRELLIS_LIB_DIR = "$PWD\build"
$env:CUDA_PATH = "C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.4"  # optional
trellis doctor --json
python scripts/support_bundle.py -o support_bundle.json
```

```python
import trellis

ctx = trellis.Context(device=0, safety="strict")  # or device="cpu"
x = ctx.alloc((64, 64), dtype="float32")
x.fill_ramp()
y = trellis.stencil(ctx, x, schedule={"tile": (16, 16)})
z = trellis.parallel_map(ctx, x, fn="relu", strategy="auto")
print(trellis.sources()["best"])
```

Peak honesty: generate kernels set `gpu_peak=false`. Stock cuBLAS (`gemm_like`) may set `gpu_peak=true`.

## Tutorials

```powershell
python examples/01_first_op.py
python examples/02_components.py
python examples/03_schedule_roofline.py
python examples/04_dlpack_interop.py
python scripts/repro_beachhead.py
python docs/e2e/run_phi1_smoke.py
```

## Contributing / support

- [CONTRIBUTING.md](CONTRIBUTING.md) · [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) · [SUPPORT.md](SUPPORT.md)
- [SECURITY.md](SECURITY.md) · [GOVERNANCE.md](GOVERNANCE.md) · [CITATION.cff](CITATION.cff)

## Hard rules

- Never invent `warp_size` — probe CSM / CUDA attrs
- Never label CPU as GPU peak
- Never skip `validate()` before launch
- Do not replace cuBLAS / FlashAttention / NCCL with DIY “stock”
- No ZLUDA-class CUDA translation

## License

Apache-2.0 — see `LICENSE` and `NOTICE`.
