# Différence entre les approches de modèles

# Vue d'ensemble

Il existe 3 grandes catégories de modèles pour créer des embeddings de code.

# 1. Modèles BERT génériques (avec mean pooling)

# Exemples

microsoft/codebert-base
huggingface/CodeBERTa-small-v1

# Comment ils fonctionnent

Entraînement original :
├─ Tâche : Masked Language Modeling
│  Exemple : "def [MASK](user)" → prédire "login"
│
└─ Tâche : Next Sentence Prediction
   Exemple : Est-ce que B suit A logiquement ?

BUT : Compréhension du code, pas recherche !

# Adaptation avec mean pooling

Quand sentence-transformers charge CodeBERT :

# Le modèle n'a PAS de couche de pooling entraînée
# → sentence-transformers ajoute mean pooling automatiquement

"Creating a new one with mean pooling"
           ↑
    Message d'avertissement !

Processus :

Input : "def authenticate(user, password):"

BERT → Vecteurs par token :
  [CLS]         → [0.1, 0.2, ..., 0.5]  (token spécial)
  def           → [0.3, 0.1, ..., 0.8]
  authenticate  → [0.9, 0.7, ..., 0.2]
  (             → [0.0, 0.1, ..., 0.1]
  user          → [0.5, 0.4, ..., 0.3]
  ...

Mean Pooling → Moyenne de TOUS les vecteurs
Result : [0.36, 0.3, ..., 0.38]

# ❌ Problèmes

Pas optimisé pour la tâche
- CodeBERT a appris à prédire des mots manquants
- Il n'a jamais appris à "résumer" du code en UN vecteur

Perte d'information importante

"def authenticate_user" et "def delete_database"
peuvent avoir des embeddings trop similaires
car le mot "def" domine la moyenne

Tous les mots ont le même poids
- authenticate (important) = même poids que ( (syntaxe)

# ✅ Quand l'utiliser quand même

Quand aucun modèle spécialisé n'existe pour votre langage
Pour du prototypage rapide
Si les résultats sont "assez bons" pour votre cas d'usage

# 2. Modèles natifs sentence-transformers (génériques)

# Exemples

all-MiniLM-L6-v2 (384 dims)
all-mpnet-base-v2 (768 dims)

# Comment ils fonctionnent

Entraînement en 2 phases :

Phase 1 : BERT classique
  ↓
Phase 2 : Fine-tuning pour similarité sémantique
  ├─ Apprentissage de la meilleure pooling strategy
  ├─ Contrastive learning (rapprocher textes similaires)
  └─ Optimisation pour cosine similarity

# Processus d'entraînement spécifique

# Exemples d'entraînement :
Phrase A : "authenticate user"
Phrase B : "login verification"     ← Similaire
Phrase C : "delete database"        ← Différent

# Le modèle apprend :
embedding(A) proche de embedding(B)
embedding(A) éloigné de embedding(C)

# ✅ Avantages

Pooling intelligent
- Pas juste une moyenne
- Attention sur les mots importants
- [CLS] token optimisé pour représenter tout le texte

Entraîné pour la recherche

Query : "user authentication"
Code  : "def verify_credentials(username, password)"

→ Le modèle a appris que ces concepts sont liés !

Pas de message d'avertissement

"No sentence-transformers model found..."
✅ Ne s'affiche PAS avec ces modèles

# ❌ Limitations pour le code

Entraîné sur texte naturel (Wikipedia, livres)
Ne comprend pas forcément :
- camelCase vs snake_case
- Conventions de nommage du code
- Syntaxe spécifique (decorators, annotations)

# 📊 Performance estimée pour mgrep

Requête : "jwt middleware"

all-mpnet-base-v2 :
├─ Comprend : "jwt" (acronyme), "middleware" (concept)
├─ Peut rater : nuances de Flask/Express middlewares
└─ Résultats : 70-80% de pertinence

# 3. Modèles spécialisés code (natifs)

# Exemples

jinaai/jina-embeddings-v2-base-code ⭐ RECOMMANDÉ
Salesforce/codet5-base (avec fine-tuning)

# Comment ils fonctionnent

Entraînement en 3 phases :

Phase 1 : BERT sur code
  Corpus : GitHub (millions de repos)
  ↓
Phase 2 : Fine-tuning pour similarité de code
  ├─ Exemples : fonction et sa docstring
  ├─ Exemples : code équivalent en différents langages
  └─ Exemples : code et description en langage naturel
  ↓
Phase 3 : Optimisation pour recherche
  ├─ Contrastive learning sur code
  └─ Support multilingue (Python, JS, Java, etc.)

# Jina Code : Cas d'usage spécifique

Entraînement sur paires code-description :

# Exemples d'entraînement
Code :
    def validate_email(email):
        return re.match(r'^[\w\.-]+@', email) is not None

Description : "check if email is valid"

# Le modèle apprend la relation directe !

Support de 8192 tokens :

MiniLM : max 256 tokens   (≈ 200 lignes)
CodeBERT : max 512 tokens  (≈ 400 lignes)
Jina Code : max 8192 tokens (≈ 6000 lignes)
           ↑
    Peut encoder des fichiers entiers !

# ✅ Avantages pour mgrep

Comprend le code nativement

Sait que :
- getUserData() ≈ fetch_user_info()
- authenticate() ≈ login() ≈ sign_in()
- validateInput() ≈ check_data() ≈ verify_params()

Meilleure précision

Requête : "jwt middleware"

Jina Code trouve :
1. @jwt_required decorator
2. def verify_jwt_token()
3. JWT configuration

vs CodeBERT (mean pooling) :
1. Flask app configuration (pas lié)
2. Database init (pas lié)
3. JWT config (correct mais rank 3)

Support multilingue
- Python, JavaScript, TypeScript, Java, Go, etc.
- Comprend les patterns cross-language

# 📊 Performance estimée

Requête : "authenticate user with password"

Jina Code :
├─ Comprend : patterns d'auth dans tout langage
├─ Trouve : fonctions même avec noms différents
└─ Résultats : 90-95% de pertinence

# Comparaison des 3 approches

Critère	BERT + Mean Pooling	Natif générique	Natif code spécialisé
Exemple	CodeBERT	all-mpnet-base-v2	Jina Code
Dimensions	768	768	768
Entraîné pour recherche	❌	✅	✅
Comprend le code	✅	⚠️ Limité	✅✅
Qualité embeddings	⭐⭐	⭐⭐⭐	⭐⭐⭐⭐⭐
Message warning	✅ Oui	❌ Non	❌ Non
Contexte max	512 tokens	512 tokens	8192 tokens
Vitesse	Rapide	Rapide	Moyen
Pour mgrep	Déconseillé	Correct	Recommandé

# Test concret avec mgrep

# Setup actuel (CodeBERT + mean pooling)

$ python sgrep.py "form submission"

Résultats :

contact.py 51-100    (score: 25.97)  ← 50 lignes générique
contact.py 101-139   (score: 25.73)  ← Suite du même code
database.py          (score: 12.58)  ← Pas vraiment lié

Problèmes :

Résultats 1 et 2 devraient être fusionnés
Score 3 pas pertinent
Chunks trop gros

# Avec Jina Code (recommandé)

$ export EMBEDDING_MODEL=jinaai/jina-embeddings-v2-base-code
$ python recreate_index.py
$ python watcher.py ../host-api
$ python sgrep.py "form submission"

Résultats attendus :

handle_contact_form()  (score: 32.5)   ← Fonction précise
validate_form_data()   (score: 28.1)   ← Très pertinent
process_submission()   (score: 25.3)   ← Pertinent

Améliorations :

Fonctions spécifiques (pas des chunks génériques)
Scores plus hauts (meilleure confiance)
Tous les résultats pertinents

# Recommandations

# Pour mgrep v1 (production)

Utiliser : jinaai/jina-embeddings-v2-base-code

Raisons :

✅ Natif sentence-transformers (pas de mean pooling)
✅ Spécialisé pour code
✅ Support multi-langages
✅ Long contexte (8192 tokens)
✅ Activement maintenu

Configuration :

# Dans .env
EMBEDDING_MODEL=jinaai/jina-embeddings-v2-base-code

# Alternative acceptable

Utiliser : all-mpnet-base-v2

Si Jina Code est trop lent ou a des bugs :

✅ Stable, éprouvé
✅ Pas de mean pooling
⚠️ Moins bon pour code spécifique
⚠️ Contexte limité (512 tokens)

# À éviter (setup actuel)

CodeBERT avec mean pooling

❌ Message warning à chaque utilisation
❌ Résultats sous-optimaux
❌ Pas entraîné pour recherche

# Prochaines étapes

✅ Comprendre les différences entre modèles (ce document)
→ Tester Jina Code sur votre codebase
→ Comparer les résultats avec CodeBERT
→ Mesurer l'amélioration quantitative