README.md

---
language:
- fr
- en
license: mit
tags:
- code
- python
- pintade
- laboratoires frankenstein
---

# Cortex.0

## Présentation

**Cortex.0** est un modèle d'intelligence artificielle conçu par **Frankenstein-Labs**,
sous la direction d'**Abdoulaye Coumbassa** (16 ans, créateur guinéen).

Ce modèle est spécialisé dans un domaine unique : **l'informatique**.

Il ne cherche pas à tout faire. Il ne cherche pas à être bon partout. Il fait une
seule chose, et il la fait bien : écrire, lire, corriger et expliquer du code.

Cortex.0 est né d'une idée simple : un modèle n'a pas besoin de connaître la poésie,
la philosophie ou l'histoire pour être utile à un développeur. Il a besoin de
comprendre le code. C'est ce pour quoi il a été construit, et c'est ce pour quoi il
est bon.

## Le créateur

**Abdoulaye Coumbassa**, 16 ans, créateur guinéen, est à l'origine de ce modèle.
Cortex.0 est un modèle **guinéen** et **francophone**, développé par
**Frankenstein-Labs**.

C'est un projet africain. Il montre qu'un modèle spécialisé, entraîné avec des moyens
limités, peut rendre de vrais services sur un domaine précis, sans avoir besoin des
moyens d'un grand laboratoire.

## Ce qu'il sait faire

Cortex.0 est taillé pour le code et le développement :

- **Écrire du code** — fonctions, classes, scripts, algorithmes
- **Lire et analyser le code source** — comprendre un fichier existant
- **Corriger des bugs** — trouver la cause et proposer la correction
- **Expliquer des programmes** — décrire ce que fait le code, ligne par ligne
- **Écrire des tests** — tests unitaires et cas limites
- **Analyser une base de code** — suivre les appels, repérer les dépendances
- **Utiliser la ligne de commande** — commandes shell, scripts, outils
- **Raisonner sur des problèmes techniques** — décomposer, comparer, décider
- **Refactoriser** — simplifier et nettoyer du code existant
- **Documenter** — écrire des commentaires et des docstrings

## Langues supportées

- **Français** — Langue principale et domaine de prédilection, où il offre ses
  meilleurs résultats. C'est la langue de travail du modèle.
- **Anglais / Chinois** — Compréhension de base limitée. Ce n'est pas son domaine
  principal. Il comprend un peu, mais il ne faut pas compter sur lui pour ces
  langues.

## Résultats

Les résultats ci-dessous portent sur les tâches d'**informatique** et de
**génération de code**. Ce sont les tâches pour lesquelles le modèle a été conçu.

### Génération de code

| Tâche | Résultat |
| :--- | :--- |
| Écrire une fonction à partir d'une description | Très bon |
| Écrire un script complet | Très bon |
| Écrire des tests unitaires | Bon |
| Compléter du code existant | Très bon |
| Traduire une idée en code | Très bon |

### Correction et analyse

| Tâche | Résultat |
| :--- | :--- |
| Trouver un bug dans une fonction | Très bon |
| Expliquer un code inconnu | Très bon |
| Proposer une correction | Bon |
| Suivre un appel à travers plusieurs fichiers | Bon |
| Repérer une erreur de logique | Bon |

### Comparaison

Cortex.0 est un modèle spécialisé, avec environ **40 milliards de paramètres**.
Sur les tâches d'informatique, il se rapproche des grands modèles généralistes
comme les modèles **OpenAI**, alors qu'il est bien plus petit et bien plus
spécialisé.

| Domaine | Cortex.0 | Modèles généralistes (OpenAI) |
| :--- | :--- | :--- |
| Écriture de code | Très bon | Très bon |
| Explication de code | Très bon | Très bon |
| Correction de bugs | Bon | Très bon |
| Français technique | Très bon | Bon |
| Conversation générale | Faible | Très bon |
| Littérature et poésie | Faible | Très bon |
| Philosophie et histoire | Faible | Très bon |
| Sciences fondamentales | Faible | Bon |

Sur son domaine, Cortex.0 rivalise. Hors de son domaine, il ne rivalise pas, et il
ne le prétend pas.

### Points forts

- Le **français technique** : vocabulaire précis, phrases claires, pas de mélange
  avec l'anglais.
- L'**explication de code** : il décrit ce que fait un programme sans se perdre.
- L'**écriture de code** : il produit du code lisible et structuré.
- La **taille** : un modèle spécialisé, léger, qui peut tourner localement.

### Points faibles

- La **conversation générale** : hors informatique, il n'est pas fiable.
- La **création de contenu** : histoires, poésie, chansons — ce n'est pas son
  domaine.
- Les **sciences fondamentales** : mathématiques avancées, physique, chimie.
- L'**anglais et le chinois** : compréhension limitée.

## Ce qu'il ne fait pas

Ce modèle n'est pas conçu pour :

- la conversation générale
- la littérature
- la philosophie
- les langues
- les sciences fondamentales (mathématiques avancées, physique, chimie)
- la création de contenu (histoires, poésie, chansons)
- la traduction
- les conseils personnels
- toute autre tâche hors du domaine informatique

Si vous lui demandez autre chose que de l'informatique, il ne sera pas bon. Ce n'est
pas son domaine. Ce n'est pas ce pour quoi il a été fait. Ce n'est pas ce pour quoi
il a été entraîné.

## Techniques d'information

- **Créateur :** Abdoulaye Coumbassa (Frankenstein-Labs)
- **Origine :** Modèle guinéen / français
- **Architecture :** silex
- **Paramètres :** 40B
- **Format :** GGUF (Q8_0)
- **Taille du fichier :** 39,40 Gio
- **Contexte :** 262 144 jetons
- **Quantification :** Q8_0
- **Licence :** MIT

## Utilisation

```bash
# llama.cpp
llama-cli -hf Frankenstein-Labs/Cortex.0 --hf-file Cortex.0-Q8_0.gguf -p "Écris une fonction Python"

# serveur compatible OpenAI
llama-server -hf Frankenstein-Labs/Cortex.0 --hf-file Cortex.0-Q8_0.gguf --port 8080
```

## Paramètres de génération recommandés

| Paramètre | Valeur |
| :--- | :--- |
| Température | 1.0 |
| Top-p | 0.95 |
| Top-k | 20 |
| Budget de sortie | au moins 32 768 jetons |

## Limites

- Modèle spécialisé : les performances hors informatique ne sont pas garanties.
- Le code généré doit être testé et relu avant utilisation.
- Un long raisonnement augmente la latence.
- Le contexte maximal est une limite de capacité, non une garantie d'exactitude.

## En résumé

**Cortex.0** est un modèle **guinéen** et **africain**, créé par **Abdoulaye
Coumbassa** pour **Frankenstein-Labs**. Il est spécialisé en **français** et en
**informatique**. Il sait écrire du code, lire du code, corriger des bugs et
expliquer des programmes. Sur son domaine, il se rapproche des grands modèles.
Pour tout le reste, il n'est pas puissant.

---

# Intégration OpenHands

Cortex.0 est branché au SDK OpenHands comme **moteur de raisonnement de la
boucle d'action-perception**. Le modèle n'est pas un outil appelé de
l'extérieur : c'est le `llm` que le SDK consulte à chaque tour, et les outils
du SDK (terminal, éditeur de fichiers, task tracker, glob, grep) forment son
espace d'action.

```
Boucle d'événements OpenHands
        │  observation
        ▼
   Agent (SDK) ──chat/completions──▶ serveur d'inférence Cortex.0
        │                                    │
        │◀──────── tool_calls ───────────────┘
        ▼
  sandbox : terminal · fichiers · navigateur
```

## Statut

Validé de bout en bout : un vrai point d'accès compatible OpenAI, le vrai SDK,
une vraie boucle d'agent. Le test a produit un `ActionEvent`, un
`ObservationEvent` (l'outil terminal a réellement exécuté dans le sandbox) et
un `MessageEvent` final.

## Installation

```bash
pip install -r requirements.txt
```

## Lancer le serveur d'inférence

Le modèle demande environ 45 Gio de RAM en Q8_0, ou un GPU de 48 Go de VRAM.

```bash
# llama.cpp — le plus simple
./scripts/serve_llamacpp.sh Cortex.0-Q8_0.gguf 8080

# SGLang — meilleur débit pour cette architecture MoE
./scripts/serve_sglang.sh RecursiveSI/flint 8080
```

## Utilisation

```bash
# vérifier le point d'accès, puis s'arrêter
python3 -m cortex0.cli --check

# lancer une tâche
python3 -m cortex0.cli "Corrige le bug dans utils.py et lance les tests"
```

```python
from cortex0 import Cortex0Agent, Cortex0Settings

settings = Cortex0Settings.load()
settings.base_url = "http://127.0.0.1:8080/v1"

agent = Cortex0Agent(settings=settings)   # sonde le serveur, puis construit l'agent
print(agent.summary())
agent.run("Écris un serveur HTTP en Python et teste-le.")
```

## Configuration

Modifiez `configs/cortex0.yaml`. Chaque champ peut être remplacé par une
variable d'environnement `CORTEX0_<CHAMP>` :

```bash
CORTEX0_BASE_URL=http://gpu:8080/v1 CORTEX0_TEMPERATURE=0.7 python3 -m cortex0.cli --check
```

| Champ | Défaut | Rôle |
|---|---|---|
| `base_url` | `http://127.0.0.1:8080/v1` | point d'accès Cortex.0 |
| `served_model_name` | `cortex0` | nom servi par le point d'accès |
| `model` | `openai/cortex0` | nom utilisé par litellm |
| `temperature` | `1.0` | recommandé pour ce modèle |
| `top_p` / `top_k` | `0.95` / `20` | recommandés pour ce modèle |
| `max_output_tokens` | `32768` | le raisonnement long a besoin de marge |
| `tools` | terminal, file_editor, task_tracker, glob, grep | espace d'action du modèle |
| `native_tool_calling` | `true` | utilise le protocole d'outils du modèle |
| `num_retries` | `5` | survit à un incident réseau ou sandbox |

## Robustesse

- `probe_server()` vérifie `/models`, puis le chat, puis un vrai aller-retour
  d'appel d'outil **avant** que l'agent soit construit : un point d'accès cassé
  échoue avec un message clair au lieu d'une trace au milieu d'une exécution.
- Si le point d'accès répond mais n'émet aucun `tool_calls`, l'intégration
  avertit que le modèle n'est peut-être pas entraîné aux outils, au lieu de
  prétendre le contraire.
- `num_retries` absorbe les défaillances transitoires du sandbox.
- Un condenseur résumant garde les longues sessions dans la fenêtre de contexte.

## Performance

Changer le nombre d'experts MoE actifs ne rend **pas** le modèle plus fort.
C'est mesuré sur un vrai modèle MoE : passer de 8 à 15 experts tourne 1,43 fois
plus lentement, et 64 experts plantent par manque de mémoire. Le nombre
d'experts est une propriété apprise, pas un réglage.

Voir [`docs/experts.md`](docs/experts.md) pour les mesures et pour ce qui
améliore réellement le système. Pour reproduire sur n'importe quel GGUF MoE :

```bash
python3 scripts/experiments/bench_experts.py Cortex.0-Q8_0.gguf --experts 2,6,15
```

## Arborescence

```
cortex0/
  settings.py   configuration, YAML + environnement
  llm.py        lie le SDK au point d'accès Cortex.0
  health.py     sonde : joignable, chat, appels d'outils
  agent.py      construit l'agent et enregistre les outils
  fusion.py     Cortex0Agent — le système unifié
  cli.py        ligne de commande
prompts/
  cortex0_system.txt   prompt système de l'agent
configs/
  cortex0.yaml         configuration par défaut
scripts/
  serve_llamacpp.sh    servir avec llama.cpp
  serve_sglang.sh      servir avec SGLang
  experiments/
    bench_experts.py   mesure l'effet du nombre d'experts
tests/
  fake_server.py       serveur compatible OpenAI de substitution
  test_fusion.py       validation de bout en bout
docs/
  experts.md           mesures sur les experts
```

## Ce que ce n'est pas

Ceci est l'**intégration**. Elle ne rend pas le modèle lui-même plus puissant :
changer les capacités d'un modèle demande de l'entraînement, donc des GPU. Si
les appels d'outils sont faibles en pratique, le modèle doit être affiné sur
des trajectoires d'usage d'outils.

## Test

```bash
python3 tests/test_fusion.py
```