Hugging Face's logo

Spaces:
K2MAR
/
docuresume-backend
Sleeping

App Files Community
docuresume-backend / API_DOCUMENTATION.md
K2MAR's picture
K2MAR
Add T5 model integration for real summary generation
c43736a
preview code
|
raw
history blame contribute delete
11.9 kB

📄 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 

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

Résultat:

{
  "service": "DocuResume Pro API",
  "version": "1.0.0",
  "status": "running",
  "supabase_connected": true
}

✅ Health Check 

curl https://k2mar-docuresume-backend.hf.space/health

Résultat:

{
  "status": "healthy",
  "database": "connected",
  "timestamp": "2026-01-27T02:24:23.680960"
}

✅ Inscription Utilisateur 

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:

{
  "message": "Utilisateur créé avec succès",
  "user_id": "c703c345-e89d-4662-b87a-b01a4badc476",
  "email": "test@demo.com",
  "username": "testuser"
}

✅ Connexion Utilisateur 

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:

{
  "message": "Connexion réussie",
  "user_id": "c703c345-e89d-4662-b87a-b01a4badc476",
  "email": "test@demo.com",
  "username": "testuser"
}

✅ Statistiques Globales 

curl https://k2mar-docuresume-backend.hf.space/stats/global

Résultat:

{
  "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

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:

{
  "message": "Utilisateur créé avec succès",
  "user_id": "uuid-here",
  "email": "user@example.com",
  "username": "myusername"
}

POST /users/login

Se connecter

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:

{
  "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)

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:

{
  "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

curl https://k2mar-docuresume-backend.hf.space/documents/user/YOUR_USER_ID?limit=100

Réponse:

{
  "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

curl https://k2mar-docuresume-backend.hf.space/documents/DOC_ID

GET /documents/{document_id}/download

Télécharger un document PDF

curl -O -J https://k2mar-docuresume-backend.hf.space/documents/DOC_ID/download

PATCH /documents/{document_id}

Mettre à jour un document

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

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

curl -X POST "https://k2mar-docuresume-backend.hf.space/search/semantic?document_id=DOC_ID&query=contrat%20de%20travail&k=5"

Réponse:

{
  "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

curl -X POST "https://k2mar-docuresume-backend.hf.space/search/semantic/multi?user_id=USER_ID&query=clause%20de%20confidentialité&k=5"

Réponse:

{
  "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)

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:

{
  "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

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

curl https://k2mar-docuresume-backend.hf.space/analytics/user/USER_ID

Réponse:

{
  "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

curl https://k2mar-docuresume-backend.hf.space/stats/global

Réponse:

{
  "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

curl https://k2mar-docuresume-backend.hf.space/documents/DOC_ID/summaries

POST /documents/{document_id}/summaries

Créer un résumé pour un document

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

curl https://k2mar-docuresume-backend.hf.space/documents/DOC_ID/chunks

POST /documents/{document_id}/chunks

Créer les chunks d'un document

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 

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 

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

Exemple d'utilisation 

// 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 

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 

curl https://k2mar-docuresume-backend.hf.space/health | jq '.database'

📞 Support

📝 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