Modèle de données
Tables fraza_ai_run et fraza_ai_result du module IA, historique des appels sans texte, propositions gardées à côté d'un contenu, rétention et migrations.
Le module crée deux tables, préfixées fraza_ai_. Elles sont créées par npx fraza-db init, qui appelle le createTables exporté par le module, et migrées par npx fraza-db migrate. Voir fraza-db.
fraza_ai_run
Une ligne par appel au fournisseur, réussi ou non. La page IA la lit, getUsage() en fait la somme, et la tâche ai-retention retire les anciennes.
| Colonne | Type | Rôle |
|---|---|---|
id | BIGSERIAL PRIMARY KEY | Identifiant. |
prompt | VARCHAR(120) NOT NULL | Nom du prompt. |
source | VARCHAR(214) | Le paquet qui l'a déclaré, ou projet. |
trigger | VARCHAR(20) NOT NULL | button, code ou test. |
provider | VARCHAR(40) NOT NULL | Le fournisseur de l'appel. |
model | VARCHAR(200) | Le modèle, tel que le fournisseur l'a rapporté, sinon celui de la configuration. |
status | VARCHAR(20) NOT NULL | success ou error, vérifié par une contrainte CHECK. |
error_code | VARCHAR(40) | Le code de l'échec. Voir Codes d'erreur. |
error_message | TEXT | Le message en français, suivi du message du fournisseur quand il en donne un, 500 caractères au plus. |
input_tokens, output_tokens | INTEGER | Jetons envoyés et reçus, deux tentatives comprises. NULL quand le fournisseur ne les donne pas, ou quand l'appel n'a pas abouti. |
attempts | SMALLINT NOT NULL DEFAULT 1 | 2 quand la première réponse était hors schéma. |
duration_ms | INTEGER | Durée de l'appel, tentatives comprises. |
user_id | TEXT | Le compte qui a cliqué, NULL pour un appel du code. |
created_at | TIMESTAMPTZ NOT NULL DEFAULT now() |
Index sur created_at, l'axe de la liste, des sommes et de la purge.
Ni le texte envoyé, ni la réponse. Un prompt peut porter une soumission, un courriel, une image : des données personnelles. L'historique garde ce qu'il faut pour suivre la consommation et trouver une panne, rien de plus. Une réponse hors schéma n'y laisse que la liste des écarts, chemins et règles, pas les valeurs.
user_id n'a pas de clé étrangère. L'historique survit à la suppression d'un compte, et la table se crée sans les tables d'authentification.
Seul un appel qui part vers le fournisseur écrit une ligne, qu'il aboutisse ou non. Un prompt inconnu, une configuration incomplète, une saisie invalide, un prompt qui ne s'applique pas ou un build() qui lève s'arrêtent avant, sans coût et sans ligne.
Rétention
La tâche ai-retention tourne chaque jour à 3 h 17, dans le fuseau de FRAZA_TIMEZONE. Elle retire les lignes plus vieilles que FRAZA_MODULE_AI_RETENTION_DAYS, 90 jours par défaut, et les propositions de fraza_ai_result utilisées ou ignorées depuis plus longtemps que cette durée, par lots, avec un verrou de 15 minutes : sur un site à plusieurs instances, une seule l'exécute. Voir Cron.
La consommation d'une période plus ancienne que la rétention n'est plus lisible. Un projet qui veut garder ses chiffres plus longtemps allonge la rétention, ou recopie getUsage() ailleurs avant la purge.
fraza_ai_result
Une réponse gardée à côté d'un contenu, montrée comme venant de l'IA jusqu'à ce que quelqu'un l'utilise ou l'ignore. Écrite par saveResult(), lue par AiResults. Voir Boutons.
| Colonne | Type | Rôle |
|---|---|---|
id | BIGSERIAL PRIMARY KEY | Identifiant, rendu en chaîne. |
target_type | VARCHAR(120) NOT NULL | Le type de contenu, medias.media par exemple. |
target_id | VARCHAR(120) NOT NULL | L'identifiant du contenu, en texte quel que soit son type. |
prompt | VARCHAR(120) NOT NULL | Le prompt qui a répondu. |
data | JSONB NOT NULL | La réponse, vérifiée contre le schéma du prompt. |
model | VARCHAR(200) | Le modèle qui a répondu. |
created_at | TIMESTAMPTZ NOT NULL DEFAULT now() | Première réponse. |
updated_at | TIMESTAMPTZ NOT NULL DEFAULT now() | Dernière réponse, celle qu'affiche l'admin. |
dismissed_at | TIMESTAMPTZ | Posée quand la réponse est utilisée ou ignorée. |
Contrainte d'unicité fraza_ai_result_target_unique sur (target_type, target_id, prompt). Une seconde réponse du même prompt pour le même contenu remplace la première, remet dismissed_at à NULL et s'affiche de nouveau. Une livraison durable rejouée écrit donc une fois.
target_id est du texte parce que les modules n'ont pas tous le même type d'identifiant : un entier pour une soumission, une chaîne pour un média.
Rien ne lie la table aux contenus : aucune clé étrangère vers une table d'un autre module. Le module qui supprime un contenu appelle deleteResults(target, id). Une réponse utilisée ou ignorée reste dans la table jusque-là.
Migrations
Les migrations sont numérotées dans src/migrations.js du module et appliquées une fois, par npx fraza-db migrate. Il n'y en a aucune pour l'instant : createTables() crée le schéma actuel.
Notes
dropTablessupprime les deux tables en cascade, avec l'historique et les propositions.- La donnée d'une proposition est une réponse du modèle, donc parfois une donnée personnelle : elle vit dans
fraza_ai_resulttant que le contenu existe.