Aurora RAG

Nom produit : Aurora Nexus (repo et code historiques : Aurora RAG).

Aurora RAG est une plateforme RAG premium : elle apporte aux équipes data/knowledge une chaîne complète (ingestion, gouvernance, requêtes LLM) avec le niveau d’exigence des SI critiques. Sécurité Zéro Trust, traçabilité bout en bout, dashboards localisés multi-tenant et API industrielles en font une alternative crédible aux solutions fermées – tout en restant auto-hébergée, extensible et pensée pour les environnements réglementés.

Aurora orchestre l’ingestion (Docling), la vectorisation (OpenAI embeddings), le stockage (Qdrant + MinIO) et les requêtes (OpenRouter / LLMs privés) via un backend FastAPI, une surcouche Aurora Gateway (cache LLM + observabilité BYOK) et un dashboard Next.js riche (account KPIs, upload storytelling, assistant multilingue, recherche documentaire, monitoring jobs).

🌟 Pour les dirigeants & responsables métiers

• Installation 1 clic : le wizard ops/install_wizard.py collecte la configuration, génère un .env dans ops/wizard_runs/_runs/<timestamp>/ (sans toucher au .env racine) et déploie toute la stack (API, UI, Qdrant, MinIO) en une commande.
• Interface d’administration moderne : pilotage complet des documents, permissions, packs métiers et KPI depuis un dashboard Next.js localisé (FR/EN/ES/DE/PT).
• Catégorisation & traçabilité des sources : gestion des source_apps, filtrage des documents par packs, badges sources et journalisation complète (queries_log, embeddings_log).
• Intégration rapide de vos systèmes : endpoints source_apps, documents, public_links pour connecter CRM, ATS ou référentiels internes sans développement lourd.
• Sécurité de niveau SI : secrets cloisonnés, MinIO/S3, Qdrant self-hosté, audit trail, changement de mot de passe sécurisé et contrôles d’accès fins (AccessGuard).

🛠️ Pour les équipes DevOps & data

• Stack éprouvée : FastAPI + Postgres + Qdrant + MinIO + Next.js 14 avec tests Pytest/RTL et docker compose unifié.
• Surcouche Gateway LLM : service dédié + worker Celery (refresh modèles), cache exact Postgres + cache sémantique Qdrant, BYOK providers chiffrés (Fernet) et secret interservices (GATEWAY_INTERNAL_SECRET).
• Observabilité prête à l’emploi : tableaux de bord (requêtes, cache, coût, RAGAS, Optimizer), tables d’usage (OpenRouter, embeddings), audit trail config_audit_log, feedback utilisateurs (Oui/Non + motifs) et stats associées.
• Extensibilité documentée : routers spécialisés (account, documents, preferences, public_links, source_apps), worker Docling, guides dans docs/ (admin, paramètres, troubleshooting, installation).
• Internationalisation native : next-intl, middleware locale-aware, messages synchronisés dans cinq langues, tests garantissant l’uniformité.
• Optimisation & Qualité : prompts système versionnés (prompt_template/prompt_version), tâches Celery RAGAS/Optimizer (scores, recommandations) avec tables llm_evaluation, optimizer_*, journalisation enrichie queries_log (coûts, cache, status, modèle).
• Traçabilité des applications externes : registry caller_app (applications appelantes) pour filtrer et piloter l’observabilité (queries_log) et l’ingestion (documents/batches) — voir docs/06_Domaine/40-Caller-App-Registry.md.

🏗️ Architecture

Les services applicatifs (api, ingestion, ui) sont construits localement via docker compose build. Qdrant et MinIO utilisent les images officielles.

🤖 Pourquoi ces briques ?

• LangChain – MIT : orchestrateur RAG mature (runnables, callbacks, observabilité) doté de centaines de connecteurs LLM et bases, idéal pour tracer chaque étape (retrieval, génération, logging) dans FastAPI.
• Docling – MIT : pipeline IBM open-source spécialisé dans la normalisation documentaire (PDF, scans, OCR, tables, diagrammes) avec des modèles optimisés pour la récupération de contexte.
• Qdrant – Apache‑2.0 : base vectorielle rust hautes performances, filtres payload avancés (must/should, payload indexés) et compatibilité MMR idéale pour les scénarios multi-tenant sensibles.
• MinIO – AGPL‑3.0 : stockage objet 100 % compatible S3, chiffrable, multi-site, parfait pour stocker les uploads, artefacts Docling et sauvegardes sans dépendre d’un cloud tiers.
• PostgreSQL – PostgreSQL License : base relationnelle robuste (transactions, JSONB, extensions analytiques) utilisée pour les métadonnées, journaux de coûts et préférences tenants.

Ces briques open-source, éprouvées en production, combinent sécurité, observabilité et extensibilité tout en évitant l’enfermement dans des offres propriétaires.

✅ Fonctionnalités clés

• Gateway + Cache LLM : cache exact (Postgres) et sémantique (Qdrant), modes exact|semantic|mixed|disabled, paramètres cache_settings par tenant/pack, BYOK chiffré (LLM_CREDENTIALS_ENC_KEY), secret interservices (GATEWAY_INTERNAL_SECRET).
• Prompts système versionnés : tables prompt_template / prompt_version (+ prompt_binding), résolveur central utilisé par RAGAS et Optimizer, seeds multi-langues (FR/EN/DE/ES/PT).
• Observabilité & dashboards : nouvelle page Admin “Observabilité” (requêtes, erreurs, coûts, cache, RAGAS, Optimizer), page “Requêtes” enrichie (cache_status, statut, coûts détaillés).
• Cache & Providers UI : écrans dédiés pour configurer le cache LLM (mode, TTL, seuil sémantique, max_hits) et gérer les credentials providers chiffrés + catalogue modèles OpenRouter.
• Aurora Optimizer : endpoints /api/optimizer/* (settings, run, runs, recommendations), tâches Celery qui agrègent métriques (latence p95, coût, cache, RAGAS) et produisent des recommandations versionnées.
• Ingestion augmentée : storytelling visuel, checklist formats supportés, messages MinIO contextualisés, OCR/preview pilotés via préférences tenant.
• Assistant multilingue : sélecteur de modèle OpenRouter dynamique, option “Toutes les sources”, champs élargis (max-w-6xl), badges sources colorés, KPI “Payloads Qdrant par tenant”.
• Gouvernance avancée : routes preferences, source_apps, public_links, compat Qdrant query_filter/count_filter, DocumentPublicLinksDialog.tsx, AccessGuard.tsx + usePermissions, audit config_audit_log sur réglages, cache, providers, prompts.
• Internationalisation intégrée : next-intl, ClientIntlProvider.tsx, middleware locale-aware, messages FR/EN/DE/ES/PT partagés entre UI/pages/tests.

📊 Comparatif express

📦 Prérequis

• Docker ≥ 24 & Docker Compose Plugin.
• Python ≥ 3.10 (pour exécuter le wizard ops/install_wizard.py).
• Accès à une base PostgreSQL (URL dans .env).
• Clés API :
  • OpenAI API Key (clé runtime + clé admin pour les embeddings).
  • OpenRouter API Key (clé runtime) + OpenRouter Usage API pour la facturation.
  • FreeCurrency API pour les taux EUR/USD.
  • Google Cloud OAuth Client si l’auth Google est activée.

🚀 Démarrage rapide

Option “3 commandes” (dev)

bash ops/dev_up.sh
bash ops/demo_local.sh
bash ops/dev_down.sh

Procédure standard (docker compose up -d)

⚠️ Production : ne copiez pas .env.example vers .env dans le repo.
Utilisez le wizard (recommandé) ou un fichier d’environnement hors repo (ex. /etc/aurora/prod.env, chmod 600) et démarrez avec :
docker compose --env-file /etc/aurora/prod.env up -d

1. Cloner le dépôt puis copier la configuration (de .env.example vers .env) en dev uniquement :

   git clone https://github.com/syl2042/Aurora-Nexus.git
   cd Aurora-Nexus
   cp .env.example .env

2. Compléter .env : PUBLIC_DOMAIN, NEXT_PUBLIC_API_URL (ex. https://rag.auroramind.fr ou http://127.0.0.1:18500 en local), identifiants Postgres/MinIO, clés OpenAI & OpenRouter.
3. Lancer toute la stack :

   docker compose up -d --build

   • UI disponible sur http://127.0.0.1:${HOST_UI_PORT:-13500}
   • API disponible sur http://127.0.0.1:${HOST_API_PORT:-18500}
4. Initialiser les dépendances une seule fois si vous n’utilisez pas le wizard (scripts ops/init_db.sh, ops/init_minio.py, ops/recreate_qdrant.py). init_db.sh applique automatiquement aurora_schema.sql, qui contient l’état complet du schéma public :

   bash ops/init_db.sh
   python3 ops/init_minio.py
   python3 ops/recreate_qdrant.py   # optionnel : reset de la collection

   • Postgres externe : appliquez le schéma/migrations côté DB avant de démarrer l’API (guide : docs/02_Installation/06-Postgres-Externe.md).
5. Vérifier la santé :

   curl http://127.0.0.1:${HOST_API_PORT:-18500}/api/health
   docker compose ps

   Checklist complète : docs/02_Installation/03-Install-Wizard.md#8-vérifications-post-installation.

Installation 1 clic (wizard)

git clone https://github.com/syl2042/Aurora-Nexus.git
cd Aurora-Nexus

# 1. Installer les dépendances du wizard
python3 -m venv .venv && source .venv/bin/activate   # optionnel mais conseillé
pip install -r ops/requirements.txt

# 2. Lancer l'assistant (génère un .env dans un dossier de run et lance docker compose up -d)
COMPOSE_PROJECT_NAME=aurorarag_wizard python3 ops/install_wizard.py run --project-name aurorarag_wizard

# 3. Vérifier le rapport final / relancer uniquement les healthchecks
python3 ops/install_wizard.py report

Le wizard écrit par défaut un .env dans ops/wizard_runs/_runs/<timestamp>/.env (sans toucher au .env racine), orchestre docker compose up -d --build, exécute ops/init_db.sh uniquement si Postgres est local, et vérifie /api/health. Si Postgres est externe, appliquez d’abord le schéma/migrations (guide : docs/02_Installation/06-Postgres-Externe.md).

⚠️ Ports : le wizard propose par défaut des ports “standards” (UI 3000, API 8000, …) sauf si vous les changez pendant l’assistant.
À l’inverse, le fichier .env.example fournit des ports “non‑standards” (ex. UI 13500, API 18500) pour éviter les collisions sur une machine de dev.
En prod, choisissez vos ports au moment du wizard (ou dans votre .env hors repo) pour rester cohérent avec votre reverse‑proxy.

⚙️ Variables d’environnement essentielles

Consultez [.env.example](.env.example) (synchronisé avec l’instance actuelle) pour la liste complète. Points d’attention :

• DATABASE_URL : URL Postgres (externe dans l’infra prod).
• Gateway & LLM : GATEWAY_INTERNAL_SECRET, OPENROUTER_API_KEY, OPENROUTER_BASE_URL, OPENAI_API_KEY (embeddings + cache sémantique), CACHE_EMBEDDING_SIZE, LLM_CREDENTIALS_ENC_KEY (Fernet pour BYOK).
• OPENAI_ADMIN_KEY, OPENAI_USAGE_PROJECT, OPENAI_ORGANIZATION_ID.
• FREECURRENCY_API_URL.
• DOC_OCR, DOC_GENERATE_PAGE_IMAGES : pipeline Docling.
• Workers : CELERY_TASK_DEFAULT_QUEUE=aurora_api_tasks, AURORA_GATEWAY_CELERY_QUEUE=aurora_gateway_tasks.

MinIO & console d’administration

Pour éviter les erreurs d’authentification de la console MinIO, utilisez la combinaison suivante :

• MINIO_SERVER_URL=http://minio:9000 → URL interne utilisée par la console pour signer les appels STS (AssumeRole).
• MINIO_BROWSER_REDIRECT_URL=https://console-minio.auroramind.fr → domaine public exposé par Caddy pour l’UI console (19501 → 9001).
• PUBLIC_UPLOAD_BASE_URL=https://minio.auroramind.fr → domaine public utilisé pour les URLs pré-signées (vhost distinct qui continue de réécrire Host minio:9000 pour préserver les signatures S3).

Dans Caddy, conservez deux vhosts :

minio.auroramind.fr {
    tls admin@auroramind.fr
    reverse_proxy 127.0.0.1:19500 {
        header_up Host minio:9000
        header_up X-Forwarded-Proto {scheme}
    }
}

console-minio.auroramind.fr {
    tls admin@auroramind.fr
    reverse_proxy 127.0.0.1:19501 {
        header_up X-Forwarded-Proto {scheme}
    }
}

Ainsi, la console dialogue directement avec MinIO via le réseau Docker interne, tandis que les téléchargements publics et les liens pré-signés continuent de passer par minio.auroramind.fr.

🔁 Workflows principaux

Ingestion de document

1. Upload via UI (Documents → Ajouter un document, route /{locale}/documents/upload) ou API :
   • POST /api/ingest/upload/init (presigned POST MinIO/S3)
   • upload multipart vers MinIO
   • Cas 1 (1 fichier) : POST /api/ingest/upload/commit (création documents + job d’ingestion)
   • Cas 2 (N fichiers / lot) : POST /api/ingest/upload/commit_batch (création ingestion_batches + N documents + N jobs)
     • suivi lot : GET /api/ingest/batches/{batch_id}
     • annulation lot (best-effort, annule les jobs queued) : POST /api/ingest/batches/{batch_id}/cancel
     • annulation job : POST /api/ingest/jobs/{job_id}/cancel
   • optionnel (si activé) : POST /api/ingest/url (ingestion depuis une URL)
2. Worker ingestion/ :
   • Télécharge la source depuis MinIO (uploads).
   • Conversion Docling → JSON / Markdown.
   • Découpe + embeddings → Qdrant (aurora_documents).
   • Sauvegarde artefacts (artifacts/) et métriques (embeddings_log, ingestion_jobs, ingestion_passes).
3. Métadonnées structurantes (exposées en UI et exploitables en filtres) :
   • source_app (obligatoire) : application/source des documents + contrôle d’accès (permissions).
   • workspace (optionnel) : classification “business” par source_app (ex : default, veille, support).

Requête utilisateur (avec Gateway)

1. UI envoie POST /api/query.
2. API construit la chaîne LangChain (retriever Qdrant MMR) et délègue l’appel LLM à Aurora Gateway (/internal/llm/call).
3. Gateway : vérifie la configuration cache (cache_settings), tente un hit exact puis sémantique, résout le provider (OpenRouter/BYOK) et renvoie la réponse.
4. API enrichit queries_log (cache_status, provider, modèle, coût, tokens, statut) et retourne réponse + citations à l’UI.
5. Tasks asynchrones : RAGAS (llm_evaluation) et Optimizer (optimizer_run + optimizer_recommendation) via Celery/Redis.

Notes (multi-tours / apps externes) :

• POST /api/query accepte thread_id (recommandé) pour corréler les requêtes d’une même conversation et activer les follow-ups robustes (ex: “détaille S2 / point B / 2e point”).
• Pour un comportement conversationnel “enterprise safe” sans réinjecter l’historique brut, les prompts de service peuvent terminer les livrables par un bloc SUIVI machine‑parsable (voir docs/07_Reference-Tech/52-Conversations-Followups.md).

🧩 Dépôts GitHub (DEV vs installation)

• DEV (privé) : Aurora_RAG_DEV — historique complet de travail (docs internes, assets marketing, backups, etc.).
• Installation (public) : Aurora-Nexus — dépôt “propre” pour installer/déployer (pas de .env ni d’assets internes).

📡 API Aurora Nexus (apps externes)

Voir AURORA_NEXUS_API.md.

🧰 Scripts utilitaires (ops/)

🧪 Tests & Qualité

pip install -r tests/requirements.txt
pytest tests

Tests existants :

• test_costing.py (conversion des logs OpenRouter en coûts).
• test_langchain_helper.py (initialisation chaîne RAG).

À étendre selon les évolutions (ingestion, API admin, etc.).

🛠️ Maintenance & Reset

• Reset data ingestion (Postgres/Qdrant/MinIO) : suivre le playbook interne (scripts ops/reset_environment.py, ops/recreate_qdrant.py, ops/init_* selon le périmètre). Pour Postgres, rejouer aurora_schema.sql suffit tant que vous n’avez pas appliqué de migrations additionnelles.
• Sauvegarde schéma Postgres :

  pg_dump --schema-only --no-owner --dbname=$DATABASE_URL > aurora_schema.sql

  (exécuter depuis pgAdmin ou la CLI avec les identifiants appropriés ; le dump public aurora_schema.sql correspond au schéma actuel. Les scripts de migration ne seront publiés qu’à partir de la première release nécessitant une évolution de base.)
• Purges Docker ciblées : voir plan de nettoyage (aucune purge automatique n’est exécutée).

📚 Documentation

• docs/ : guides (admin, paramètres, troubleshooting, installation).
• Index recommandé : docs/00-INDEX.md
• openapi.json : description des endpoints api/.

Une documentation développeur/API complète est en cours de consolidation (cf. étapes du plan).

🤝 Contribution

• Guide : CONTRIBUTING.md
• Respecter les conventions internes (guidelines d’ingénierie Aurora) partagées lors de l’onboarding.
• Les scripts intègrent un minimum d’hypothèses (env .env, clés via variables). Éviter toute clé en dur dans le dépôt.
• ToDo principaux : étendre les tests, finaliser la doc API, améliorer la factorisation des scripts ops/.

Aurora RAG est un dépôt public ; adapter les scripts et la configuration à votre infrastructure (Postgres, secrets, CI/CD). Pour toute question technique ou onboarding, se référer aux documents dans docs/ ou contacter l’équipe support Aurora.

🚀 Roadmap

🛣️ MVP vs V1 vs V2

MVP (actuel) – livraison prioritaire pour les 3 développeurs pilotes et les premiers clients

1. Téléchargements publics MinIO : corriger le flux UI, fiabiliser la génération/révocation des liens (document_public_links), ajouter journalisation + quotas.
2. Internationalisation & sélecteur de langue : réparer le dropdown, synchroniser INSTANCE_LOCALE/cookie NEXT_LOCALE, finaliser les traductions FR/EN/ES/PT/DE et les toasts critiques.
3. Installation & mises à jour guidées : refactor du wizard ops/install_wizard.py, page Northern “Installer Aurora”, ajout d’un manifeste de release + changelog in-app pour proposer les mises à jour.
4. Qualité & tests UI : QA responsive (chat/account/upload), complétion des tests RTL/snapshots i18n, couverture des nouveaux toasts et reporting uploaded_by.

V1 (post‑MVP) – durcissement produit + onboarding “enterprise”

• Packs métiers (installables) : installation/activation de packs (ex : Finance, Juridique, RH) incluant services, workspaces, prompts de service et réglages RAG recommandés.
• Wizard & reset : valider (et refactor si nécessaire) ops/install_wizard.py + scripts de reset/maintenance (tests de non‑régression, garde‑fous, runbook).
• Tools (tool-calling) : cadrer et implémenter une V1 “safe” (registry + exécuteur serveur + audit/permissions) afin d’activer des actions métier pilotées par l’assistant (sans exposer de composants majeurs non validés).

V2 – fonctionnalités qui suivront la MVP

• Assistant avancé (réglages, mémoire multi-tour).
• Recherche multi-domaines, hybride + cache sémantique.
• Knowledge Graph & packs RAG métiers.
• Serveur MCP Aurora + connecteurs API externes (CRM/ATS/Helpdesk).
• Monitoring des installations et télémétrie/licensing léger.