# diffulex.strategy

`diffulex.strategy` contains the built-in decoding strategies. Importing the
package imports each strategy subpackage so its registry decorators run. The
engine then resolves the selected strategy name through the request, scheduler,
KV cache manager, model runner, sampler, and attention metadata registries.

| Strategy | Template family | Registered components |
| --- | --- | --- |
| `d2f` | Full-prefix block diffusion | `D2fReq`, `D2fScheduler`, `D2fKVCacheManager`, `D2fModelRunner`, `D2fAttnMetaData` |
| `dmax` | Token-merging multi-block diffusion | `DMaxReq`, `DMaxScheduler`, `DMaxKVCacheManager`, `DMaxModelRunner`, `DMaxAttnMetaData` |
| `multi_bd` | Multi-Block Diffusion | `MultiBDReq`, `MultiBDScheduler`, `MultiBDKVCacheManager`, `MultiBDModelRunner`, `MultiBDAttnMetaData` |
| `diffusion_gemma` | DiffusionGemma canvas/block decoding | `DiffusionGemmaReq`, `DiffusionGemmaScheduler`, `DiffusionGemmaKVCacheManager`, `DiffusionGemmaModelRunner`, `DiffusionGemmaAttnMetaData` |

The package-level helpers keep the currently selected strategy name:

| Symbol | How to use it | What it does |
| --- | --- | --- |
| `fetch_decoding_strategy` | Call from code that needs to inspect the active strategy. | Returns the current strategy name or `None`. |
| `set_decoding_strategy` | Pass a strategy name before strategy-dependent setup. | Stores the active decoding strategy globally. |
| `reset_decoding_strategy` | Call during teardown or tests. | Clears the global strategy name. |

These helpers do not register components by themselves. Registration happens
inside the strategy subpackages through `AutoReq`, `AutoScheduler`,
`AutoKVCacheManager`, and `AutoModelRunner` decorators.

## diffulex.strategy.d2f

`d2f` is the default block-diffusion strategy. It uses the multi-block template
stack and keeps prefix attention full by setting `is_prefix_full=True` in the
model runner.

| Symbol | How to use it | What it does |
| --- | --- | --- |
| `D2fReq` | Created through `AutoReq.create(..., decoding_strategy="d2f")`. | Inherits `MultiBlockReqTemplate`; strategy-specific state is initialized later by the scheduler. |
| `D2fScheduler` | Created through `AutoScheduler`. | Adds requests with `init_multi_block`, schedules prefill/decode blocks, handles preemption, and postprocesses accepted token writes. |
| `D2fKVCacheManager` | Created through `AutoKVCacheManager`. | Uses multi-block page allocation and append behavior. |
| `D2fModelRunner` | Created through `AutoModelRunner`. | Prepares chunked multi-block prefill/decode batches, runs the model, samples outputs, and captures multi-block CUDA graphs. |
| `D2fAttnMetaData` | Fetched by the attention backend. | Extends `MultiBlockAttnMetaDataTemplate` and stores per-batch multi-block attention fields. |
| `fetch_d2f_attn_metadata` | Called through the global attention metadata fetch hook. | Returns the current D2F metadata instance. |
| `set_d2f_attn_metadata` | Called by the model runner before attention. | Replaces the current D2F metadata with request/page/sequence tensors for the next forward pass. |
| `reset_d2f_attn_metadata` | Called after a forward pass or capture. | Restores an empty D2F metadata object. |

Use `d2f` as the reference when adding a strategy that follows the standard
multi-block request lifecycle without token-merging metadata.

## diffulex.strategy.dmax

`dmax` is the built-in token-merging strategy. It starts from the token-merging
multi-block template and adds DMax-specific request activation behavior,
attention metadata, and graph capture buffers for token merge descriptors.

| Symbol | How to use it | What it does |
| --- | --- | --- |
| `DMaxReq` | Created through `AutoReq.create(..., decoding_strategy="dmax")`. | Inherits `TokenMergingMultiBlockReqTemplate` and initializes token-merge state from `Config`. |
| `DMaxScheduler` | Created through `AutoScheduler`. | Uses token-merge request state, schedules multi-block work, and postprocesses token-merge sampler output. |
| `DMaxKVCacheManager` | Created through `AutoKVCacheManager`. | Uses token-merging multi-block cache behavior on top of the multi-block page allocator. |
| `DMaxModelRunner` | Created through `AutoModelRunner`. | Binds DMax attention metadata, prepares token-merging metadata tensors, and captures token-merging CUDA graphs. |
| `DMaxAttnMetaData` | Fetched by the attention backend. | Extends `TokenMergingMultiBlockAttnMetaDataTemplate` and resets token-merging fields on construction. |
| `fetch_dmax_attn_metadata` | Called through the global attention metadata fetch hook. | Returns the current DMax metadata instance. |
| `set_dmax_attn_metadata` | Called by the model runner before attention. | Replaces the current DMax metadata with request/page/sequence tensors for the next forward pass. |
| `reset_dmax_attn_metadata` | Called after a forward pass or capture. | Restores an empty DMax metadata object. |

`DMaxReq` also honors `DIFFULEX_DMAX_FORCE_PREFILL_ACTIVE=1`. That environment
switch keeps active-block iterations on the prefill-style path, which is useful
when comparing against reference DMax behavior.

## diffulex.strategy.multi_bd

`multi_bd` is the built-in Multi-Block Diffusion strategy. It shares most of
the same template surface as `d2f`, but uses block-causal prefix behavior so
prefix caching can remain enabled.

| Symbol | How to use it | What it does |
| --- | --- | --- |
| `MultiBDReq` | Created through `AutoReq.create(..., decoding_strategy="multi_bd")`. | Inherits `MultiBlockReqTemplate`; request attributes are filled by `init_multi_block`. |
| `MultiBDScheduler` | Created through `AutoScheduler`. | Adds, schedules, preempts, and postprocesses multi-block requests. |
| `MultiBDKVCacheManager` | Created through `AutoKVCacheManager`. | Uses multi-block cache allocation and append behavior. |
| `MultiBDModelRunner` | Created through `AutoModelRunner`. | Prepares multi-block batches and sets attention flags from `Config`, including DiffusionGemma-specific prefix handling. |
| `MultiBDAttnMetaData` | Fetched by the attention backend. | Extends `MultiBlockAttnMetaDataTemplate` for the MultiBD strategy. |
| `fetch_multi_bd_attn_metadata` | Called through the global attention metadata fetch hook. | Returns the current MultiBD metadata instance. |
| `set_multi_bd_attn_metadata` | Called by the model runner before attention. | Replaces the current MultiBD metadata with request/page/sequence tensors for the next forward pass. |
| `reset_multi_bd_attn_metadata` | Called after a forward pass or capture. | Restores an empty MultiBD metadata object. |

Use `multi_bd` as the closer reference when a new strategy needs block-causal
prefix behavior and prefix caching.

## diffulex.strategy.diffusion_gemma

`diffusion_gemma` is the native DiffusionGemma strategy. It uses a
DiffusionGemma-specific request, sampler, model runner, and attention metadata
path with 256-token block/page defaults.

| Symbol | How to use it | What it does |
| --- | --- | --- |
| `DiffusionGemmaReq` | Created through `AutoReq.create(..., decoding_strategy="diffusion_gemma")`. | Tracks DiffusionGemma canvas state and commit timing. |
| `DiffusionGemmaScheduler` | Created through `AutoScheduler`. | Uses the DiffusionGemma request lifecycle with standard scheduling hooks. |
| `DiffusionGemmaKVCacheManager` | Created through `AutoKVCacheManager`. | Uses the DiffusionGemma page/block layout. |
| `DiffusionGemmaModelRunner` | Created through `AutoModelRunner`. | Prepares DiffusionGemma prefill/decode tensors, self-conditioning context, and model forward calls. |
| `DiffusionGemmaAttnMetaData` | Fetched by the attention backend. | Stores DiffusionGemma attention metadata for the current forward pass. |