Cléa-API 🚀
Hybrid document-search framework for PostgreSQL + pgvector
Cléa-API charge des documents multi-formats, les segmente, les vectorise et fournit une recherche hybride (vectorielle + filtres SQL) prête à l'emploi. Il s'utilise :
- via endpoints REST (FastAPI) ;
- en librairie Python (extraction, pipeline, recherche) ;
- avec une base PostgreSQL + pgvector auto-indexée par corpus ;
- 100% local et hors-ligne pour vos données sensibles.
Sommaire rapide
| Sujet | Documentation |
|---|---|
| Chargement & extraction | Extracteurs · Segmentation |
| Base de données & index vectoriels | Database |
| Moteur de recherche hybride | Search |
| Pipeline end-to-end | Pipeline |
| Référence API Python (autogen) | Doc Loader · Vectordb · Pipeline |
| IA génératrice (RAG) | AskAI |
| Stats | Stats |
| OpenAPI / Endpoints REST | REST API |
Caractéristiques clés
-
🔒 100% local & hors-ligne : traitement sécurisé pour données confidentielles
-
🔄 Chargement multi-formats : PDF, DOCX, HTML, JSON, TXT, …
-
🧩 Segmentation hiérarchique : Section ▶ Paragraphe ▶ Chunk
-
🔍 Recherche hybride : ivfflat ou HNSW + Cross-Encoder rerank
-
🤖 RAG avec petits LLMs : génération augmentée via modèles Qwen3 légers
-
⚡ Pipeline "one-liner" :
from pipeline import process_and_store from askai.src.rag import RAGProcessor # Traitement de documents process_and_store("rapport.pdf", theme="R&D") # Interrogation des documents via RAG response, context = rag_processor.retrieve_and_generate( "Quelles sont les principales recommandations du rapport?" )
-
📦 Architecture modulaire : ajoutez un extracteur ou un modèle en quelques lignes
-
🐳 Docker-ready & CI-friendly (tests PyTest, docs MkDocs)
Options de lancement
Cléa-API supporte plusieurs modes de lancement avec différentes options de configuration:
# Mode standard
./start.sh
# Mode développeur avec logs détaillés
uv run main.py --debug
# Configuration avancée
uv run main.py --host 0.0.0.0 --port 9000 --workers 4
# Avec variables d'environnement
API_LOG_LEVEL=debug API_PORT=9000 ./start.sh
Niveaux de journalisation
Le système de logs est centralisé et configurable:
| Mode | Description | Commande |
|---|---|---|
| INFO (défaut) | Informations essentielles | uv run main.py |
| DEBUG | Détails techniques | uv run main.py --debug |
| WARN/ERROR | Uniquement alertes et erreurs | API_LOG_LEVEL=warning uv run main.py |
Les logs suivent le format standard:
2025-05-04 16:30:21,483 - clea-api.doc_loader - INFO - Document chargé: demo.pdf (3.2MB)
Arborescence du dépôt
.
├── doc_loader/ # Extraction & chargement de documents
├── vectordb/ # Modèles SQLAlchemy + recherche
├── pipeline/ # Orchestrateur end-to-end
├── askai/ # Génération RAG avec modèles légers
├── docs/ # Documentation MkDocs
├── demo/ # Fichiers d'exemple
├── models/ # Models de traitement
├── start.sh # Script de démarrage API
├── Dockerfile # Build image
└── ...
Installation
Prérequis
- Python ≥ 3.11
- PostgreSQL ≥ 14 avec l'extension pgvector
- (Recommandé) WSL 2 + openSUSE Tumbleweed
Installation sur openSUSE Tumbleweed
# 1. Installer les dépendances système
sudo zypper install postgresql15 postgresql15-server postgresql15-devel python311 python311-devel gcc
# 2. Activer PostgreSQL
sudo systemctl enable postgresql
sudo systemctl start postgresql
# 3. Installer uv (gestionnaire de paquets Python moderne)
curl -sSf https://astral.sh/uv/install.sh | sh
Installation de Cléa-API
# 1. Cloner
git clone https://github.com/<your-gh-user>/clea-api.git
cd clea-api
# 2. Dépendances (avec uv)
uv pip install -r requirements.txt
# 3. Pour le module askai (optionnel)
uv pip install -r askai/requirements_askai.txt
# 4. Variables d'environnement
cp .env.sample .env # puis éditez au besoin
# 5. Initialisation DB et extension pgvector
uv python -m vectordb.src.database init_db
# 6. Lancer l'API
uv run main.py # ➜ http://localhost:8080
Utilisation express
Chargement simple
curl -X POST http://localhost:8080/doc_loader/upload-file \
-F "file=@demo/devis.pdf" -F "theme=Achat"
Pipeline complet (upload → segment → index)
curl -X POST http://localhost:8080/pipeline/process-and-store \
-F "file=@demo/devis.pdf" -F "theme=Achat" -F "max_length=800"
Recherche hybride
curl -X POST http://localhost:8080/search/hybrid_search \
-H "Content-Type: application/json" \
-d '{"query":"analyse risques", "top_k":8}'
Génération RAG (AskAI)
curl -X POST http://localhost:8080/askai/query \
-H "Content-Type: application/json" \
-d '{
"question": "Résumer les points importants du document",
"theme": "Achat",
"enable_thinking": true
}'
Utilisation en mode streaming
curl -N -X POST http://localhost:8080/askai/query_stream \
-H "Content-Type: application/json" \
-d '{"question": "Expliquer la structure du document"}'
Sécurité et confidentialité
Cléa-API est conçu pour traiter des données sensibles et confidentielles avec une approche orientée sécurité:
- 100% hors-ligne: aucune donnée n'est envoyée vers des services externes
- Modèles légers locaux: tous les LLMs sont exécutés localement (Qwen3-0.6B/1.7B)
- Aucune télémétrie: pas de tracking ni d'analytics
- Aucune dépendance cloud: fonctionne en environnement air-gapped
Cette approche est idéale pour les organisations avec des contraintes strictes de confidentialité (données médicales, financières, juridiques, etc.).
Tests
uv run pytest # tous les tests unitaires
Déploiement Docker
docker build -t clea-api .
docker run -p 8080:8080 clea-api
Contribuer 🤝
- Fork → branche (
feat/ma-feature) uv run pytest && mkdocs builddoivent passer- Ouvrez une Pull Request claire et concise
Licence
Distribué sous licence MIT – voir LICENSE.
Metadata
Release files for clea-api 0.2.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| clea_api-0.2.2.tar.gz | 8.5 kB | Without provenance | Details for clea_api-0.2.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| clea_api-0.2.2-py3-none-any.whl | Python 3 | none | any | Details for clea_api-0.2.2-py3-none-any.whl |
Total release size: 17.5 kB
Release files / clea_api-0.2.2.tar.gz
| Download URL | clea_api-0.2.2.tar.gz |
|---|---|
| Size | 8.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
67d1bbdc7b00840402d891e055e2a64a1f3af43863f5082df0ba9ae578949cc1
|
|
BLAKE2b-256 checksum How to use checksums |
0eb09b0b3ca5f4c0af919038a6ba403c88d7705c14aa6f737f15ac03f0cceffa
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.6.16
|
Release files / clea_api-0.2.2-py3-none-any.whl
| Download URL | clea_api-0.2.2-py3-none-any.whl |
|---|---|
| Size | 9.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b78ed30a80f5589b2283c8de7e8c3516d919fc4e78bd7eab7f8fcf3076d96687
|
|
BLAKE2b-256 checksum How to use checksums |
15dc8120a283b0fb3aa9a94841ddbef9c60a13b941ae2d17b58e846d4926c646
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.6.16
|
Security for clea-api 0.2.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.