N'Ko Brain Scanner

Gold: ߞߋ ߡߎߛߋ ߕߐ ߛߏߙߏ ߛߋߢߊߟߌ ߟߊ ߞʔߎ ߓʔߊ ߘߍߟߌ
Pred: ߞߋ ߡߎߛߋ ߕߐ ߛߏߙߏ ߛߋߢߊߟߌ ߟߊ ߞߎ ߓߊ ߘߌߜߌ

nko-brain-scanner/
+-- paper/               # ACL/EMNLP 2026 paper (LaTeX)
+-- scanner/             # Brain scan activation profiling
|   +-- mlx_activation_profiler.py
|   +-- mlx_brain_scan_8b.py
|   +-- compare_profiles.py
|   +-- eval_translation_tax.py
+-- training/            # Training pipeline (MLX LoRA)
|   +-- build_sft_data_v3.py  # V3 data builder (92K examples)
|   +-- build_sft_data.py     # SFT data builder
|   +-- build_cpt_data.py     # CPT sliding window data
|   +-- build_sft_data_v2.py  # V2 extended vocab data
+-- tokenizer/           # N'Ko BPE tokenizer
|   +-- train_bpe.py         # Standard 512-merge BPE
|   +-- train_morpheme_bpe.py # Morpheme-constrained BPE
|   +-- eval_tokenizers.py   # Comparison evaluation
|   +-- morpheme_tokenizer.py
|   +-- build_vocab_extension.py
|   +-- extend_hf_tokenizer.py
+-- constrained/         # Admissibility-constrained decoding
|   +-- nko_fsm.py           # 4-state syllable FSM
|   +-- logits_processor.py  # MLX logits processor
|   +-- eval_admissibility.py
|   +-- gk_scorer.py         # Graph Kernel semantic scorer
+-- asr/                 # ASR pipeline (char-level CTC)
|   +-- char_level_train.py      # Char-level CTC training (primary, 5.4M params)
|   +-- extract_human_features.py # Whisper feature extraction from bam-asr-early
|   +-- eval_bam_test.py         # CER/WER evaluation on test set (1,463 samples)
|   +-- submit_leaderboard.py    # MALIBA-AI benchmark submission
|   +-- postprocess.py           # CTC decode + syllable segmentation + FSM validation
|   +-- retrieval_asr_v2.py      # V2 Transformer architecture (36M params)
|   +-- watchdog.sh              # Auto-recovery daemon for GPU instances
|   +-- stream_with_features.py  # Streaming pipeline (YouTube→features→transcribe)
|   +-- train_on_human_data.py   # bam-asr-early fine-tuning
|   +-- train_retrieval_asr.py   # Retrieval-based ASR training
|   +-- audio_pipeline.py        # YouTube download + VAD segmentation
|   +-- audio_encoder.py         # Whisper encoder (frozen features)
|   +-- bridge_to_nko.py         # Latin Bambara → N'Ko cross-script bridge
|   +-- dynamic_ocr_pipeline.py  # Scene-adaptive OCR for teaching videos
|   +-- download_djoko.py        # Djoko + babamamadidiane audio downloader
|   +-- eval_vs_maliba.py        # WER evaluation vs MALIBA-AI baseline
|   +-- speaker_diarizer.py      # pyannote speaker clustering
|   +-- scene_encoder.py         # SigLIP visual feature extraction
|   +-- joint_embedding.py       # Shared embedding space (d=512)
|   +-- syllable_retriever.py    # Codebook retrieval + FSM beam search
|   +-- round_trip_eval.py       # Round-trip accuracy evaluation
|   +-- vastai_pipeline.py       # Vast.ai distributed training orchestration
+-- nko_core/            # N'Ko language core
|   +-- __init__.py          # Unicode, phonology, morphology
+-- data/                # Corpora and codebooks
|   +-- syllable_codebook.json  # 3,024-entry codebook
|   +-- nko_bpe_vocab.json
|   +-- morpheme_bpe_vocab.json
|   +-- nicolingua/          # WMT 2023 parallel corpus (32,792 segments)
+-- eval/                # Evaluation scripts
|   +-- run_corrected_profiler.py  # Base/2-stage/3-stage comparison
|   +-- run_v3_profiler.py         # V3 fused model evaluation
|   +-- run_v3_generation.py       # Mode collapse check (20 prompts)
+-- results/             # Experimental results (JSON)
+-- figures/             # Brain scan visualizations
+-- blog/                # Research blog posts
|   +-- post.md              # Part 1: The Script That Machines Can't Read (brain scan)
|   +-- index.md             # Summary: Adapting LLMs for N'Ko
|   +-- asr-breakthrough.md  # Part 2: From Dead Circuits to Living Speech (ASR)
+-- model_card.md        # HuggingFace model card

python3 scanner/mlx_brain_scan_8b.py

# Stage 1: Continued Pre-Training (17,360 examples)
python3 -m mlx_lm lora --model mlx-community/Qwen3-8B-8bit \
    --data training/cpt/ --iters 2000 --learning-rate 1e-5

# Stage 2: Supervised Fine-Tuning (21,240 examples)
python3 -m mlx_lm lora --model mlx-community/Qwen3-8B-8bit \
    --adapter-path adapters-stage1/ --data training/sft/ --iters 1000

# Stage 3: BPE-Aware Training (25,100 examples)
python3 -m mlx_lm lora --model mlx-community/Qwen3-8B-8bit \
    --adapter-path adapters-stage2/ --data training/bpe/ --iters 1000

# Build V3 data (combines all sources + nicolingua parallel corpus)
python3 training/build_sft_data_v3.py

# Train V3 adapter on extended-vocabulary model
python3 -m mlx_lm lora -c v3_training_config.yaml

python3 tokenizer/train_bpe.py --merges 512
python3 tokenizer/train_morpheme_bpe.py --merges 512 --compare-bpe
python3 tokenizer/eval_tokenizers.py

python3 constrained/eval_admissibility.py --model path/to/fused-model --num-samples 50

# Train on human-labeled bam-asr-early (Vast.ai, RTX 4090)
python3 asr/char_level_train.py --epochs 100 --batch-size 8
python3 asr/train_on_human_data.py --epochs 100 --batch-size 4

# Download YouTube data
python3 asr/download_djoko.py --limit 100          # Djoko episodes
python3 asr/download_djoko.py --channel babamamadidiane --limit 50

# OCR: extract N'Ko text from teaching video frames (Gemini 3 Flash)
python3 asr/dynamic_ocr_pipeline.py --limit 5

# Cross-script bridge: Latin Bambara → N'Ko
python3 asr/bridge_to_nko.py --input results/transcriptions.jsonl --output results/nko_pairs.jsonl

# Evaluate vs MALIBA-AI baseline (45.73% WER)
python3 asr/eval_vs_maliba.py --model-path results/best_retrieval_asr.pt

# Smoke tests
python3 asr/joint_embedding.py
python3 asr/round_trip_eval.py

# V1-V3 comparison
python3 eval/run_corrected_profiler.py
python3 eval/run_v3_profiler.py

# Generation quality (mode collapse check)
python3 eval/run_v3_generation.py

@misc{diomande2026nko,
  title={The Script That Machines Can't Read: Adapting Large Language Models for N'Ko},
  author={Diomande, Mohamed},
  year={2026},
  url={https://github.com/Diomandeee/nko-brain-scanner}
}