@lastbrain/module-ai 0.1.7 → 0.1.8

package/README.md

@@ -0,0 +1,481 @@
+# @lastbrain/module-ai
+
+Module de génération IA complet pour LastBrain avec OpenAI. Fournit des pages web, des API routes et un système de gestion de tokens pour la génération de texte et d'images.
+
+## 🎯 Vue d'ensemble
+
+Ce module inclut tout ce dont vous avez besoin pour l'IA :
+
+- 🤖 **Génération de texte** - Utilise GPT-4o pour la génération de contenu
+- 🎨 **Génération d'images** - Intégration DALL-E pour créer des images
+- 💳 **Gestion de tokens** - Système de crédits et suivi de consommation
+- 📊 **Dashboard admin** - Gestion des tokens utilisateurs par les admins
+- 🛡️ **Sécurité** - Protection RLS et contrôle d'accès
+
+## 🚀 Démarrage rapide
+
+> **Recommandé :** Utilisez le CLI LastBrain pour créer une application complète avec le module AI
+
+```bash
+# Créer une nouvelle application avec le module AI inclus
+pnpx @lastbrain/app@latest init mon-app
+# Sélectionner "🤖 AI Generation" lors de la création
+
+cd mon-app
+pnpm db:init  # Applique automatiquement les migrations
+pnpm dev
+```
+
+## 📦 Installation manuelle
+
+Si vous intégrez LastBrain dans un projet existant :
+
+```bash
+pnpm add @lastbrain/module-ai @lastbrain/core @lastbrain/ui
+```
+
+Puis ajoutez le module à votre projet LastBrain :
+
+```bash
+pnpm lastbrain add-module ai
+pnpm build:modules
+```
+
+## ⚙️ Configuration
+
+### Variables d'environnement
+
+```bash
+# .env.local
+OPENAI_API_KEY=sk-your-openai-api-key-here
+
+# Supabase (requis)
+NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
+NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
+SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
+```
+
+### Configuration OpenAI
+
+Le module utilise les modèles OpenAI suivants par défaut :
+
+- **Texte** : `gpt-4o` (ou `gpt-4o-mini` pour les tâches simples)
+- **Images** : `dall-e-3` (ou `dall-e-2` pour des coûts réduits)
+
+## 🖼️ Pages Web fournies
+
+### Pages Utilisateur Authentifié
+
+#### 1. Gestion des Tokens (`/auth/ai/token`)
+
+**Component**: `TokenPage`
+
+Page de gestion des tokens utilisateur :
+
+- Solde actuel de tokens
+- Historique des transactions
+- Bouton pour acheter des tokens (placeholder)
+- Statistiques d'utilisation
+
+```tsx
+import { TokenPage } from "@lastbrain/module-ai";
+
+export default function UserTokens() {
+  return <TokenPage />;
+}
+```
+
+### Pages Administration
+
+#### 2. Administration des Tokens (`/admin/ai/user-token`)
+
+**Component**: `AdminUserTokenPage`
+
+Page d'administration pour gérer les tokens de tous les utilisateurs :
+
+- Liste de tous les utilisateurs avec leurs soldes
+- Recherche par email ou nom
+- Ajout/retrait de tokens pour un utilisateur
+- Pagination et tri
+
+```tsx
+import { AdminUserTokenPage } from "@lastbrain/module-ai";
+
+export default function AdminTokens() {
+  return <AdminUserTokenPage />;
+}
+```
+
+#### 3. Détail Utilisateur (`/admin/ai/user-token/[id]`)
+
+**Component**: `AdminUserTokenDetailPage`
+
+Page détaillée pour un utilisateur spécifique :
+
+- Historique complet des transactions
+- Ajout/retrait de tokens avec commentaire
+- Statistiques d'utilisation détaillées
+
+```tsx
+import { AdminUserTokenDetailPage } from "@lastbrain/module-ai";
+
+export default function AdminUserDetail() {
+  return <AdminUserTokenDetailPage />;
+}
+```
+
+## 🔌 Routes API
+
+### API Génération IA (`/api/ai/*`)
+
+#### POST `/api/ai/generate-text`
+
+Génère du texte avec GPT.
+
+**Body** :
+
+```json
+{
+  "prompt": "Écris un article sur l'IA",
+  "model": "gpt-4o", // optionnel, défaut: gpt-4o
+  "max_tokens": 1000, // optionnel, défaut: 500
+  "temperature": 0.7, // optionnel, défaut: 0.7
+  "cost_tokens": 100 // coût en tokens pour cette génération
+}
+```
+
+**Réponse** :
+
+```json
+{
+  "data": {
+    "text": "L'intelligence artificielle...",
+    "tokens_used": 95,
+    "model": "gpt-4o",
+    "cost_tokens": 100,
+    "remaining_tokens": 900
+  }
+}
+```
+
+#### POST `/api/ai/generate-image`
+
+Génère une image avec DALL-E.
+
+**Body** :
+
+```json
+{
+  "prompt": "Un chat en costume d'astronaute",
+  "model": "dall-e-3", // optionnel, défaut: dall-e-3
+  "size": "1024x1024", // optionnel, défaut: 1024x1024
+  "quality": "hd", // optionnel, défaut: standard
+  "cost_tokens": 200 // coût en tokens pour cette génération
+}
+```
+
+**Réponse** :
+
+```json
+{
+  "data": {
+    "image_url": "https://...",
+    "revised_prompt": "A cat wearing an astronaut suit...",
+    "model": "dall-e-3",
+    "cost_tokens": 200,
+    "remaining_tokens": 800
+  }
+}
+```
+
+### API Administration (`/api/ai/admin/*`)
+
+⚠️ **Toutes les routes admin nécessitent un accès super admin.**
+
+#### GET `/api/ai/admin/user-token`
+
+Liste tous les utilisateurs avec leurs soldes de tokens.
+
+**Query Parameters** :
+
+- `page` (optionnel, défaut: 1)
+- `per_page` (optionnel, défaut: 20)
+- `search` (optionnel) : Recherche par email ou nom
+
+**Réponse** :
+
+```json
+{
+  "data": [
+    {
+      "user_id": "uuid",
+      "email": "user@example.com",
+      "full_name": "John Doe",
+      "balance": 1500,
+      "total_spent": 500,
+      "last_transaction": "2024-01-01T00:00:00Z"
+    }
+  ],
+  "pagination": {
+    "page": 1,
+    "per_page": 20,
+    "total": 100,
+    "total_pages": 5
+  }
+}
+```
+
+#### POST `/api/ai/admin/user-token`
+
+Ajoute ou retire des tokens pour un utilisateur.
+
+**Body** :
+
+```json
+{
+  "user_id": "uuid",
+  "amount": 1000, // positif pour ajouter, négatif pour retirer
+  "description": "Achat de tokens premium",
+  "transaction_type": "purchase" // purchase, admin_grant, admin_debit, etc.
+}
+```
+
+#### GET `/api/ai/admin/user-token/[id]`
+
+Détails et historique pour un utilisateur spécifique.
+
+**Réponse** :
+
+```json
+{
+  "data": {
+    "user": {
+      "id": "uuid",
+      "email": "user@example.com",
+      "full_name": "John Doe",
+      "balance": 1500
+    },
+    "transactions": [
+      {
+        "id": "uuid",
+        "amount": 1000,
+        "description": "Achat de tokens",
+        "transaction_type": "purchase",
+        "created_at": "2024-01-01T00:00:00Z"
+      }
+    ],
+    "stats": {
+      "total_spent": 500,
+      "total_generated_texts": 25,
+      "total_generated_images": 10
+    }
+  }
+}
+```
+
+## 🗄️ Schéma de Base de Données
+
+### Table `user_token_ledger`
+
+Stocke les transactions de tokens des utilisateurs.
+
+```sql
+CREATE TABLE public.user_token_ledger (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  owner_id UUID NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE,
+  amount INTEGER NOT NULL,
+  balance_after INTEGER NOT NULL,
+  description TEXT,
+  transaction_type TEXT NOT NULL DEFAULT 'usage',
+  metadata JSONB DEFAULT '{}'::jsonb,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+```
+
+**Types de transactions** :
+
+- `purchase` : Achat de tokens
+- `usage` : Utilisation pour génération IA
+- `admin_grant` : Attribution par un admin
+- `admin_debit` : Retrait par un admin
+- `refund` : Remboursement
+
+### Table `user_prompts`
+
+Stocke l'historique des prompts et générations.
+
+```sql
+CREATE TABLE public.user_prompts (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  owner_id UUID NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE,
+  prompt TEXT NOT NULL,
+  response TEXT,
+  model TEXT NOT NULL,
+  tokens_used INTEGER,
+  cost_tokens INTEGER,
+  generation_type TEXT NOT NULL, -- 'text' ou 'image'
+  metadata JSONB DEFAULT '{}'::jsonb,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+```
+
+### Vues et Fonctions
+
+#### Vue `user_token_balance_v`
+
+Calcule automatiquement le solde actuel de chaque utilisateur :
+
+```sql
+CREATE VIEW user_token_balance_v AS
+SELECT
+  owner_id,
+  COALESCE(SUM(amount), 0) as balance,
+  COUNT(*) as total_transactions,
+  MAX(created_at) as last_transaction
+FROM user_token_ledger
+GROUP BY owner_id;
+```
+
+## 🔧 Utilisation dans le Code
+
+### Hooks React
+
+```tsx
+import { useTokenBalance, useAIGeneration } from "@lastbrain/module-ai";
+
+function MyAIComponent() {
+  const { balance, loading, refetch } = useTokenBalance();
+  const { generateText, generating } = useAIGeneration();
+
+  const handleGenerate = async () => {
+    const result = await generateText({
+      prompt: "Écris un poème sur l'automne",
+      max_tokens: 200,
+      cost_tokens: 50,
+    });
+
+    if (result.success) {
+      console.log("Texte généré:", result.data.text);
+      refetch(); // Rafraîchir le solde
+    }
+  };
+
+  return (
+    <div>
+      <p>Solde: {balance} tokens</p>
+      <Button onPress={handleGenerate} isLoading={generating}>
+        Générer du texte
+      </Button>
+    </div>
+  );
+}
+```
+
+### Utilisation directe des APIs
+
+```typescript
+// Génération de texte
+const response = await fetch("/api/ai/generate-text", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({
+    prompt: "Explique l'intelligence artificielle",
+    max_tokens: 500,
+    cost_tokens: 100,
+  }),
+});
+
+const result = await response.json();
+console.log(result.data.text);
+
+// Génération d'image
+const imageResponse = await fetch("/api/ai/generate-image", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({
+    prompt: "Un paysage futuriste",
+    size: "1024x1024",
+    cost_tokens: 200,
+  }),
+});
+
+const imageResult = await imageResponse.json();
+console.log(imageResult.data.image_url);
+```
+
+## 💳 Système de Tokens
+
+### Coûts par défaut
+
+Les coûts en tokens sont configurables mais voici les valeurs par défaut :
+
+**Génération de texte** :
+
+- GPT-4o : 1 token = ~10 tokens OpenAI
+- GPT-4o-mini : 1 token = ~5 tokens OpenAI
+
+**Génération d'images** :
+
+- DALL-E 3 (1024x1024) : 200 tokens
+- DALL-E 2 (1024x1024) : 100 tokens
+
+### Gestion du solde
+
+```typescript
+// Vérifier le solde avant génération
+const checkBalance = async (requiredTokens: number) => {
+  const response = await fetch("/api/ai/user/balance");
+  const { balance } = await response.json();
+
+  if (balance < requiredTokens) {
+    throw new Error("Solde insuffisant");
+  }
+};
+
+// Débiter automatiquement lors de la génération
+await generateText({
+  prompt: "...",
+  cost_tokens: 100, // Sera automatiquement débité
+});
+```
+
+## 🛡️ Sécurité et Limitations
+
+### Protection contre l'abus
+
+- **Rate limiting** : Les APIs ont des limites de débit
+- **Validation des prompts** : Filtrage du contenu inapproprié
+- **Vérification du solde** : Impossible de générer sans tokens suffisants
+
+### Row Level Security (RLS)
+
+- Les utilisateurs ne voient que leurs propres transactions et prompts
+- Les admins ont accès à toutes les données via les routes `/admin/*`
+
+### Exemple de politique RLS
+
+```sql
+-- Les utilisateurs ne voient que leurs propres transactions
+CREATE POLICY "user_token_ledger_owner_select" ON public.user_token_ledger
+FOR SELECT USING (auth.uid() = owner_id);
+
+-- Seuls les admins peuvent modifier via les APIs admin
+CREATE POLICY "user_token_ledger_admin_all" ON public.user_token_ledger
+FOR ALL USING (public.is_superadmin(auth.uid()));
+```
+
+## 🤝 Contribuer
+
+Ce package fait partie du monorepo LastBrain. Voir le [CONTRIBUTING.md](../../CONTRIBUTING.md) principal.
+
+## 📄 Licence
+
+MIT - Voir [LICENSE](../../LICENSE)
+
+## 🔗 Liens utiles
+
+- [OpenAI API Documentation](https://platform.openai.com/docs/api-reference)
+- [DALL-E Guide](https://platform.openai.com/docs/guides/images)
+- [GPT-4 Documentation](https://platform.openai.com/docs/models/gpt-4)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lastbrain/module-ai",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Module de génération IA (texte et images) avec gestion de tokens pour LastBrain",
   "private": false,
   "type": "module",
@@ -38,8 +38,8 @@
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "zod": "^3.23.8",
-    "@lastbrain/core": "0.1.8",
-    "@lastbrain/ui": "0.1.11"
+    "@lastbrain/core": "0.1.9",
+    "@lastbrain/ui": "0.1.12"
   },
   "peerDependencies": {
     "next": ">=15.0.0"