README.md · Frankenstein-Labs/Cortex-0 at main

Cortex-0 / README.md

release: Cortex-0 (Phases 0-12)

3a2cb1d verified 14 days ago

8.2 kB

---
license: apache-2.0
base_model: []
language:
  - fr
  - en
library_name: pytorch
pipeline_tag: text-generation
tags:
  - multimodal
  - from-scratch
  - transformer
  - vision
  - audio
  - video
  - moe
  - rag
  - french
  - no-pretrained-weights
---
# Cortex-0

> **FR** — **Cortex-0** : IA multimodale (texte · image · audio · vidéo) construite
> **entièrement from scratch**, sans **aucun** modèle pré-entraîné ni API externe.
> **EN** — **Cortex-0**: multimodal AI (text · image · audio · video) built
> **entirely from scratch**, with **no** pretrained model and **no** external API.

*Dépôt : `Frankenstein-Labs/opendevin-multimodal` — renommage « Cortex-0 » différé (ADR-008).*

---

## 🇫🇷 Français

### Statut : ✅ Phases 0 → 12 livrées

Chaque phase a été franchie avec **tests verts**, **commit** et **publication Hub**.
Un seul décodeur texte génère ; image, audio et vidéo y sont injectés comme tokens
projetés. Tout (tokenizer, attention, RoPE, ViT, encodeur audio, MoE, RAG, API, démo)
est **codé à la main**.

### Ce que ce projet EST
- Un transformer **texte** decoder-only écrit à la main (attention, RoPE, FFN, blocs).
- Un encodeur **image** ViT maison (patch embedding + blocs), projecteur MLP.
- Un encodeur **audio** maison sur spectrogrammes mel (mel calculé à la main).
- Un encodeur **vidéo** : ViT partagé par frame + embedding temporel + transformer spatio-temporel.
- Une **fusion** multimodale **précoce** dans une séquence unique de tokens.
- Un **MoE** (20 experts, top-2) avec routeur et loss d'équilibrage maison.
- Une **mémoire RAG** maison (embeddings feature-hashing + index cosinus numpy).
- Une **API FastAPI**, une **démo Gradio**, un **Dockerfile**, une publication Hub.

### Ce que ce projet N'EST PAS
- ❌ Ni GPT-4V, ni DeepSeek, ni LLaVA. Un modèle de ~15 M de paramètres n'a **pas**
  les capacités d'un modèle de plusieurs centaines de milliards. Aucune équivalence
  n'est prétendue.
- ❌ L'« apprentissage permanent » (Phase 11, mode B) est **expérimental et instable** :
  l'oubli catastrophique est **démontré par les tests**, pas caché.

### Contraintes matérielles
Développement, tests et entraînement jouet : **CPU uniquement**.
Tous les chiffres ci-dessous sont **mesurés localement sur CPU**, jamais inventés.

### Résultats mesurés (corpus jouets, CPU)
| Phase | Tâche | Mesure |
|-------|-------|--------|
| 3 | Texte (langage) | perplexité val < 30 atteinte sur corpus jouet |
| 6/8 | Grounding image | exactitude ~0.87–0.92 |
| 7/8 | Grounding audio | exactitude 1.00 |
| 8 | Mixte image+audio | ~0.92 |
| 9 | Vidéo (+ audio) | grounding ~0.78–0.85 (hasard 0.055) |
| 10 | MoE 20 experts | perplexité val 1.005 ; charge H=0.9999 ; 14.86 M params / 5.42 M actifs |
| 12 | Audio via le moteur | transcription correcte sur les voyelles jouets |

**Limite honnête** : la **génération libre** d'une description d'image reste faible
(accord mot-à-mot parfois partiel) — c'est la limite d'un modèle de cette taille.

### Installation
```bash
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env   # puis renseigner HF_TOKEN (jamais en dur)
```

### Utilisation (bibliothèque)
```python
import numpy as np
from src.inference import CortexEngine
eng = CortexEngine(checkpoint="checkpoints/best.pt")  # vide => poids init, trained=False
# Texte
print(eng.chat("Bonjour, qui es-tu ?")["text"])
# Image (ndarray uint8, PIL.Image, chemin ou bytes PNG)
img = (np.random.rand(32, 32, 3) * 255).astype("uint8")
print(eng.describe_image(img))
# Audio (échantillons float32, chemin WAV ou bytes WAV)
print(eng.transcribe_audio(np.zeros(8000, dtype="float32")))
# Vidéo (T, H, W, 3) + audio optionnel
frames = np.zeros((4, 32, 32, 3), dtype="uint8")
print(eng.describe_video(frames))
```

### Mémoire / RAG (apprendre un cours)
```python
from src.memory.rag import LessonMemory
mem = LessonMemory()
mem.add_video(
    transcript=[(0.0, "Un volcan crache de la lave chaude.")],
    frame_captions=[(0.0, "une coulée de lave orange")],
    source="volcans.mp4",
)
print(mem.answer("De quoi est faite la lave ?"))   # réponse extractive + sources
```

### API REST (FastAPI)
```bash
CORTEX_CHECKPOINT=checkpoints/best.pt python -m src.api
# http://localhost:8000/docs
# GET  /health   /capabilities
# POST /chat     {"prompt": "...", "max_new_tokens": 40}
# POST /vision   (upload image)      POST /audio  (upload WAV)
# POST /video    (frames .npy)       POST /memory/ingest  /memory/query
```

### Démo (Gradio)
```bash
CORTEX_CHECKPOINT=checkpoints/best.pt python app/gradio_app.py   # http://localhost:7860
```

### Docker
```bash
docker build -t cortex-0 .
docker run -p 8000:8000 -e CORTEX_CHECKPOINT= cortex-0
```

### Tests
```bash
pytest -q     # suite complète, tourne sur CPU
ruff check .
```

### Publication Hub
```bash
export HF_TOKEN=...   # jamais écrit en dur
python -m src.push_to_hub --repo-id Frankenstein-Labs/opendevin-multimodal \
    --public --checkpoint checkpoints/best.pt --card README.md \
    --message "release: Cortex-0"
```

### Licence
Apache-2.0 — voir [`LICENSE`](LICENSE).

---

## 🇬🇧 English

### Status: ✅ Phases 0 → 12 shipped

Every phase was crossed with **green tests**, a **commit** and a **Hub publication**.
A single text decoder generates; image, audio and video are injected as projected
tokens. Everything (tokenizer, attention, RoPE, ViT, audio encoder, MoE, RAG, API,
demo) is **hand-written**.

### What this project IS
- A hand-written decoder-only **text** transformer (attention, RoPE, FFN, blocks).
- A from-scratch **image** ViT encoder (patch embedding + blocks) + MLP projector.
- A from-scratch **audio** encoder over mel-spectrograms (mel computed by hand).
- A **video** encoder: shared per-frame ViT + learned temporal embedding + spatio-temporal transformer.
- Early multimodal **fusion** into a single token sequence.
- A **MoE** (20 experts, top-2) with a hand-written router and load-balancing loss.
- A from-scratch **RAG** memory (feature-hashing embeddings + numpy cosine index).
- A **FastAPI** service, a **Gradio** demo, a **Dockerfile**, a Hub publication.

### What this project is NOT
- ❌ Not GPT-4V, DeepSeek or LLaVA. A ~15M-parameter model does **not** match models
  with hundreds of billions of parameters. No equivalence is claimed.
- ❌ "Permanent learning" (Phase 11, mode B) is **experimental and unstable**: catastrophic
  forgetting is **demonstrated by the tests**, not hidden.

### Hardware constraints
Development, tests and toy training: **CPU only**. All numbers above are **measured
locally on CPU**, never invented.

### Install
```bash
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env   # then set HF_TOKEN (never hard-coded)
```

### Library usage
```python
from src.inference import CortexEngine
eng = CortexEngine(checkpoint="checkpoints/best.pt")   # empty => random init, trained=False
print(eng.chat("Hello, who are you?")["text"])
```

### REST API · Demo · Docker · Tests
Same commands as the French section above (`python -m src.api`, `app/gradio_app.py`,
`docker build`, `pytest -q`).

### License
Apache-2.0 — see [`LICENSE`](LICENSE).

---

## Roadmap (phases)

| # | Phase | Statut / Status |
|---|-------|-----------------|
| 0 | Fondations / Foundations | ✅ |
| 1 | Tokenizer BPE from scratch | ✅ |
| 2 | Transformer texte / Text transformer | ✅ |
| 3 | Entraînement texte / Text training | ✅ |
| 4 | Encodeur image / Image encoder | ✅ |
| 5 | Alignement image-texte / Image-text alignment | ✅ |
| 6 | VLM génératif / Generative VLM | ✅ |
| 7 | Encodeur audio / Audio encoder | ✅ |
| 8 | Multimodal complet / Full multimodal | ✅ |
| 9 | Vidéo / Video | ✅ |
| 10 | MoE multi-expert (20, top-2) | ✅ |
| 11 | Mémoire / RAG + apprentissage permanent | ✅ |
| 12 | API + Démo + Publication | ✅ |

Détail complet : [`docs/phases.md`](docs/phases.md).
Choix techniques : [`docs/architecture.md`](docs/architecture.md).
Journal des décisions : [`docs/decisions.md`](docs/decisions.md).

---

	---
	license: apache-2.0
	base_model: []
	language:
	- fr
	- en
	library_name: pytorch
	pipeline_tag: text-generation
	tags:
	- multimodal
	- from-scratch
	- transformer
	- vision
	- audio
	- video
	- moe
	- rag
	- french
	- no-pretrained-weights
	---

	# Cortex-0

	> FR — Cortex-0 : IA multimodale (texte · image · audio · vidéo) construite
	> entièrement from scratch, sans aucun modèle pré-entraîné ni API externe.
	> EN — Cortex-0: multimodal AI (text · image · audio · video) built
	> entirely from scratch, with no pretrained model and no external API.

	Dépôt : `Frankenstein-Labs/opendevin-multimodal` — renommage « Cortex-0 » différé (ADR-008).

	---

	## 🇫🇷 Français

	### Statut : ✅ Phases 0 → 12 livrées

	Chaque phase a été franchie avec tests verts, commit et publication Hub.
	Un seul décodeur texte génère ; image, audio et vidéo y sont injectés comme tokens
	projetés. Tout (tokenizer, attention, RoPE, ViT, encodeur audio, MoE, RAG, API, démo)
	est codé à la main.

	### Ce que ce projet EST
	- Un transformer texte decoder-only écrit à la main (attention, RoPE, FFN, blocs).
	- Un encodeur image ViT maison (patch embedding + blocs), projecteur MLP.
	- Un encodeur audio maison sur spectrogrammes mel (mel calculé à la main).
	- Un encodeur vidéo : ViT partagé par frame + embedding temporel + transformer spatio-temporel.
	- Une fusion multimodale précoce dans une séquence unique de tokens.
	- Un MoE (20 experts, top-2) avec routeur et loss d'équilibrage maison.
	- Une mémoire RAG maison (embeddings feature-hashing + index cosinus numpy).
	- Une API FastAPI, une démo Gradio, un Dockerfile, une publication Hub.

	### Ce que ce projet N'EST PAS
	- ❌ Ni GPT-4V, ni DeepSeek, ni LLaVA. Un modèle de ~15 M de paramètres n'a pas
	les capacités d'un modèle de plusieurs centaines de milliards. Aucune équivalence
	n'est prétendue.
	- ❌ L'« apprentissage permanent » (Phase 11, mode B) est expérimental et instable :
	l'oubli catastrophique est démontré par les tests, pas caché.

	### Contraintes matérielles
	Développement, tests et entraînement jouet : CPU uniquement.
	Tous les chiffres ci-dessous sont mesurés localement sur CPU, jamais inventés.

	### Résultats mesurés (corpus jouets, CPU)
	\| Phase \| Tâche \| Mesure \|
	\|-------\|-------\|--------\|
	\| 3 \| Texte (langage) \| perplexité val < 30 atteinte sur corpus jouet \|
	\| 6/8 \| Grounding image \| exactitude ~0.87–0.92 \|
	\| 7/8 \| Grounding audio \| exactitude 1.00 \|
	\| 8 \| Mixte image+audio \| ~0.92 \|
	\| 9 \| Vidéo (+ audio) \| grounding ~0.78–0.85 (hasard 0.055) \|
	\| 10 \| MoE 20 experts \| perplexité val 1.005 ; charge H=0.9999 ; 14.86 M params / 5.42 M actifs \|
	\| 12 \| Audio via le moteur \| transcription correcte sur les voyelles jouets \|

	Limite honnête : la génération libre d'une description d'image reste faible
	(accord mot-à-mot parfois partiel) — c'est la limite d'un modèle de cette taille.

	### Installation
	```bash
	python -m venv .venv && source .venv/bin/activate
	pip install -r requirements.txt
	cp .env.example .env # puis renseigner HF_TOKEN (jamais en dur)
	```

	### Utilisation (bibliothèque)
	```python
	import numpy as np
	from src.inference import CortexEngine

	eng = CortexEngine(checkpoint="checkpoints/best.pt") # vide => poids init, trained=False

	# Texte
	print(eng.chat("Bonjour, qui es-tu ?")["text"])

	# Image (ndarray uint8, PIL.Image, chemin ou bytes PNG)
	img = (np.random.rand(32, 32, 3) * 255).astype("uint8")
	print(eng.describe_image(img))

	# Audio (échantillons float32, chemin WAV ou bytes WAV)
	print(eng.transcribe_audio(np.zeros(8000, dtype="float32")))

	# Vidéo (T, H, W, 3) + audio optionnel
	frames = np.zeros((4, 32, 32, 3), dtype="uint8")
	print(eng.describe_video(frames))
	```

	### Mémoire / RAG (apprendre un cours)
	```python
	from src.memory.rag import LessonMemory
	mem = LessonMemory()
	mem.add_video(
	transcript=[(0.0, "Un volcan crache de la lave chaude.")],
	frame_captions=[(0.0, "une coulée de lave orange")],
	source="volcans.mp4",
	)
	print(mem.answer("De quoi est faite la lave ?")) # réponse extractive + sources
	```

	### API REST (FastAPI)
	```bash
	CORTEX_CHECKPOINT=checkpoints/best.pt python -m src.api
	# http://localhost:8000/docs
	# GET /health /capabilities
	# POST /chat {"prompt": "...", "max_new_tokens": 40}
	# POST /vision (upload image) POST /audio (upload WAV)
	# POST /video (frames .npy) POST /memory/ingest /memory/query
	```

	### Démo (Gradio)
	```bash
	CORTEX_CHECKPOINT=checkpoints/best.pt python app/gradio_app.py # http://localhost:7860
	```

	### Docker
	```bash
	docker build -t cortex-0 .
	docker run -p 8000:8000 -e CORTEX_CHECKPOINT= cortex-0
	```

	### Tests
	```bash
	pytest -q # suite complète, tourne sur CPU
	ruff check .
	```

	### Publication Hub
	```bash
	export HF_TOKEN=... # jamais écrit en dur
	python -m src.push_to_hub --repo-id Frankenstein-Labs/opendevin-multimodal \
	--public --checkpoint checkpoints/best.pt --card README.md \
	--message "release: Cortex-0"
	```

	### Licence
	Apache-2.0 — voir [`LICENSE`](LICENSE).

	---

	## 🇬🇧 English

	### Status: ✅ Phases 0 → 12 shipped

	Every phase was crossed with green tests, a commit and a Hub publication.
	A single text decoder generates; image, audio and video are injected as projected
	tokens. Everything (tokenizer, attention, RoPE, ViT, audio encoder, MoE, RAG, API,
	demo) is hand-written.

	### What this project IS
	- A hand-written decoder-only text transformer (attention, RoPE, FFN, blocks).
	- A from-scratch image ViT encoder (patch embedding + blocks) + MLP projector.
	- A from-scratch audio encoder over mel-spectrograms (mel computed by hand).
	- A video encoder: shared per-frame ViT + learned temporal embedding + spatio-temporal transformer.
	- Early multimodal fusion into a single token sequence.
	- A MoE (20 experts, top-2) with a hand-written router and load-balancing loss.
	- A from-scratch RAG memory (feature-hashing embeddings + numpy cosine index).
	- A FastAPI service, a Gradio demo, a Dockerfile, a Hub publication.

	### What this project is NOT
	- ❌ Not GPT-4V, DeepSeek or LLaVA. A ~15M-parameter model does not match models
	with hundreds of billions of parameters. No equivalence is claimed.
	- ❌ "Permanent learning" (Phase 11, mode B) is experimental and unstable: catastrophic
	forgetting is demonstrated by the tests, not hidden.

	### Hardware constraints
	Development, tests and toy training: CPU only. All numbers above are **measured
	locally on CPU**, never invented.

	### Install
	```bash
	python -m venv .venv && source .venv/bin/activate
	pip install -r requirements.txt
	cp .env.example .env # then set HF_TOKEN (never hard-coded)
	```

	### Library usage
	```python
	from src.inference import CortexEngine
	eng = CortexEngine(checkpoint="checkpoints/best.pt") # empty => random init, trained=False
	print(eng.chat("Hello, who are you?")["text"])
	```

	### REST API · Demo · Docker · Tests
	Same commands as the French section above (`python -m src.api`, `app/gradio_app.py`,
	`docker build`, `pytest -q`).

	### License
	Apache-2.0 — see [`LICENSE`](LICENSE).

	---

	## Roadmap (phases)

	\| # \| Phase \| Statut / Status \|
	\|---\|-------\|-----------------\|
	\| 0 \| Fondations / Foundations \| ✅ \|
	\| 1 \| Tokenizer BPE from scratch \| ✅ \|
	\| 2 \| Transformer texte / Text transformer \| ✅ \|
	\| 3 \| Entraînement texte / Text training \| ✅ \|
	\| 4 \| Encodeur image / Image encoder \| ✅ \|
	\| 5 \| Alignement image-texte / Image-text alignment \| ✅ \|
	\| 6 \| VLM génératif / Generative VLM \| ✅ \|
	\| 7 \| Encodeur audio / Audio encoder \| ✅ \|
	\| 8 \| Multimodal complet / Full multimodal \| ✅ \|
	\| 9 \| Vidéo / Video \| ✅ \|
	\| 10 \| MoE multi-expert (20, top-2) \| ✅ \|
	\| 11 \| Mémoire / RAG + apprentissage permanent \| ✅ \|
	\| 12 \| API + Démo + Publication \| ✅ \|

	Détail complet : [`docs/phases.md`](docs/phases.md).
	Choix techniques : [`docs/architecture.md`](docs/architecture.md).
	Journal des décisions : [`docs/decisions.md`](docs/decisions.md).

	---