# API — langextract-api

Service FastAPI : enveloppe [LangExtract](https://github.com/google/langextract) pour extractions structurées depuis du texte.

- **Code** : [`services/langextract-api/`](../../services/langextract-api/)
- **Bind** : `LANGEXTRACT_API_HOST` (défaut `127.0.0.1`)
- **Port** : `LANGEXTRACT_API_PORT` (défaut `37141`)
- **OpenAPI** : `GET http://<host>:<port>/docs` une fois le service lancé

## Authentification

Si `LANGEXTRACT_SERVICE_TOKEN` est défini (non vide), toutes les routes **sauf** celles sans dépendance explicite doivent envoyer :

```http
Authorization: Bearer <LANGEXTRACT_SERVICE_TOKEN>
```

Actuellement **`/health`** n’impose pas le Bearer ; **`/extract`** impose le Bearer lorsque le token service est configuré.

## Endpoints

### `GET /health`

**Réponse `200`**

```json
{ "status": "ok" }
```

### `POST /extract`

Exécute une extraction LangExtract.

**Corps JSON** (modèle Pydantic `ExtractRequest`)

| Champ | Obligatoire | Description |
|-------|-------------|-------------|
| `text` | oui | Texte source |
| `prompt_description` | oui | Consigne d’extraction |
| `examples` | oui | Liste d’exemples (voir ci-dessous) |
| `model_id` | oui | Identifiant modèle (ex. tag Ollama) |
| `model_url` | non | URL du serveur modèle (ex. Ollama `http://127.0.0.1:11434`) |
| `extraction_passes` | non | Passes d’extraction |
| `max_workers` | non | Parallélisme |
| `max_char_buffer` | non | Taille tampon caractères |
| `api_key` | non | Clé cloud (sinon `LANGEXTRACT_API_KEY` en env) |
| `fence_output` | non | Option LangExtract |
| `use_schema_constraints` | non | Option LangExtract |

**Élément `examples`**

Chaque entrée : `{ "text": "...", "extractions": [ { "extraction_class", "extraction_text", "attributes": {} } ] }`.

**Réponse `200`**

```json
{
  "documents": [
    {
      "extractions": [
        {
          "extraction_class": "...",
          "extraction_text": "...",
          "attributes": {},
          "char_interval": { "start": 0, "end": 0 }
        }
      ]
    }
  ]
}
```

`char_interval` est présent lorsque le moteur le fournit.

**Erreurs**

- `400` : corps invalide ou exception LangExtract (`detail` message texte)
- `401` : Bearer attendu mais absent ou incorrect (si token service configuré)

## Variables d’environnement

| Variable | Obligatoire | Description |
|----------|-------------|-------------|
| `LANGEXTRACT_SERVICE_TOKEN` | non | Si défini, protège `/extract` |
| `LANGEXTRACT_API_HOST` | non | Bind |
| `LANGEXTRACT_API_PORT` | non | Port |
| `LANGEXTRACT_API_KEY` | non | Clé par défaut pour modèles cloud si le client n’envoie pas `api_key` |