Registry `caller_app` (applications appelantes) — Aurora Nexus

Objectif

caller_app permet d’identifier l’application externe qui appelle Aurora Nexus (extension Chrome, connecteur, app métier, etc.) afin de :

fiabiliser l’observabilité (table queries_log, dashboards)
piloter le cache / les quotas côté Gateway (si activé)
éviter des valeurs “parasites” en imposant une nomenclature contrôlée

Définitions (à ne pas confondre)

source_app : Service/corpus (permissions, filtrage Qdrant, workspaces rattachés).
caller_app : application appelante (origine technique de la requête).

Exemple :

source_app = "crm_salesforce" (corpus Salesforce)
caller_app = "aurora_summarizer" (extension Chrome)

Où est stocké le registry ?

Table Postgres : public.caller_apps_config
Champ log : public.queries_log.caller_app
Champs ingestion / documents :
- public.documents.caller_app
- public.ingestion_batches.caller_app
- public.ingestion_jobs.caller_app

La migration seed deux entrées minimales :

aurora_nexus_ui : UI web
unknown : compat clients legacy (si caller_app absent)

Comportement serveur

1) Résolution

Si caller_app n’est pas fourni dans POST /api/query, Nexus applique le fallback contrôlé caller_app="unknown".

2) Enforcement registry (recommandé)

Variable d’environnement : ENFORCE_CALLER_APP_REGISTRY=true
Si activé : un caller_app inconnu ou inactif est refusé avec 400.
Si la table caller_apps_config est absente (migrations non jouées) : 500 avec un message explicite.

Gérer les `caller_app` (Admin)

UI

Admin → Paramètres → Services connectés → section Applications appelantes

Vous pouvez :

créer une application (name/label/description)
activer/désactiver (soft)

API admin

Auth requise (admin).

Lister : GET /api/admin/caller-apps
Créer : POST /api/admin/caller-apps
Mettre à jour : PUT /api/admin/caller-apps/{caller_app_id}
Désactiver : DELETE /api/admin/caller-apps/{caller_app_id} (soft, met is_active=false)

Contraintes de naming (name) :

2–64 caractères
minuscules + chiffres + _ ou - uniquement (^[a-z0-9_-]+$)

Utiliser `caller_app` côté client (apps externes)

Procédure de bout en bout (app externe)

Objectif : tracer correctement l’application appelante sans casser les permissions.

Créer l’entrée caller_app
- UI : Admin → Paramètres → Services connectés → Applications appelantes.
- Renseigner name (stable), label, puis activer.
Créer un utilisateur de service
- UI : Admin → Utilisateurs → créer un compte “service”.
Mapper les permissions (source_app)
- UI : Admin → Utilisateurs → Permissions → activer can_read (et can_write si besoin) par source_app.
- Rappel : caller_app ne donne pas de droits. Les permissions restent attachées à l’utilisateur + source_app.
Authentifier le client
- POST /api/auth/login → récupérer un JWT (mode Bearer).
Appeler /api/query
- Inclure caller_app, source_app, workspace, plus thread_id (recommandé) et language si nécessaire.
Vérifier les logs / observabilité
- Les requêtes sont tracées avec caller_app dans queries_log.
- Les dashboards d’observabilité peuvent filtrer par caller_app (usage, cache_status, coûts).

👉 Bon réflexe : garder un caller_app stable pour éviter de “diluer” les statistiques et faciliter les diagnostics.

1) Auth (JWT)

Le client doit d’abord obtenir un JWT via /api/auth/login et l’envoyer avec Authorization: Bearer <token>.

2) Appel `/api/query`

Payload minimal recommandé :

{
  "query": "Quelle est la politique de remboursement ?",
  "source_app": "support",
  "workspace": "default",
  "caller_app": "aurora_summarizer",
  "thread_id": "thread-123",
  "tenant_id": null,
  "pack_id": null
}

Notes :

Si vous envoyez workspace, vous devez aussi envoyer source_app.
caller_app doit correspondre à une entrée active dans caller_apps_config si l’enforcement est activé.
thread_id est fortement recommandé pour des conversations multi‑tours robustes (follow-ups : “détaille S2 / point B / 2e point”).

Follow-ups multi-tours (résolution “S2 / point B / 2e point”)

Pour des échanges naturels sans réinjecter l’historique brut, Nexus supporte un mécanisme de navigation conversationnelle :

Le client envoie thread_id (stable par conversation).
Le service (prompt) termine ses réponses “livrables” (résumé/synthèse/rapport) par un bloc machine‑parsable non traduit :

SUIVI
[S1] ...
[S2] ...
[S3] ...
[S4] ...

Ensuite, le client peut envoyer des follow-ups du type :

Détaille S2
Détaille le point B (compat legacy → S2)
Détaille le 2e point (→ S2)

3) Lister les `caller_app` disponibles (optionnel)

Endpoint “public” (retourne uniquement les actifs) :

GET /api/caller-apps

4) Ingestion (upload) — recommandé pour tracer l’origine

Pour les uploads (UI, extension, connecteurs), renseignez aussi caller_app afin de pouvoir filtrer les documents et les batches par application.

Endpoints :

POST /api/ingest/upload/commit
POST /api/ingest/upload/commit_batch

Exemple minimal (commit) :

{
  "object_key": "uploads/default/....",
  "caller_app": "aurora_summarizer",
  "tags": ["web"],
  "source_meta": {
    "source_app": "support",
    "workspace": "default",
    "title": "Page FAQ",
    "caller_app": "aurora_summarizer"
  }
}

Notes :

Si caller_app est absent, Nexus stocke caller_app="unknown" (compat). Pour une gouvernance stricte, envoyez-le systématiquement.
Si ENFORCE_CALLER_APP_REGISTRY=true, un caller_app inconnu ou inactif est refusé avec 400.

Filtrage (UI & API)

UI : pages Documents, Ingestion et Statistiques requêtes proposent un filtre caller_app (si activé).
API :
- GET /api/documents?caller_app=...
- GET /api/ingest/batches?caller_app=...

Erreurs fréquentes

400 caller_app inconnu ou inactif :
- créez l’entrée dans Admin → Applications appelantes, ou réactivez-la.
500 Registry caller_app indisponible :
- exécutez les migrations DB (table manquante).
500 column "caller_app" does not exist :
- migrations DB incomplètes (schéma trop ancien) : rejouer bash ops/init_db.sh.

Bonnes pratiques (nomenclature)

name stable et technique : aurora_summarizer, sap_connector, jira_bot
éviter les variantes environnement : préférez gérer l’environnement via tenant_id/pack_id ou via des tags côté app
ne pas réutiliser caller_app pour décrire le corpus : c’est le rôle de source_app

Registry `caller_app` (applications appelantes) — Aurora Nexus

On this page