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

# Architecture Compatibility Algorithm and Checks

> Architecture compatibility specification for EMEP. Checks model family, layer count, hidden size, attention heads, RoPE, and context config. Cross-family merges are INCOMPATIBLE unless franken-merge.

Architecture compatibility verifies that two models share the same structural blueprint. This page specifies the algorithm, the exact checks, and the conditions under which a cross-family merge can proceed.

## Check Dimensions

The ModelCompatibilityAnalyzer evaluates architecture across these dimensions:

| Dimension         | What It Checks                    |
| ----------------- | --------------------------------- |
| Model family      | Llama, Mistral, Qwen, Gemma, etc. |
| Model type        | base, instruct, chat, code        |
| Layer count       | Number of transformer layers      |
| Hidden size       | Dimension per layer               |
| Intermediate size | MLP expansion dimension           |
| Attention heads   | Count and grouping                |
| KV heads          | GQA/MQA head count                |
| Embedding size    | Vocab embedding dimension         |
| RoPE base         | Rotary base frequency             |
| RoPE theta        | Scaling factor                    |
| RoPE scaling      | None, linear, NTK, YaRN           |
| Context length    | Maximum supported context         |

## Compatibility Decision Flow

```mermaid theme={null}
flowchart TD
    START([START]) --> INPUT[Input: Model A + Model B]
    INPUT --> FAMILY{Same architecture family?}
    FAMILY -->|no| FRANKEN{Franken-Merge strategy selected?}
    FRANKEN -->|yes| ADAPTERS{Explicit adapters declared?}
    ADAPTERS -->|yes| CONDITIONALLY_COMPATIBLE_1[CONDITIONALLY_COMPATIBLE: franken-merge with adapters]
    ADAPTERS -->|no| INCOMPATIBLE_1[INCOMPATIBLE: cross-family without adapters]
    FRANKEN -->|no| INCOMPATIBLE_1
    FAMILY -->|yes| LAYERS{Layer count matches?}
    LAYERS -->|no| INCOMPATIBLE_2[INCOMPATIBLE: layer mismatch]
    LAYERS -->|yes| HIDDEN{Hidden size matches?}
    HIDDEN -->|no| INCOMPATIBLE_2
    HIDDEN -->|yes| INTERM{Intermediate size matches?}
    INTERM -->|no| INCOMPATIBLE_2
    INTERM -->|yes| ATTN{Attention heads match?}
    ATTN -->|no| INCOMPATIBLE_2
    ATTN -->|yes| KV{KV heads match?}
    KV -->|no| INCOMPATIBLE_2
    KV -->|yes| EMBED{Embedding size matches?}
    EMBED -->|no| INCOMPATIBLE_2
    EMBED -->|yes| ROPE{RoPE config matches?}
    ROPE -->|no| CONDITIONALLY_COMPATIBLE_2[CONDITIONALLY_COMPATIBLE: RoPE mismatch]
    ROPE -->|yes| CONTEXT{Context config matches?}
    CONTEXT -->|no| CONDITIONALLY_COMPATIBLE_3[CONDITIONALLY_COMPATIBLE: context mismatch]
    CONTEXT -->|yes| COMPATIBLE[COMPATIBLE]
    COMPATIBLE --> END([END])
    CONDITIONALLY_COMPATIBLE_1 --> END
    CONDITIONALLY_COMPATIBLE_2 --> END
    CONDITIONALLY_COMPATIBLE_3 --> END
    INCOMPATIBLE_1 --> END
    INCOMPATIBLE_2 --> END
```

## Cross-Family Merge Rule

Cross-family merges are INCOMPATIBLE unless the MergeStrategy is explicitly Franken-Merge and adapters are declared. This is an engineering assumption: structural differences between families (attention variants, MLP layouts, normalization placement) require hand-designed adapter layers that cannot be generated automatically.

## CONDITIONALLY\_COMPATIBLE Cases

| Case                        | Required Action                                    |
| --------------------------- | -------------------------------------------------- |
| RoPE mismatch               | Strategy must interpolate or override RoPE config  |
| Context mismatch            | Strategy must clamp or scale context               |
| Franken-Merge with adapters | Strategy must provide and validate adapter weights |

## INCOMPATIBLE Cases

| Case                          | Reason                                        |
| ----------------------------- | --------------------------------------------- |
| Layer count mismatch          | Tensor shapes diverge at every layer boundary |
| Hidden size mismatch          | Attention and MLP shapes incompatible         |
| Attention/KV heads mismatch   | GQA grouping invalid                          |
| Embedding size mismatch       | Output projection shape invalid               |
| Cross-family without adapters | Structural layout incompatible                |

## Cross-Links

* [Model Compatibility](/compatibility/model-compatibility) for the full decision tree.
* [Tokenizer Compatibility](/compatibility/tokenizer-compatibility) for the tokenizer branch.
* [Tensor Shape Validation](/compatibility/tensor-shape-validation) for the tensor branch.
* [Merge Strategies](/merge/merge-strategies) for Franken-Merge details.