# Documentation mgrep

Bienvenue dans la documentation complète de mgrep ! 📚

Si vous découvrez mgrep, lisez dans cet ordre :

1. Embeddings - Comprendre comment le code est converti en vecteurs
2. Modèles - Différences entre CodeBERT, Jina, MPNet, etc.
3. Architecture - Vue d'ensemble du système
4. Compromis - Trade-offs précision vs performance
5. Cas d'usage - Configurations pratiques selon vos besoins

Pour qui : Tout le monde Temps de lecture : 10 min Contenu :

• Qu'est-ce qu'un embedding ?
• Comment ça marche dans mgrep ?
• Dimensions (384 vs 768)
• Le problème du "mean pooling"

À retenir :

Un embedding transforme du code en vecteur de nombres. La similarité entre vecteurs = similarité sémantique du code.

Pour qui : Utilisateurs qui veulent optimiser la qualité Temps de lecture : 15 min Contenu :

• 3 types de modèles (BERT+pooling, natifs génériques, spécialisés code)
• Comparaison détaillée CodeBERT vs Jina vs MPNet
• Pourquoi Jina Code est recommandé
• Tests et résultats attendus

À retenir :

Jina Code (jinaai/jina-embeddings-v2-base-code) est le meilleur modèle pour mgrep. CodeBERT avec mean pooling est sous-optimal.

Pour qui : Utilisateurs avancés, optimisation Temps de lecture : 20 min Contenu :

• Taille des chunks (10 vs 20 vs 50 lignes)
• Overlap : avantages et coûts
• Modèles : vitesse vs qualité
• Configurations selon taille du projet

À retenir :

Chaque choix a un trade-off. La config actuelle (20 lignes, Jina Code, pas d'overlap) est un bon équilibre pour la plupart des cas.

Pour qui : Développeurs qui veulent contribuer Temps de lecture : 25 min Contenu :

• Flow complet indexation → recherche
• Rôle de chaque composant (Tree-sitter, Elasticsearch, etc.)
• Schémas et exemples de code
• Points d'optimisation possibles

À retenir :

mgrep = Tree-sitter (parse) + Chunking (découpe) + Sentence-transformers (embeddings) + Elasticsearch (index/search)

Pour qui : Tous les utilisateurs Temps de lecture : 15 min Contenu :

• 7 cas d'usage concrets (exploration, debug, refactoring, etc.)
• Configuration recommandée pour chaque cas
• Workflows pratiques
• Scripts d'exemple

À retenir :

Adapter la configuration selon votre besoin : debug = rapide, refactoring = overlap 50%, exploration = k=10

# 1. Cloner et installer
git clone <repo>
cd mgrep
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# 2. Configurer
cp .env.example .env
# Éditer .env avec vos credentials Elasticsearch

# 3. Créer l'index
python recreate_index.py

# 4. Indexer votre code
python watcher.py /path/to/your/code

# Recherche simple
python sgrep.py "user authentication"

# Avec affichage du code
python sgrep.py "database connection" --show-code

# Plus de résultats
python sgrep.py "error handling" -k 10

• Meilleure qualité : jinaai/jina-embeddings-v2-base-code
• Compromis : all-mpnet-base-v2
• Le plus rapide : all-MiniLM-L6-v2

Configuration dans .env :

EMBEDDING_MODEL=jinaai/jina-embeddings-v2-base-code

• Très précis : 15 lignes
• Équilibré (recommandé) : 20 lignes
• Rapide : 30-50 lignes

Modifier dans watcher.py :

MAX_CHUNK_LINES = 20  # Ligne 44

OUI si :

• Refactoring (besoin de tout trouver)
• Projet complexe avec fonctions longues

NON si :

• Projet petit/moyen
• Contraintes de stockage
• Première utilisation (tester sans d'abord)

C'est un avertissement que CodeBERT n'est pas optimal. Utilisez Jina Code ou MPNet à la place.

Voir : 2-modeles.md pour l'explication complète.

Checklist :

1. ✅ Modèle utilisé : Jina Code ou MPNet ? (pas CodeBERT)
2. ✅ Chunks : 20 lignes max ?
3. ✅ Index récent : python watcher.py a tourné ?
4. ✅ Requête : assez spécifique ? ("auth" vs "user authentication")

Voir : 5-cas-usage.md pour des exemples de requêtes efficaces.

En plus de cette documentation :

• ../CLAUDE.md - Guide pour Claude Code (commandes, architecture)
• ../todo.txt - Roadmap et améliorations futures
• ../limitations.txt - Limitations actuelles du chunking
• ../.env.example - Template de configuration

Pour améliorer cette documentation :

1. Les docs sont en Markdown dans docs/
2. Chaque fichier = 1 sujet
3. Garder un ton pédagogique avec exemples concrets
4. Ajouter des schémas ASCII quand utile

• 📖 Lire cette documentation
• 🐛 Issues : problèmes techniques
• 💡 Discussions : questions, suggestions

Bonne lecture ! 🚀