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

# Model Compatibility: Full Decision Tree and States

> Complete compatibility decision tree for EMEP model pairs. Covers architecture, tokenizer, tensor shapes, and metadata checks down to COMPATIBLE, CONDITIONALLY_COMPATIBLE, and INCOMPATIBLE states.

Model compatibility is the gate through which every candidate merge must pass. This page defines every check dimension and the exact decision tree that produces one of three states: COMPATIBLE, CONDITIONALLY\_COMPATIBLE, or INCOMPATIBLE.

## Check Dimensions

The ModelCompatibilityAnalyzer evaluates every pair across these dimensions:

| Dimension           | What It Checks                        |
| ------------------- | ------------------------------------- |
| Architecture family | Llama, Mistral, Qwen, Gemma, etc.     |
| Model type          | base, instruct, chat, code            |
| Parameter count     | exact match or declared tolerance     |
| Layers              | layer count and ordering              |
| Hidden size         | hidden dimension per layer            |
| Intermediate size   | MLP expansion dimension               |
| Attention heads     | count and grouping                    |
| KV heads            | GQA/MQA head count                    |
| Embedding size      | vocab embedding dimension             |
| Vocabulary          | tokenizer vocab size and overlap      |
| Special tokens      | BOS, EOS, PAD, UNK presence and IDs   |
| Tokenizer family    | BPE, SentencePiece, WordPiece         |
| RoPE config         | base, theta, scaling method           |
| Context config      | max context length and scaling        |
| Parameter names     | key naming conventions in state\_dict |
| Tensor shapes       | per-parameter shape equality          |
| dtype               | weight data type                      |
| Weight format       | safetensors, bin, gguf, etc.          |
| Revision            | model commit or tag                   |
| Source              | Hugging Face hub, mirror, local path  |
| License             | permissible merge license             |
| Hash                | SHA-256 of weight files               |

## Compatibility Decision Tree

The following flowchart shows the full path from two input models to a final state.

```mermaid theme={null}
flowchart TD
    START([START]) --> INPUT[Input: Model A + Model B]
    INPUT --> META[Fetch metadata for both]
    META --> HASH{Hash match?}
    HASH -->|same model| INCOMPATIBLE[INCOMPATIBLE: identical model]
    HASH -->|different| LICENSE{License permits merge?}
    LICENSE -->|no| INCOMPATIBLE
    LICENSE -->|yes| ARCH{Same architecture family?}
    ARCH -->|no| FRANKEN{Franken-Merge strategy?}
    FRANKEN -->|yes| CONDITIONALLY_COMPATIBLE_1[CONDITIONALLY_COMPATIBLE: franken-merge with adapters]
    FRANKEN -->|no| INCOMPATIBLE
    ARCH -->|yes| TYPE{Same model type?}
    TYPE -->|no| CONDITIONALLY_COMPATIBLE_2[CONDITIONALLY_COMPATIBLE: type mismatch]
    TYPE -->|yes| PARAMS{Parameter count matches?}
    PARAMS -->|no| INCOMPATIBLE
    PARAMS -->|yes| LAYERS{Layer count matches?}
    LAYERS -->|no| INCOMPATIBLE
    LAYERS -->|yes| HIDDEN{Hidden size matches?}
    HIDDEN -->|no| INCOMPATIBLE
    HIDDEN -->|yes| INTERM{Intermediate size matches?}
    INTERM -->|no| INCOMPATIBLE
    INTERM -->|yes| ATTN{Attention heads match?}
    ATTN -->|no| INCOMPATIBLE
    ATTN -->|yes| KV{KV heads match?}
    KV -->|no| INCOMPATIBLE
    KV -->|yes| EMBED{Embedding size matches?}
    EMBED -->|no| INCOMPATIBLE
    EMBED -->|yes| ROPE{RoPE config matches?}
    ROPE -->|no| CONDITIONALLY_COMPATIBLE_3[CONDITIONALLY_COMPATIBLE: RoPE mismatch]
    ROPE -->|yes| CONTEXT{Context config matches?}
    CONTEXT -->|no| CONDITIONALLY_COMPATIBLE_4[CONDITIONALLY_COMPATIBLE: context mismatch]
    CONTEXT -->|yes| TOKENIZER{Tokenizer compatible?}
    TOKENIZER -->|INCOMPATIBLE| INCOMPATIBLE
    TOKENIZER -->|CONDITIONALLY_COMPATIBLE| CONDITIONALLY_COMPATIBLE_5[CONDITIONALLY_COMPATIBLE: tokenizer partial match]
    TOKENIZER -->|COMPATIBLE| TENSOR{Tensor shapes match?}
    TENSOR -->|no| INCOMPATIBLE
    TENSOR -->|yes| DTYPE{dtype compatible?}
    DTYPE -->|no| CONDITIONALLY_COMPATIBLE_6[CONDITIONALLY_COMPATIBLE: dtype mismatch, quantize required]
    DTYPE -->|yes| REVISION{Same revision?}
    REVISION -->|no| CONDITIONALLY_COMPATIBLE_7[CONDITIONALLY_COMPATIBLE: different revision]
    REVISION -->|yes| COMPATIBLE[COMPATIBLE]
    COMPATIBLE --> END([END])
    INCOMPATIBLE --> END
    CONDITIONALLY_COMPATIBLE_1 --> END
    CONDITIONALLY_COMPATIBLE_2 --> END
    CONDITIONALLY_COMPATIBLE_3 --> END
    CONDITIONALLY_COMPATIBLE_4 --> END
    CONDITIONALLY_COMPATIBLE_5 --> END
    CONDITIONALLY_COMPATIBLE_6 --> END
    CONDITIONALLY_COMPATIBLE_7 --> END
```

## CONDITIONALLY\_COMPATIBLE Explained

A pair is CONDITIONALLY\_COMPATIBLE when the core architecture matches but a non-fatal discrepancy exists. The MergeStrategy must handle the discrepancy explicitly.

| Condition                        | Required Action                                   |
| -------------------------------- | ------------------------------------------------- |
| Different revision               | Strategy must accept revision drift               |
| RoPE mismatch                    | Strategy must interpolate or override RoPE config |
| Context mismatch                 | Strategy must clamp or scale context              |
| Tokenizer partial match          | Strategy must remap or retrain embeddings         |
| dtype mismatch                   | Strategy must cast or quantize                    |
| Type mismatch (base vs instruct) | Strategy must handle task vector sign             |
| Franken-Merge selected           | Strategy must provide structural adapters         |

## INCOMPATIBLE Explained

A pair is INCOMPATIBLE when a fatal mismatch blocks all standard strategies. Cross-family merges without franken-merge adapters, mismatched layer counts, and mismatched tensor shapes are all fatal. The MergeEngine rejects these pairs before strategy selection.

## Cross-Links

* [Architecture Compatibility](/compatibility/architecture-compatibility) for the architecture-only subset of this tree.
* [Tokenizer Compatibility](/compatibility/tokenizer-compatibility) for the tokenizer branch in detail.
* [Tensor Shape Validation](/compatibility/tensor-shape-validation) for the tensor shape and dtype branch.
* [Merge Engine](/merge/merge-engine) for how the compatibility result feeds into the merge pipeline.