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

# Tensor Shape Validation Algorithm and Rules

> Tensor shape validation specification for EMEP. Iterates over state_dict, compares shapes and dtypes per parameter, reports first mismatch, and references broadcasting rules from Tensor Math.

Tensor shape validation is the final gate before a merge can proceed. This page specifies the algorithm that iterates over state\_dict entries, compares shapes and dtypes, and reports the first fatal mismatch.

## Validation Algorithm

```mermaid theme={null}
flowchart TD
    START([START]) --> INPUT[Input: Model A state_dict + Model B state_dict]
    INPUT --> KEYS{Key sets equal?}
    KEYS -->|no| DIFF[Compute key difference]
    DIFF --> ONLY_A{Keys only in A?}
    ONLY_A -->|yes| INCOMPATIBLE_1[INCOMPATIBLE: parameter set mismatch]
    ONLY_A -->|no| ONLY_B{Keys only in B?}
    ONLY_B -->|yes| INCOMPATIBLE_1
    ONLY_B -->|no| ITER[Iterate over shared keys]
    KEYS -->|yes| ITER
    ITER --> SHAPE{Shape match?}
    SHAPE -->|no| REPORT[Report mismatch: key, expected, actual]
    REPORT --> INCOMPATIBLE_2[INCOMPATIBLE: shape mismatch]
    SHAPE -->|yes| DTYPE{dtype compatible?}
    DTYPE -->|no| CONDITIONALLY_COMPATIBLE[CONDITIONALLY_COMPATIBLE: dtype mismatch]
    DTYPE -->|yes| NEXT{More keys?}
    NEXT -->|yes| ITER
    NEXT -->|no| COMPATIBLE[COMPATIBLE]
    COMPATIBLE --> END([END])
    CONDITIONALLY_COMPATIBLE --> END
    INCOMPATIBLE_1 --> END
    INCOMPATIBLE_2 --> END
```

## Dtype Compatibility Rules

| Dtype A | Dtype B | Compatible? | Action if CONDITIONALLY\_COMPATIBLE |
| - | - | - | - |
| fp32 | fp32 | Yes | None |
| fp32 | bf16 | CONDITIONALLY\_COMPATIBLE | Cast to fp32 or bf16 |
| fp32 | fp16 | CONDITIONALLY\_COMPATIBLE | Cast to fp32 or fp16 |
| bf16 | bf16 | Yes | None |
| bf16 | fp16 | CONDITIONALLY\_COMPATIBLE | Cast to fp32 |
| fp16 | fp16 | Yes | None |
| int8 | int8 | Yes | None |
| int8 | fp16 | CONDITIONALLY\_COMPATIBLE | Dequantize or quantize |
| int4 | int4 | Yes | None |
| int4 | any | CONDITIONALLY\_COMPATIBLE | Dequantize |

## Broadcasting Rules

When shapes do not match exactly, the TensorEngine applies broadcasting rules defined in [Tensor Math](https://doc.blueapi.ir/math/tensor-math.md). Broadcasting is only permitted when the shapes are compatible per elementwise rules: dimensions must be equal or one of them must be 1. Broadcasting across parameter keys (e.g., different layer counts) is not supported and produces INCOMPATIBLE.

## Mismatch Report Format

The first mismatch terminates validation and produces a structured report:

```json theme={null}
{
  "status": "INCOMPATIBLE",
  "key": "model.layers.0.self_attn.q_proj.weight",
  "expected_shape": [4096, 4096],
  "actual_shape": [4096, 5120],
  "expected_dtype": "float32",
  "actual_dtype": "float32"
}
```

## Cross-Links

* [Model Compatibility](https://doc.blueapi.ir/compatibility/model-compatibility.md) for the full decision tree.
* [Architecture Compatibility](https://doc.blueapi.ir/compatibility/architecture-compatibility.md) for architecture checks.
* [Tensor Math](https://doc.blueapi.ir/math/tensor-math.md) for broadcasting and elementwise rules.
* [Merge Engine](https://doc.blueapi.ir/merge/merge-engine.md) for how validation feeds into merging.


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