> ## Documentation Index
> Fetch the complete documentation index at: https://docs.theformalera.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Annotation reference

> The full syntax of @tfe.implements, tfe.layout, and the C++ comment and macro forms.

## Python: `tfe.implements`

```python theme={"system"}
theformalera.implements(
    key: str | list[str],
    *,
    grid: tuple[str, ...] | list[str] | None = None,
    bind: dict[str, str] | None = None,
    layout: dict[str, Layout] | None = None,
    domain: dict[str, tuple[int, int]] | None = None,
    assume: list[str] | None = None,
    configs: list[dict[str, Any]] | None = None,
    level: str | None = None,
) -> Callable[[F], F]
```

| Parameter | Required | Meaning |
| - | - | - |
| `key` | yes | A [Spec Key](https://docs.theformalera.com/concepts/spec-keys.md), or a list; each key is verified separately |
| `grid` | yes for kernels; no for launchers | Launch grid: one expression per dimension (≤ 3), over shape symbols, constexprs, integer literals, `+ - * //` and `cdiv(a, b)` |
| `bind` | no | Kernel parameter → spec tensor or scalar name, or an integer expression for integer parameters |
| `layout` | no | Pointer parameter → a `tfe.layout` mapping |
| `domain` | no | Symbol → `(lo, hi)`; may only narrow the default domain |
| `assume` | no | Preconditions: integer conditions (`T % 16 == 0`) and `contiguous(P)` |
| `configs` | no | Constexpr combinations to verify; default: every `@triton.autotune` config |
| `level` | no | Minimum level for this kernel (recorded in the request; not enforced by this release's policy) |

`implements` returns the decorated object unchanged. It attaches the annotation as `__theformalera__`, which `tfe.annotations_of(obj)` reads, for tools that inspect live objects. The CLI never imports kernel modules, so all arguments must be literals or `tfe.layout` calls.

Place it above `@triton.jit` and above `@triton.autotune`. It also works on a plain Python function that launches kernels (a **launcher**); see [Annotate Triton kernels](https://docs.theformalera.com/guides/annotate-triton.md#launcher-level-annotations).

## Python: `tfe.layout`

| Constructor | Meaning |
| - | - |
| `strided(*strides, contiguous=False)` | `x[i, j] = mem[i·s0 + j·s1]`; each stride is an int or a parameter name |
| `row_major(*dims)` | Contiguous, last dimension fastest |
| `col_major(*dims)` | Contiguous, first dimension fastest |
| `paged_kv(block_table, page)` | `K[b, s, h, d] = cache[bt[b, s // P], s % P, h, d]` |
| `ragged(cu_seqlens)` | `x[b, s, :] = mem[cu[b] + s, :]` |
| `recurrent_state(slot)` | `S[b]` = the spec's recurrent state after sequence `b`'s prefix |
| `blockwise_scaled(block=128, scale="scale")` | `W[i, j] = q[i, j] × scale[i // B, j // B]` |
| `permuted(*order)` | Dimension permutation |
| `interleaved(dim, parts)` | `parts` logical tensors interleaved along `dim` |
| `custom(fn)` | A pure index function, given as `"module:function"` |

See [Layouts and assumptions](https://docs.theformalera.com/guides/layouts-and-assumptions.md#layouts) for which layouts the engine models in this release.

## C++: comment form

```cpp theme={"system"}
// @theformalera implements  = "Qwen/Qwen3.8-27B@1.0:layers[*].mlp.gate_up"
// @theformalera bind        = { A: x, B: w_gate_up, D: gate_up }
// @theformalera layout      = { A: row_major(T, 5120), B: col_major(5120, 34816), D: row_major(T, 34816) }
// @theformalera domain      = { T: [1, 262144] }
// @theformalera assume      = [ "T % 64 == 0" ]
// @theformalera grid        = ( "cdiv(T, 128)", "272" )
// @theformalera instantiate = GateUpGemm<Shape<_128,_256,_64>, KernelTmaWarpSpecializedCooperative>
//                             GateUpGemm<Shape<_64,_128,_64>,  KernelTmaWarpSpecialized>
```

* Each line is `// @theformalera <field> = <value>`. Indented comment lines continue the previous value.
* The block attaches to the next declaration, and must contain `implements`.
* `implements` lists one or more double-quoted Spec Keys.

## C++: macro form

`#include <theformalera/annotate.h>`, then `THEFORMALERA_IMPLEMENTS("<key>")`, `THEFORMALERA_BIND(…)`, `THEFORMALERA_LAYOUT(…)`, `THEFORMALERA_DOMAIN(…)`, `THEFORMALERA_ASSUME(…)`, `THEFORMALERA_INSTANTIATE(…)` and `THEFORMALERA_GRID(…)`. Every macro expands to nothing. `THEFORMALERA_TRACE_LAUNCH(…)` records a launch for `theformalera trace` when compiled with `-DTHEFORMALERA_TRACE`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.