QualiCheck

Application web d'aide à l'audit qualité web basée sur le référentiel Opquast (245 règles). Les agents LLM assistent l'auditeur à chaque étape — génération de constats, dialogue, question libre — sans jamais se substituer à sa décision finale.

Projet fil rouge de la certification RNCP37827 — Développeur IA agentique, réalisé avec le soutien d'Élie Sloïm (fondateur d'Opquast).

---

Fonctionnalités

• US0 — Ingestion : import des 245 règles Opquast (API + scraping), enrichissement par agent LLM, vectorisation et indexation pgvector
• US1 — Audit assisté : crawl léger, sélection de pages et de règles, génération de constats, dialogue et validation humaine, rapport final
• US2 — Question libre : RAG sémantique pur sur une URL ou une capture d'écran, guardrails, mémoire de session

---

Stack technique

Composant	Technologie
Backend	FastAPI (Python)
Frontend	Vue.js
Base de données	PostgreSQL + pgvector (HNSW, 1536 dim)
Migrations	Alembic
Gestion des dépendances	uv
LLM (dev)	Kimi K2.6, gpt-5.4, gpt-5.4-mini via Azure
LLM (prod)	Apertus-70B, Mistral Small via Infomaniak
Embedding (actuel)	text-embedding-3-small via Azure
Embedding (cible)	BGE Multilingual Gemma2 via Infomaniak (quand disponible)
Déploiement	Docker + docker-compose

---

Lancer le projet

Séquence vérifiée sur une installation neuve (clone de dev, base vide) le 2026-10-05 : docs/developpement/installation_vierge_2026-10-05.md.

Prérequis

• Docker + docker-compose
• Python 3.11+ avec uv
• Un fichier .env à la racine : copier .env.example, puis remplir les secrets. Un jeton de l'API des règles se génère avec python3 -c "import secrets; print(secrets.token_urlsafe(32))" (docs/developpement/creation_cle_api_regles.md).

uv sync
cp .env.example .env    # puis remplir les secrets

1. Démarrer la base de données

make up-db    # PostgreSQL + pgvector, accessible sur localhost:8832

2. Créer les schémas

uv run python scripts/migration.py    # base du référentiel (silencieux s'il réussit)
make migration-metier                 # crée puis migre la base métier

3. Créer les comptes PostgreSQL des deux API

Chaque API se connecte avec son propre compte, non superutilisateur. Le script pose aussi les droits sur les bases de test déclarées dans .env : elles doivent exister d'abord.

make migration-test           # base de test du référentiel
make migration-metier-test    # base de test métier
make comptes-bdd

4. Importer le référentiel : ingestion, puis enrichissement

Deux étapes, lancées à part : l'ingestion collecte et stocke les règles, l'enrichissement écrit ensuite un guide d'analyse par règle. Détail : conception/2_us0/ingestion/ingestion.md ; aide : make help ingestion.

Dépendances : Python et les paquets de uv sync, la base démarrée et migrée (étapes 1 et 2), et dans .env :

• OPQUAST_API_BASE_URL et OPQUAST_SITE_BASE_URL : les deux sources (API REST et site Opquast, lu par scraping) ;
• AZURE_AI_ENDPOINT et AZURE_AI_API_KEY : le fournisseur des modèles ;
• les variables des deux modèles, nommées par env_var dans app/ingestion/config.yml (rôles embedding et enrichissement).

Étape 1 — ingestion (scripts/ingestion.py) : API et scraping, agrégation, vecteur de chaque règle (modèle d'embedding, payant), stockage, puis sauvegarde dans backups/. La première erreur arrête tout, rien n'est stocké.

make ingestion            # les 245 règles
make ingestion LIMIT=3    # les 3 premières, pour essayer

Sur une base déjà remplie, la commande demande :

• m (mise à jour) : les règles collectées sont mises à jour par leur numéro, leurs guides d'analyse et leur revue restent ;
• n puis y (nouvelle ingestion) : le référentiel est vidé, guides compris.

Étape 2 — enrichissement (scripts/enrichissement.py) : un appel au modèle par règle (payant), sauvegarde avant et après. Chaque guide est écrit dès qu'il est produit : relancer reprend les règles sans guide, sans repayer les autres.

make enrichissement               # les règles sans guide
make enrichissement REGLES=3,69   # ces règles seules, guide remplacé

Après la revue humaine des guides : make enrich-again ré-enrichit les règles renvoyées, avec la note de l'expert (uv run python scripts/enrich_again.py --dry-run pour voir lesquelles, sans appeler le modèle).

Sauvegarder et restaurer le référentiel :

make export_sql                          # écrit backups/AAAAMMJJ_HHMMSS.sql
make import_sql FILE=backups/<fichier>.sql   # sur une base vide : import_sql ne vide rien

5. Lancer les deux API

make up    # API des règles (port 8880) et API business (port 8882)

Vérifier http://localhost:8880/health et http://localhost:8882/health (statut ok, base ok). L'API business met quelques secondes à démarrer (chargement du modèle d'anonymisation).

6. Créer un compte utilisateur de l'API business

make comptes ARGS="creer --nom Dupont --prenom Jean --email jean@exemple.fr"

Le jeton n'est affiché qu'une fois. Il permet d'appeler POST /questions (exemples dans http/).

Lister les comptes (état et fin de validité du jeton, jamais d'empreinte) : make comptes ARGS=lister.

Logs

Un fichier par contexte d'exécution, dans logs/ :

Fichier	Écrit par
ingestion.log	pipeline de données (ingestion, enrich-again, embed-rules, clear)
tests.log	scripts d'acceptance et de mesure (tests/acceptance/, tests/mesures/)
api_regles.log	conteneur api-regles
questions_libres.log	conteneur api-business (agent US2)

---

API de revue du référentiel (api_regles)

Service séparé du produit d'audit (US0-US2) : pas une fonctionnalité de plus, un étage de données à part, avec son propre persona (un expert Opquast qui corrige une classification), sa propre frontière de service et sa propre authentification. Justification complète : jury/decisions/2026-07-28-separation-api-regles-api-audit.md.

Permet à un tiers externe (le formateur, Élie Sloïm — fondateur d'Opquast) d'annoter la classification strategie_analyse du référentiel enrichi sans passer par psql :

• GET /regles (filtrable par outil/review_status), GET /regles/{numero} — lecture ouverte, sans jeton
• PATCH /regles/{numero} — pose ou retire une annotation de revue (review_status/review_note), protégé par jeton Bearer
• Documentation interactive : http://localhost:8880/docs

Authentification — un jeton par client nommé (pas un compte utilisateur complet), déclaré dans app/api_regles/config.yml (section des clients) et lu depuis .env : dev, elie-sloim, david-legrand, formateur. Solution volontairement provisoire et manuelle — détail et justification : jury/decisions/2026-07-28-cle-valeur-multi-clients-api-regles.md.

Exécution — tourne en permanence via docker compose up -d (service api-regles, port 8880), pas de commande séparée à retenir. Logs dans logs/api_regles.log (démarrage, authentifications refusées, annotations avec le nom du client). Suite d'acceptance sur données réelles : make api-regles-acceptance (API démarrée requise).

Licence du contenu servi : voir Licence — attribution CC BY-SA 4.0 portée directement par l'API (license_info OpenAPI).

---

Architecture IA

QualiCheck mobilise trois usages distincts du RAG :

US	Mode	Justification
US1 — génération	SQL déterministe	Règles connues, sélectionnées par l'auditeur
US1 — dialogue	SQL déterministe	Contexte d'audit connu, constats posés
US2 — question libre	RAG sémantique pur	Pas de présélection, pgvector cherche les règles pertinentes

La feedback loop collecte les validations et rejets des auditeurs (validation_humaine, feedback_auditeur) pour alimenter une ré-ingestion ciblée en post-MVP.

---

Positionnement éthique

• Souveraineté numérique : production hébergée chez Infomaniak (Suisse), hors Cloud Act américain
• Éco-conception : embedding léger (33M paramètres), pas de base vectorielle externe, infrastructure 100% renouvelable
• IA non décisionnaire : l'agent propose, l'auditeur valide — toujours

---

Structure du projet

app/            # Domaine métier (models, migration, ingestion)
app/api_regles/ # API de revue du référentiel (voir section dédiée ci-dessus)
conception/     # Documents de conception (specs, MCD, flux)
scripts/        # Points d'entrée CLI (migration.py, ingestion.py)
logs/           # Logs d'exécution
docker-compose.yml
Dockerfile      # Image de l'API de revue (service api-regles)

---

Branches

Branche	Rôle
main	Stable, destinée à la production — pas encore déployée
dev	Branche de travail courante, tout le développement s'y fait au fil de l'eau
staging	Préproduction, déployée automatiquement (cd-staging.yml) au merge d'une PR dev → staging
veille	Veille technique personnelle, hors périmètre du produit

Branche par défaut sur Gitea (git.david-legrand.fr/david/qualicheck) : dev. main n'a pas encore reçu les ~290 commits de dev (rien n'est déployé en production) — quiconque ouvre ce dépôt sans préciser de branche doit voir l'état réel du projet, pas un squelette figé au setup initial.

---

Licence

Le code source est un logiciel libre, sous AGPL-3.0. Le référentiel Opquast enrichi est diffusé sous CC BY-SA 4.0 — attribution et partage à l'identique. La conception, les maquettes et la documentation sont aussi sous CC BY-SA 4.0. Texte de référence : LICENSE ; détail des trois licences : LICENCE.md.

Ce projet pédagogique bénéficie en outre du soutien d'Élie Sloïm (fondateur d'Opquast), qui légitime l'usage expérimental du référentiel et du serveur MCP dans le cadre de la certification — ce que la licence seule ne couvre pas.