Référence API — IA

Puwapi IA est la couche d'intelligence transversale. C'est le seul service autorisé à appeler l'API du modèle sous-jacent : aucun autre module n'appelle un fournisseur d'IA directement — ils passent par IA.

• Base URL — prod : https://ia.api.puwapi.com · dev : http://localhost:6600
• Auth : JWT + gating ia (Business+, hors essai).

Pipeline asynchrone¶

L'inférence est asynchrone :

POST /api/ai/infer  →  vérif feature + quota  →  requête "pending"  →  file (Redis Stream)
                    →  202 { requestId, estimatedMs, convexChannel }

Un worker traite la file, appelle le modèle, met à jour la requête et l'usage, puis notifie Convex. Le client récupère le résultat par polling (GET /api/ai/requests/{id}) ou via Convex.

Endpoints (authentifiés)¶

Base : /api/ai

Méthode	Route	Rôle
POST	/api/ai/infer	Lancer une inférence { featureKey, scopeRef?, variables, continueContextId? } → 202
GET	/api/ai/requests/{id}	État + résultat de la requête
POST	/api/ai/requests/{id}/feedback	Retour 👍/👎
GET	/api/ai/contexts/{id}/messages	Messages d'un contexte conversationnel
GET	/api/ai/usage?month=YYYY-MM	Consommation du mois (quota, tokens)

Administration¶

Base : /api/ai/admin

Méthode	Route	Rôle
GET	/api/ai/admin/features	Lister les features
GET	/api/ai/admin/prompts/{featureKey}	Versions de gabarit d'une feature
POST	/api/ai/admin/prompts/{featureKey}	Créer une version de gabarit
PUT	/api/ai/admin/prompts/{featureKey}/{version}/activate	Activer une version
GET	/api/ai/admin/usage	Usage global

Surface interne (M2M)¶

Base : /api/ai/internal — pour les serveurs non-web (ex. VR). X-Internal-Secret, fail-closed, tenant au corps.

Méthode	Route
POST	/api/ai/internal/infer
GET	/api/ai/internal/requests/{id}

Features¶

Une feature est une capacité nommée avec son gabarit de prompt versionné. Exemples livrés : ticket_description, ticket_prioritize, sprint_summary, rag_qa, chat_*, mail_*, crm_*, doc_summary, slides_outline, vr_assistant, loyalty_*, rdv_reminder_message, noshow_predict…

Quotas et confidentialité¶

• Quota global par organisation selon le palier (nombre de requêtes + tokens par mois).
• Les features sensibles (mail_*, chat_*) ne persistent pas leur résultat en base : il est servi une seule fois via un cache court. Les variables ne sont jamais persistées ; Convex ne reçoit que { requestId, tenantId, featureKey, status }.