@omniyat/aimodule 1.0.0

package/README.md

@@ -0,0 +1,180 @@
+# 🤖 @brinda_yawa/ai-module
+
+A unified Node.js module for AI-powered invoice extraction and task generation using Google's Gemini models.
+
+## ✨ Features
+
+- 🧾 **Invoice Extraction** - Extract structured data from PDF and image invoices
+- ✅ **Task Generation** - Generate structured task lists from intervention descriptions
+- 🖼️ **Multi-modal Support** - Handles images (PNG, JPG, JPEG, WEBP) and audio files
+- 🎯 **Structured Output** - Returns clean, structured JSON data
+- 🔑 **Single Initialization** - One `init()` call configures all services
+- 🧩 **Modular Design** - Access each service independently via `AiModule.invoices` or `AiModule.tasks`
+
+## 📦 Installation
+
+```bash
+npm install @brinda_yawa/ai-module
+```
+
+## 🚀 Quick Start
+
+```javascript
+import AiModule from '@brinda_yawa/ai-module';
+import fs from 'fs';
+
+// Initialize the module once
+AiModule.init({
+    apiKey: 'YOUR_GEMINI_API_KEY',
+    model: 'gemini-2.5-flash' // optional, default: gemini-2.5-flash
+});
+
+// Extract invoice data from a PDF
+const buffer = fs.readFileSync('invoice.pdf');
+const base64 = buffer.toString('base64');
+const invoiceData = await AiModule.invoices.extractFromBase64(base64);
+
+// Generate tasks from an intervention description
+const tasks = await AiModule.tasks.generateTasks(
+    'Pneu crevé',
+    'Intervention de dépannage suite à un pneu crevé...'
+);
+```
+
+## 📖 API Reference
+
+### `AiModule.init(options)`
+
+Initializes all services with the provided configuration. Must be called before using any service.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `apiKey` | `string` | ✅ | — | Your Google Gemini API key |
+| `model` | `string` | ❌ | `gemini-2.5-flash` | Gemini model to use |
+
+```javascript
+AiModule.init({ apiKey: process.env.GEMINI_API_KEY });
+```
+
+---
+
+### `AiModule.invoices`
+
+Access the invoice extraction service.
+
+#### `AiModule.invoices.extractFromBase64(base64Data)`
+
+Extracts structured invoice data from a base64-encoded file.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `base64Data` | `string` | ✅ | Base64 string (with or without `data:...;base64,` prefix) |
+
+**Returns:** `Promise<Object | null>`
+
+```javascript
+const buffer = fs.readFileSync('invoice.pdf');
+const base64 = buffer.toString('base64');
+
+const result = await AiModule.invoices.extractFromBase64(base64);
+console.log(result);
+// {
+//   invoiceNumber: "INV-2024-001",
+//   date: "2024-01-15",
+//   total: 1250.00,
+//   vendor: { name: "...", address: "..." },
+//   items: [...]
+// }
+```
+
+**Supported formats:** PDF, PNG, JPG, JPEG, WEBP
+
+---
+
+### `AiModule.tasks`
+
+Access the task generation service.
+
+#### `AiModule.tasks.generateTasks(title, description, joinedImage?, joinedAudio?)`
+
+Generates a structured list of tasks from an intervention description.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `title` | `string` | ✅ | Short title of the intervention |
+| `description` | `string` | ✅ | Detailed description of the intervention |
+| `joinedImage` | `{ buffer: Buffer, extension: string }` | ❌ | Optional image file |
+| `joinedAudio` | `{ buffer: Buffer, extension: string }` | ❌ | Optional audio file |
+
+**Returns:** `Promise<Array<{ title: string, description: string }>>`
+
+```javascript
+// Text only
+const tasks = await AiModule.tasks.generateTasks(
+    'Vidange moteur',
+    'Vidange complète du moteur avec remplacement du filtre à huile.'
+);
+
+// With an image
+const imageBuffer = fs.readFileSync('photo.webp');
+const tasks = await AiModule.tasks.generateTasks(
+    'Pneu crevé',
+    'Intervention suite à un pneu crevé...',
+    { buffer: imageBuffer, extension: '.webp' }
+);
+
+console.log(tasks);
+// [
+//   { title: "Diagnostic", description: "Inspecter le pneumatique..." },
+//   { title: "Réparation", description: "Poser une mèche ou remplacer..." },
+//   ...
+// ]
+```
+
+**Supported image formats:** PNG, JPG, JPEG, WEBP  
+**Supported audio formats:** MP3, WAV
+
+---
+
+## 🗂️ Module Structure
+
+```
+ai-module/
+├── index.js                  # AiModule entry point
+├── services/
+│   ├── InvoiceExtractor.js   # Invoice extraction logic
+│   └── TasksGenerator.js     # Task generation logic
+└── utils/
+    └── util.js               # Shared utilities (prompts, mime types...)
+```
+
+## 🔑 Environment Variables
+
+It is recommended to store your API key in a `.env` file:
+
+```env
+GEMINI_API_KEY=your_api_key_here
+```
+
+```javascript
+import dotenv from 'dotenv';
+dotenv.config();
+
+AiModule.init({ apiKey: process.env.GEMINI_API_KEY });
+```
+
+## ⚠️ Error Handling
+
+```javascript
+try {
+    AiModule.init({ apiKey: process.env.GEMINI_API_KEY });
+
+    const tasks = await AiModule.tasks.generateTasks(title, description);
+} catch (error) {
+    if (error.message.includes('not initialized')) {
+        console.error('Call AiModule.init() before using any service.');
+    } else {
+        console.error('Unexpected error:', error.message);
+    }
+}
+```