Skip to main content

Cléa-API 🚀

Hybrid document-search framework for PostgreSQL + pgvector

Licence MIT Docs

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 🤝

  1. Fork → branche (feat/ma-feature)
  2. uv run pytest && mkdocs build doivent passer
  3. 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)

Source distribution for clea-api 0.2.2
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)

Table of built distributions (wheels) for clea-api 0.2.2
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page