Metadata-Version: 2.4
Name: tt-lang
Version: 1.1.3.dev20260619
Summary: Python Bindings and Package for TT-Lang Compiler Project
Author: Tenstorrent AI ULC
Maintainer: Tenstorrent AI ULC
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/tenstorrent/tt-lang
Project-URL: Repository, https://github.com/tenstorrent/tt-lang
Project-URL: Issues, https://github.com/tenstorrent/tt-lang/issues
Keywords: mlir,tt-lang,tt-mlir,tenstorrent,compiler,dsl,kernel
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: C++
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Compilers
Classifier: Topic :: Software Development :: Code Generators
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: LICENSE_understanding.txt
Requires-Dist: pydantic<3
Requires-Dist: torch>=1.9.0
Requires-Dist: numpy<2,>=1.24.4
Requires-Dist: greenlet>=3.0.0
Requires-Dist: PyYAML>=5.4.0
Requires-Dist: typing_extensions>=4.12.2
Requires-Dist: ml_dtypes<1.0,>=0.1.0; python_version < "3.13"
Requires-Dist: ml_dtypes<1.0,>=0.5.0; python_version >= "3.13"
Requires-Dist: loguru>=0.6.0
Requires-Dist: networkx>=3.1
Requires-Dist: graphviz>=0.20.3
Requires-Dist: click>=8.1.7
Requires-Dist: pandas>=2.0.3
Requires-Dist: seaborn>=0.13.2
Dynamic: description
Dynamic: description-content-type
Dynamic: license-file
Dynamic: requires-dist

[Hardware](https://tenstorrent.com/cards/) | [Documentation](https://docs.tenstorrent.com/tt-lang/) | [Discord](https://discord.gg/tenstorrent) | [Join Us](https://job-boards.greenhouse.io/tenstorrent?gh_src=22e462047us) | [Issues](https://github.com/tenstorrent/tt-lang/issues)

  TT-Lang

pl

![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)
![Python Version](https://img.shields.io/badge/python-3.10%20%7C%203.12-blue.svg)
![Build Status](https://github.com/tenstorrent/tt-lang/actions/workflows/ci.yml/badge.svg)

A Python-based Domain-Specific Language (DSL) for authoring high-performance custom kernels on Tenstorrent hardware. This project is under active development — see the [functionality matrix](docs/sphinx/specs/TTLangSpecification.md#appendix-d-functionality-matrix) for current simulator and compiler support.

-----
**Contents:** [Vision](#1-vision) · [Quick Start](#2-quick-start) · [Documentation](#3-documentation) · [Contributing](#4-contributing) · [Support](#5-support) · [License](#6-license)

-----

## 1. Vision

TT-Lang joins the Tenstorrent software ecosystem as an expressive yet ergonomic middle ground between [TT-NN](https://docs.tenstorrent.com/tt-metal/latest/ttnn/index.html) and [TT-Metalium](https://docs.tenstorrent.com/tt-metal/latest/tt-metalium/index.html), aiming to provide a unified entrypoint with integrated simulation, performance analysis, and AI-assisted development tooling.

  ecosystem graph

The language is designed to support generative AI workflows and a robust tooling ecosystem: Python as the host language enables AI tools to translate GPU DSL kernels (Triton, CUDA, cuTile, TileLang) to Tenstorrent hardware more reliably than direct TT-Metalium translation, while tight integration with functional simulation will allow AI agents to propose kernel implementations, validate correctness, and iterate on configurations autonomously. Developers should be able to catch errors and performance issues in their IDE rather than on hardware, with a functional simulator to surface bugs early. Line-by-line performance metrics and data flow graphs can guide both programmers and AI agents to easily spot bottle necks and optimization opportunities.

Tenstorrent developers today face a choice between TT-NN which provides high-level operations that are straightforward to use but lack the expressivity needed for custom kernels and TT-Metalium which provides full hardware control through explicit low-level management of memory and compute. This is not a shortcoming of TT-Metalium; it is designed to be low-level and expressive, providing direct access to hardware primitives without abstraction overhead, and it serves its purpose well for developers who need that level of control. The problem is that there is no middle ground where the compiler handles what it does best—resource management, validation, optimization—while maintaining high expressivity for application-level concerns.

TT-Lang bridges this gap through progressive disclosure: simple kernels require minimal specification where the compiler infers compute API operations, NOC addressing, DST register allocation and more from high-level abstractions, while complex kernels allow developers to open the hood and craft pipelining and synchronization details directly. The primary use case is kernel fusion for model deployment. Engineers porting models through TT-NN quickly encounter operations that need to be fused for performance or patterns that TT-NN cannot express, and today this requires rewriting in TT-Metalium which takes weeks and demands undivided attention and hardware debugging expertise. TT-Lang makes this transition fast and correct: a developer can take a sequence of TT-NN operations, express the fused equivalent with explicit control over intermediate results and memory layout, validate correctness through simulation, and integrate the result as a drop-in replacement in their TT-NN graph.

## 2. Quick Start

### 2.1 Install from PyPI

We provide two tt-lang packages: the [tt-lang](https://pypi.org/project/tt-lang/) package includes the tt-lang compiler, Tenstorrent hardware support and depends on the `ttnn`, `pytorch` and several smaller python packages, while [tt-lang-sim](https://pypi.org/project/tt-lang-sim/) includes only the functional simulator (no compiler or hardware support) and does not depend on `ttnn`.

First, create an isolated Python environment (venv, conda, etc.) with Python
matching the selected wheel. Public PyPI hardware wheels currently use Python
3.12; S3 light wheels are built for Python 3.10 and Python 3.12. For example:

```bash
python3 -m venv --prompt ttlang ttlang-venv
source ttlang-venv/bin/activate
```

On linux machines with Tenstorrent hardware (Linux x86_64 / aarch64):
```bash
pip install tt-lang
tt-lang-setup                     # install matching sfpi runtime + copy tutorials
```

Functional simulator-only on Linux or MacOS, does not require Tenstorrent hardware:
```bash
pip install tt-lang-sim
tt-lang-setup                    # copy bundled tutorials to ./tutorials/
```

`tt-lang-setup` is idempotent (can be run multiple times without accumulating side effects).
It does two things, both inside the venv (no sudo):
- Downloads the sfpi compiler that pairs with the installed `ttnn` and extracts it under `<venv>/.../ttnn/runtime/sfpi/` (for `tt-lang` installation only).
- Copies bundled tutorials (`elementwise`, `matmul`, `broadcast`) to `./tutorials/`.

For finer control: `tt-lang-setup-sfpi` runs only the sfpi step, `tt-lang-setup-tutorials -t <DIR>` only the tutorials copy.

Run a tutorial example:

```bash
tt-lang-sim tutorials/elementwise/step_4_multinode_grid_full.py    # simulated (no compilation, runs on CPU)
python tutorials/elementwise/step_4_multinode_grid_full.py        # compiles and runs on hardware
```

To develop tt-lang itself or debug the compiler, use the Docker images below or [build from source](#25-building-without-docker).

### 2.2 Pre-built Docker images

TT-Lang is also usable through Docker images for both users and developers.
Two images are available:

| Image                                                                                           | Purpose                                                            | Preinstalled tt-lang
(including tt-lang-sim) | Can clone/build tt-lang? |
| ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | :----------------------------------------------: | :----------------------: |
| ![dist](https://img.shields.io/badge/dist-tt--lang--dist--ubuntu--24--04-brightgreen)
"dist" | Run tt-lang programs using
tt-lang-sim or Tenstorrent hardware |                       Yes                       |            No            |
| ![ird](https://img.shields.io/badge/ird-tt--lang--ird--ubuntu--24--04-blueviolet)
"ird"      | Develop and build tt-lang from source                              |                        No                        |           Yes           |

Both images can be used with `ird reserve` (see [container build docs](.github/containers/README.md) for details).

### 2.3 ![dist](https://img.shields.io/badge/dist-brightgreen) Pre-built tt-lang (for users)

Image: ghcr.io/tenstorrent/tt-lang/tt-lang-dist-ubuntu-24-04:latest ([all versions](https://github.com/tenstorrent/tt-lang/pkgs/container/tt-lang-dist-ubuntu-24-04))

The **dist** image contains a single, fully built tt-lang installation in `/opt/ttlang-toolchain`. Use it to compile and run any tt-lang program without building any of the prerequisites.

> ⚠️ **Important**: Do not attempt to build tt-lang inside a dist container — it has no build toolchain. To clone and build tt-lang yourself, use the [**ird** image](#22--development-image-for-building-tt-lang) instead.

Create the container (one-time):

```bash
docker run -d --name $USER-dist \
  --device=/dev/tenstorrent/0:/dev/tenstorrent/0 \
  -v /dev/hugepages:/dev/hugepages \
  -v /dev/hugepages-1G:/dev/hugepages-1G \
  -v $HOME:$HOME \
  ghcr.io/tenstorrent/tt-lang/tt-lang-dist-ubuntu-24-04:latest \
  sleep infinity
```

Open a shell:

```bash
docker exec -it $USER-dist /bin/bash
```

The environment activates automatically on login. Run an example immediately:

```bash
python /opt/ttlang-toolchain/examples/elementwise-tutorial/step_4_multinode_grid_full.py
```

To learn more, take a [tour](docs/sphinx/tour/index.md), explore the [programming guide](docs/sphinx/programming-guide.md) for compiler options, debugging, and performance tools, or use [Claude Code](https://claude.com/claude-code) with the built-in [slash commands](docs/sphinx/claude-skills.md) to translate kernels, profile, and optimize.

### 2.4 ![ird](https://img.shields.io/badge/ird-blueviolet) Development image (for building tt-lang)

Image: ghcr.io/tenstorrent/tt-lang/tt-lang-ird-ubuntu-24-04:latest ([all versions](https://github.com/tenstorrent/tt-lang/pkgs/container/tt-lang-ird-ubuntu-24-04))

The **ird** image has the pre-built toolchain (LLVM, tt-metal, Python venv) but does not include tt-lang itself. Clone the repository and build against the toolchain. You can maintain multiple clones or branches side by side, each with its own build directory.

To use directly with docker on your local linux machine, first create a container (one-time):

```bash
docker run -d --name $USER-ird \
  --device=/dev/tenstorrent/0:/dev/tenstorrent/0 \
  -v /dev/hugepages:/dev/hugepages \
  -v /dev/hugepages-1G:/dev/hugepages-1G \
  -v $HOME:$HOME \
  -v $SSH_AUTH_SOCK:/ssh-agent -e SSH_AUTH_SOCK=/ssh-agent \
  -v $HOME/.ssh/known_hosts:/root/.ssh/known_hosts:ro \
  ghcr.io/tenstorrent/tt-lang/tt-lang-ird-ubuntu-24-04:latest \
  sleep infinity
```

Open a shell:

```bash
docker exec -it $USER-ird /bin/bash
```

Inside the container, clone and build:

```bash
git clone https://github.com/tenstorrent/tt-lang.git
cd tt-lang
cmake -G Ninja -B build -DTTLANG_USE_TOOLCHAIN=ON
source build/env/activate
cmake --build build
```

Verify the build:

```bash
ninja -C build check-ttlang-all
```

Run an example:

```bash
python examples/elementwise-tutorial/step_4_multinode_grid_full.py
```

The `-DTTLANG_USE_TOOLCHAIN=ON` flag tells CMake to use the pre-built LLVM and tt-metal from `/opt/ttlang-toolchain` instead of building them from source, which saves significant build time.

Performance tracing (Tracy) is enabled by default. To disable it, add `-DTTLANG_ENABLE_PERF_TRACE=OFF` to the cmake configure command. See the [programming guide](docs/sphinx/programming-guide.md) for profiling usage.

### 2.5 Building without Docker

To build tt-lang directly on a host machine without Docker, see the [build system documentation](docs/sphinx/build.md). It covers prerequisites, all supported build modes (from submodules, reusable toolchain, pre-built toolchain), and version compatibility.

### 2.6 Container Tips

To map a different TT device, change the `--device` argument (e.g., `--device=/dev/tenstorrent/1:/dev/tenstorrent/0`).

### 2.7 Functional Simulator

tt-lang includes a functional simulator that runs kernels as pure Python, without requiring Tenstorrent hardware or the full compiler stack. Use it to validate kernel logic and debug with any Python debugger:

```bash
tt-lang-sim examples/eltwise_add.py
```

The simulator typically supports more language features than the compiler at any given point — see the [functionality matrix](docs/sphinx/specs/TTLangSpecification.md#appendix-d-functionality-matrix) for current coverage. See the [programming guide](docs/sphinx/simulator.md) for debugger setup and details.

## 3. Documentation

Full documentation is built with Sphinx. The source lives in [docs/sphinx/](docs/sphinx/) and covers:

- [Tour of TT-Lang](docs/sphinx/tour/index.md) — an introduction to TT-Lang features
- [Programming Guide](docs/sphinx/programming-guide.md) — compiler options, print debugging, performance tools
- [Functional Simulator](docs/sphinx/simulator.md) — run kernels without hardware, debugging setup
- [Claude Skills](docs/sphinx/claude-skills.md) — AI-assisted kernel translation, profiling, and optimization via [Claude Code](https://claude.com/claude-code)
- [Build System](docs/sphinx/build.md) — build configuration, toolchain modes, and version compatibility
- [Testing](docs/sphinx/testing.md) — how to write and run tests
- [Contributor Guide](docs/sphinx/contributor-guide.md) — workflow, validation, adding new ops

To build and view the Sphinx docs locally:

```bash
cmake -G Ninja -B build -DTTLANG_ENABLE_DOCS=ON
cmake --build build --target ttlang-docs
python -m http.server 8000 -d build/docs/sphinx/_build/html
```

## 4. Contributing

We welcome contributions. Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

### 4.1 Developer Guidelines

See the Sphinx [contributor guide](docs/sphinx/contributor-guide.md) and [code style guidelines](docs/sphinx/guidelines.md) for coding standards, dialect design patterns, and testing practices.

### 4.2 Updating Submodule Versions

tt-mlir defines the compatible versions of LLVM and tt-metal. When updating tt-mlir, the other submodules should be updated to match.

Update tt-mlir (and read the versions it expects):

```bash
cd third-party/tt-mlir && git fetch && git checkout <commit> && cd ../..

# Read the LLVM and tt-metal commits that this tt-mlir version expects:
grep LLVM_PROJECT_VERSION third-party/tt-mlir/env/CMakeLists.txt
grep TT_METAL_VERSION third-party/tt-mlir/third_party/CMakeLists.txt
```

Update LLVM to the compatible version:

```bash
cd third-party/llvm-project && git fetch && git checkout <llvm-sha> && cd ../..
```

Update tt-metal to the compatible version. The canonical tt-metal version
lives in `third-party/tt-metal-version` (a tt-metal release tag, e.g.
`v0.69.0`); see [build.md](docs/sphinx/build.md#updating-tt-metal) for the
full list of artifacts derived from it. Edit the file and run the verifier
in update mode to check out the submodule at the matching commit:

```bash
echo v0.69.0 > third-party/tt-metal-version
.github/scripts/check-tt-metal-version.sh --update
```

Commit all submodule updates together:

```bash
git add third-party/tt-mlir third-party/llvm-project third-party/tt-metal \
        third-party/tt-metal-version pyproject.toml
git commit -m "Update submodules to tt-mlir <commit>"
```

The build system verifies SHA compatibility during configure. If submodule versions are intentionally mismatched, pass `-DTTLANG_ACCEPT_LLVM_MISMATCH=ON` or `-DTTLANG_ACCEPT_TTMETAL_MISMATCH=ON` to suppress the check.

### 4.3 Code Formatting with Pre-commit

tt-lang uses [pre-commit](https://pre-commit.com/) to format code and enforce style guidelines before commits.

Install and activate:

```bash
pip install pre-commit
cd /path/to/tt-lang
pre-commit install
```

Pre-commit runs automatically on `git commit`. It formats Python code with [Black](https://github.com/psf/black), C++ code with [clang-format](https://clang.llvm.org/docs/ClangFormat.html) (LLVM style), removes trailing whitespace, and checks YAML/TOML syntax.

If pre-commit modifies files, the commit is stopped. Stage the changes and commit again:

```bash
git add -u
git commit -m "Your commit message"
```

To run manually on all files: `pre-commit run --all-files`

### 4.4 Code of Conduct

This project adheres to a [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code and treat all community members with respect.

## 5. Support

- [GitHub Issues](https://github.com/tenstorrent/tt-lang/issues) — report bugs or request features

## 6. License

This project is licensed under the Apache License 2.0 — see the [LICENSE](LICENSE) file for details.

Third-party dependencies and their licenses are listed in the [NOTICE](NOTICE) file.
