> ## 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](https://doc.blueapi.ir/compatibility/model-compatibility.md) for the full decision tree.
* [Tokenizer Compatibility](https://doc.blueapi.ir/compatibility/tokenizer-compatibility.md) for the tokenizer branch.
* [Tensor Shape Validation](https://doc.blueapi.ir/compatibility/tensor-shape-validation.md) for the tensor branch.
* [Merge Strategies](https://doc.blueapi.ir/merge/merge-strategies.md) for Franken-Merge details.


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