# Custom Tensor Adapters

A `ModelAdapter` is what turns a loaded checkpoint into a [Semantic Model Graph](/docs/core-concepts/model-architecture-layer-module) - recognizing which weights form an attention block, which form an MLP, whether there's MoE routing or multiple modality towers. Tensormorph ships adapters for common architectures and falls back to a generic adapter for anything unrecognized; writing a custom `ModelAdapter` is how you get architecture-specific views and correct structural navigation for something the built-in adapters don't cover.

## What an adapter is responsible for

-   **Recognition** - inspecting a loaded checkpoint's tensor names, shapes, and any available metadata to decide whether this adapter applies at all.
-   **Structure building** - grouping recognized tensors into the address-space hierarchy (layer, module) rather than leaving them as a flat list.
-   **Special-casing** - flagging structures that unlock dedicated views, most notably MoE routing (for the [Expert Galaxy](/docs/working-with-models/mixture-of-experts-models)) and multi-tower fusion points (for [multimodal models](/docs/working-with-models/multimodal-models)).

## Falling back gracefully

An adapter should recognize confidently or not at all - a `ModelAdapter` that partially misclassifies a structure is worse than one that declines to match and lets the fallback adapter handle it. The fallback adapter's flat structure is always a safe, correct baseline.

## Where an adapter runs

A `ModelAdapter` implements the trait of the same name under the [`tm-plugin/1`](/docs/developer-platform/extension-api) ABI - like any plugin, it can run sandboxed (the default for a third-party adapter) or, if it needs capabilities the sandbox doesn't allow, through the signed native path.

## Testing an adapter

Because recognition is the highest-risk part of an adapter (a false-positive match can misrepresent a model's structure), test against both checkpoints your adapter should recognize and checkpoints it should explicitly decline - confirming the fallback adapter still handles the latter correctly is as important as confirming the former.

## Related resources

-   [Model, Architecture, Layer and Module](/docs/core-concepts/model-architecture-layer-module) - the address space an adapter builds.
-   [Extension API](/docs/developer-platform/extension-api) - the plugin ABI and trait system an adapter is built against.
-   [Multimodal Models](/docs/working-with-models/multimodal-models) - an example of the kind of structure a custom adapter would need to recognize.