← Documentation API Reference

Self-Audit et Auto-Réparation AISIA

Version : 4.15.0 Société : AISIA — Structure juridique en cours de création URL publique : https://aisia.fr/

---

Table des matières

1. Vue d'ensemble 2. Self-Audit : GET /admin/self-audit 3. Self-Repair : POST /admin/self-repair 4. Auto-Test par LLM : POST /admin/auto-test 5. Health Monitor continu 6. Scores et interprétation 7. Architecture du système d'audit 8. Tâche de maintenance : self-audit automatique 9. Intégration avec le monitoring 10. Diagnostics avancés 11. Bonnes pratiques 12. Référence API complète

---

1. Vue d'ensemble

AISIA dispose de trois mécanismes d'auto-diagnostic et d'auto-réparation complémentaires :

Mécanisme	Endpoint	Déclenchement	Description
Self-Audit	`GET /admin/self-audit`	Manuel ou automatique (1h)	Diagnostic complet de la plateforme
Self-Repair	`POST /admin/self-repair`	Manuel	Réparation automatique basée sur le self-audit
Auto-Test	`POST /admin/auto-test`	Manuel	Test fonctionnel complet par LLM

En complément, le Health Monitor continu vérifie périodiquement la disponibilité des providers et des dépendances (MariaDB, Redis, Qdrant).

Tous ces endpoints sont protégés par Depends(get_admin_user) et nécessitent un token JWT admin.

---

2. Self-Audit : GET /admin/self-audit

Description

Le self-audit exécute un diagnostic complet et automatique de la plateforme AISIA. Il vérifie tous les composants critiques et produit un rapport JSON structuré avec un score global.

Appel

curl -H "Authorization: Bearer TOKEN_ADMIN" \
  https://aisia.fr/admin/self-audit

Composants vérifiés

Le self-audit inspecte les éléments suivants :

#### 1. Services Docker

Vérification que tous les services Swarm sont en cours d'exécution :

aisia_api (14 replicas attendues)
aisia_bot (1 replica)
aisia_ollama (3 replicas)
aisia-core_mariadb
aisia-core_redis
aisia-core_qdrant
aisia-core_prometheus
aisia-core_grafana

#### 2. Endpoints API

Test de chaque endpoint critique :

GET /health : état général
GET /v1/providers : liste des providers (attendu >50)
GET /v1/local-models : modèles locaux (attendu >40)
GET /openapi.json : spécification OpenAPI (attendu >60 paths)

#### 3. Base de données MariaDB

Connectivité : SELECT 1
Tables existantes : vérification des tables aisia_*
Intégrité : comptage des enregistrements dans les tables critiques

#### 4. Modèles Ollama

Liste des modèles disponibles via /api/tags
Vérification de la disponibilité des modèles prioritaires

#### 5. Connectivité Redis

PING Redis
Vérification des clés critiques (bandit, circuit breakers)

#### 6. Connectivité Qdrant

Liste des collections
Comptage des points par collection

Structure du rapport

{
  "audit_at": "2026-04-19T10:30:00Z",
  "score": 92,
  "total_checks": 50,
  "passed": 46,
  "failed": 4,
  "sections": {
    "docker_services": {
      "checks": [...],
      "passed": 8,
      "total": 8
    },
    "api_endpoints": {
      "checks": [...],
      "passed": 12,
      "total": 14
    },
    "database": {
      "checks": [...],
      "passed": 10,
      "total": 10
    },
    "ollama": {
      "checks": [...],
      "passed": 6,
      "total": 8
    },
    "redis": {
      "checks": [...],
      "passed": 5,
      "total": 5
    },
    "qdrant": {
      "checks": [...],
      "passed": 5,
      "total": 5
    }
  },
  "warnings": ["..."],
  "critical": ["..."],
  "elapsed_ms": 4500
}

Configuration

La variable d'environnement AISIA_SELF_AUDIT_URL permet de spécifier l'URL de base pour les tests internes (défaut : http://127.0.0.1:8000).

En mode container, l'API est accessible en localhost. En mode externe, il faut spécifier l'URL publique.

---

3. Self-Repair : POST /admin/self-repair

Description

Le self-repair exécute des actions correctives automatiques basées sur le diagnostic du self-audit. Il tente de réparer les problèmes détectés sans intervention manuelle.

Appel

curl -X POST -H "Authorization: Bearer TOKEN_ADMIN" \
  https://aisia.fr/admin/self-repair

Actions correctives

Le self-repair peut effectuer les actions suivantes :

#### Tables de base de données manquantes

Si des tables aisia_* sont absentes, elles sont recréées automatiquement via les DDL idempotents (CREATE TABLE IF NOT EXISTS) :

aisia_users : comptes utilisateurs
aisia_api_keys : clés API gérées
aisia_conversations : historique des conversations
aisia_messages : messages des conversations
aisia_ai_rules : guardrails IA
aisia_local_model_overrides : surcharges modèles locaux
aisia_user_profiles : profils étendus
aisia_login_history : historique des connexions
aisia_groups : groupes d'utilisateurs
aisia_group_members : membres des groupes
aisia_group_permissions : permissions des groupes
aisia_user_consents : consentements RGPD
aisia_maintenance_tasks : états des tâches de maintenance

#### Reconnexion Redis

Si Redis est déconnecté, le self-repair tente une reconnexion :

3 tentatives avec 2 secondes d'intervalle
Rebind du client Redis aux composants (bandit, circuit breakers, bot, learning, maintenance)

#### Reconnexion Qdrant

Si Qdrant est déconnecté :

Tentative de reconnexion
Recréation des collections manquantes via _ensure_collections

#### Rechargement des modèles locaux

Si des modèles locaux sont inaccessibles :

Hot-reload via AutonomousLocalRouter.hot_reload()
Réinitialisation des adaptateurs de runtime

Structure du rapport de réparation

{
  "repair_at": "2026-04-19T10:35:00Z",
  "actions_taken": [
    {
      "action": "recreate_tables",
      "target": "aisia_conversations",
      "status": "success"
    },
    {
      "action": "reconnect_redis",
      "status": "success"
    },
    {
      "action": "reload_local_models",
      "models_loaded": 74,
      "status": "success"
    }
  ],
  "total_actions": 3,
  "successful": 3,
  "failed": 0,
  "elapsed_ms": 2500
}

---

4. Auto-Test par LLM : POST /admin/auto-test

Description

L'auto-test est le plus complet des trois mécanismes. AISIA utilise ses propres modèles LLM pour tester fonctionnellement l'intégralité de la plateforme et évaluer la qualité des réponses.

Appel

curl -X POST -H "Authorization: Bearer TOKEN_ADMIN" \
  https://aisia.fr/admin/auto-test

Sections testées

#### Section 1 : Pages web (17 pages)

Teste le statut HTTP de chaque page publique :

Page	Attendu
`/`	HTTP 200
`/chat`	HTTP 200
`/about`	HTTP 200
`/contact`	HTTP 200
`/investors`	HTTP 200
`/plan-projet`	HTTP 200
`/docs-service`	HTTP 200
`/nda`	HTTP 200
`/models`	HTTP 200
`/status`	HTTP 200
`/privacy`	HTTP 200
`/docs`	HTTP 200
`/health`	HTTP 200
`/landing`	HTTP 200
`/robots.txt`	HTTP 200
`/sitemap.xml`	HTTP 200
`/favicon.ico`	HTTP 200

#### Section 2 : Endpoints admin (12 endpoints)

Teste l'accessibilité des endpoints admin avec un token valide :

/admin/bot/status
/admin/maintenance/status
/admin/self-audit
/admin/datasets
/admin/investors
/admin/ai-rules
/admin/groups/
/admin/local-models
/admin/autonomy/status
/admin/onboarding
/admin/knowledge
/admin/billing

Vérifie aussi la sécurité : un appel sans token doit retourner HTTP 401.

#### Section 3 : Chat fonctionnel (10 questions)

Teste le chat avec des questions couvrant différents domaines :

Domaine	Prompt	Attendu
Général	"Dis bonjour en une phrase."	Contient "bonjour"
Math	"Calcule 15 * 23."	Contient "345"
Coding	"Écris une fonction Python qui inverse une chaîne."	Contient "def"
Factual	"Quelle est la capitale de la France ?"	Contient "Paris"
Science	"Explique le théorème de Pythagore en 2 phrases."	Contient "triangle"
Translation	"Traduis 'Hello world' en français."	Contient "Bonjour"
Creative	"Résume en une phrase : L'IA transforme le monde."	Texte >10 chars
Math	"Quel est le résultat de sqrt(144) ?"	Contient "12"
Général	"Donne 3 conseils pour bien dormir."	Texte >10 chars
Creative	"Écris un haiku sur la technologie."	Texte >10 chars

Chaque réponse est évaluée sur :

Présence du contenu attendu
Latence < 10 secondes
Succès HTTP 200

#### Section 4 : Cycle d'authentification

1. Register : création d'un compte test (autotest-{timestamp}@aisia.test) 2. Login : connexion avec le compte créé 3. Profile : accès à /auth/me, /auth/me/profile, /auth/me/login-history 4. OIDC : test de la redirection Google (HTTP 307)

#### Section 5 : Intégrité des données

Providers : vérification qu'il y a au moins 50 providers
Modèles locaux : au moins 40 modèles déclarés
OpenAPI : au moins 60 paths dans la spécification
Health : statut "ok" avec latence DB

Structure du rapport

{
  "test_at": "2026-04-19T10:30:00Z",
  "base_url": "http://127.0.0.1:8000",
  "score": 87.5,
  "total_checks": 40,
  "passed": 35,
  "failed": 5,
  "sections": {
    "pages": {"checks": [...], "total": 17, "passed": 16},
    "admin": {"checks": [...], "total": 13, "passed": 12},
    "chat": {"checks": [...], "total": 10, "passed": 8},
    "auth": {"checks": [...], "total": 6, "passed": 5},
    "data": {"checks": [...], "total": 4, "passed": 4}
  },
  "strengths": [
    "Page / accessible",
    "Chat général: 402ms",
    "Routes admin protégées"
  ],
  "weaknesses": [
    "page:/docs: HTTP 404",
    "chat:coding: Réponse incorrecte"
  ],
  "recommendations": [
    "Corriger /docs (HTTP 404)",
    "Réponse coding incorrecte ou lente"
  ],
  "elapsed_ms": 25000
}

---

5. Health Monitor continu

Endpoint /health

GET /health

Retourne l'état de santé général de la plateforme avec la latence de chaque dépendance :

{
  "status": "ok",
  "version": "4.21.0",
  "database": {"status": "ok", "latency_ms": 2.3},
  "redis": {"status": "ok", "latency_ms": 0.8},
  "qdrant": {"status": "ok", "latency_ms": 5.1},
  "autonomy": {
    "available": true,
    "model_count": 74,
    "available_model_count": 12
  }
}

Health check périodique des providers

Une boucle de fond (periodic_health_loop) vérifie la disponibilité des providers toutes les 5 minutes (300 secondes) :

1. Envoie un prompt "ping" à chaque provider 2. Enregistre le résultat dans Prometheus : - ai_provider_health_up : 1 (OK) ou 0 (KO) - ai_provider_health_latency_seconds : durée du check

Cache du health check

Pour éviter de surcharger les dépendances, le health check général utilise un cache avec TTL :

Clé : _health_cache
Contenu : payload du dernier health check
Verrou async pour éviter les appels simultanés

---

6. Scores et interprétation

Grille de scores

Score	État	Action
95-100%	Excellent	Aucune action requise
85-94%	Bon	Vérifier les points faibles
70-84%	Acceptable	Lancer un self-repair
50-69%	Dégradé	Investigation urgente
<50%	Critique	Intervention manuelle immédiate

Interprétation des résultats

#### Score du self-audit

Le score est calculé comme le pourcentage de checks réussis sur le total :

score = (passed / total_checks) * 100

Chaque section contribue de manière égale au score global.

#### Score de l'auto-test

Le score intègre les 5 sections (pages, admin, chat, auth, data). Les checks échoués sont classés en :

Strengths : éléments fonctionnels avec des notes positives
Weaknesses : éléments défaillants avec leur détail d'erreur
Recommendations : actions correctives suggérées

#### Alertes critiques vs warnings

Dans le self-audit :

Critique : service Docker arrêté, MariaDB inaccessible, 0 providers
Warning : Redis indisponible, Qdrant indisponible, modèles Ollama manquants

---

7. Architecture du système d'audit

Scripts

Les scripts d'audit sont situés dans scripts/ :

scripts/
��── self_audit.py     — Audit automatique complet
└── self_repair.py    — Réparation automatique

Ces scripts sont importés dynamiquement par main.py via sys.path.insert.

Flux d'exécution

GET /admin/self-audit
    │
    ├── Charge self_audit.py
    │
    ├── run_audit(base_url, db_pool, redis_client, qdrant_store)
    │   ├── Teste les services Docker
    │   ├── Teste les endpoints API via httpx
    │   ├── Teste la DB via le pool aiomysql
    │   ├── Teste Redis via ping
    │   ├── Teste Qdrant via get_collections
    │   └── Compile le rapport JSON
    │
    └── Retourne le rapport

POST /admin/self-repair
    │
    ├── Charge self_repair.py
    │
    ├── run_repair(base_url, db_pool, redis_client, internal_token)
    │   ├── Exécute le self-audit
    │   ├── Analyse les failures
    │   ├── Exécute les actions correctives
    │   └── Compile le rapport
    │
    └── Retourne le rapport

---

8. Tâche de maintenance : self-audit automatique

Le self-audit est aussi défini comme tâche de maintenance dans maintenance_tasks.yaml :

- task_id: self-audit
  title: Auto-diagnostic AISIA
  description: >
    Exécute un audit automatique complet de la plateforme AISIA :
    services Docker, endpoints API, tables DB, modèles Ollama,
    connectivité Redis/Qdrant. Produit un rapport JSON avec score.
  category: audit
  command: ["python3", "scripts/self_audit.py"]
  enabled: true
  auto_run: true
  interval_s: 3600
  timeout_s: 120
  tags: ["audit", "monitoring", "self-diagnostic"]
  destructive: false

Cela signifie que le self-audit s'exécute automatiquement toutes les heures via le MaintenanceScheduler, en complément des appels manuels via l'API.

---

9. Intégration avec le monitoring

Métriques Prometheus

Les résultats des health checks sont exposés via les métriques Prometheus :

# Providers disponibles (health check)
ai_provider_health_up

Latence des health checks
ai_provider_health_latency_seconds

Providers disponibles (routing)
ai_provider_up

Circuit breakers ouverts (indicateur indirect de problème)
ai_circuit_breaker_state == 2

Alertes Grafana recommandées

Alerte	Condition	Sévérité
Tous providers down	`sum(ai_provider_up) == 0`	Critique
DB inaccessible	health.database.status != "ok"	Critique
Redis down	health.redis.status != "ok"	Warning
Qdrant down	health.qdrant.status != "ok"	Warning
Score audit < 70%	self-audit.score < 70	Warning
Score audit < 50%	self-audit.score < 50	Critique

Publication du statut

Le statut de la maintenance (incluant le self-audit) est publié dans Redis :

Clé : aisia:maintenance:status
Format : JSON
Accessible via GET /admin/maintenance/status

---

10. Diagnostics avancés

Diagnostic réseau

Si le self-audit montre des problèmes de connectivité, vérifiez :

# Depuis un container API
docker exec -it $(docker ps -q -f name=aisia_api) bash

Test MariaDB
python3 -c "import socket; s=socket.create_connection(('aisia-core_mariadb', 3306), 5); print('OK')"

Test Redis
python3 -c "import socket; s=socket.create_connection(('aisia-core_redis', 6379), 5); print('OK')"

Test Qdrant
python3 -c "import socket; s=socket.create_connection(('aisia-core_qdrant', 6333), 5); print('OK')"

Diagnostic de la base de données

# Lister les tables
curl -H "Authorization: Bearer TOKEN" https://aisia.fr/health
Vérifier que database.status == "ok" et database.latency_ms < 100

Diagnostic des modèles locaux

# Statut des modèles locaux
curl -H "Authorization: Bearer TOKEN" \
  https://aisia.fr/admin/autonomy/status

Vérifiez dans la réponse :

available_model_count > 0
Pour chaque modèle : available: true et last_error: ""

Diagnostic du bot

curl -H "Authorization: Bearer TOKEN" \
  https://aisia.fr/admin/bot/status

Vérifiez :

running: true
cycles_completed qui augmente
last_cycle_at récent

---

11. Bonnes pratiques

Fréquence des audits

Mécanisme	Fréquence recommandée	Cas d'usage
Health check	Continu (5min)	Monitoring temps réel
Self-audit	Automatique (1h)	Détection proactive
Self-repair	À la demande	Après détection de problème
Auto-test	Hebdomadaire	Validation fonctionnelle complète

Après un déploiement

Exécutez toujours la séquence suivante après un déploiement :

1. GET /health — vérification rapide 2. GET /admin/self-audit — diagnostic complet 3. Si score < 90% : POST /admin/self-repair 4. GET /admin/self-audit — vérification post-réparation

Après un incident

1. GET /admin/self-audit — évaluer l'étendue des dégâts 2. POST /admin/self-repair — tentative de réparation automatique 3. POST /admin/auto-test — vérification fonctionnelle complète 4. Comparer les scores avant/après

Conservation des rapports

Les rapports de self-audit et d'auto-test sont retournés en réponse HTTP et ne sont pas persistés automatiquement. Pour conserver un historique :

Sauvegardez les rapports dans un fichier ou un système de monitoring
Utilisez la tâche de maintenance self-audit qui publie dans Redis

---

12. Référence API complète

Endpoints d'audit et monitoring

Méthode	Endpoint	Description
`GET`	`/health`	État de santé général
`GET`	`/metrics`	Métriques Prometheus
`GET`	`/admin/self-audit`	Diagnostic complet
`POST`	`/admin/self-repair`	Réparation automatique
`POST`	`/admin/auto-test`	Test fonctionnel par LLM
`GET`	`/admin/autonomy/status`	Statut modèles locaux
`GET`	`/admin/bot/status`	Statut du bot
`GET`	`/admin/maintenance/status`	Statut du scheduler
`GET`	`/admin/billing`	Statistiques billing
`GET`	`/admin/knowledge`	Stats knowledge base

Codes de retour

Code	Signification
200	Succès, rapport retourné
401	Token admin manquant ou invalide
500	Erreur interne lors de l'audit
503	Service indisponible (DB down)

---

Document AISIA v4.21.0