Annotation reference

Python: `tfe.implements`

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, 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.

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 for which layouts the engine models in this release.

C++: comment form

// @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.

CLI

Configuration

Formats

Python: `tfe.implements`

Python: `tfe.layout`

C++: comment form

C++: macro form

​Python: tfe.implements

​Python: tfe.layout

​C++: comment form

​C++: macro form

Python: `tfe.implements`

Python: `tfe.layout`

C++: comment form

C++: macro form