API_DOCUMENTATION.md

# 📄 DocuResume Pro API - Documentation

## 🌐 URL de l'API déployée sur Hugging Face Spaces

```
https://k2mar-docuresume-backend.hf.space
```

**Statut:** ✅ En ligne avec FAISS activé (16GB RAM)  
**Plateforme:** Hugging Face Spaces (Docker)  
**Base de données:** Supabase PostgreSQL + Storage  
**Recherche:** FAISS + Sentence-Transformers (all-MiniLM-L6-v2)

---

## 🧪 Tests Effectués (27 janvier 2026)

### ✅ Status Check
```bash
curl https://k2mar-docuresume-backend.hf.space/
```
**Résultat:**
```json
{
  "service": "DocuResume Pro API",
  "version": "1.0.0",
  "status": "running",
  "supabase_connected": true
}
```

### ✅ Health Check
```bash
curl https://k2mar-docuresume-backend.hf.space/health
```
**Résultat:**
```json
{
  "status": "healthy",
  "database": "connected",
  "timestamp": "2026-01-27T02:24:23.680960"
}
```

### ✅ Inscription Utilisateur
```bash
curl -X POST https://k2mar-docuresume-backend.hf.space/users/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@demo.com",
    "username": "testuser",
    "password": "test123"
  }'
```
**Résultat:**
```json
{
  "message": "Utilisateur créé avec succès",
  "user_id": "c703c345-e89d-4662-b87a-b01a4badc476",
  "email": "test@demo.com",
  "username": "testuser"
}
```

### ✅ Connexion Utilisateur
```bash
curl -X POST https://k2mar-docuresume-backend.hf.space/users/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@demo.com",
    "password": "test123"
  }'
```
**Résultat:**
```json
{
  "message": "Connexion réussie",
  "user_id": "c703c345-e89d-4662-b87a-b01a4badc476",
  "email": "test@demo.com",
  "username": "testuser"
}
```

### ✅ Statistiques Globales
```bash
curl https://k2mar-docuresume-backend.hf.space/stats/global
```
**Résultat:**
```json
{
  "total_users": 5,
  "total_documents": 4,
  "total_queries": 0,
  "timestamp": "2026-01-27T02:24:52.783266"
}
```

---

## 📚 Endpoints Disponibles

### 🔐 Authentification

#### POST `/users/register`
Créer un nouvel utilisateur
```bash
curl -X POST https://k2mar-docuresume-backend.hf.space/users/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "username": "myusername",
    "password": "mypassword"
  }'
```
**Réponse:**
```json
{
  "message": "Utilisateur créé avec succès",
  "user_id": "uuid-here",
  "email": "user@example.com",
  "username": "myusername"
}
```

#### POST `/users/login`
Se connecter
```bash
curl -X POST https://k2mar-docuresume-backend.hf.space/users/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "mypassword"
  }'
```
**Réponse:**
```json
{
  "message": "Connexion réussie",
  "user_id": "uuid-here",
  "email": "user@example.com",
  "username": "myusername"
}
```

---

### 📄 Gestion des Documents

#### POST `/documents/upload`
Uploader un document PDF (avec OCR Tesseract)
```bash
curl -X POST https://k2mar-docuresume-backend.hf.space/documents/upload \
  -F "file=@document.pdf" \
  -F "user_id=YOUR_USER_ID" \
  -F "tags=[]" \
  -F "document_type=rapport"
```
**Réponse:**
```json
{
  "message": "Document uploadé avec succès",
  "document_id": "doc-uuid",
  "filename": "uuid_document.pdf",
  "status": "completed",
  "pages": 5,
  "text_length": 2847,
  "faiss_indexed": true,
  "chunks": 12
}
```

#### GET `/documents/user/{user_id}`
Récupérer tous les documents d'un utilisateur
```bash
curl https://k2mar-docuresume-backend.hf.space/documents/user/YOUR_USER_ID?limit=100
```
**Réponse:**
```json
{
  "documents": [
    {
      "id": "doc-uuid",
      "filename": "document.pdf",
      "original_filename": "Mon Document.pdf",
      "file_size": 245678,
      "page_count": 5,
      "processing_status": "completed",
      "uploaded_at": "2026-01-27T00:00:00"
    }
  ],
  "count": 1
}
```

#### GET `/documents/{document_id}`
Récupérer les détails d'un document
```bash
curl https://k2mar-docuresume-backend.hf.space/documents/DOC_ID
```

#### GET `/documents/{document_id}/download`
Télécharger un document PDF
```bash
curl -O -J https://k2mar-docuresume-backend.hf.space/documents/DOC_ID/download
```

#### PATCH `/documents/{document_id}`
Mettre à jour un document
```bash
curl -X PATCH https://k2mar-docuresume-backend.hf.space/documents/DOC_ID \
  -H "Content-Type: application/json" \
  -d '{
    "tags": ["important", "contrat"],
    "is_archived": false
  }'
```

#### DELETE `/documents/{document_id}`
Supprimer un document
```bash
curl -X DELETE https://k2mar-docuresume-backend.hf.space/documents/DOC_ID
```

---

### 🔍 Recherche Sémantique (FAISS)

#### POST `/search/semantic`
Recherche sémantique dans un document spécifique
```bash
curl -X POST "https://k2mar-docuresume-backend.hf.space/search/semantic?document_id=DOC_ID&query=contrat%20de%20travail&k=5"
```
**Réponse:**
```json
{
  "document_id": "doc-uuid",
  "query": "contrat de travail",
  "results": [
    {
      "text": "Le contrat de travail à durée indéterminée...",
      "score": 0.87,
      "chunk_index": 3,
      "document_id": "doc-uuid"
    }
  ],
  "count": 5
}
```

#### POST `/search/semantic/multi`
Recherche sémantique dans tous les documents d'un utilisateur
```bash
curl -X POST "https://k2mar-docuresume-backend.hf.space/search/semantic/multi?user_id=USER_ID&query=clause%20de%20confidentialité&k=5"
```
**Réponse:**
```json
{
  "user_id": "user-uuid",
  "query": "clause de confidentialité",
  "results": [
    {
      "text": "Article 5 - Confidentialité...",
      "score": 0.92,
      "chunk_index": 8,
      "document_id": "doc-uuid-1"
    },
    {
      "text": "Les parties s'engagent à...",
      "score": 0.85,
      "chunk_index": 2,
      "document_id": "doc-uuid-2"
    }
  ],
  "count": 5,
  "searched_documents": 3
}
```

#### POST `/query`
RAG - Poser une question sur un document (avec contexte)
```bash
curl -X POST https://k2mar-docuresume-backend.hf.space/query \
  -H "Content-Type: application/json" \
  -d '{
    "document_id": "DOC_ID",
    "query": "Quelle est la durée du contrat?"
  }'
```
**Réponse:**
```json
{
  "query": "Quelle est la durée du contrat?",
  "response": "Basé sur le document, voici les passages pertinents:\n\nLe contrat est conclu pour une durée de...",
  "sources": [
    {
      "text": "Article 2 - Durée: Le présent contrat...",
      "score": 0.91
    }
  ],
  "query_id": "query-uuid"
}
```

#### GET `/query/history/{user_id}`
Historique des questions d'un utilisateur
```bash
curl https://k2mar-docuresume-backend.hf.space/query/history/USER_ID?limit=50
```

---

### 📊 Statistiques et Analytics

#### GET `/analytics/user/{user_id}`
Analytics d'un utilisateur
```bash
curl https://k2mar-docuresume-backend.hf.space/analytics/user/USER_ID
```
**Réponse:**
```json
{
  "user_id": "user-uuid",
  "analytics": {
    "total_documents": 12,
    "total_queries": 45,
    "total_summaries": 8,
    "total_storage_mb": 15.6,
    "last_activity": "2026-01-27T02:00:00"
  }
}
```

#### GET `/stats/global`
Statistiques globales de la plateforme
```bash
curl https://k2mar-docuresume-backend.hf.space/stats/global
```
**Réponse:**
```json
{
  "total_users": 156,
  "total_documents": 892,
  "total_queries": 3421,
  "timestamp": "2026-01-27T02:24:52.783266"
}
```

---

### 📝 Résumés

#### GET `/documents/{document_id}/summaries`
Récupérer les résumés d'un document
```bash
curl https://k2mar-docuresume-backend.hf.space/documents/DOC_ID/summaries
```

#### POST `/documents/{document_id}/summaries`
Créer un résumé pour un document
```bash
curl -X POST https://k2mar-docuresume-backend.hf.space/documents/DOC_ID/summaries \
  -H "Content-Type: application/json" \
  -d '{
    "summary_type": "extractive",
    "summary_level": "medium",
    "content": "Résumé du document...",
    "model_name": "t5-small"
  }'
```

---

### 📦 Chunks

#### GET `/documents/{document_id}/chunks`
Récupérer les chunks d'un document
```bash
curl https://k2mar-docuresume-backend.hf.space/documents/DOC_ID/chunks
```

#### POST `/documents/{document_id}/chunks`
Créer les chunks d'un document
```bash
curl -X POST https://k2mar-docuresume-backend.hf.space/documents/DOC_ID/chunks \
  -H "Content-Type: application/json" \
  -d '[
    {
      "content": "Premier paragraphe du document...",
      "page_number": 1,
      "section_title": "Introduction"
    }
  ]'
```

---

## 🔧 Configuration Technique

### Variables d'Environnement sur HF Spaces
```bash
SUPABASE_URL=https://kbccbdqdrdfdvxhugjrn.supabase.co
SUPABASE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
ENABLE_FAISS=true
```

### Stack Technique
- **Framework:** FastAPI 0.115.12
- **Base de données:** Supabase (PostgreSQL + Storage)
- **Recherche vectorielle:** FAISS (faiss-cpu 1.8.0)
- **Embeddings:** Sentence-Transformers 2.7.0 (all-MiniLM-L6-v2)
- **OCR:** Tesseract + Poppler-utils
- **Hébergement:** Hugging Face Spaces (Docker, 16GB RAM)

### Modèles de Machine Learning
- **Embeddings:** `all-MiniLM-L6-v2` (384 dimensions)
- **OCR:** Tesseract (français + anglais)
- **Chunking:** 500 caractères avec overlap de 50

---

## 🚀 Utilisation depuis une Application Mobile (Flutter)

### Configuration
```dart
class ApiConfig {
  static const String baseUrl = 'https://k2mar-docuresume-backend.hf.space';
  
  static Map<String, String> headers = {
    'Content-Type': 'application/json',
  };
}
```

### Exemple d'utilisation
```dart
// Connexion
final response = await http.post(
  Uri.parse('${ApiConfig.baseUrl}/users/login'),
  headers: ApiConfig.headers,
  body: jsonEncode({
    'email': 'user@example.com',
    'password': 'password123'
  })
);

// Upload document
var request = http.MultipartRequest(
  'POST', 
  Uri.parse('${ApiConfig.baseUrl}/documents/upload')
);
request.files.add(await http.MultipartFile.fromPath('file', pdfPath));
request.fields['user_id'] = userId;
request.fields['tags'] = '[]';
var response = await request.send();

// Recherche sémantique
final response = await http.post(
  Uri.parse('${ApiConfig.baseUrl}/search/semantic/multi?user_id=$userId&query=$query&k=5')
);
```

---

## 🔒 Sécurité

- ✅ CORS activé pour tous les domaines (à restreindre en production)
- ✅ Mots de passe hashés avec bcrypt
- ✅ Connexion sécurisée à Supabase
- ✅ Variables d'environnement stockées dans HF Secrets
- ⚠️ Ajouter un système d'authentification JWT pour production

---

## 📈 Limites et Quotas

| Ressource | Limite |
|-----------|--------|
| RAM | 16 GB |
| CPU | Partagé |
| Stockage | Illimité (Supabase) |
| Taille fichier | Configurable (actuellement ~10MB) |
| Requêtes/min | Illimité |

---

## 🐛 Debugging

### Vérifier le statut de FAISS
```bash
curl https://k2mar-docuresume-backend.hf.space/ | jq '.service, .status'
```

### Consulter les logs sur Hugging Face
1. Aller sur https://huggingface.co/spaces/K2MAR/docuresume-backend
2. Onglet "Logs"
3. Chercher "✓ FAISS activé et prêt"

### Tester la connexion Supabase
```bash
curl https://k2mar-docuresume-backend.hf.space/health | jq '.database'
```

---

## 📞 Support

- **GitHub:** [Votre repo]
- **Hugging Face Space:** https://huggingface.co/spaces/K2MAR/docuresume-backend
- **Email:** [Votre email]

---

## 📝 Notes de Version

### v1.0.0 (27 janvier 2026)
- ✅ Déploiement initial sur Hugging Face Spaces
- ✅ FAISS activé avec 16GB RAM
- ✅ OCR Tesseract pour extraction de texte
- ✅ Recherche sémantique multi-documents
- ✅ Système RAG basique
- ✅ Connexion Supabase PostgreSQL + Storage
- ✅ CORS activé pour intégration mobile

---

## 🎯 Roadmap

- [ ] Authentification JWT
- [ ] Génération de résumés avec T5/BART
- [ ] Support multi-langues
- [ ] Webhooks pour notifications
- [ ] Cache Redis pour performances
- [ ] Rate limiting
- [ ] Documentation Swagger interactive
- [ ] Tests unitaires et d'intégration