api.pawol.nu/README.md

# API made with Strapi

<p  align="center">
  <a href="https://liberapay.com/OKI/donate/">
    <img src="https://img.shields.io/liberapay/receives/OKI.svg?logo=liberapay">
    <img src="https://img.shields.io/liberapay/patrons/OKI.svg?logo=liberapay">
    <img src="https://img.shields.io/liberapay/goal/OKI.svg?logo=liberapay">
  </a>
</p>

## Prérequis
- Node >= 16
- Npm ou Yarn

## Variables d'environnement
- Copier le contenu du fichier `.env.sample` dans un nouveau fichier `.env`
```
cp .env.sample .env
```

`STRAPI_URL` sera utile en production uniquement. Cette variable fait référence à l'url du site de production *(exemple : `https://api.mon-site.fr`)*.

`STRAPI_ADMIN_URL` fait référence à la route pour accéder à l'espace d'administration *(par défaut : `/admin`)* .

## Générer les clés nécessaires :

Ces variables d'environnement sont obligatoires :

- **APP_KEYS**
- **API_TOKEN_SALT**
- **ADMIN_JWT_SECRET**
- **JWT_SECRET** *(générée automatique si non renseignée)*

Afin de les renseigner, vous pouvez générer des clés en passant par node :

```bash
node
```

Une fois dans la console node, tapez :

```bash
crypto.randomBytes(16).toString('base64')
```
*retourne par exemple : 'BwUANVKSfenqAs1eFBHDIA=='*

Générez une clé pour chaque variable et ajoutez les au fichier .env.
La varialbe APP_KEYS peut en contenir plusieurs séparées, par une virgule :
*APP_KEYS=BwUANVKSfenqAs1eFBHDIA==,GiznuBga8kH0ZcOM5YO85w==*

Si la variable JWT_SECRET n'est pas renseignée, elle est générée automatiquement par Strapi.

## Installation des dépendances & lancement du serveur

```
yarn && yarn build && yarn dev
```

## Tokens API

Les endpoints marqués ⚙️ **Token requis** nécessitent un token API Strapi.

**Créer le token** : Administration Strapi → *Settings → API Tokens → Create new API Token*

| Endpoint | Type de token | Permissions requises |
|----------|---------------|----------------------|
| `GET /paroles/export` | Custom | Parole → `export` |
| `POST /paroles/bulk-translate` | Custom | Parole → `bulkTranslate` |

Pour un token couvrant les deux endpoints, créer un token de type **Custom** et cocher dans la section *Parole* : `export` et `bulkTranslate`.

Le token est à passer dans le header HTTP :
```
Authorization: Bearer <token>
```

---

## Point d'accès

### `/awtis`
- `GET` : Lister tous les artistes

### `/awtis/{id}`
- `GET` : Récupérer les informations d'un artiste

### `/awtis/count`
- `GET` : Récupère le nombre d'artiste
___

### `/paroles`
- `GET` : Lister tous les textes

### `/paroles/{id}`
- `GET` : Récupérer les informations d'un texte

### `/paroles/count`
- `GET` : Récupère le nombre de texte

### `/paroles/bulk-translate` ⚙️ Token requis
- `POST` : Traduit automatiquement via DeepL toutes les paroles ayant une source française (`traductions.francais` ou `langueSource: fr`) vers les langues manquantes (EN, ES, DE, IT). Ne modifie pas les traductions déjà existantes.

**Réponse :**
```json
{"translated": 42, "skipped": 18, "errors": []}
```

| Champ | Description |
|-------|-------------|
| `translated` | Nombre de traductions ajoutées |
| `skipped` | Paroles ignorées (pas de source FR ou déjà complètes) |
| `errors` | Erreurs DeepL avec `documentId`, `titre` et `lang` |

**Exemple :**
```bash
curl -X POST -H "Authorization: Bearer <token>" \
  "https://api.pawol.nu/api/paroles/bulk-translate"
```

___

### `/paroles/export` ⚙️ Token requis
- `GET` : Exporter les paroles et traductions au format JSONL ou JSON pour l'entraînement de modèles LLM

**Paramètres de requête :**

| Paramètre | Valeurs acceptées | Défaut | Description |
|-----------|-------------------|--------|-------------|
| `type`    | `pairs` \| `instruct` | `pairs` | Format des exemples d'entraînement |
| `lang`    | `fr,en,es,de,it` | toutes | Langues cibles à inclure (séparées par des virgules) |
| `format`  | `jsonl` \| `json` | `jsonl` | Format de la réponse |

**Type `pairs`** — corpus parallèle source/cible, adapté aux modèles de traduction :
```json
{"source_lang":"ka","target_lang":"fr","source":"Mwen ka palé épi ou…","target":"Je suis en train de te parler…","title":"Titre","artists":["Artiste"]}
```

**Type `instruct`** — format instruction/chat, adapté au fine-tuning de modèles d'instruction :
```json
{"messages":[{"role":"system","content":"Tu es un expert en langue KA…"},{"role":"user","content":"Tradui an fransé :\n\nMwen ka palé épi ou…"},{"role":"assistant","content":"Je suis en train de te parler…"}]}
```

**Format `jsonl`** : la première ligne contient les métadonnées (champ `_metadata: true`). Pour les filtrer :
```bash
jq 'select(._metadata | not)' export.jsonl
```

**Métadonnées incluses** (`_metadata: true` en JSONL, clé `metadata` en JSON) :

| Champ | Description |
|-------|-------------|
| `exported_at` | Horodatage de l'export |
| `total_paroles` | Nombre de paroles traitées |
| `total_pairs` | Nombre d'exemples d'entraînement générés |
| `languages` | Nombre de paires par langue |
| `missing_translations` | Paroles avec des traductions manquantes, par langue |
| `non_ka_transcriptions` | Paroles dont la transcription est suspectée d'être dans une autre langue (ex. français) |

**Exemple :**
```bash
curl -H "Authorization: Bearer <token>" \
  "https://api.pawol.nu/api/paroles/export?type=instruct&lang=fr,en&format=jsonl" \
  -o dataset.jsonl
```

## License

Copyright (C) 2024 Cédric Famibelle-Pronzola & ORGANISATION KA INTERNATIONALE (OKI)


### FR

Ce programme est un logiciel libre : vous pouvez le redistribuer et/ou le modifier selon les termes de la licence publique générale GNU Affero publiée par la Free Software Foundation, soit la version 3 de la licence, soit (à votre choix) toute version ultérieure.

Ce programme est distribué dans l'espoir qu'il sera utile, mais SANS AUCUNE GARANTIE ; sans même la garantie implicite de COMMERCIALISATION ou d'ADAPTATION À UN USAGE PARTICULIER. Voir la licence publique générale GNU Affero pour plus de détails.

Vous devriez avoir reçu une copie de la licence publique générale GNU Affero avec ce programme. Si ce n'est pas le cas, consultez https://www.gnu.org/licenses/.


### EN

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this program. If not, see https://www.gnu.org/licenses/.