API

Le module s'appelle de deux façons : le projet importe @fraza/module-ai/server, et un autre module lit l'intégration ai sans importer le paquet. Les deux donnent les mêmes fonctions. Les routes HTTP ne servent qu'aux écrans de l'admin.

Règle absolue : un appel au modèle passe toujours par runPrompt, jamais par une requête directe au fournisseur. C'est lui qui vérifie la réponse, compte les jetons et écrit l'historique, et lui seul suit le fournisseur que la configuration nomme.

ImportCopier le lien de la section

import { runPrompt } from '@fraza/module-ai/server';

./server ne vérifie aucune permission : son appelant est le code du serveur, qui fait ses propres vérifications.

Fonctions serveurCopier le lien de la section

runPrompt(name, options?)Copier le lien de la section

const result = await runPrompt('site.summary', { context: { message } });

if (result.success) {
  console.log(result.data.summary, result.usage.outputTokens);
} else {
  console.warn(result.error.code, result.error.message);
}

La réponse a l'une de ces deux formes :

{ success: true, data, model, usage: { inputTokens, outputTokens } }
{ success: false, error: { code, message, retryable } }

data est la réponse, déjà vérifiée contre le schéma du prompt. model est le modèle que le fournisseur dit avoir utilisé, sinon celui de la configuration. usage additionne les deux tentatives, et un compte vaut null quand le fournisseur ne le donne pas. message est en français, prêt pour l'admin. retryable dit qu'un essai plus tard peut réussir.

runPrompt ne lève que pour une erreur de programmation, jamais pour une panne, une configuration absente ou une réponse hors schéma. Le module n'a pas besoin d'être activé pour qu'un appel du code parte : FRAZA_MODULE_AI décide des routes, de l'admin et de l'intégration, pas de ./server.

Codes d'erreurCopier le lien de la section

Dans une réponse d'erreur de la route, le code est dans le champ code.

saveResult, getResults, dismissResult, deleteResultsCopier le lien de la section

const saved = await saveResult({ target: 'medias.media', id: media.id, prompt: 'medias.alt', data: result.data, model: result.model });
// { id: '17', target: 'medias.media', targetId: 'a1b2…', prompt: 'medias.alt', data: { altText: '…' }, model: '…', createdAt: '2026-11-07T…' }

target est un nom en mots minuscules séparés par des points, 120 caractères au plus. id est un entier ou une chaîne de 120 caractères au plus, gardé en texte. Une valeur hors de ces règles lève une TypeError. data est un objet, et createdAt la date de la dernière réponse.

saveResult remplace la réponse déjà gardée pour le même contenu et le même prompt, et la remontre si elle avait été ignorée. getResults ne rend que les réponses ni utilisées ni ignorées. dismissResult rend false pour un identifiant inconnu ou déjà marqué. deleteResults rend le nombre de réponses retirées. Voir Modèle de données.

getUsage({ from, to })Copier le lien de la section

const to = new Date();
const from = new Date(to.getTime() - 30 * 24 * 60 * 60 * 1000);
const usage = await getUsage({ from, to });
// {
//   from, to,
//   totals: { calls, errors, inputTokens, outputTokens },
//   byDay: [{ day: '2026-11-06', calls, errors, inputTokens, outputTokens }, …],
//   byPrompt: [{ prompt, calls, errors, inputTokens, outputTokens }, …],
//   byModel: [{ provider, model, calls, errors, inputTokens, outputTokens }, …],
// }

from et to sont des Date, to exclue. Les jours sont coupés en UTC. byPrompt et byModel sont triés du plus gros consommateur au plus petit. Des dates invalides, ou from après to, lèvent une TypeError.

Des jetons seulement, jamais un prix : le module ne connaît pas le contrat passé avec le fournisseur. La fonction est publiée sous cette forme pour qu'un registre de consommation du core, à venir, la lise comme celle de tout module qui consomme un service payant.

describeAiConfig()Copier le lien de la section

Rend { configured, provider, providerLabel, model, hasKey, baseUrl, problem }. hasKey dit si une clé est présente, jamais sa valeur. baseUrl n'est rendue que pour openai-compatible et ollama. problem est le message de la première variable en défaut, ou null.

L'intégration aiCopier le lien de la section

Un module ne déclare pas @fraza/module-ai en dépendance : importer un paquet absent ferait échouer le build du site. Il lit l'intégration ai, publiée par le module quand il est activé.

import { getIntegration } from '@fraza/core/integrations';

const AI_CONTRACT = 1;

function aiOf() {
  const ai = getIntegration('ai');
  return ai && ai.contract === AI_CONTRACT ? ai : null;
}

Lire le contrat. contract vaut 1. Il augmente quand la forme d'une de ces fonctions change, et un module ignore une intégration dont il ne parle pas le contrat : il perd ses boutons, il ne casse pas.

Déclarer dans onModulesReady. Le module IA peut s'enregistrer après le module qui l'utilise. Un module déclare donc ses prompts dans un callback de onModulesReady(), où toutes les intégrations sont publiées. Voir Enregistrement inter-modules.

// register-server.js d'un module, exemple
import { onModulesReady } from '@fraza/core/modules';

onModulesReady(() => {
  const ai = aiOf();
  if (!ai) return;
  ai.definePrompt({ name: 'acme.write', /* … */ }, { source: '@acme/module-x' });
});

Un module passe toujours son source à definePrompt : sans lui, le prompt est attribué au projet, et c'est la source qui distingue un rechargement d'un conflit de nom.

Routes HTTPCopier le lien de la section

Toutes sont montées sous /za/api, et toutes demandent une session d'admin.

POST /ai/run refuse un prompt sans target par un 404, comme un prompt inconnu, et un compte sans la permission du prompt par un 403. Il rend { success: true, data, model }, sans usage.

NotesCopier le lien de la section

• Les fonctions de ./server et celles de l'intégration sont les mêmes objets : un appel par l'une ou par l'autre écrit le même historique.
• isAiConfigured() et describeAiConfig() tiennent aussi compte de FRAZA_MODULE_AI_RETENTION_DAYS : une rétention hors bornes les rend non configurés, alors que runPrompt n'en dépend pas et appelle le fournisseur.
• Les propositions d'un contenu se lisent et se marquent avec ai.use seul : la route ne vérifie pas la permission du module qui possède le contenu.