Guide d’intégration
Construire
Extraire une demande client fictive. `SCHEMA` dans `extract.py` décrit tous les champs : chaînes ou null, quantité entière positive ou null, date ISO ou null. Tous les champs sont obligatoires dans l’objet ; leur valeur est facultative. `missing_fields` énumère exactement les champs null. Les propriétés supplémentaires sont rejetées. La validation structurelle ne prouve pas l’exactitude des faits : vérifiez le résultat avant tout traitement métier.
Prérequis et installation
Python 3.10 ou supérieur, bibliothèque standard uniquement, aucune installation pip.
cp .env.example .env
# Renseigner les variables, puis :
python3 extract.py
python3 extract.py 'Je voudrais un devis pour des carnets.'
python3 -m unittest -vFonctionnement et personnalisation
Le programme charge `.env` comme données sans l’exécuter. Une variable déjà exportée a priorité. Il effectue un seul appel avec `response_format: json_schema`, nom `customer_request`, `strict: true`, puis parse et valide le JSON. Le schéma transmis fixe les types et les champs ; Python vérifie en plus les dates, les quantités, les longueurs et la cohérence des champs manquants. Un prompt seul ne garantit pas le JSON. En cas d’échec, aucun objet n’est accepté. Modifiez `samples.json` pour essayer les cas complet, incomplet et ambigu : chaque exécution normale ne traite que le premier texte, ou le texte passé en argument. Pour tester l’ambiguïté, passez le troisième texte en argument : noms, quantités, villes et date relative doivent rester null. Cette attente doit être évaluée avec le modèle réel ; les tests mock vérifient uniquement le contrat et le validateur. 4 000 caractères en entrée, 512 tokens maximum, délai réseau de 20 s, pas de relance. Le JSON validé sort sur stdout, la consommation sur stderr. Codes de sortie : 0 succès, 1 erreur API/réseau, 2 configuration/validation.
Compte et clé
Ouvrez `/signup` dans la console déployée, créez votre projet, puis une clé dans `/app/api-keys`. Ajoutez des crédits si nécessaire. Conservez la clé côté serveur. Les domaines sont centralisés dans `apps/web/lib/domains.ts` : site https://todou.dev, console https://console.todou.dev, documentation https://docs.todou.dev, API https://api.todou.dev. Site, console et documentation partagent le même frontend Next.js. En local, utilisez l’URL de votre backend, par défaut http://127.0.0.1:8000. Le champ TODOU_API_BASE_URL inclut toujours `/v1`.
Variables d’environnement
Copiez `.env.example` vers `.env`. Renseignez `TODOU_API_KEY`, `TODOU_API_BASE_URL` (URL terminée par `/v1`) et `TODOU_MODEL`. `todou-fast` est un identifiant initialisé par la migration du 23 août 2026 ; vérifiez sa disponibilité avec `GET /v1/models` et le même Bearer. Ne commitez jamais `.env`. Aucun SDK Todou n’est nécessaire.
Appel API
`POST /v1/chat/completions`, `Authorization: Bearer <clé>`, JSON avec `model`, `messages`, `max_tokens`, `temperature` et `stream: false`. Le contenu se trouve dans `choices[0].message.content` et la consommation dans `usage.prompt_tokens`, `usage.completion_tokens`, `usage.total_tokens`. Le backend relaie le streaming SSE du fournisseur lorsqu’il est activé pour le modèle. Ces exemples utilisent `stream: false` pour valider une réponse complète. `response_format` est relayé au fournisseur ; l’exemple Python transmet un schéma JSON strict. Vérifiez la capacité `structured_outputs` dans GET /v1/models. Une capacité refusée ou un fournisseur incompatible produit une erreur : le validateur Python reste obligatoire même avec une sortie structurée.
Consommation
Consultez `/app/usage` et `/app/billing`. Calcul en USD : `tokens_entrée / 1 000 000 × prix_entrée + tokens_sortie / 1 000 000 × prix_sortie`. Contrat examiné le 9 septembre 2026, modèle proposé `todou-fast`, un appel sans relance automatique. Les prix de migration sont modifiables ; les tarifs effectifs doivent être vérifiés dans la console au moment du test. Aucun montant de production n’est garanti ici. Le backend réserve le coût maximal avant génération puis libère la part inutilisée. Un timeout client ne garantit pas l’annulation de la facturation.
Erreurs et limites communes
401 : clé absente/invalide ; 402 : crédit insuffisant ; 404 : modèle indisponible ; 422 : requête invalide ; 429 : fréquence dépassée ; 502/503 : fournisseur indisponible. Les limites API sont configurables et utilisent le mécanisme Redis existant. Un refus HTTP 429 indique une limite atteinte ; suivez les informations renvoyées par le backend et consultez la configuration de votre déploiement. Ne relancez pas automatiquement un appel facturable. Ne transmettez pas de données personnelles réelles dans ces démonstrations. Les tests locaux utilisent des mocks, ne prouvent pas la qualité d’un modèle réel et ne consomment aucun crédit.
Publication et licence
Dossier autonome, prêt à être copié dans un dépôt après revue. Aucun dépôt public n’a été créé. Aucune licence applicable explicitement aux exemples n’a été trouvée : choisir une licence avant publication. Ne déployez pas ces scripts comme service public sans authentification, quotas persistants et plafond monétaire.