📖 Guide de Référence des Filtres & API

Documentation interactive de l'API Neuro-Cognitive Hiztegia • 741 081 phrases alignées
🎯 Base Neuro-Linguistique : Ce serveur a été conçu selon les principes de neuro-pédagogie de l'apprentissage des langues (Krashen $i+1$, rétention mnésique par variabilité d'encodage). Il extrait parmi 741 081 phrases réelles bilingues des exemples parfaitement calibrés en longueur, complexité syntaxique, temps, mode et actants.

🌐 1. Les Endpoints Disponibles

GET /api/sentences/explore ✨ NOUVEAU • Mode Découverte

Moteur intelligent universel (utilisé par l'interface Grand Public) : prend n'importe quelle saisie et sélectionne automatiquement la meilleure stratégie linguistique :

curl "http://192.168.1.34:8088/api/sentences/explore?q=ikusi&difficulty=simple&count=5"
GET /api/sentences/random

Génère des phrases aléatoires calibrées selon vos filtres morphologiques, syntaxiques et thématiques. Idéal pour les générateurs de flashcards, fiches de révision et exercices réguliers.

curl "http://192.168.1.34:8088/api/sentences/random?difficulty=simple&length=short&tense=present&count=3"
GET /api/sentences/verb/{lemma}

Isole un verbe spécifique (ex: joan, ikusi, etorri, iritsi, jakin, eduki, etc.) et exploite la variabilité d'encodage neuro-cognitive (diverse=true) pour délivrer des angles grammaticaux complémentaires (1ère personne, 2ème personne, négation, formes synthétiques trinkoak, futur, etc.).

curl "http://192.168.1.34:8088/api/sentences/verb/joan?tense=future&diverse=true&count=5"
GET /api/sentences/search

Recherche plein-texte ultra-rapide (moteur SQLite FTS5) sur les phrases basques ou leurs traductions françaises, combinable avec tous les filtres de difficulté et de temps.

curl "http://192.168.1.34:8088/api/sentences/search?q=etxe&lang=eu&difficulty=simple&count=5"
GET /api/sentences/contrast (alias /api/sentences/confused-pairs)

Mode Paires Confuses (Discrimination Lexicale Contrastive) : Confronte 2 termes ou verbes fréquemment confondus ou complémentaires (ex: ikasi vs irakatsi, ekarri vs eraman, egon vs izan, bihar vs behar). Délivre 6 phrases réelles (3 pour chaque terme), vérifiées et ajustées par Gemini 3.6 Flash pour une mémorisation contrastive optimale.

curl "http://192.168.1.34:8088/api/sentences/contrast?w1=ikasi&w2=irakatsi&count_per_word=3&difficulty=simple"
GET /api/stats

Retourne l'état complet du corpus : nombre de phrases par niveau, répartition des systèmes d'actants, verbes synthétiques et subordonnées.

⚙️ 2. Matrice Complète des Paramètres de Filtrage

Paramètre Valeurs acceptées Description linguistique & pédagogique
count Entier (1 à 50, défaut: 5) Nombre de phrases à retourner.
difficulty simple, medium, advanced, all Niveau $i+1$ de Krashen : simple (A1-A2, phrases courtes et directes), medium (B1, déclinaisons, transitifs/datifs), advanced (B2+, subordonnées denses).
length short, medium, long, all Longueur en mots : short (2 à 6 mots), medium (7 à 12 mots), long (13+ mots).
min_words / max_words Entiers (ex: min_words=4&max_words=8) Contrôle précis et granulaire du nombre minimum ou maximum de mots.
tense present, past, future, all Temps verbal : present (Orainaldia), past (Lehenaldia : nuen, zuen, zen, zegoen...), future (Geroaldia : -ko da, -ko du, -go naiz...).
mood indicative, conditional, potential, all Mode verbal : indicative (mode réel standard), conditional (Baldintza / Ondorioa : balitz, balu, luke, nuke, litzateke), potential (Ahalera : daiteke, dezake, dezaket, liteke).
nominalization true, false (défaut: omis = all) Nominalisation du verbe (infinitif substantivé) : isole les structures en -tea / -tzea / -tzeko (ex: men egitea da, lan egiteko, joatea).
noun_cases
(ou noun_case)
Une ou plusieurs déclinaisons séparées par des virgules, ou all.
Ex: allative,inessive
Déclinaison nominale complète (Izen-deklinabidea - 13 cas) avec logique multi-sélection (OU) :
• inessive (Non ? Inessif en -an, -etan : lieu où l'on est • etxean, kalean, gelan)
• allative (Nora ? Allatif en -ra, -etara : direction / vers où • etxera, kalera, mendira)
• allative_terminal (Noraino ? Allatif terminal en -raino : jusqu'où • etxeraino, plazaraino)
• allative_directional (Norantz ? Allatif directionnel en -rantz : en direction de • etxerantz, mendirantz)
• ablative (Nondik ? Ablatif en -tik, -etatik : provenance / d'où • etxetik, kaletik, handik)
• genitive_possessive (Noren ? Génitif possessif en -en, -aren : possesseur • nire, zure, amaren)
• genitive_locative (Nongo ? Génitif locatif en -ko, -eko : origine locale • etxeko, Donostiako)
• sociative (Norekin ? Sociatif en -rekin, -ekin : accompagnement • zurekin, nirekin, lagunarekin)
• destinative (Norentzat ? Destinatif en -rentzat, -entzat : destinataire • niretzat, zuretzat, umeentzat)
• causal (Zergatik ? Causatif / motif en -gatik : cause / pourquoi • horregatik, zugatik)
• instrumental (Zertaz ? Instrumental en -z, -ez : moyen / matière • autoz, oinez, trenez, bidez)
• partitive (Zerik ? Partitif en -(r)ik : quantité indéterminée / doute • ogirik, dirurik, arazorik)
• prolative (Zertzat ? Prolatif en -tzat : rôle / en tant que • adibidetzat, laguntzat hartu)
case_system nor, nor_nork, nor_nori_nork, all Système d'actants : nor (intransitif : da, dira), nor_nork (transitif ergatif : du, dute, nuen), nor_nori_nork (ditransitif datif : dio, dit, zidan).
subordination lako, nean, la, rel_n, cond_ba, none, all Connecteur subordonnant : lako (cause: parce que), nean (temps: quand), la (complétive: que), rel_n (relative en -n: qui), cond_ba (si conditionnel).
is_synthetic true, false (défaut: omis) Verbes synthétiques directs (Trinkoak) : filtre les formes fléchies directes sans auxiliaire (noa, zoaz, doa, nator, dabil, dakit, dago, daukat...).
polarity negative, affirmative, all Polarité de la phrase : negative (automatise l'inversion de l'auxiliaire collé à ez / ezin), affirmative.
type statement, question, exclamation, all Type de phrase : déclarative, question (travail des mots interrogatifs Nora, Nondik, Nork, Zer), ou exclamation.
theme maison_quotidien, ville_transport, famille, nourriture, emotions, travail_etudes, temps_meteo, all Filtrage sémantique contextuel basé sur les champs lexicaux.
diverse true, false (sur l'endpoint /verb) Active l'échantillonnage de diversité neuro-cognitive pour maximiser la rétention mnésique en variant les temps, personnes et polarités.

💡 3. Exemples Concrets de Requêtes Adaptées aux Modules d'Apprentissage

Scénario A : Phrases à trous sur l'inversion négative (Niveau Débutant, Phrases Courtes)

GET /api/sentences/random?polarity=negative&difficulty=simple&length=short&count=5

Exemple de résultat : « Ez naiz hemen geratuko. » (Je ne resterai pas ici.)

Scénario B : Travailler le Conditionnel (Baldintza / Ondorioa)

GET /api/sentences/random?mood=conditional&count=3

Exemple de résultat : « Eskuina naizelako, ez nuke sekulan ezkerra erabili beharko? »

Scénario C : Travailler le Potentiel (Ahalera : daiteke / dezake)

GET /api/sentences/random?mood=potential&count=3

Exemple de résultat : « Nehor ez daiteke dirudien bezain ona izan. »

Scénario D : Nominalisation du Verbe (-tea / -tzea / -tzeko)

GET /api/sentences/random?nominalization=true&count=3

Exemple de résultat : « Tentazioari aurre egiteko manera bakarra, men egitea da. »

Scénario E : Maîtriser le Datif (NOR-NORI-NORK)

GET /api/sentences/random?case_system=nor_nori_nork&count=3

Exemple de résultat : « Mesede bat eskatu behar dizut. » (Je dois te demander un service.)

Scénario F : Variabilité complète sur le verbe « joan » au Passé

GET /api/sentences/verb/joan?tense=past&diverse=true&count=5

Scénario G : Déclinaisons Nominales & Multi-sélection (ex: Allatif + Sociatif)

GET /api/sentences/random?noun_cases=allative,sociative&difficulty=simple&count=5

Exemple de résultat : Phrases combinant soit le mouvement vers un lieu (-ra), soit l'accompagnement (-rekin) selon la logique disjonctive (OU).