Zfred-Request

Outil en ligne de commande qui traduit vos questions en langage naturel en requêtes SQL ou NoSQL, les exécute sur votre base de données et affiche le résultat dans le terminal.

Fonctionnalités

• Requêtes en français, anglais, espagnol, chinois ou toute autre langue (aucune configuration).
• Support relationnel : PostgreSQL, MySQL, SQLite.
• Support NoSQL : MongoDB, Redis, Elasticsearch.
• Introspection automatique du schéma (tables / collections / index / clés, types, exemples de valeurs).
• Mode lecture seule par défaut — --write pour autoriser les écritures.
• Configuration stockée localement, hors du projet (~/.config/zfred-request/).
• Utilisable en CLI et comme bibliothèque Node.js.

Installation

Le paquet est publié sur GitHub Packages sous le nom @foumvn/zfred-request (privé — nécessite un jeton GitHub avec le scope read:packages).

# Ajoute le registre puis installe
npm install -g @foumvn/zfred-request --registry=https://npm.pkg.github.com

Sans jeton renseigné, installe-le depuis les sources du dépôt : npm install -g .

Utilisation

1. Configuration initiale

zfred init

Un questionnaire interactif collecte le moteur de base de données et ses paramètres (hôte, port, base, utilisateur, mot de passe — ou URI/URL pour MongoDB, Redis et Elasticsearch). L'intelligence intégrée est préconfigurée, aucune saisie n'est nécessaire. Le schéma de la base est analysé et enregistré (tables, colonnes, collections, indices, exemples de valeurs) pour que vos requêtes restent cohérentes avec vos données. La connexion est testée avant d'être enregistrée.

2. Interroger la base

SQL :

zfred "dans ma table utilisateur, sélectionne tous les utilisateurs ayant une note supérieure à 13"
zfred "select all users with a grade above 13"

MongoDB :

zfred "dans ma collection utilisateurs, tous les documents avec une note supérieure à 13"

Redis :

zfred "récupère la valeur de la clé user:1"
zfred "donne-moi les 5 premiers éléments de la liste messages"

Elasticsearch :

zfred "cherche les documents de l'index produits où nom contient café"

Le SQL ou la commande NoSQL générée (JSON structuré) est affiché, puis la requête est exécutée immédiatement (aucune confirmation). La traduction est bornée (timeout 30 s par tentative, 2 tentatives) avec secours automatique si le modèle par défaut échoue — en cas de problème réseau transitoire, la traduction est réessayée automatiquement.

3. Mode interactif (REPL)

Après zfred init, ou en lançant simplement zfred sans argument, tu entres en mode interactif : le prompt zfred " est déjà affiché, tu tapes directement ta question (sans zfred, sans guillemets), et tu enchaînes autant de requêtes que tu veux.

zfred " moyenne des notes par élève
zfred " les 3 meilleures notes
zfred " exit

• Sortie : exit, quit, q, Ctrl+C ou Ctrl+D.
• Historique : flèches ↑/↓ pour retrouver les requêtes précédentes.
• Écritures : lance zfred --write pour autoriser les opérations d'écriture (INSERT / UPDATE / DELETE en SQL, insert / update / delete en NoSQL) pendant la session (prompt zfred --write ").
• Connexion réutilisée : une seule connexion à la base pour toute la session.

Options

| Option | Description | | --- | --- | | --write | Autorise les écritures (désactivé par défaut) | | --model <nom> | Modèle IA utilisé (défaut : codestral-latest, secours automatique : mistral-medium-latest ; variable d'env ZFRED_MODEL) |

zfred sans argument ouvre le mode interactif (voir plus haut). Les opérations de lecture sont exécutées immédiatement, sans confirmation. Les écritures sont bloquées sauf si --write est fourni.

Utilisation en bibliothèque

import { translate, query } from '@foumvn/zfred-request';

// Traduction seule
const sql = await translate("combien d'utilisateurs par ville ?", { db });

// Traduction + exécution (lecture seule) — sql est une chaîne (SQL) ou un objet commande (NoSQL)
const { data, rows } = await query("les 5 meilleures notes", { db });

// Autoriser les écritures
await query("mets à jour la note de Jean à 18", { db }, { write: true });

query renvoie { sql, rows } : sql est la requête SQL ou la commande JSON NoSQL, rows les lignes/documents résultants. Si config n'est pas fourni, la configuration enregistrée via zfred init est utilisée.

Sécurité

• Les identifiants de base de données ne sont jamais stockés dans le code source (configuration locale à l'utilisateur).
• SQL : les requêtes de lecture (SELECT, PRAGMA, SHOW, EXPLAIN, DESCRIBE, …) sont exécutées directement ; toute requête contenant un mot-clé de modification (INSERT, UPDATE, DELETE, DROP, ALTER, CREATE, TRUNCATE, …) est bloquée sans --write.
• MongoDB : les opérations write (insert*, update*, replaceOne, delete*, drop, createIndex…) et les agrégations avec $out/$merge sont bloquées sans --write.
• Redis : les commandes d'écriture (SET, HSET, DEL, LPUSH, SADD, ZADD, FLUSHDB…) sont bloquées sans --write.
• Elasticsearch : les opérations d'écriture (index, create, update, delete, bulk, reindex…) sont bloquées sans --write.
• Le SQL / la commande générée est toujours affiché avant exécution.

Structure du projet

zfred-request/
├── package.json
├── index.js            # API bibliothèque
├── bin/cli.js          # CLI (zfred init, zfred "requête", mode interactif)
├── scripts/postinstall.js
├── test/               # tests node:test
└── src/
    ├── config.js       # stockage local de la config + schéma
    ├── db.js           # répartiteur de connexions
    ├── llm.js          # traduction langage naturel → SQL / commande NoSQL
    ├── safety.js       # mode lecture seule
    └── drivers/
        ├── sql-common.js       # helpers partagés (postgres, mysql, sqlite)
        ├── postgres.js
        ├── mysql.js
        ├── sqlite.js
        ├── mongodb.js
        ├── redis.js
        └── elasticsearch.js

Licence

MIT