deployment_instructions.md

# 🚀 Instructions de déploiement - Smart Chunker v4.0

## 📋 Étapes à suivre

### 1. **Remplacement des fichiers**
Remplace les fichiers suivants dans ton projet par les versions corrigées :

```bash
# Fichiers à remplacer
├── chunker_pipeline.py    # ✅ Version corrigée avec CustomRecursiveChunker
├── requirements.txt       # ✅ Dépendances compatibles épinglées
├── app.py                # ✅ API FastAPI mise à jour
└── custom_recursive_chunker.py  # ✅ Nouveau fichier à ajouter
```

### 2. **Garde les fichiers existants**
Ces fichiers restent inchangés :
- `config.yaml` ✅ (déjà compatible)
- `schemas.py` ✅ (déjà compatible)
- `Dockerfile` (si nécessaire)

### 3. **Structure finale du projet**
```
ton_projet/
├── app.py                      # ✅ API FastAPI corrigée
├── chunker_pipeline.py         # ✅ Pipeline principal corrigé
├── custom_recursive_chunker.py # ✅ NOUVEAU - Chunker personnalisé
├── requirements.txt            # ✅ Dépendances mises à jour
├── config.yaml                # ✅ Configuration existante (OK)
├── schemas.py                 # ✅ Schémas existants (OK)
└── Dockerfile                 # ✅ Si nécessaire
```

## 🔧 Changements principaux

### ✅ Chunker personnalisé au lieu de chonkie instable
- Plus de problèmes avec `separators=` ou `chunk_sizes=`
- Logique récursive native et contrôlée
- Compatible avec toutes les versions

### ✅ Embeddings corrigés
- `EmbeddingWrapper` pour compatibilité LlamaIndex
- Plus d'erreurs `encode()` 
- SentenceTransformer utilisé directement

### ✅ Imports simplifiés
- Import seulement de `SemanticChunker` depuis chonkie (optionnel)
- Plus de dépendances sur des modules instables
- Fallback automatique si chonkie indisponible

## 🧪 Test de fonctionnement

Après déploiement, teste avec :

```bash
# 1. Health check
curl -X GET "http://localhost:7860/health"

# 2. Test simple
curl -X POST "http://localhost:7860/test"

# 3. Chunking personnalisé
curl -X POST "http://localhost:7860/chunk" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Ton texte à chunker ici...",
    "method": "custom_recursive",
    "export_obsidian": true,
    "metadata": {"title": "Test Document"}
  }'
```

## 📊 Méthodes disponibles

1. **`custom_recursive`** (recommandée) - Chunker intelligent personnalisé
2. **`chonkie_semantic`** (si chonkie disponible) - Chunking sémantique
3. **`llamaindex`** (fallback) - Chunking standard LlamaIndex

## 🔍 Vérifications de debug

Si problèmes persistent :

### 1. Vérifier les logs d'initialisation
```bash
# Recherche ces lignes dans les logs :
✅ CustomRecursiveChunker initialisé avec succès
✅ SmartChunkerPipeline v4.0 initialisé avec succès
✅ Pipeline initialisé avec succès
```

### 2. Endpoint de diagnostic
```bash
GET /config  # Configuration active
GET /methods # Méthodes disponibles
GET /health  # État détaillé des composants
```

### 3. Test minimal
```python
# Test local rapide
import asyncio
from chunker_pipeline import SmartChunkerPipeline

async def test():
    pipeline = SmartChunkerPipeline()
    await pipeline.initialize()
    chunks = await pipeline.chunk_text("Test simple", method="custom_recursive")
    print(f"✅ {len(chunks)} chunks générés")

asyncio.run(test())
```

## 🎯 Avantages de cette solution

### ✅ **Stabilité**
- Plus de dépendances sur des versions instables de chonkie
- Chunker personnalisé 100% maîtrisé
- Compatibilité garantie avec LlamaIndex v0.12

### ✅ **Fonctionnalités complètes**
- Chunking récursif hiérarchique intelligent
- Relations parent-enfant automatiques
- Embeddings sémantiques intégrés
- Export Obsidian formaté

### ✅ **Performance**
- Optimisé pour HuggingFace Spaces
- Modèles légers (CPU-friendly)
- Cache intelligent des embeddings

### ✅ **Flexibilité**
- 3 méthodes de chunking disponibles
- Configuration modulaire via YAML
- API RESTful complète

## 🚨 Points d'attention

1. **Première initialisation** peut prendre 1-2 minutes (téléchargement modèles)
2. **Mémoire requise** : ~2GB RAM pour les modèles
3. **CPU uniquement** sur HF Spaces gratuits (normal)
4. **Cache des modèles** : utilise le répertoire temporaire

## 📞 Support

Si tu rencontres des erreurs après déploiement :

1. **Copie les logs complets** (surtout les lignes avec ❌)
2. **Teste l'endpoint** `/health` pour diagnostic
3. **Vérifie** que tous les fichiers sont bien remplacés
4. **Confirme** la version Python (3.10+ recommandée)

---

🎉 **Cette solution devrait résoudre définitivement tous les problèmes identifiés dans ta discussion avec GPT !**