# LangExtract — API locale (`services/langextract-api`)

## Objectif

Exposer [LangExtract](https://github.com/google/langextract) (Google, Apache-2.0) comme **service HTTP local** : à partir d’un texte, d’une consigne et d’exemples few-shot, produire des **extractions structurées** (classes, attributs, texte extrait) avec **ancrage** dans le texte lorsque le modèle et la librairie le fournissent (`char_interval`).

## Périmètre

- Pas de logique métier supplémentaire : l’API se limite à valider le JSON, appeler `langextract.extract`, sérialiser le résultat.
- Les modèles **cloud** (Gemini, etc.) suivent la configuration amont (clés API, quotas).
- Les modèles **locaux** passent typiquement par **Ollama** (`model_url`, options `fence_output` / `use_schema_constraints` selon la doc amont).

## Exploitation

| Élément | Détail |
|--------|--------|
| Code | [repo/service-langextract.md](../repo/service-langextract.md) |
| Hôte / port | `127.0.0.1` et port par défaut `37141` (voir README) |
| Auth | Si `LANGEXTRACT_SERVICE_TOKEN` est défini : en-tête `Authorization: Bearer …` obligatoire sur `POST /extract` |
| Santé | `GET /health` |

## Schéma de requête (`POST /extract`)

Champs principaux : `text`, `prompt_description`, `examples[]` (`text`, `extractions[]` avec `extraction_class`, `extraction_text`, `attributes`), `model_id`, et options optionnelles alignées sur l’API Python (`model_url`, `extraction_passes`, `max_workers`, `max_char_buffer`, `api_key`, `fence_output`, `use_schema_constraints`).

Réponse : `{ "documents": [ { "extractions": [ … ] } ] }` avec, par extraction, `extraction_class`, `extraction_text`, `attributes`, et `char_interval` `{ "start", "end" }` si présent.

## Intégration architecture

Ce service complète le socle décrit dans [system-architecture.md](../system-architecture.md) : un client (éditeur type Lapce, gateway, script) peut appeler l’extraction structurée **sans** embarquer Python dans l’UI, tant que le réseau local et le token le permettent.

## Références

- Dépôt amont : [https://github.com/google/langextract](https://github.com/google/langextract)
- PyPI : [https://pypi.org/project/langextract/](https://pypi.org/project/langextract/)