cognitive core loading framework

README.md

@@ -1,5 +1,161 @@
----
-license: other
-license_name: proprietary
-license_link: LICENSE
----
+# COGNITIVE-CORE Framework
+
+> Standard universel pour les architectures cognitives d'Ame Web Studio
+
+## 🏗️ Structure
+
+```
+cognitive-core/
+├── __init__.py              # Exports du package
+├── cognitive_base.py        # Classes de base (Config, Modules, PreTrainedModel)
+├── cognitive_checkpoint.py  # Chargement/sauvegarde avec remappage auto
+├── cognitive_utils.py       # Utilitaires (device, mémoire, tokens)
+└── README.md               # Cette documentation
+```
+
+## 🚀 Installation
+
+```python
+# Ajouter à votre modèle
+import sys
+sys.path.append("/path/to/standardisation")
+
+from cognitive_core import (
+    CognitiveConfig,
+    CognitivePreTrainedModel,
+    setup_environment,
+    get_device
+)
+```
+
+## 📖 Guide d'Utilisation
+
+### 1. Créer une Configuration
+
+```python
+from cognitive_core import CognitiveConfig
+
+class MyModelConfig(CognitiveConfig):
+    model_type = "my_cognitive_model"
+    
+    def __init__(
+        self,
+        vocab_size: int = 50000,
+        # ... vos paramètres
+        **kwargs
+    ):
+        super().__init__(**kwargs)
+        self.vocab_size = vocab_size
+```
+
+### 2. Créer un Modèle Cognitif
+
+```python
+from cognitive_core import CognitivePreTrainedModel, CognitiveModule
+import torch.nn as nn
+
+class MyMemoryModule(CognitiveModule):
+    def __init__(self, config):
+        super().__init__(config)
+        self.memory = nn.Parameter(torch.randn(1000, config.d_model))
+    
+    def forward(self, x, **kwargs):
+        # Votre logique
+        return {"output": x, "memory_used": True}
+    
+    def reset_state(self):
+        pass
+
+class MyModel(CognitivePreTrainedModel):
+    config_class = MyModelConfig
+    
+    def __init__(self, config):
+        super().__init__(config)
+        self.embeddings = nn.Embedding(config.vocab_size, config.d_model)
+        self.memory = MyMemoryModule(config)
+        self.lm_head = nn.Linear(config.d_model, config.vocab_size)
+        self.post_init()
+    
+    def forward(self, input_ids, **kwargs):
+        x = self.embeddings(input_ids)
+        mem_out = self.memory(x)
+        logits = self.lm_head(mem_out["output"])
+        return logits
+```
+
+### 3. Chargement Automatique
+
+Le framework gère automatiquement:
+- ✅ Remappage des clés (avec/sans préfixe `model.`)
+- ✅ Validation du checkpoint
+- ✅ Compatibilité HuggingFace
+
+```python
+from cognitive_core import load_cognitive_checkpoint
+
+# Charger un checkpoint personnalisé
+info = load_cognitive_checkpoint(model, "path/to/checkpoint.pt", verbose=True)
+print(f"Clés chargées: {info['validation']['matched_keys']}")
+```
+
+### 4. Configuration Environnement (Kaggle/Colab)
+
+```python
+from cognitive_core import setup_environment, get_device, get_hf_token
+
+# Configure cache HuggingFace dans répertoire accessible
+cache_dir = setup_environment()
+
+# Détection automatique GPU/CPU
+device = get_device()
+
+# Récupérer token HuggingFace
+token = get_hf_token()
+```
+
+## 🔧 Modules Disponibles
+
+| Module | Description |
+|--------|-------------|
+| `CognitiveConfig` | Configuration de base héritant de PretrainedConfig |
+| `CognitiveModule` | Interface abstraite pour modules cognitifs |
+| `MemoryModule` | Interface pour modules de mémoire (store/retrieve) |
+| `TemporalModule` | Interface pour modules temporels (predict) |
+| `WorldModelModule` | Interface pour modèles du monde (update/imagine) |
+| `CognitivePreTrainedModel` | Modèle HuggingFace avec remappage auto |
+
+## 🎯 Cas d'Usage
+
+### Vision Cognitive
+```python
+class CognitiveViTConfig(CognitiveConfig):
+    model_type = "cognitive_vit"
+    # ... config vision
+```
+
+### World Model
+```python
+class CognitiveWorldConfig(CognitiveConfig):
+    model_type = "cognitive_world"
+    # ... config world model
+```
+
+### Multimodal
+```python
+class CognitiveMultimodalConfig(CognitiveConfig):
+    model_type = "cognitive_multimodal"
+    vision_enabled = True
+    audio_enabled = True
+```
+
+## 📊 Garanties du Standard
+
+- ✅ **Intégrité des poids** - Aucun poids réinitialisé silencieusement
+- ✅ **Compatibilité HuggingFace** - AutoModel fonctionne nativement
+- ✅ **Portabilité** - Kaggle, Colab, Local sans modification
+- ✅ **Extensibilité** - Ajouter vos modules facilement
+
+## 📄 Licence
+
+**PROPRIETARY - ALL RIGHTS RESERVED**
+Copyright © 2026 Mike Amega (Logo) - Ame Web Studio

__init__.py

@@ -0,0 +1,86 @@
+"""
+COGNITIVE-CORE Framework
+========================
+
+Universal template for Ame Web Studio's cognitive AI architectures.
+Provides standardized loading, checkpoint management, and utilities
+for vision, language, world model, and multimodal cognitive systems.
+
+Copyright © 2026 Mike Amega (Logo) - Ame Web Studio
+License: Proprietary - All Rights Reserved
+"""
+
+from .cognitive_base import (
+    CognitiveConfig,
+    CognitiveModule,
+    MemoryModule,
+    TemporalModule,
+    WorldModelModule,
+    CognitivePreTrainedModel,
+    register_cognitive_model,
+)
+
+from .cognitive_checkpoint import (
+    remap_checkpoint_keys,
+    validate_checkpoint,
+    save_cognitive_checkpoint,
+    load_cognitive_checkpoint,
+)
+
+from .cognitive_utils import (
+    setup_environment,
+    get_device,
+    get_optimal_dtype,
+    get_memory_info,
+    clear_memory,
+    estimate_model_memory,
+    print_model_info,
+    print_training_progress,
+    get_hf_token,
+)
+
+from .cognitive_training import (
+    CognitiveTrainingConfig,
+    CognitiveTrainer,
+    prepare_dataset,
+    create_instruction_dataset,
+    quick_train,
+    CognitiveStateCallback,
+)
+
+__version__ = "1.0.0"
+__author__ = "Mike Amega"
+__license__ = "Proprietary"
+
+__all__ = [
+    # Base classes
+    "CognitiveConfig",
+    "CognitiveModule",
+    "MemoryModule",
+    "TemporalModule",
+    "WorldModelModule",
+    "CognitivePreTrainedModel",
+    "register_cognitive_model",
+    # Checkpoint
+    "remap_checkpoint_keys",
+    "validate_checkpoint",
+    "save_cognitive_checkpoint",
+    "load_cognitive_checkpoint",
+    # Utils
+    "setup_environment",
+    "get_device",
+    "get_optimal_dtype",
+    "get_memory_info",
+    "clear_memory",
+    "estimate_model_memory",
+    "print_model_info",
+    "print_training_progress",
+    "get_hf_token",
+    # Training
+    "CognitiveTrainingConfig",
+    "CognitiveTrainer",
+    "prepare_dataset",
+    "create_instruction_dataset",
+    "quick_train",
+    "CognitiveStateCallback",
+]

cognitive_base.py

@@ -0,0 +1,272 @@
+"""
+COGNITIVE-CORE: Base Classes for Cognitive Architectures
+=========================================================
+
+This module provides the foundational classes for building cognitive AI models
+that follow the Ame Web Studio standard. All cognitive models (vision, language,
+world model, multimodal) should inherit from these base classes.
+
+Copyright © 2026 Mike Amega (Logo) - Ame Web Studio
+License: Proprietary - All Rights Reserved
+"""
+
+import torch
+import torch.nn as nn
+from typing import Dict, List, Optional, Any, Tuple
+from abc import ABC, abstractmethod
+
+from transformers import PreTrainedModel, PretrainedConfig
+
+
+# ==============================================================================
+# CONFIGURATION DE BASE
+# ==============================================================================
+
+
+class CognitiveConfig(PretrainedConfig):
+    """
+    Configuration de base pour tous les modèles cognitifs.
+
+    Tous les modèles cognitifs (vision, language, world, multimodal) doivent
+    hériter de cette configuration pour garantir la compatibilité.
+    """
+
+    model_type = "cognitive"
+
+    def __init__(
+        self,
+        # Dimensions de base
+        d_model: int = 512,
+        d_ff: int = 2048,
+        n_layers: int = 12,
+        n_heads: int = 8,
+        dropout: float = 0.1,
+        # Modules cognitifs (peuvent être activés/désactivés)
+        use_memory: bool = True,
+        use_temporal: bool = True,
+        use_synaptic: bool = True,
+        use_dream: bool = True,
+        use_world_model: bool = True,
+        use_neurogenesis: bool = True,
+        # Mémoire
+        memory_size: int = 8192,
+        short_term_dim: int = 512,
+        long_term_dim: int = 256,
+        # États internes
+        internal_state_dim: int = 128,
+        latent_state_dim: int = 768,
+        # Meta
+        version: str = "1.0",
+        author: str = "Mike Amega",
+        license: str = "Proprietary",
+        **kwargs,
+    ):
+        super().__init__(**kwargs)
+
+        # Dimensions
+        self.d_model = d_model
+        self.hidden_size = d_model  # Alias HuggingFace
+        self.d_ff = d_ff
+        self.n_layers = n_layers
+        self.n_heads = n_heads
+        self.dropout = dropout
+
+        # Modules cognitifs
+        self.use_memory = use_memory
+        self.use_temporal = use_temporal
+        self.use_synaptic = use_synaptic
+        self.use_dream = use_dream
+        self.use_world_model = use_world_model
+        self.use_neurogenesis = use_neurogenesis
+
+        # Mémoire
+        self.memory_size = memory_size
+        self.short_term_dim = short_term_dim
+        self.long_term_dim = long_term_dim
+
+        # États
+        self.internal_state_dim = internal_state_dim
+        self.latent_state_dim = latent_state_dim
+
+        # Meta
+        self.version = version
+        self.author = author
+        self.license = license
+
+    @property
+    def head_dim(self) -> int:
+        return self.d_model // self.n_heads
+
+
+# ==============================================================================
+# MODULES COGNITIFS ABSTRAITS
+# ==============================================================================
+
+
+class CognitiveModule(nn.Module, ABC):
+    """
+    Classe de base abstraite pour tous les modules cognitifs.
+
+    Chaque module cognitif doit implémenter:
+    - forward(): traitement principal
+    - reset_state(): réinitialisation des états internes
+    - get_state(): récupérer l'état courant
+    """
+
+    def __init__(self, config: CognitiveConfig):
+        super().__init__()
+        self.config = config
+
+    @abstractmethod
+    def forward(self, x: torch.Tensor, **kwargs) -> Dict[str, Any]:
+        """Traitement principal du module."""
+        pass
+
+    @abstractmethod
+    def reset_state(self):
+        """Réinitialiser les états internes du module."""
+        pass
+
+    def get_state(self) -> Dict[str, torch.Tensor]:
+        """Récupérer l'état courant (pour sauvegarde/debug)."""
+        return {}
+
+
+class MemoryModule(CognitiveModule):
+    """Interface pour les modules de mémoire."""
+
+    @abstractmethod
+    def store(self, key: torch.Tensor, value: torch.Tensor):
+        """Stocker une information en mémoire."""
+        pass
+
+    @abstractmethod
+    def retrieve(self, query: torch.Tensor, k: int = 1) -> torch.Tensor:
+        """Récupérer les k informations les plus pertinentes."""
+        pass
+
+
+class TemporalModule(CognitiveModule):
+    """Interface pour les modules temporels/prédictifs."""
+
+    @abstractmethod
+    def predict(self, state: torch.Tensor, horizon: int = 1) -> torch.Tensor:
+        """Prédire l'état futur à l'horizon donné."""
+        pass
+
+
+class WorldModelModule(CognitiveModule):
+    """Interface pour les modèles du monde."""
+
+    @abstractmethod
+    def update(self, observation: torch.Tensor) -> Dict[str, float]:
+        """Mettre à jour le modèle du monde avec une observation."""
+        pass
+
+    @abstractmethod
+    def imagine(self, action: torch.Tensor) -> torch.Tensor:
+        """Imaginer l'effet d'une action."""
+        pass
+
+
+# ==============================================================================
+# MODÈLE COGNITIF DE BASE
+# ==============================================================================
+
+
+class CognitivePreTrainedModel(PreTrainedModel):
+    """
+    Classe de base pour tous les modèles cognitifs HuggingFace-compatibles.
+
+    Fournit:
+    - Remappage automatique des clés de checkpoint
+    - Gestion des modules cognitifs optionnels
+    - Méthodes d'initialisation standardisées
+    """
+
+    config_class = CognitiveConfig
+    base_model_prefix = "cognitive"
+    supports_gradient_checkpointing = False  # Incompatible avec architecture cognitive
+
+    # Clés à ignorer lors du chargement (buffers dynamiques)
+    _keys_to_ignore_on_load_missing = [
+        r".*\.state$",
+        r".*\.history$",
+        r".*\.buffer$",
+        r".*rope\..*_cache",
+        r".*rope\.inv_freq",
+    ]
+
+    def _init_weights(self, module):
+        """Initialisation standard des poids."""
+        if isinstance(module, nn.Linear):
+            torch.nn.init.normal_(module.weight, mean=0.0, std=0.02)
+            if module.bias is not None:
+                torch.nn.init.zeros_(module.bias)
+        elif isinstance(module, nn.Embedding):
+            torch.nn.init.normal_(module.weight, mean=0.0, std=0.02)
+
+    def _load_from_state_dict(
+        self,
+        state_dict,
+        prefix,
+        local_metadata,
+        strict,
+        missing_keys,
+        unexpected_keys,
+        error_msgs,
+    ):
+        """
+        Remappage automatique des clés de checkpoint.
+
+        Gère les différences de préfixes entre formats de checkpoint
+        (ex: avec/sans 'model.' prefix).
+        """
+        from .cognitive_checkpoint import remap_checkpoint_keys
+
+        # Remapper les clés si nécessaire
+        remapped = remap_checkpoint_keys(state_dict, self.state_dict())
+
+        # Appeler l'implémentation parent
+        super()._load_from_state_dict(
+            remapped,
+            prefix,
+            local_metadata,
+            strict,
+            missing_keys,
+            unexpected_keys,
+            error_msgs,
+        )
+
+    def get_cognitive_state(self) -> Dict[str, Any]:
+        """Récupérer l'état de tous les modules cognitifs."""
+        state = {}
+        for name, module in self.named_modules():
+            if isinstance(module, CognitiveModule):
+                state[name] = module.get_state()
+        return state
+
+    def reset_cognitive_state(self):
+        """Réinitialiser l'état de tous les modules cognitifs."""
+        for module in self.modules():
+            if isinstance(module, CognitiveModule):
+                module.reset_state()
+
+
+# ==============================================================================
+# UTILITAIRES D'ENREGISTREMENT AUTO
+# ==============================================================================
+
+
+def register_cognitive_model(config_class, model_class):
+    """
+    Enregistrer un modèle cognitif pour utilisation avec AutoModel.
+
+    Usage:
+        register_cognitive_model(MyConfig, MyModel)
+        # Puis: AutoModelForCausalLM.from_pretrained(..., trust_remote_code=True)
+    """
+    from transformers import AutoConfig, AutoModel
+
+    AutoConfig.register(config_class.model_type, config_class)
+    AutoModel.register(config_class, model_class)

cognitive_checkpoint.py

@@ -0,0 +1,298 @@
+"""
+COGNITIVE-CORE: Checkpoint Loading & Key Remapping
+===================================================
+
+This module provides robust checkpoint loading with automatic key remapping
+to handle different checkpoint formats (with/without 'model.' prefix, etc.)
+
+Copyright © 2026 Mike Amega (Logo) - Ame Web Studio
+License: Proprietary - All Rights Reserved
+"""
+
+import re
+from typing import Dict, Set, Optional
+import torch
+
+
+def remap_checkpoint_keys(
+    checkpoint_state_dict: Dict[str, torch.Tensor],
+    model_state_dict: Dict[str, torch.Tensor],
+    verbose: bool = False,
+) -> Dict[str, torch.Tensor]:
+    """
+    Remappe automatiquement les clés du checkpoint pour correspondre au modèle.
+
+    Gère les scénarios suivants:
+    1. Checkpoint a préfixe 'model.' mais modèle n'en a pas → retirer préfixe
+    2. Checkpoint n'a pas préfixe 'model.' mais modèle en a → ajouter préfixe
+    3. Autres préfixes personnalisés
+
+    Args:
+        checkpoint_state_dict: État du checkpoint chargé
+        model_state_dict: État du modèle cible
+        verbose: Afficher les détails du remappage
+
+    Returns:
+        Dict remappé compatible avec le modèle
+    """
+    model_keys = set(model_state_dict.keys())
+    checkpoint_keys = set(checkpoint_state_dict.keys())
+
+    # Vérifier si le checkpoint correspond déjà
+    matching = model_keys & checkpoint_keys
+    if len(matching) >= len(checkpoint_keys) * 0.9:
+        if verbose:
+            print(
+                f"✅ Checkpoint compatible: {len(matching)}/{len(checkpoint_keys)} clés correspondent"
+            )
+        return checkpoint_state_dict
+
+    # Tester différentes stratégies de remappage
+    strategies = [
+        ("remove_model_prefix", _remove_prefix, "model."),
+        ("add_model_prefix", _add_prefix, "model."),
+        ("remove_backbone_prefix", _remove_prefix, "backbone."),
+        ("remove_encoder_prefix", _remove_prefix, "encoder."),
+    ]
+
+    best_strategy = None
+    best_match_count = len(matching)
+    best_result = checkpoint_state_dict
+
+    for name, func, prefix in strategies:
+        remapped = func(checkpoint_state_dict, prefix)
+        match_count = len(model_keys & set(remapped.keys()))
+
+        if match_count > best_match_count:
+            best_match_count = match_count
+            best_strategy = name
+            best_result = remapped
+
+    if verbose and best_strategy:
+        print(f"🔄 Stratégie appliquée: {best_strategy}")
+        print(f"   Clés correspondantes: {best_match_count}/{len(checkpoint_keys)}")
+
+    # Fallback: mapper intelligemment clé par clé
+    if best_match_count < len(checkpoint_keys) * 0.5:
+        best_result = _smart_key_mapping(checkpoint_state_dict, model_keys)
+        if verbose:
+            final_match = len(model_keys & set(best_result.keys()))
+            print(
+                f"🧠 Remappage intelligent: {final_match}/{len(checkpoint_keys)} clés"
+            )
+
+    return best_result
+
+
+def _remove_prefix(state_dict: Dict, prefix: str) -> Dict:
+    """Retirer un préfixe de toutes les clés."""
+    return {
+        (k[len(prefix) :] if k.startswith(prefix) else k): v
+        for k, v in state_dict.items()
+    }
+
+
+def _add_prefix(state_dict: Dict, prefix: str) -> Dict:
+    """Ajouter un préfixe à toutes les clés."""
+    return {f"{prefix}{k}": v for k, v in state_dict.items()}
+
+
+def _smart_key_mapping(
+    checkpoint_dict: Dict[str, torch.Tensor], model_keys: Set[str]
+) -> Dict[str, torch.Tensor]:
+    """
+    Mapping intelligent clé par clé basé sur les suffixes et patterns.
+    """
+    result = {}
+    model_keys_list = list(model_keys)
+
+    for ckpt_key, value in checkpoint_dict.items():
+        # Correspondance exacte
+        if ckpt_key in model_keys:
+            result[ckpt_key] = value
+            continue
+
+        # Essayer avec préfixe 'model.'
+        with_prefix = f"model.{ckpt_key}"
+        if with_prefix in model_keys:
+            result[with_prefix] = value
+            continue
+
+        # Essayer sans préfixe 'model.'
+        if ckpt_key.startswith("model."):
+            without_prefix = ckpt_key[6:]
+            if without_prefix in model_keys:
+                result[without_prefix] = value
+                continue
+
+        # Chercher par suffixe (ex: ".weight", ".bias")
+        ckpt_suffix = ckpt_key.split(".")[-1]
+        ckpt_base = ".".join(ckpt_key.split(".")[:-1])
+
+        for model_key in model_keys_list:
+            if model_key.endswith(ckpt_suffix):
+                model_base = ".".join(model_key.split(".")[:-1])
+                # Vérifier similarité structurelle
+                if _keys_similar(ckpt_base, model_base):
+                    result[model_key] = value
+                    break
+        else:
+            # Garder la clé originale (sera ignorée si pas dans modèle)
+            result[ckpt_key] = value
+
+    return result
+
+
+def _keys_similar(key1: str, key2: str) -> bool:
+    """Vérifier si deux clés sont structurellement similaires."""
+    parts1 = key1.split(".")
+    parts2 = key2.split(".")
+
+    # Même nombre de parties
+    if len(parts1) != len(parts2):
+        return False
+
+    # Comparer chaque partie (ignorer les préfixes comme 'model')
+    matches = sum(
+        1 for p1, p2 in zip(parts1, parts2) if p1 == p2 or p1.isdigit() and p2.isdigit()
+    )
+    return matches >= len(parts1) * 0.7
+
+
+def validate_checkpoint(
+    checkpoint_state_dict: Dict[str, torch.Tensor],
+    model_state_dict: Dict[str, torch.Tensor],
+    strict: bool = False,
+) -> Dict[str, any]:
+    """
+    Valider qu'un checkpoint est compatible avec un modèle.
+
+    Returns:
+        Dict avec:
+        - valid: bool
+        - missing_keys: clés manquantes dans checkpoint
+        - unexpected_keys: clés inattendues dans checkpoint
+        - size_mismatches: clés avec tailles incompatibles
+    """
+    model_keys = set(model_state_dict.keys())
+    ckpt_keys = set(checkpoint_state_dict.keys())
+
+    missing = model_keys - ckpt_keys
+    unexpected = ckpt_keys - model_keys
+
+    # Vérifier les tailles
+    size_mismatches = []
+    for key in model_keys & ckpt_keys:
+        model_shape = model_state_dict[key].shape
+        ckpt_shape = checkpoint_state_dict[key].shape
+        if model_shape != ckpt_shape:
+            size_mismatches.append(
+                {"key": key, "model_shape": model_shape, "checkpoint_shape": ckpt_shape}
+            )
+
+    valid = len(missing) == 0 and len(size_mismatches) == 0
+    if not strict:
+        valid = len(size_mismatches) == 0 and len(missing) < len(model_keys) * 0.1
+
+    return {
+        "valid": valid,
+        "missing_keys": list(missing),
+        "unexpected_keys": list(unexpected),
+        "size_mismatches": size_mismatches,
+        "matched_keys": len(model_keys & ckpt_keys),
+        "total_model_keys": len(model_keys),
+    }
+
+
+def save_cognitive_checkpoint(
+    model,
+    path: str,
+    include_optimizer: bool = False,
+    optimizer=None,
+    extra_state: Optional[Dict] = None,
+):
+    """
+    Sauvegarder un checkpoint de modèle cognitif.
+
+    Args:
+        model: Le modèle à sauvegarder
+        path: Chemin de sauvegarde
+        include_optimizer: Inclure l'état de l'optimiseur
+        optimizer: L'optimiseur (si include_optimizer=True)
+        extra_state: État additionnel à sauvegarder
+    """
+    checkpoint = {
+        "model_state_dict": model.state_dict(),
+        "config": model.config.to_dict() if hasattr(model, "config") else {},
+    }
+
+    if include_optimizer and optimizer is not None:
+        checkpoint["optimizer_state_dict"] = optimizer.state_dict()
+
+    # Sauvegarder l'état cognitif si disponible
+    if hasattr(model, "get_cognitive_state"):
+        checkpoint["cognitive_state"] = model.get_cognitive_state()
+
+    if extra_state:
+        checkpoint["extra_state"] = extra_state
+
+    torch.save(checkpoint, path)
+    print(f"✅ Checkpoint sauvegardé: {path}")
+
+
+def load_cognitive_checkpoint(
+    model, path: str, strict: bool = False, verbose: bool = True
+) -> Dict:
+    """
+    Charger un checkpoint dans un modèle cognitif avec remappage automatique.
+
+    Args:
+        model: Le modèle cible
+        path: Chemin du checkpoint
+        strict: Mode strict (erreur si clés manquantes)
+        verbose: Afficher les détails
+
+    Returns:
+        Dict avec informations de chargement
+    """
+    checkpoint = torch.load(path, map_location="cpu")
+
+    # Extraire le state_dict
+    if "model_state_dict" in checkpoint:
+        state_dict = checkpoint["model_state_dict"]
+    elif "state_dict" in checkpoint:
+        state_dict = checkpoint["state_dict"]
+    else:
+        state_dict = checkpoint
+
+    # Remapper les clés
+    remapped = remap_checkpoint_keys(state_dict, model.state_dict(), verbose=verbose)
+
+    # Valider
+    validation = validate_checkpoint(remapped, model.state_dict(), strict=strict)
+
+    if verbose:
+        print(
+            f"📊 Clés chargées: {validation['matched_keys']}/{validation['total_model_keys']}"
+        )
+        if validation["missing_keys"]:
+            print(f"⚠️ Clés manquantes: {len(validation['missing_keys'])}")
+        if validation["size_mismatches"]:
+            print(f"⚠️ Tailles incompatibles: {len(validation['size_mismatches'])}")
+
+    # Charger avec ignore_mismatched_sizes pour robustesse
+    model.load_state_dict(remapped, strict=False)
+
+    # Restaurer l'état cognitif si disponible
+    if "cognitive_state" in checkpoint and hasattr(model, "reset_cognitive_state"):
+        # L'état cognitif est généralement réinitialisé, pas restauré
+        pass
+
+    if verbose:
+        print("✅ Checkpoint chargé avec succès")
+
+    return {
+        "validation": validation,
+        "config": checkpoint.get("config", {}),
+        "extra_state": checkpoint.get("extra_state", {}),
+    }

cognitive_training.py

@@ -0,0 +1,372 @@
+"""
+COGNITIVE-CORE: Training Utilities
+====================================
+
+Standardized training utilities for cognitive models, including:
+- Training configurations
+- Trainer wrappers
+- Dataset preparation helpers
+- Progress tracking
+
+Copyright © 2026 Mike Amega (Logo) - Ame Web Studio
+License: Proprietary - All Rights Reserved
+"""
+
+import os
+import torch
+import torch.nn as nn
+from typing import Dict, List, Optional, Any, Callable
+from dataclasses import dataclass, field
+
+
+# ==============================================================================
+# CONFIGURATION D'ENTRAÎNEMENT
+# ==============================================================================
+
+
+@dataclass
+class CognitiveTrainingConfig:
+    """
+    Configuration standard pour l'entraînement de modèles cognitifs.
+    """
+
+    # Output
+    output_dir: str = "./cognitive-output"
+
+    # Training params
+    num_epochs: int = 1
+    batch_size: int = 1
+    gradient_accumulation_steps: int = 8
+    learning_rate: float = 1e-5
+    warmup_steps: int = 100
+    weight_decay: float = 0.01
+    max_grad_norm: float = 1.0
+
+    # Sequence
+    max_seq_len: int = 2048  # IMPORTANT: >= 2048 pour modules cognitifs
+
+    # Precision
+    use_fp16: bool = True
+    use_bf16: bool = False
+
+    # Logging
+    logging_steps: int = 10
+    save_steps: int = 200
+    save_total_limit: int = 2
+
+    # Hub
+    push_to_hub: bool = False
+    hub_model_id: Optional[str] = None
+    hub_private: bool = True
+
+    # Device
+    device: Optional[str] = None  # auto-detected if None
+
+    def __post_init__(self):
+        os.makedirs(self.output_dir, exist_ok=True)
+
+
+# ==============================================================================
+# PRÉPARATION DES DONNÉES
+# ==============================================================================
+
+
+def prepare_dataset(
+    dataset,
+    tokenizer,
+    text_column: str = "text",
+    max_length: int = 2048,
+    num_proc: int = 4,
+):
+    """
+    Prépare un dataset pour l'entraînement d'un modèle cognitif.
+
+    Args:
+        dataset: Dataset HuggingFace
+        tokenizer: Tokenizer du modèle
+        text_column: Nom de la colonne contenant le texte
+        max_length: Longueur maximale des séquences
+        num_proc: Nombre de processus pour le mapping
+
+    Returns:
+        Dataset tokenisé prêt pour l'entraînement
+    """
+
+    def tokenize_function(examples):
+        texts = examples[text_column]
+        if not isinstance(texts, list):
+            texts = [texts]
+
+        return tokenizer(
+            texts,
+            truncation=True,
+            padding="max_length",
+            max_length=max_length,
+            return_tensors=None,
+        )
+
+    # Supprimer les colonnes originales
+    columns_to_remove = dataset.column_names
+    if isinstance(columns_to_remove, dict):
+        columns_to_remove = columns_to_remove.get("train", [])
+
+    tokenized = dataset.map(
+        tokenize_function,
+        batched=True,
+        num_proc=num_proc,
+        remove_columns=columns_to_remove,
+    )
+
+    tokenized.set_format(type="torch")
+    return tokenized
+
+
+def create_instruction_dataset(
+    examples: List[Dict[str, str]],
+    tokenizer,
+    max_length: int = 2048,
+    instruction_template: str = "### Instruction:\n{instruction}\n\n### Response:\n{response}",
+):
+    """
+    Crée un dataset d'instructions à partir d'exemples.
+
+    Args:
+        examples: Liste de dicts avec 'instruction' et 'response'
+        tokenizer: Tokenizer du modèle
+        max_length: Longueur maximale
+        instruction_template: Template de formatage
+
+    Returns:
+        Dataset tokenisé
+    """
+    from datasets import Dataset
+
+    formatted = []
+    for ex in examples:
+        text = instruction_template.format(
+            instruction=ex.get("instruction", ""), response=ex.get("response", "")
+        )
+        formatted.append({"text": text})
+
+    dataset = Dataset.from_list(formatted)
+    return prepare_dataset(dataset, tokenizer, "text", max_length)
+
+
+# ==============================================================================
+# TRAINER WRAPPER
+# ==============================================================================
+
+
+class CognitiveTrainer:
+    """
+    Trainer simplifié pour modèles cognitifs.
+
+    Wrapper autour du Trainer HuggingFace avec configuration optimisée
+    pour les architectures cognitives.
+    """
+
+    def __init__(
+        self,
+        model,
+        tokenizer,
+        train_dataset,
+        config: CognitiveTrainingConfig,
+        eval_dataset=None,
+        callbacks: Optional[List] = None,
+    ):
+        self.model = model
+        self.tokenizer = tokenizer
+        self.train_dataset = train_dataset
+        self.eval_dataset = eval_dataset
+        self.config = config
+        self.callbacks = callbacks or []
+
+        # Configurer tokenizer
+        if tokenizer.pad_token is None:
+            tokenizer.pad_token = tokenizer.eos_token
+
+        self._setup_trainer()
+
+    def _setup_trainer(self):
+        """Configure le Trainer HuggingFace."""
+        from transformers import (
+            Trainer,
+            TrainingArguments,
+            DataCollatorForLanguageModeling,
+        )
+
+        # Déterminer device
+        if self.config.device:
+            device = self.config.device
+        elif torch.cuda.is_available():
+            device = "cuda"
+        else:
+            device = "cpu"
+
+        # Arguments d'entraînement
+        training_args = TrainingArguments(
+            output_dir=self.config.output_dir,
+            overwrite_output_dir=True,
+            num_train_epochs=self.config.num_epochs,
+            per_device_train_batch_size=self.config.batch_size,
+            gradient_accumulation_steps=self.config.gradient_accumulation_steps,
+            learning_rate=self.config.learning_rate,
+            warmup_steps=self.config.warmup_steps,
+            weight_decay=self.config.weight_decay,
+            max_grad_norm=self.config.max_grad_norm,
+            logging_steps=self.config.logging_steps,
+            save_steps=self.config.save_steps,
+            save_total_limit=self.config.save_total_limit,
+            fp16=self.config.use_fp16 and device == "cuda",
+            bf16=self.config.use_bf16 and device == "cuda",
+            push_to_hub=self.config.push_to_hub,
+            hub_model_id=self.config.hub_model_id,
+            hub_private_repo=self.config.hub_private,
+            report_to="none",
+            remove_unused_columns=False,
+            dataloader_num_workers=0,  # Évite problèmes sur certains environnements
+        )
+
+        # Data collator
+        data_collator = DataCollatorForLanguageModeling(
+            tokenizer=self.tokenizer, mlm=False
+        )
+
+        # Créer le trainer
+        self.trainer = Trainer(
+            model=self.model,
+            args=training_args,
+            train_dataset=self.train_dataset,
+            eval_dataset=self.eval_dataset,
+            data_collator=data_collator,
+            tokenizer=self.tokenizer,
+            callbacks=self.callbacks,
+        )
+
+    def train(self, resume_from_checkpoint: Optional[str] = None):
+        """
+        Lance l'entraînement.
+
+        Args:
+            resume_from_checkpoint: Chemin pour reprendre l'entraînement
+
+        Returns:
+            Résultats de l'entraînement
+        """
+        print("\n🚀 ENTRAÎNEMENT COGNITIF")
+        print("=" * 60)
+
+        try:
+            result = self.trainer.train(resume_from_checkpoint=resume_from_checkpoint)
+            print("=" * 60)
+            print("✅ Entraînement terminé!")
+            return result
+        except Exception as e:
+            print(f"❌ Erreur: {e}")
+            import traceback
+
+            traceback.print_exc()
+            return None
+
+    def save(self, output_dir: Optional[str] = None):
+        """Sauvegarde le modèle et tokenizer."""
+        save_dir = output_dir or self.config.output_dir
+        self.trainer.save_model(save_dir)
+        self.tokenizer.save_pretrained(save_dir)
+        print(f"💾 Modèle sauvegardé: {save_dir}")
+
+    def push_to_hub(self, repo_id: Optional[str] = None):
+        """Push le modèle vers HuggingFace Hub."""
+        if repo_id:
+            self.config.hub_model_id = repo_id
+
+        try:
+            self.trainer.push_to_hub()
+            print(f"📤 Modèle pushé: {self.config.hub_model_id}")
+        except Exception as e:
+            print(f"⚠️ Erreur push: {e}")
+
+
+# ==============================================================================
+# CALLBACKS PERSONNALISÉS
+# ==============================================================================
+
+
+class CognitiveStateCallback:
+    """
+    Callback pour monitorer l'état des modules cognitifs pendant l'entraînement.
+    """
+
+    def __init__(self, log_every: int = 100):
+        self.log_every = log_every
+        self.step = 0
+
+    def on_step_end(self, args, state, control, model=None, **kwargs):
+        self.step += 1
+
+        if self.step % self.log_every == 0 and model is not None:
+            if hasattr(model, "get_cognitive_state"):
+                cog_state = model.get_cognitive_state()
+                print(f"\n📊 État cognitif (step {self.step}):")
+                for name, state_dict in cog_state.items():
+                    if state_dict:
+                        print(f"   {name}: {len(state_dict)} buffers")
+
+
+# ==============================================================================
+# QUICK TRAIN FUNCTION
+# ==============================================================================
+
+
+def quick_train(
+    model,
+    tokenizer,
+    texts: List[str],
+    output_dir: str = "./quick-train-output",
+    num_epochs: int = 1,
+    max_seq_len: int = 2048,
+    learning_rate: float = 1e-5,
+    push_to_hub: bool = False,
+    hub_model_id: Optional[str] = None,
+):
+    """
+    Entraînement rapide avec configuration minimale.
+
+    Args:
+        model: Modèle à entraîner
+        tokenizer: Tokenizer
+        texts: Liste de textes d'entraînement
+        output_dir: Répertoire de sortie
+        num_epochs: Nombre d'époques
+        max_seq_len: Longueur max des séquences
+        learning_rate: Taux d'apprentissage
+        push_to_hub: Pusher vers HuggingFace
+        hub_model_id: ID du repo HuggingFace
+
+    Returns:
+        Résultats de l'entraînement
+    """
+    from datasets import Dataset
+
+    # Créer dataset
+    dataset = Dataset.from_dict({"text": texts})
+    tokenized = prepare_dataset(dataset, tokenizer, "text", max_seq_len)
+
+    # Config
+    config = CognitiveTrainingConfig(
+        output_dir=output_dir,
+        num_epochs=num_epochs,
+        max_seq_len=max_seq_len,
+        learning_rate=learning_rate,
+        push_to_hub=push_to_hub,
+        hub_model_id=hub_model_id,
+    )
+
+    # Trainer
+    trainer = CognitiveTrainer(model, tokenizer, tokenized, config)
+    result = trainer.train()
+
+    if result:
+        trainer.save()
+
+    return result

cognitive_utils.py

@@ -0,0 +1,282 @@
+"""
+COGNITIVE-CORE: Utility Functions
+==================================
+
+Common utilities for cognitive model development, including:
+- Environment setup for Kaggle/Colab
+- Device detection
+- Memory optimization helpers
+- Logging utilities
+
+Copyright © 2026 Mike Amega (Logo) - Ame Web Studio
+License: Proprietary - All Rights Reserved
+"""
+
+import os
+import sys
+import torch
+import warnings
+from typing import Optional, Dict, Any
+
+
+# ==============================================================================
+# ENVIRONNEMENT & CACHE
+# ==============================================================================
+
+
+def setup_environment(cache_dir: Optional[str] = None) -> str:
+    """
+    Configure l'environnement pour Kaggle/Colab/Local.
+
+    Résout les problèmes de:
+    - Read-only file system sur Kaggle
+    - Chemins de cache HuggingFace
+
+    Args:
+        cache_dir: Répertoire cache personnalisé (optionnel)
+
+    Returns:
+        Chemin du répertoire cache configuré
+    """
+    if cache_dir is None:
+        # Détecter l'environnement
+        if os.path.exists("/kaggle"):
+            cache_dir = "/kaggle/working/.cache"
+        elif os.path.exists("/content"):  # Colab
+            cache_dir = "/content/.cache"
+        else:
+            cache_dir = os.path.expanduser("~/.cache/cognitive")
+
+    # Créer le répertoire
+    os.makedirs(cache_dir, exist_ok=True)
+    os.makedirs(os.path.join(cache_dir, "datasets"), exist_ok=True)
+
+    # Configurer les variables d'environnement
+    os.environ["HF_HOME"] = cache_dir
+    os.environ["TRANSFORMERS_CACHE"] = cache_dir
+    os.environ["HF_DATASETS_CACHE"] = os.path.join(cache_dir, "datasets")
+
+    # Désactiver les warnings non critiques
+    warnings.filterwarnings("ignore", category=FutureWarning)
+    warnings.filterwarnings("ignore", category=UserWarning, module="transformers")
+
+    return cache_dir
+
+
+def get_device(prefer_gpu: bool = True) -> torch.device:
+    """
+    Détecte et retourne le meilleur device disponible.
+
+    Args:
+        prefer_gpu: Préférer GPU si disponible
+
+    Returns:
+        torch.device configuré
+    """
+    if prefer_gpu and torch.cuda.is_available():
+        device = torch.device("cuda")
+        gpu_name = torch.cuda.get_device_name(0)
+        gpu_mem = torch.cuda.get_device_properties(0).total_memory / 1e9
+        print(f"🔧 GPU: {gpu_name} ({gpu_mem:.1f} GB)")
+    elif (
+        prefer_gpu
+        and hasattr(torch.backends, "mps")
+        and torch.backends.mps.is_available()
+    ):
+        device = torch.device("mps")
+        print("🔧 Apple MPS")
+    else:
+        device = torch.device("cpu")
+        print("🔧 CPU")
+
+    return device
+
+
+def get_optimal_dtype(device: torch.device) -> torch.dtype:
+    """
+    Retourne le dtype optimal pour le device.
+
+    Args:
+        device: Le device cible
+
+    Returns:
+        torch.dtype optimal (float16 pour GPU, float32 pour CPU)
+    """
+    if device.type == "cuda":
+        # Vérifier support BF16
+        if torch.cuda.is_bf16_supported():
+            return torch.bfloat16
+        return torch.float16
+    return torch.float32
+
+
+# ==============================================================================
+# MÉMOIRE & OPTIMISATION
+# ==============================================================================
+
+
+def get_memory_info() -> Dict[str, float]:
+    """
+    Retourne les informations mémoire (GPU si disponible).
+
+    Returns:
+        Dict avec allocated, reserved, free en GB
+    """
+    if torch.cuda.is_available():
+        allocated = torch.cuda.memory_allocated() / 1e9
+        reserved = torch.cuda.memory_reserved() / 1e9
+        total = torch.cuda.get_device_properties(0).total_memory / 1e9
+        return {
+            "allocated_gb": allocated,
+            "reserved_gb": reserved,
+            "free_gb": total - allocated,
+            "total_gb": total,
+        }
+    return {"allocated_gb": 0, "reserved_gb": 0, "free_gb": 0, "total_gb": 0}
+
+
+def clear_memory():
+    """Libère la mémoire GPU si possible."""
+    if torch.cuda.is_available():
+        torch.cuda.empty_cache()
+        torch.cuda.synchronize()
+
+
+def estimate_model_memory(model, dtype: torch.dtype = torch.float32) -> float:
+    """
+    Estime la mémoire nécessaire pour un modèle.
+
+    Args:
+        model: Le modèle PyTorch
+        dtype: Le dtype utilisé
+
+    Returns:
+        Estimation en GB
+    """
+    param_bytes = sum(p.numel() * p.element_size() for p in model.parameters())
+    buffer_bytes = sum(b.numel() * b.element_size() for b in model.buffers())
+
+    # Facteur pour activations (estimation: 2x les paramètres)
+    activation_factor = 2.0
+
+    total_bytes = (param_bytes + buffer_bytes) * activation_factor
+
+    # Ajuster selon dtype
+    if dtype in (torch.float16, torch.bfloat16):
+        total_bytes *= 0.5
+
+    return total_bytes / 1e9
+
+
+# ==============================================================================
+# LOGGING & AFFICHAGE
+# ==============================================================================
+
+
+def print_model_info(model, show_params: bool = True):
+    """
+    Affiche les informations du modèle.
+
+    Args:
+        model: Le modèle à analyser
+        show_params: Afficher le détail des paramètres
+    """
+    total_params = sum(p.numel() for p in model.parameters())
+    trainable_params = sum(p.numel() for p in model.parameters() if p.requires_grad)
+
+    print(f"\n📊 MODÈLE: {model.__class__.__name__}")
+    print(f"   Total paramètres: {total_params:,}")
+    print(f"   Paramètres entraînables: {trainable_params:,}")
+    print(f"   Mémoire estimée: {estimate_model_memory(model):.2f} GB")
+
+    if show_params and hasattr(model, "config"):
+        print(f"\n   Configuration:")
+        for key in ["d_model", "n_layers", "n_heads", "vocab_size"]:
+            if hasattr(model.config, key):
+                print(f"   - {key}: {getattr(model.config, key)}")
+
+
+def print_training_progress(
+    step: int,
+    total_steps: int,
+    loss: float,
+    lr: Optional[float] = None,
+    extras: Optional[Dict[str, float]] = None,
+):
+    """
+    Affiche la progression d'entraînement.
+
+    Args:
+        step: Étape actuelle
+        total_steps: Nombre total d'étapes
+        loss: Valeur de la loss
+        lr: Learning rate actuel
+        extras: Métriques additionnelles
+    """
+    progress = step / total_steps * 100
+    msg = f"[{step:>6}/{total_steps}] ({progress:>5.1f}%) | Loss: {loss:.4f}"
+
+    if lr is not None:
+        msg += f" | LR: {lr:.2e}"
+
+    if extras:
+        for key, val in extras.items():
+            msg += f" | {key}: {val:.4f}"
+
+    print(msg)
+
+
+# ==============================================================================
+# TOKEN HUGGINGFACE
+# ==============================================================================
+
+
+def get_hf_token() -> Optional[str]:
+    """
+    Récupère le token HuggingFace depuis différentes sources.
+
+    Ordre de recherche:
+    1. Variable d'environnement HF_TOKEN
+    2. Secrets Kaggle
+    3. Secrets Colab
+    4. Token local HuggingFace CLI
+
+    Returns:
+        Token ou None si non trouvé
+    """
+    # Env var
+    token = os.environ.get("HF_TOKEN")
+    if token:
+        return token
+
+    # Kaggle
+    try:
+        from kaggle_secrets import UserSecretsClient
+
+        token = UserSecretsClient().get_secret("HF_TOKEN")
+        if token:
+            return token
+    except Exception:
+        pass
+
+    # Colab
+    try:
+        from google.colab import userdata
+
+        token = userdata.get("HF_TOKEN")
+        if token:
+            return token
+    except Exception:
+        pass
+
+    # Local HuggingFace CLI
+    try:
+        from huggingface_hub import HfFolder
+
+        token = HfFolder.get_token()
+        if token:
+            return token
+    except Exception:
+        pass
+
+    return None