# Chimera GGUF Import — v2.0 Optimized

Importer universel : convertit **n'importe quel modèle GGUF** (n'importe quelle quantisation, n'importe quelle architecture) en checkpoint compatible Chimera 5.1.

## Ce que fait le script

```
GGUF (Q4_0, Q5_1, Q8_0, F16, F32, BF16...)
  → Déquantification FP32 via gguf.dequantize()
  → Noise reduction (outlier-aware, par ligne ou global)
  → Conversion ternaire {-1, 0, +1} avec AbsMean par ligne
  → 2-bit packing (4 poids/byte = 16× réduction mémoire)
  → Checkpoint Chimera 5.1 (.pt)
```

## Installation

```bash
pip install gguf torch numpy
```

## Usage rapide

```bash
python gguf_import.py \
    --gguf /chemin/vers/nimportequel-modele.gguf \
    --config /chemin/vers/chimera/config.json \
    --scale tiny \
    --output ./imported_chimera.pt
```

## Modes de stockage

| Mode | Description | Quand l'utiliser |
|---|---|---|
| `fp32` (défaut) | Sauvegarde weight latent FP32 natif Chimera. Compatible avec `Chimera51ForCausalLM.load_state_dict()`. | **Recommandé** — le plus simple. |
| `packed` | Sauvegarde uniquement `packed_weight` + `alpha` pour les couches linéaires. **Nécessite un loader custom** dans Chimera. | Expérimental — checkpoint ultra-compact. |
| `both` | Sauvegarde les deux : weight FP32 + packed + alpha. | Pour migration progressive vers packed. |

```bash
# Mode packed (expérimental)
python gguf_import.py \
    --gguf model.gguf \
    --config config.json \
    --scale tiny \
    --storage packed \
    --output ./chimera_packed.pt
```

## Réduction de bruit configurable

| Méthode | Description | Par défaut |
|---|---|---|
| `row_outlier_clip` | Clip par ligne `mean ± 3σ` — préserve la structure locale des poids. | **✅ défaut** |
| `global_clip` | Clip global mean ± σ — plus agressif, moins de granularité. | |
| `median_center` | Center par médiane, scale par MAD — robuste aux distributions lourdes. | |
| `none` | Passthrough — si la source est déjà propre. | |

```bash
python gguf_import.py \
    --gguf model.gguf \
    --config config.json \
    --noise-method row_outlier_clip \
    --noise-sigma 2.5 \
    --output ./model_chimera.pt
```

## Stratégies de resize

| Stratégie | Description | Par défaut |
|---|---|---|
| `crop_pad` | Copie les zones communes, init le reste avec des gaussiennes de même std. | **✅ défaut** |
| `interpolate` | Interpolation bilinéaire (préserve la structure spatiale). | |
| `strict` | Échoue si les shapes ne matchent exactement. | |

## Auto-transpose

Détecte automatiquement si les dimensions source et cible sont inversées (`[out, in]` vs `[in, out]`) et transpose silencieusement.

Désactiver avec `--no-auto-transpose`.

## Quantisations GGUF supportées

| Type | Statut |
|---|---|
| F32 | ✅ Direct |
| F16 | ✅ Cast |
| BF16 | ✅ Cast |
| Q8_0 / Q8_1 | ✅ Déquantification |
| Q5_0 / Q5_1 | ✅ Déquantification |
| Q4_0 / Q4_1 | ✅ Déquantification |
| Q2_K / Q3_K / Q4_K / Q5_K / Q6_K | ✅ Via `gguf.dequantize` |

## Architectures source supportées

Tout modèle GGUF : LLaMA, Qwen, Mistral, Phi, Gemma, DeepSeek, etc.

## Mapping GGUF → Chimera

| GGUF source | Chimera cible |
|---|---|
| `token_embd` | `embed.weight` |
| `output` | `lm_head.weight` |
| `output_norm` | `norm.weight` |
| `blk.N.attn_q/k/v/output` | `layers.N.attn.q/k/v/o_proj` |
| `blk.N.ffn_gate/up/down` | `layers.N.mlp.gate/up/down_proj` |
| `blk.N.attn_norm` | `layers.N.attn_norm` |
| `blk.N.ffn_norm` | `layers.N.mlp_norm` |

## Clés manquantes

Par défaut (`--no-init-missing` désactivé), toutes les couches Chimera absentes du GGUF source sont initialisées automatiquement :
- Norms : `torch.ones(...)`
- Embeddings/Head : `normal_(0, 0.02)`
- Linéaires BitLinear : `normal_(0, sqrt(2/fan_in))` + ternarisation

## Après import : fine-tuning obligatoire

Chimera utilise des couches récurrentes hybrides (GatedDeltaNet, xLSTM, Titans, TSP Span Knot) — **pas** du transformer standard. Le mapping QKV↔recurrence est intrinsèquement lossy. Fine-tunez avec MeZO sur CPU :

```bash
OMP_NUM_THREADS=20 python train.py \
  --optimizer mezo --scale tiny --seq_len 64 --max_steps 100000 \
  --dataset_name HuggingFaceFW/fineweb-2 --dataset_config fra_Latn \
  --max_tokens 50000000 --compile --no-bf16 --num_workers 0 \
  --output_dir ./finetune_imported
```

## Exemple complet

```bash
python gguf_import.py \
    --gguf ./models/mistral-7b-q4_0.gguf \
    --config ./chimera/config.json \
    --scale tiny \
    --storage fp32 \
    --param-dtype fp32 \
    --noise-method row_outlier_clip \
    --noise-sigma 3.0 \
    --ternary-threshold 0.5 \
    --resize-strategy crop_pad \
    --output ./mistral_chimera_tiny.pt
```

## Dépôt

- Repo HuggingFace : [`Lgr54HFi/chimera-gguf-import`](https://huggingface.co/Lgr54HFi/chimera-gguf-import)
- Version : 2.0-optimized