civjdr/API_CONFLUENT.md

# API ConfluentTranslator - Documentation

Cette API permet de traduire entre le français et la langue de la Confluence (Ancien Confluent et Proto-Confluent).

## URL de base

```
https://confluent.etheryale.com
```

## Authentification

Toutes les requêtes (sauf `/api/stats`) nécessitent une authentification par clé API :

```
X-API-Key: [CLÉ_API]
```

**Note** : Claude Code a accès à la clé API pour ce projet. Elle n'est pas incluse dans ce document pour des raisons de sécurité.

---

## Endpoints principaux

### 1. Traduire FR → Confluent (avec LLM)

Utilise un LLM (Claude ou GPT) pour traduire du français vers le Confluent.

**Endpoint** : `POST /translate`

**Paramètres** :
- `text` (string, requis) : Texte français à traduire
- `target` (string, requis) : `"ancien"` ou `"proto"`
- `provider` (string, requis) : `"anthropic"` (recommandé) ou `"openai"`
- `model` (string, requis) :
  - Anthropic : `"claude-sonnet-4-20250514"` ou `"claude-haiku-4-20250514"`
  - OpenAI : `"gpt-4o"` ou `"gpt-4o-mini"`
- `temperature` (number, optionnel) : Température du LLM (défaut: 1.0)
- `useLexique` (boolean, optionnel) : Utiliser l'analyse contextuelle (défaut: true)

**Exemple** :

```bash
curl -X POST https://confluent.etheryale.com/translate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: [CLÉ_API]" \
  -d '{
    "text": "bonjour",
    "target": "ancien",
    "provider": "anthropic",
    "model": "claude-sonnet-4-20250514"
  }'
```

**Réponse** :

```json
{
  "layer1": {
    "translation": "oratosa"
  },
  "layer2": {
    "wordsFound": [...],
    "wordsNotFound": [...],
    "entriesUsed": 15,
    "tokensUsed": 2500,
    "tokensSaved": 12000,
    "savingsPercent": 82.7
  },
  "layer3": {
    "analyse": "...",
    "strategie": "...",
    "decomposition": "...",
    "notes": "..."
  },
  "translation": "oratosa"
}
```

---

### 2. Traduire Confluent → FR (lookup direct)

Traduction brute mot-à-mot depuis le Confluent vers le français (sans LLM).

**Endpoint** : `POST /api/translate/conf2fr`

**Paramètres** :
- `text` (string, requis) : Texte en Confluent
- `variant` (string, optionnel) : `"ancien"` (défaut) ou `"proto"`
- `detailed` (boolean, optionnel) : Retourner les détails par mot (défaut: false)

**Exemple** :

```bash
curl -X POST https://confluent.etheryale.com/api/translate/conf2fr \
  -H "Content-Type: application/json" \
  -H "X-API-Key: [CLÉ_API]" \
  -d '{
    "text": "nakuura",
    "variant": "ancien"
  }'
```

**Réponse** :

```json
{
  "translation": "enfants du courant",
  "coverage": 100,
  "wordsTranslated": 1,
  "wordsNotTranslated": 0
}
```

---

### 3. Traduire Confluent → FR (avec raffinage LLM)

Traduction mot-à-mot suivie d'un raffinage par LLM pour un français naturel.

**Endpoint** : `POST /api/translate/conf2fr/llm`

**Paramètres** :
- `text` (string, requis) : Texte en Confluent
- `variant` (string, optionnel) : `"ancien"` (défaut) ou `"proto"`
- `provider` (string, optionnel) : `"anthropic"` (défaut) ou `"openai"`
- `model` (string, optionnel) : Modèle à utiliser

**Exemple** :

```bash
curl -X POST https://confluent.etheryale.com/api/translate/conf2fr/llm \
  -H "Content-Type: application/json" \
  -H "X-API-Key: [CLÉ_API]" \
  -d '{
    "text": "nakuura oratosa",
    "variant": "ancien",
    "provider": "anthropic",
    "model": "claude-sonnet-4-20250514"
  }'
```

**Réponse** :

```json
{
  "confluentText": "nakuura oratosa",
  "rawTranslation": "enfants du courant bonjour",
  "refinedTranslation": "Les enfants du courant vous saluent",
  "translation": "Les enfants du courant vous saluent",
  "coverage": 100,
  "wordsTranslated": 2,
  "wordsNotTranslated": 0
}
```

---

### 4. Rechercher un mot dans le lexique

Recherche bidirectionnelle dans le lexique (FR→CF ou CF→FR).

**Endpoint** : `GET /api/search`

**Paramètres** :
- `q` (string, requis) : Mot à rechercher
- `variant` (string, optionnel) : `"ancien"` (défaut) ou `"proto"`
- `direction` (string, optionnel) : `"fr2conf"` (défaut) ou `"conf2fr"`

**Exemple** :

```bash
curl "https://confluent.etheryale.com/api/search?q=enfant&variant=ancien&direction=fr2conf" \
  -H "X-API-Key: [CLÉ_API]"
```

**Réponse** :

```json
{
  "query": "enfant",
  "variant": "ancien",
  "direction": "fr2conf",
  "results": [
    {
      "mot": "enfant",
      "traductions": [
        {
          "confluent": "kuura",
          "type": "racine",
          "contexte": "jeune humain"
        }
      ]
    }
  ]
}
```

---

### 5. Analyser la couverture lexicale

Analyse un texte français pour voir combien de mots sont présents dans le lexique.

**Endpoint** : `POST /api/analyze/coverage`

**Paramètres** :
- `text` (string, requis) : Texte français à analyser
- `target` (string, optionnel) : `"ancien"` (défaut) ou `"proto"`

**Exemple** :

```bash
curl -X POST https://confluent.etheryale.com/api/analyze/coverage \
  -H "Content-Type: application/json" \
  -H "X-API-Key: [CLÉ_API]" \
  -d '{
    "text": "Les enfants du courant pêchent dans la rivière",
    "target": "ancien"
  }'
```

**Réponse** :

```json
{
  "coverage": 85.7,
  "found": [
    {"word": "enfants", "confluent": "nakuura", "type": "composition"},
    {"word": "courant", "confluent": "kuuraa", "type": "racine"}
  ],
  "missing": [
    {"word": "pêchent"}
  ],
  "stats": {
    "totalWords": 7,
    "uniqueWords": 7,
    "foundCount": 6,
    "missingCount": 1
  },
  "recommendation": "Good coverage - context only"
}
```

---

### 6. Statistiques du lexique

Récupère les statistiques globales du lexique (endpoint public, pas d'authentification).

**Endpoint** : `GET /api/stats`

**Paramètres** :
- `variant` (string, optionnel) : `"ancien"` (défaut) ou `"proto"`

**Exemple** :

```bash
curl "https://confluent.etheryale.com/api/stats?variant=ancien"
```

**Réponse** :

```json
{
  "motsCF": 450,
  "motsFR": 520,
  "totalTraductions": 680,
  "racines": 180,
  "racinesSacrees": 35,
  "racinesStandards": 145,
  "compositions": 250,
  "verbes": 45,
  "particules": 30,
  "nomsPropes": 25
}
```

---

## Utilisation dans du code JavaScript

```javascript
const API_KEY = '[CLÉ_API]';
const BASE_URL = 'https://confluent.etheryale.com';

// Traduire FR → Confluent
async function translateToConfluent(text) {
  const response = await fetch(`${BASE_URL}/translate`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': API_KEY
    },
    body: JSON.stringify({
      text: text,
      target: "ancien",
      provider: "anthropic",
      model: "claude-sonnet-4-20250514"
    })
  });

  const data = await response.json();
  return data.translation;
}

// Traduire Confluent → FR
async function translateFromConfluent(text) {
  const response = await fetch(`${BASE_URL}/api/translate/conf2fr`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': API_KEY
    },
    body: JSON.stringify({
      text: text,
      variant: "ancien"
    })
  });

  const data = await response.json();
  return data.translation;
}

// Rechercher un mot
async function searchWord(word) {
  const response = await fetch(
    `${BASE_URL}/api/search?q=${encodeURIComponent(word)}&variant=ancien&direction=fr2conf`,
    {
      headers: {
        'X-API-Key': API_KEY
      }
    }
  );

  const data = await response.json();
  return data.results;
}
```

---

## Notes importantes

- **Rate limiting** : L'API suit l'utilisation des tokens LLM. Vérifie `/api/llm/limit` pour connaître ton quota.
- **Variantes** :
  - `"ancien"` : Ancien Confluent (langue mature, recommandé)
  - `"proto"` : Proto-Confluent (langue primitive)
- **Provider recommandé** : Anthropic (Claude) pour la meilleure qualité de traduction
- **Analyse contextuelle** : Active par défaut, envoie uniquement les mots pertinents au LLM (économise ~80% de tokens)

---

## Ressources

- **Interface web** : https://confluent.etheryale.com
- **Interface admin** : https://confluent.etheryale.com/admin.html
- **Documentation linguistique** : Voir le dépôt `confluent/` pour les détails de la langue