Installation

Cette page installe @fraza/module-ai dans un projet créé par npx @fraza/start. Le module n'est jamais déclaré à la main : il est découvert au boot par scan des dépendances, comme décrit dans Cycle de vie d'un module.

PrérequisCopier le lien de la section

• Un projet créé par npx @fraza/start, avec @fraza/core à jour.
• Un compte chez le fournisseur choisi et sa clé d'API, ou un serveur Ollama. Voir Configuration.
• Aucun compte Fraza : le paquet est publié sur npmjs.

InstallerCopier le lien de la section

npm i @fraza/module-ai

Ajouter les variables à .env.local, et aux variables de la plateforme en production :

#------ MODULE - AI ------#
FRAZA_MODULE_AI=true
FRAZA_MODULE_AI_PROVIDER=anthropic
FRAZA_MODULE_AI_MODEL=claude-sonnet-5-5
FRAZA_MODULE_AI_API_KEY=

Sans FRAZA_MODULE_AI=true, le module est ignoré : aucune route, aucune entrée d'admin, aucune intégration, et les boutons des autres modules n'apparaissent pas. Le modèle n'a pas de valeur par défaut : c'est le nom que le fournisseur lui donne. La clé est un secret : elle ne va jamais dans .env.example, et fraza-doctor signale une valeur trouvée dans un fichier suivi par git.

Régénérer les manifestes, puis créer les tables :

npx fraza-modules sync    # déclenché automatiquement au postinstall
npx fraza-db init         # crée fraza_ai_run et fraza_ai_result

fraza-db init est idempotent : sur une base qui a déjà les tables, il applique les migrations en attente sans toucher aux données. Il enregistre aussi les deux permissions du module, ai.use et ai.view, et les attribue au rôle admin. Voir Modèle de données.

Ajouter ai.jsCopier le lien de la section

Le projet ajuste les prompts des modules et déclare les siens dans un fichier ai.js, à la racine. Le starter ne le crée pas : il n'est utile qu'avec ce module, et un projet sans ai.js reçoit les prompts des modules tels quels.

// ai.js
import { configureAi, customizePrompt } from '@fraza/module-ai/server';

configureAi({ instructions: 'Le site s\'adresse à des propriétaires d\'animaux, au Québec.' });

customizePrompt('posts.write', {
  system: 'Tu écris pour une clinique vétérinaire.',
});

instrumentation.js le charge au démarrage, dans la branche Node, avant ou après initializeFraza() :

// instrumentation.js
export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    const { initializeFraza } = await import('@fraza/core/init');
    const { modules } = await import('./app/.fraza/modules.generated.js');
    await import('./app/.fraza/blocks.server.js');
    await import('./app/.fraza/templates.server.js');
    await import('./ai.js');
    const { default: theme } = await import('./theme.js');
    const { default: permissions } = await import('./permissions.js');
    const { default: events } = await import('./events.js');
    await initializeFraza({ modules, theme, permissions, events });
  }
}

L'ordre n'importe pas : un ajustement attend que son prompt soit déclaré, et les modules déclarent les leurs pendant le démarrage. Ce que ai.js peut contenir est dans Prompts.

ai.js importe @fraza/module-ai/server directement : le projet dépend alors du paquet. Désinstaller le module demande de retirer d'abord la ligne de instrumentation.js.

VérifierCopier le lien de la section

1. La connexion à la base répond :

   Copier

   npx fraza-db test

2. IA apparaît dans la barre latérale de l'admin, sous « Outils », pour un compte qui a ai.view.
3. Sur /admin/ai, le bloc Configuration montre le fournisseur, le modèle et la présence de la clé. Une variable manquante ou illisible y est nommée.
4. Le bouton « Tester » envoie une courte demande au fournisseur, avec une réponse structurée. Il prouve toute la chaîne : la clé, le modèle, le format de réponse. L'appel apparaît dans l'historique, sous l'origine « Test ».

Un échec du test donne le message du fournisseur dans l'historique : clé refusée, modèle inconnu, adresse injoignable. Voir API.

Mettre à jourCopier le lien de la section

npx fraza-update

La commande installe la dernière version de tous les paquets Fraza du site, toutes à la fois, puis enchaîne fraza-modules sync, fraza-db migrate et fraza-doctor. Tous les paquets Fraza à leur dernière version fonctionnent ensemble : mettre à jour @fraza/module-ai seul, par npm i, laisserait le core et les autres modules en arrière.

Les notes de version sont livrées avec le paquet, dans node_modules/@fraza/module-ai/CHANGELOG.md.

NotesCopier le lien de la section

• Le module dépend de @fraza/core et de @fraza/icons en peerDependencies. Il n'embarque pas sa propre copie du core, et n'a aucune dépendance de production.
• La tâche ai-retention retire chaque nuit les appels plus vieux que la rétention. Comme toute tâche du core, elle demande un serveur qui reste allumé : sur une plateforme serverless, l'historique n'est plus purgé. Voir Cron.
• Désinstaller le module ne supprime pas ses tables. dropTables est exporté depuis @fraza/module-ai pour la partie base.
• Désactiver le module laisse les propositions en attente dans fraza_ai_result. Elles réapparaissent à sa réactivation.