README.md

# 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_modules.py     # 🆕 TOUS les modules cognitifs réutilisables
├── cognitive_training.py    # Utilitaires d'entraînement
├── cognitive_utils.py       # Utilitaires (device, mémoire, tokens)
└── README.md               # Cette documentation
```


## 🚀 Installation

### Option 1: Via Pip (Recommandé)

```bash
# Installation standard
pip install cognitive-core

# Avec support Vision
pip install "cognitive-core[vision]"

# Avec support Audio
pip install "cognitive-core[audio]"

# Avec support Entraînement (WandB/Tensorboard)
pip install "cognitive-core[training]"

# Installation Complète
pip install "cognitive-core[all]"
```

### Option 2: Via Git (Dernière version)

```bash
pip install git+https://github.com/Volgat/nexus-standardisation.git
```

### Option 3: Via HuggingFace

```bash
pip install git+https://huggingface.co/amewebstudio/cognitive-core
```

### Option 4: Mode Développement (Local)

```bash
git clone https://github.com/Volgat/nexus-standardisation.git
cd nexus-standardisation
pip install -e .
```

Si vous n'utilisez pas pip, vous pouvez simplement ajouter le chemin :

```python
import sys
sys.path.append("/path/to/standardisation")

from cognitive_core import *
```

## 📦 Modules Disponibles

### Normalisation
| Module | Description |
|--------|-------------|
| `RMSNorm` | Root Mean Square Normalization (plus efficace que LayerNorm) |

### Encodage Positionnel
| Module | Description |
|--------|-------------|
| `RotaryEmbedding` | RoPE avec scaling pour contextes longs |
| `SinusoidalPositionalEncoding` | Encodage sinusoïdal classique |

### Attention
| Module | Description |
|--------|-------------|
| `GroupedQueryAttention` | GQA avec RoPE et KV-Cache |
| `CrossAttention` | Attention croisée pour fusion multimodale |

### Réseaux Feed-Forward
| Module | Description |
|--------|-------------|
| `SwiGLU` | Activation SwiGLU (meilleure que GELU) |
| `MLP` | MLP standard avec GELU |

### Mixture of Experts
| Module | Description |
|--------|-------------|
| `Expert` | Expert unique avec SwiGLU |
| `SparseMoE` | MoE sparse avec routing Top-K |

### Systèmes de Mémoire
| Module | Description |
|--------|-------------|
| `ContrastiveLPOL` | Mémoire LPOL avec 9 domaines de connaissances |
| `MultiScaleMemory` | Mémoire court/long terme avec consolidation |
| `EpisodicMemory` | Mémoire épisodique pour expériences |

### World Model
| Module | Description |
|--------|-------------|
| `WorldBuffer` | Buffer de monde unique avec prédiction |
| `MultiWorldBuffer` | Buffers multi-domaines (physical, social, abstract, temporal) |

### État Interne
| Module | Description |
|--------|-------------|
| `NonVerbalTension` | Tracker de tension basé sur erreur de prédiction |
| `InternalState` | État cognitif interne complet |

### Rêve & Identité
| Module | Description |
|--------|-------------|
| `DreamPhase` | Phase de rêve pour consolidation mémoire |
| `SelfTrace` | Tracking d'identité à travers le temps |

### Neurogenèse
| Module | Description |
|--------|-------------|
| `NeurogenesisLayer` | Couche avec naissance/mort dynamique de neurones |

### EARCP
| Module | Description |
|--------|-------------|
| `EARCPModule` | Ensemble Auto-Regulated Coherence Protocol |

### VAE (Vision/World Model)
| Module | Description |
|--------|-------------|
| `VAEEncoder` | Encodeur VAE convolutionnel |
| `VAEDecoder` | Décodeur VAE convolutionnel |

### Espace Latent Universel
| Module | Description |
|--------|-------------|
| `UniversalLatentSpace` | ULS pour alignement cross-modal (text, vision, audio) |

## 🎯 Exemples d'Utilisation

### Modèle de Langage Cognitif

```python
from cognitive_core import (
    CognitiveConfig, CognitivePreTrainedModel,
    GroupedQueryAttention, SparseMoE, ContrastiveLPOL,
    MultiScaleMemory, RMSNorm
)

class MyLLMConfig(CognitiveConfig):
    model_type = "cognitive_llm"
    vocab_size = 50000

class MyCognitiveLayer(nn.Module):
    def __init__(self, config):
        super().__init__()
        self.attn = GroupedQueryAttention(config.d_model, config.n_heads)
        self.moe = SparseMoE(config.d_model, config.d_ff, num_experts=8)
        self.norm1 = RMSNorm(config.d_model)
        self.norm2 = RMSNorm(config.d_model)
    
    def forward(self, x):
        x = x + self.attn(self.norm1(x))[0]
        moe_out, aux = self.moe(self.norm2(x))
        return x + moe_out, aux
```

### World Model Cognitif

```python
from cognitive_core import (
    CognitiveConfig, VAEEncoder, VAEDecoder,
    MultiWorldBuffer, EpisodicMemory, NeurogenesisLayer
)

class WorldModelConfig(CognitiveConfig):
    model_type = "cognitive_world"
    world_state_dim = 256

class CognitiveWorldModel(nn.Module):
    def __init__(self, config):
        super().__init__()
        self.encoder = VAEEncoder(in_channels=3, latent_dim=256)
        self.decoder = VAEDecoder(latent_dim=256, out_channels=3)
        self.world = MultiWorldBuffer(config.d_model, config)
        self.memory = EpisodicMemory(config.d_model, config)
        self.neurogenesis = NeurogenesisLayer(256, 64, config)
```

### Vision-Language Multimodal

```python
from cognitive_core import (
    CognitiveConfig, UniversalLatentSpace, CrossAttention,
    ContrastiveLPOL, DreamPhase, SelfTrace
)

class MultimodalConfig(CognitiveConfig):
    model_type = "cognitive_multimodal"

class CognitiveMultimodal(nn.Module):
    def __init__(self, config):
        super().__init__()
        self.uls = UniversalLatentSpace(config.d_model, config)
        self.cross_attn = CrossAttention(config.d_model)
        self.memory = ContrastiveLPOL(config.d_model, config)
        self.dream = DreamPhase(config.d_model, config)
        self.self_trace = SelfTrace(config.d_model, config)
    
    def forward(self, text_features, vision_features):
        # Fusion dans l'espace latent universel
        uls_out = self.uls({"text": text_features, "vision": vision_features})
        # Attention croisée
        fused = self.cross_attn(text_features, vision_features)
        # Mémoire
        mem_out = self.memory(fused)
        return mem_out["output"]
```

## 📊 Garanties du Standard

- ✅ **Agnostique** - Fonctionne pour LLM, Vision, Audio, World Model, Multimodal
- ✅ **Composable** - Tous les modules sont indépendants et combinables
- ✅ **HuggingFace-Compatible** - Hérite de PreTrainedModel
- ✅ **Remappage Auto** - Gère les différences de format de checkpoint
- ✅ **Portabilité** - Kaggle, Colab, Local sans modification

## 📄 Licence

**PROPRIETARY - ALL RIGHTS RESERVED**
Copyright © 2026 Mike Amega (Logo) - Ame Web Studio