> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fim.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Variables d'environnement
> Référence de configuration complète pour FIM One.
Toute la configuration se fait via `.env`. Copiez `example.env` et remplissez vos valeurs :
```bash theme={null}
cp example.env .env
```
## Niveaux de Configuration
Chaque intégration a un niveau de configuration indiquant son importance :
| Niveau | Signification | Comportement si non configuré |
| -------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------- |
| **Requis** | Dépendance système essentielle | Le système génère une erreur — le chat et les fonctions principales ne fonctionnent pas |
| **Recommandé** | Activateur de fonctionnalité significative | Dégradation progressive — la fonctionnalité est visiblement indisponible mais le système fonctionne |
| **Optionnel** | Capacité d'amélioration | Dégradation transparente — le système fonctionne correctement, la capacité est simplement absente |
> **Remarque** : Les modèles configurés par l'administrateur (Admin → page Modèles) peuvent remplacer les variables d'environnement LLM. La vérification de santé considère les deux sources.
***
## Frontend (Développement local uniquement)
Le frontend a un fichier env séparé **uniquement pour le développement local** : `frontend/.env.local`.
> **Ce fichier n'est PAS utilisé dans Docker.** À l'intérieur du conteneur Docker, Next.js proxifie `/api/*` vers le backend Python en interne (le port 8000 est interne au conteneur), donc aucun fichier env frontend n'est nécessaire.
Pour le développement local, les valeurs par défaut fonctionnent directement — vous n'avez **pas** besoin de créer `frontend/.env.local` sauf si votre backend s'exécute sur un port non-standard.
Si vous devez remplacer les valeurs, créez `frontend/.env.local` manuellement :
```bash theme={null}
echo 'NEXT_PUBLIC_API_URL=http://localhost:9000' > frontend/.env.local
```
| Variable | Par défaut | Description |
| --------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `NEXT_PUBLIC_API_URL` | `http://localhost:8000` *(auto)* | URL du backend que le **navigateur** utilise pour les appels API directs (redirections OAuth, streaming). Détectée automatiquement à partir de `window.location` si non définie — remplacez-la uniquement si votre backend s'exécute sur un port non-standard localement. |
> **Note au moment de la compilation** : les variables `NEXT_PUBLIC_*` sont intégrées au bundle JS au moment de `pnpm build`. Les modifier à l'exécution (par ex. via le fichier `.env` racine) n'a aucun effet — c'est pourquoi elles se trouvent dans `frontend/.env.local` pour le développement local uniquement.
## LLM (Requis)
| Variable | Requis | Par défaut | Description |
| --------------------------------- | ------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `LLM_API_KEY` | **Oui** | — | Clé API du fournisseur LLM |
| `LLM_BASE_URL` | Non | `https://api.openai.com/v1` | URL de base de toute API compatible OpenAI |
| `LLM_MODEL` | Non | `gpt-4o` | Modèle principal — utilisé pour la planification, l'analyse et l'agent ReAct |
| `FAST_LLM_MODEL` | Non | *(revient à `LLM_MODEL`)* | Modèle rapide — utilisé pour l'exécution des étapes DAG (moins cher, plus rapide) |
| `LLM_TEMPERATURE` | Non | `0.7` | Température d'échantillonnage par défaut |
| `LLM_CONTEXT_SIZE` | Non | `128000` | Taille de la fenêtre de contexte pour le LLM principal |
| `LLM_MAX_OUTPUT_TOKENS` | Non | `64000` | Tokens de sortie max par appel pour le LLM principal |
| `FAST_LLM_API_KEY` | Non | *(revient à `LLM_API_KEY`)* | Clé API du fournisseur du modèle rapide. À utiliser quand le modèle rapide est hébergé par un fournisseur différent du modèle principal |
| `FAST_LLM_BASE_URL` | Non | *(revient à `LLM_BASE_URL`)* | URL de base du fournisseur du modèle rapide |
| `FAST_LLM_TEMPERATURE` | Non | *(revient à `LLM_TEMPERATURE`)* | Température d'échantillonnage pour le modèle rapide |
| `FAST_LLM_CONTEXT_SIZE` | Non | *(revient à `LLM_CONTEXT_SIZE`)* | Taille de la fenêtre de contexte pour le LLM rapide |
| `FAST_LLM_MAX_OUTPUT_TOKENS` | Non | *(revient à `LLM_MAX_OUTPUT_TOKENS`)* | Tokens de sortie max par appel pour le LLM rapide |
| `LLM_REASONING_EFFORT` | Non | *(désactivé)* | Niveau de réflexion étendue pour les modèles supportés (OpenAI série o, Gemini 2.5+, Claude). Valeurs : `low`, `medium`, `high`. LiteLLM traduit cela au format natif de chaque fournisseur automatiquement. La chaîne de réflexion du modèle est affichée dans l'étape « thinking » de l'interface. |
| `LLM_REASONING_BUDGET_TOKENS` | Non | *(auto à partir de l'effort)* | Budget de tokens explicite pour la réflexion Anthropic (minimum 1024). Pour OpenAI/Gemini, le niveau d'effort est utilisé directement. Effectif uniquement quand `LLM_REASONING_EFFORT` est défini. |
| `LLM_JSON_MODE_ENABLED` | Non | `true` | Basculement global pour `response_format=json_object`. Définir à `false` si votre fournisseur rejette l'injection de prefill assistant de LiteLLM (par ex. relais AWS Bedrock → `ValidationException` à la 2e itération d'agent+). Quand désactivé, les appels structurés ignorent le mode JSON et reviennent à l'extraction regex en texte brut — aucune perte de qualité. S'applique à tous les modèles (configurés par ENV et Admin). |
| `LLM_TOOL_CHOICE_ENABLED` | Non | `true` | Basculement global pour `tool_choice` forcé dans l'extraction de sortie structurée (Niveau 1 — Appel de fonction natif). Définir à `false` si votre modèle retourne des erreurs avec la sélection d'outil forcée (par ex. modèles en mode réflexion qui rejettent `tool_choice='specified'`). Quand désactivé, les appels structurés ignorent le FC natif et commencent à partir du mode JSON. Remplacement par modèle disponible dans Paramètres → Modèles → Avancé. |
| `REASONING_LLM_MODEL` | Non | *(revient à `LLM_MODEL`)* | Nom du modèle pour le tier de réflexion. Utilisé pour les tâches nécessitant une analyse approfondie (par ex., planification DAG, analyse de plan) |
| `REASONING_LLM_API_KEY` | Non | *(revient à `LLM_API_KEY`)* | Clé API du fournisseur du modèle de réflexion |
| `REASONING_LLM_BASE_URL` | Non | *(revient à `LLM_BASE_URL`)* | URL de base du fournisseur du modèle de réflexion |
| `REASONING_LLM_TEMPERATURE` | Non | *(revient à `LLM_TEMPERATURE`)* | Température d'échantillonnage pour le modèle de réflexion |
| `REASONING_LLM_CONTEXT_SIZE` | Non | *(revient à `LLM_CONTEXT_SIZE`)* | Taille de la fenêtre de contexte pour le modèle de réflexion |
| `REASONING_LLM_MAX_OUTPUT_TOKENS` | Non | *(revient à `LLM_MAX_OUTPUT_TOKENS`)* | Tokens de sortie max par appel pour le modèle de réflexion |
| `REASONING_LLM_EFFORT` | Non | *(revient à `LLM_REASONING_EFFORT`)* | Niveau d'effort de réflexion pour le tier du modèle de réflexion. Valeurs : `low`, `medium`, `high` |
| `REASONING_LLM_BUDGET` | Non | *(revient à `LLM_REASONING_BUDGET_TOKENS`)* | Budget de tokens pour la réflexion (principalement Anthropic). Remplace le budget auto-calculé pour le tier de réflexion |
| `LLM_SUPPORTS_VISION` | Non | `true` *(optimiste)* | Contrôle si l'OCR de document en mode ENV (via MarkItDown + `markitdown-ocr`) est tenté. S'applique uniquement quand **aucun groupe de modèles actif n'est configuré dans Admin → Modèles** (mode ENV pur). Quand la valeur par défaut `true` est en vigueur, `convert_to_markdown` et l'ingestion RAG supposent que `LLM_MODEL` supporte la vision et l'appellent pour l'OCR d'image — c'est le comportement correct pour tous les choix courants (`gpt-4o`, `claude-3-5-sonnet`, `gemini-1.5-pro/flash`). Définir à `false` quand votre `LLM_MODEL` configuré par ENV ne supporte **pas** la vision (par ex. `deepseek-v3`, `qwen-chat`, `llama-3.1`, `gpt-3.5-turbo`, `o1-mini`) pour ignorer l'appel de vision défaillant et aller directement à l'extraction texte uniquement. Quand un groupe de modèles actif existe dans le panneau Admin → Modèles, ce drapeau est ignoré et les drapeaux `supports_vision` du groupe prennent le relais — le choix curé par l'admin est toujours la source de vérité en mode DB. |
> **Ordre de résolution** : Préférence utilisateur → Modèles Admin (DB) → Fallback ENV. Si un modèle admin avec le rôle « General » est configuré dans Admin → Modèles, ces variables ENV servent de fallback uniquement. La vérification de santé considère les deux sources.
### Résolution OCR MarkItDown
L'outil intégré `convert_to_markdown` et le pipeline d'ingestion RAG utilisent tous deux [MarkItDown](https://github.com/microsoft/markitdown) de Microsoft + le plugin officiel [`markitdown-ocr`](https://github.com/microsoft/markitdown/tree/main/packages/markitdown-ocr) pour extraire du texte à partir de documents — y compris l'OCR sur les images intégrées et les pages PDF numérisées lorsqu'un LLM capable de vision est disponible.
**Ordre de résolution du LLM Vision** (première correspondance gagne) :
| # | Source | Justification de la priorité |
| - | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 1 | **LLM principal** de l'agent si `supports_vision=True` | Cohérence : même clé API, même bucket de facturation, même pool de limite de débit que la conversation. |
| 2 | **ModelGroup → Fast Model** actif si `supports_vision=True` | Les modèles rapides (`gpt-4o-mini`, `claude-haiku`, `gemini-1.5-flash`) sont l'outil OCR idéal — bon marché, faible latence, généralement multimodaux. |
| 3 | **ModelGroup → General Model** actif si `supports_vision=True` | Fallback de qualité lorsque le modèle principal n'est pas dans le groupe. |
| 4 | **LLM principal ENV** (`LLM_MODEL`) | Fallback optimiste pour le mode ENV pur. Utilisé uniquement lorsqu'aucun ModelGroup actif n'existe. Contrôlé par `LLM_SUPPORTS_VISION`. |
**Les modèles de reasoning ne sont jamais préférés pour l'OCR.** Les niveaux de reasoning (`o1`, `o3-mini`, `DeepSeek-R1`) manquent historiquement de support vision et ne sont pas l'outil approprié pour l'OCR de toute façon — l'OCR est une tâche de perception, pas de délibération. Si un espace de travail n'a qu'un modèle de reasoning avec `supports_vision=True`, il sera toujours sélectionné via le chemin du LLM principal, mais le résolveur ne le classe pas activement au-dessus des modèles rapides/généraux.
**Fallback sans régression** : lorsqu'aucun modèle capable de vision n'est trouvé à aucun niveau, l'OCR est silencieusement désactivé et MarkItDown s'exécute en mode texte uniquement. L'OCR des images intégrées dans Word/PowerPoint/Excel devient indisponible (comme avant le lancement de cette fonctionnalité), mais toute autre extraction de texte (titres, tableaux, texte de paragraphe) continue de fonctionner sans modification. **Il n'y a jamais de cas où l'ajout de cette fonctionnalité a rendu l'extraction pire que le comportement précédent.**
**Les fournisseurs non-OpenAI (Anthropic, Google Gemini, etc.)** sont pris en charge de manière transparente : le LLM résolu est enveloppé dans un `LiteLLMOpenAIShim` qui achemine les appels `chat.completions.create(...)` via `litellm.completion()`, qui gère la traduction du format de message spécifique au fournisseur (par exemple, le bloc d'image `source.type="base64"` d'Anthropic). Un seul shim couvre chaque fournisseur que LiteLLM supporte — l'ajout d'un nouveau fournisseur ne coûte aucune modification de code dans FIM One.
### Réflexion étendue (Raisonnement)
Lorsque `LLM_REASONING_EFFORT` est défini, FIM One active la capacité de réflexion étendue du modèle afin que la chaîne de pensée interne soit affichée dans l'étape « thinking » de l'interface utilisateur. FIM One utilise [LiteLLM](https://github.com/BerriAI/litellm) pour traduire automatiquement le paramètre d'effort de raisonnement dans le format natif de chaque fournisseur.
#### Fournisseurs pris en charge
| Fournisseur | `LLM_BASE_URL` | Fonctionnement | Contenu de raisonnement retourné ? |
| ------------------------------ | ---------------------------------------------------------- | ------------------------------------------------------------------------ | ---------------------------------- |
| **OpenAI** (o1 / o3 / o4-mini) | `https://api.openai.com/v1` | `reasoning_effort` envoyé nativement | Oui |
| **Anthropic** (Claude 3.7+) | `https://api.anthropic.com/v1/` | LiteLLM achemine via l'API Anthropic native avec le paramètre `thinking` | Oui |
| **Google Gemini** (2.5+) | `https://generativelanguage.googleapis.com/v1beta/openai/` | `reasoning_effort` envoyé sur le point de terminaison de compatibilité | Oui |
LiteLLM détecte automatiquement le fournisseur à partir de `LLM_BASE_URL` et le mappe au format API correct. Les URL inconnues sont traitées comme compatibles avec OpenAI.
#### Avertissements importants
**Les proxies tiers / points de terminaison personnalisés ne sont pas garantis.**
Si votre `LLM_BASE_URL` pointe vers un proxy API tiers (par exemple, OpenRouter, one-api, passerelle personnalisée), LiteLLM tentera d'acheminer correctement en fonction de l'URL. Cependant, si votre proxy s'attend à un format non standard, le raisonnement peut ne pas fonctionner comme prévu. Consultez la documentation du proxy pour connaître le format de paramètre attendu.
#### Contraintes de température avec le raisonnement
Certains fournisseurs imposent des restrictions de température lorsque le raisonnement est actif :
* **Anthropic** : Nécessite `temperature=1` lorsque la réflexion étendue est activée. Si vous utilisez Anthropic avec la réflexion étendue, vous **devez** définir `LLM_TEMPERATURE=1` — Anthropic rejette les autres valeurs lorsque la réflexion est activée.
* **OpenAI GPT-5.x** : Supporte uniquement `temperature=1` à tout moment. Le filtrage `drop_params` de LiteLLM gère cela automatiquement — les valeurs de température non supportées sont silencieusement supprimées. Aucune action de l'utilisateur n'est nécessaire pour GPT-5.x.
#### Comment fonctionne `LLM_REASONING_BUDGET_TOKENS`
Cette variable est **principalement significative pour le chemin Anthropic**. Lorsqu'elle est définie, elle remplace le budget calculé automatiquement et est envoyée en tant que `budget_tokens` dans le paramètre `thinking` via LiteLLM. Lorsqu'elle n'est pas définie, le budget est dérivé de `LLM_MAX_OUTPUT_TOKENS` x ratio d'effort :
| `LLM_REASONING_EFFORT` | Ratio de budget | Exemple (max\_tokens = 64000) |
| ---------------------- | --------------- | ----------------------------- |
| `low` | 20% | 12 800 tokens |
| `medium` | 50% | 32 000 tokens |
| `high` | 80% | 51 200 tokens |
Le budget minimum est de 1 024 tokens (minimum absolu d'Anthropic).
Pour OpenAI et Gemini, le fournisseur gère l'allocation de tokens en interne en fonction du niveau `reasoning_effort` — `LLM_REASONING_BUDGET_TOKENS` n'a aucun effet.
## Exécution de l'agent
### Agent ReAct
| Variable | Requis | Par défaut | Description |
| ----------------------------------- | ------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `REACT_MAX_ITERATIONS` | Non | `20` | Nombre maximal d'itérations d'appels d'outils par requête ReAct. Plus élevé = plus approfondi mais plus lent et plus coûteux |
| `REACT_MAX_TURN_TOKENS` | Non | `0` | Disjoncteur d'urgence : nombre maximal de tokens cumulés (prompt + completion sur toutes les itérations) par tour ReAct unique. Par défaut `0` = illimité. **Ceci n'est PAS pour le contrôle des tokens quotidiens** — utilisez `token_quota` par utilisateur pour cela. C'est une soupape de sécurité de dernier recours pour les scénarios extrêmes comme un agent bloqué dans une boucle infinie d'appels d'outils. Atteindre cette limite abandonne la tâche en cours d'exécution, gaspillant tous les tokens consommés jusqu'à présent et renvoyant un résultat incomplet. Conservez à `0` sauf si vous avez un problème spécifique d'agent incontrôlable à contenir |
| `REACT_TOOL_SELECTION_THRESHOLD` | Non | `12` | Lorsque le nombre total d'outils enregistrés dépasse ce seuil, un appel LLM léger sélectionne le sous-ensemble le plus pertinent avant chaque requête |
| `REACT_TOOL_SELECTION_MAX` | Non | `6` | Nombre maximal d'outils à conserver après sélection intelligente (effectif uniquement lorsque le nombre d'outils dépasse `REACT_TOOL_SELECTION_THRESHOLD`) |
| `REACT_SELF_REFLECTION_INTERVAL` | Non | `6` | Injecter une invite d'auto-réflexion tous les N appels d'outils pour aider l'agent à corriger sa trajectoire et éviter les boucles |
| `REACT_TOOL_OBS_TRUNCATION` | Non | `8000` | Nombre maximal de caractères par observation d'outil lors de la synthèse de la réponse finale. Les valeurs plus élevées conservent plus de données structurées (JSON, tableaux) au détriment de plus de tokens |
| `REACT_TOOL_RESULT_BUDGET` | Non | `40000` | Budget de tokens agrégé pour tous les résultats d'outils dans une session unique. Lorsque le total des tokens de résultats d'outils dépasse ce plafond, les nouveaux résultats sont tronqués avec un avis. Prévient l'encombrement du contexte causé par les grandes réponses API (par ex., 5 appels de connecteur renvoyant 8K chacun). Définissez à `0` pour désactiver le plafond |
| `REACT_COMPLETION_CHECK_SKIP_CHARS` | Non | `800` | Ignorer l'appel LLM de vérification post-réponse lorsque la réponse finale de l'agent dépasse ce nombre de caractères. Les réponses longues et détaillées n'ont pas besoin d'un aller-retour de vérification « ai-je oublié quelque chose ? ». Définissez plus bas pour ignorer plus agressivement ; définissez à une valeur très grande pour toujours exécuter la vérification |
| `REACT_CYCLE_DETECTION_THRESHOLD` | Non | `2` | Lorsque le même outil est appelé avec des arguments identiques ce nombre de fois d'affilée, un avertissement déterministe est injecté indiquant à l'agent d'essayer une approche différente. Contrairement à l'auto-réflexion (qui s'appuie sur le LLM remarquant la boucle), c'est une vérification basée sur le hash qui ne peut pas être contournée. S'applique également aux étapes DAG |
| `REACT_COMPLETION_CHECK_MIN_TOOLS` | Non | `3` | Nombre minimal d'appels d'outils avant le déclenchement de la liste de vérification d'achèvement. Les tâches simples (1-2 appels d'outils) ignorent la vérification pour éviter une latence inutile. Définissez à `1` pour une vérification toujours active. S'applique également aux étapes DAG |
| `REACT_TURN_PROFILE_ENABLED` | Non | `true` | Émettre des journaux de synchronisation au niveau des phases par tour (`memory_load`, `compact`, `tool_schema_build`, `llm_first_token`, `llm_total`, `tool_exec`). Une ligne de journal structurée par tour. Définissez à `false` pour désactiver complètement le profilage (zéro surcharge) |
| `REACT_PLAN_TOOL_ENABLED` | Non | `true` | Enregistrer l'outil `update_plan` pour que l'agent écrive et maintienne une liste de contrôle des tâches pendant les tâches multi-étapes. Automatiquement ignoré pour les agents d'étapes DAG et les agents sans outils |
| `REACT_PLAN_REMINDER_INTERVAL` | Non | `3` | Tours d'outils sans appel `update_plan` avant qu'un rappel de plan obsolète (intégrant la liste de contrôle complète) soit réinjecté dans la conversation, afin que le plan survive à la compaction du contexte |
| `REACT_MAX_CONTINUATIONS` | Non | `3` | Nombre maximal de tours de continuation lorsque la réponse du modèle est coupée par la limite de tokens de sortie du fournisseur (`finish_reason=length`). Les segments tronqués sont assemblés en une réponse transparente, à la fois dans la boucle d'agent et dans la synthèse en continu |
| `REACT_BACKGROUND_TOOLS_ENABLED` | Non | `true` | Offrir une option `run_in_background` sur les outils lents (exécution Python/shell/node en sandbox). L'agent obtient immédiatement un identifiant de tâche et continue de travailler ; le résultat arrive sous forme de message `` lorsque l'outil se termine |
| `REACT_BG_WAIT_TIMEOUT` | Non | `300` | Nombre maximal de secondes à attendre pour les outils d'arrière-plan encore en cours d'exécution lorsque l'agent souhaite finaliser sa réponse. Les tâches non terminées dans la fenêtre sont annulées avec une notification de délai d'attente explicite |
| `DAG_CHECKPOINT_EVIDENCE_CHARS` | Non | `4000` | Plafond de preuves par étape dans le fichier de point de contrôle de reprise après sinistre DAG (`data/dag_checkpoints/`). Les résumés d'étapes sont stockés en intégralité |
| `DAG_CHECKPOINT_MAX_AGE_HOURS` | Non | `24` | Les points de contrôle DAG plus anciens que cela sont ignorés au chargement, donc les restes de sinistre obsolètes ne reprennent jamais dans une exécution nouvelle |
| `LLM_RATE_LIMIT_PER_USER` | Non | `true` | Utiliser des buckets de limite de débit à clé par utilisateur au lieu d'un bucket global unique au processus. Empêche un utilisateur bruyant de priver tous les autres sur le même worker. Le débit sous-jacent est codé en dur à 60 requêtes/min et 100K tokens/min par bucket — ce paramètre contrôle uniquement si le bucket est partagé (global) ou partitionné (par utilisateur). Définissez à `false` pour revenir au bucket global hérité (non recommandé) |
### Planificateur DAG
| Variable | Requis | Par défaut | Description |
| -------------------------------- | ------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `MAX_CONCURRENCY` | Non | `5` | Nombre maximum d'étapes parallèles dans l'exécuteur DAG |
| `DAG_STEP_MAX_ITERATIONS` | Non | `15` | Nombre maximum d'itérations d'appels d'outils dans chaque étape DAG |
| `DAG_STEP_TIMEOUT` | Non | `600` | Délai d'expiration de l'exécution d'une étape en secondes. Les étapes dépassant ce délai sont marquées comme échouées et leurs dépendants sont ignorés en cascade |
| `DAG_MAX_REPLAN_ROUNDS` | Non | `3` | Nombre maximum de tentatives de replanification autonome lorsque l'objectif n'est pas atteint. Les interruptions utilisateur (injection) sont illimitées et ne sont pas comptabilisées dans ce budget |
| `DAG_REPLAN_STOP_CONFIDENCE` | Non | `0.8` | Arrêter les nouvelles tentatives lorsque la confiance de l'agent que l'objectif est inatteignable dépasse ce seuil (`0.0` = ne jamais arrêter tôt, `1.0` = arrêter en cas d'échec quelconque) |
| `DAG_VERIFY_TRUNCATION` | Non | `2000` | Nombre maximum de caractères de la sortie d'étape envoyés au vérificateur d'étape LLM pour l'évaluation de la qualité |
| `DAG_ANALYZER_TRUNCATION` | Non | `10000` | Nombre maximum de caractères par résultat d'étape lors du formatage pour l'analyseur post-exécution |
| `DAG_STEP_EVIDENCE_CHARS` | Non | `16000` | Nombre maximum de caractères de la sortie d'outil brute (récupérations web, résultats de recherche, lectures de fichiers) conservés par étape comme « preuve source » faisant autorité. Ceci est fourni à l'analyseur et à la synthèse finale aux côtés du propre résumé de l'étape, de sorte que les affirmations factuelles de la réponse (totaux, énumérations, sévérités) peuvent être vérifiées par rapport à la source au lieu de faire confiance à un résumé qui pourrait avoir silencieusement supprimé ou mal étiqueté des éléments. Définir à `0` pour désactiver la capture de preuve |
| `DAG_REPLAN_RECENT_TRUNCATION` | Non | `500` | Nombre maximum de caractères par résultat d'étape du tour le plus récent lors de la construction du contexte de replanification |
| `DAG_REPLAN_OLDER_TRUNCATION` | Non | `200` | Nombre maximum de caractères par résultat d'étape des tours antérieurs lors de la construction du contexte de replanification. Les tours antérieurs sont tronqués plus agressivement pour économiser le contexte |
| `DAG_TOOL_CACHE` | Non | `true` | Mettre en cache les appels d'outils identiques au sein d'une seule exécution DAG. Seuls les outils explicitement marqués comme `cacheable` (outils en lecture seule comme la recherche, la récupération de connaissances) sont mis en cache. Définir à `false` pour désactiver entièrement la mise en cache |
| `DAG_STEP_VERIFICATION` | Non | `false` | Vérification générique de la qualité basée sur LLM après chaque étape DAG. En cas d'échec, l'étape est relancée une fois avec des commentaires. **Désactivé par défaut** — ajoute de la latence à chaque étape et est rarement nécessaire ; la plupart des sorties d'étape sont acceptables sans revérification. À utiliser uniquement si vous observez des résultats d'étape de faible qualité fréquents |
| `DAG_CITATION_VERIFICATION` | Non | `true` | Vérification de l'exactitude des citations pour les étapes de domaines spécialisés. **Condition préalable** : la requête doit d'abord être classée comme un domaine spécialisé par le classificateur de domaine LLM (voir `ESCALATION_DOMAINS`). Lorsque le domaine est détecté ET que cet indicateur est `true`, chaque étape complétée est analysée pour les citations juridiques/médicales/financières et vérifiée pour l'exactitude — détectant les numéros d'articles hallucés, les références de cas fabriquées et les citations réglementaires incorrectes. Si la classification de domaine retourne `null` (requête générale), la vérification des citations ne s'exécute pas quel que soit ce paramètre |
| `DAG_CITATION_VERIFY_TRUNCATION` | Non | `6000` | Nombre maximum de caractères du résultat d'étape envoyés à l'invite de vérification des citations |
### Classification des domaines
Contrôle la couche de détection de domaine indépendante basée sur LLM qui s'exécute **avant** l'exécution de ReAct et DAG. Lorsqu'une requête est classée comme appartenant à un domaine spécialisé, le système active les fonctionnalités sensibles au domaine : escalade du modèle vers le modèle de raisonnement, instructions SOP spécifiques au domaine et vérification des citations (DAG uniquement).
| Variable | Requis | Par défaut | Description |
| -------------------- | ------ | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ESCALATION_DOMAINS` | Non | `legal,medical,financial,tax,compliance,patent` | Liste séparée par des virgules des domaines spécialisés. Un LLM rapide classe chaque requête par rapport à cette liste. En cas de correspondance, le système : (1) bascule vers le modèle de raisonnement pour une plus grande précision, (2) injecte des instructions SOP spécifiques au domaine (par exemple, vérifier les citations via la recherche avant d'écrire), (3) active la vérification des citations pour les étapes DAG. Ajoutez des domaines personnalisés selon les besoins (par exemple, `legal,education,construction`) |
### Context Guard
Contrôle la gestion automatique de la fenêtre de contexte qui empêche les conversations de dépasser la limite du modèle.
| Variable | Requis | Par défaut | Description |
| ------------------------------ | ------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CONTEXT_GUARD_DEFAULT_BUDGET` | Non | `32000` | Budget de jetons par défaut pour la gestion de la fenêtre de contexte. Lorsque la conversation dépasse cette limite, les messages plus anciens sont compactés |
| `CONTEXT_GUARD_MAX_MSG_CHARS` | Non | `50000` | Limite de caractères stricte pour tout message unique. Les messages dépassant cette limite sont tronqués comme filet de sécurité |
| `CONTEXT_GUARD_KEEP_RECENT` | Non | `4` | Nombre de messages les plus récents à conserver lors de la compaction de l'historique de conversation |
### Garde-fous de contenu
Noms de garde-fous séparés par des virgules qui inspectent le *contenu* des entrées ou sorties. Indépendants de la porte de permission d'outil (`core/hooks/*`) et de la couche de sécurité (`core/security/*`). Voir [Garde-fous de contenu](/configuration/guardrails) pour l'image complète.
| Variable | Requis | Par défaut | Description |
| -------------------------------- | ------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `FIM_GUARDRAILS_INPUT` | Non | `jailbreak` | Garde-fous d'entrée actifs. Le détecteur regex `jailbreak` par défaut interrompt le tour avant que des jetons LLM ne soient dépensés lorsque des phrases de dépassement d'invite connues sont détectées. Définir sur vide pour désactiver. Les noms inconnus sont enregistrés et ignorés |
| `FIM_GUARDRAILS_OUTPUT` | Non | (vide) | Garde-fous de sortie actifs. Actuellement fournis : `max_length` (limite le nombre de caractères de la réponse). Exécutés après que l'agent produit sa réponse finale |
| `FIM_GUARDRAIL_MAX_OUTPUT_CHARS` | Non | `50000` | Limite de caractères utilisée par le garde-fou de sortie `max_length`. Effectif uniquement lorsque `max_length` est listé dans `FIM_GUARDRAILS_OUTPUT` |
### Espace de travail de l'agent
| Variable | Requis | Par défaut | Description |
| ----------------------------- | ------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `WORKSPACE_OFFLOAD_THRESHOLD` | Non | `8000` | Lorsqu'une sortie d'outil dépasse ce nombre de caractères, elle est enregistrée dans un fichier d'espace de travail et un aperçu tronqué est injecté dans le contexte de conversation |
| `WORKSPACE_PREVIEW_CHARS` | Non | `2000` | Nombre de caractères d'aperçu à inclure dans les références d'espace de travail tronquées |
| `WORKSPACE_CLEANUP_MAX_HOURS` | Non | `72` | Les fichiers d'espace de travail plus anciens que ce nombre d'heures sont éligibles au nettoyage automatique |
### Système
| Variable | Requise | Par défaut | Description |
| --------------------------- | ------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ~~`SYSTEM_PROMPT_RESERVE`~~ | — | — | **Supprimée.** Précédemment, elle soustrayait une réserve fixe de 4K du budget de contexte pour les invites système. Cela causait un double comptage car ContextGuard inclut déjà l'invite système lors de l'estimation des jetons de la liste de messages. La formule de budget est maintenant simplement `context_size - max_output_tokens`, et la taille réelle de l'invite système est comptabilisée dynamiquement |
***
## Outils Web (Optionnel)
| Variable | Requis | Par défaut | Description |
| --------------------- | ------ | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `JINA_API_KEY` | Non | — | Clé API Jina. Agit comme un fallback partagé pour **search, fetch, embedding, et reranker** quand aucune clé spécifique au service n'est définie. Obtenez la vôtre sur [jina.ai](https://jina.ai/) |
| `TAVILY_API_KEY` | Non | — | Clé API Tavily Search (sélectionnée automatiquement si définie et `WEB_SEARCH_PROVIDER` n'est pas défini) |
| `BRAVE_API_KEY` | Non | — | Clé API Brave Search (sélectionnée automatiquement si définie et `WEB_SEARCH_PROVIDER` n'est pas défini) |
| `EXA_API_KEY` | Non | — | Clé API Exa Search (sélectionnée automatiquement si définie et `WEB_SEARCH_PROVIDER` n'est pas défini). Obtenez la vôtre sur [exa.ai](https://exa.ai/) |
| `WEB_SEARCH_PROVIDER` | Non | `jina` | Sélecteur de fournisseur de recherche : `jina` / `tavily` / `brave` / `exa` |
| `WEB_FETCH_PROVIDER` | Non | `jina` (si clé définie, sinon `httpx`) | Fournisseur de fetch : `jina` (utilise l'API Jina Reader) / `httpx` (requête HTTP directe, aucune clé API nécessaire) |
> **Conseil de démarrage rapide** : Définir simplement `JINA_API_KEY` active la recherche web, le fetch web, l'embedding et le reranking en même temps — une clé, quatre services. Vous pouvez remplacer chaque service individuellement avec les variables ci-dessous.
***
## RAG et Base de Connaissances (Recommandé)
### Intégration
L'intégration convertit le texte en vecteurs pour la recherche de base de connaissances. FIM One utilise le point de terminaison standard compatible OpenAI **`/v1/embeddings`**, il fonctionne donc avec n'importe quel fournisseur qui expose cette interface — pas seulement Jina.
| Variable | Requis | Par défaut | Description |
| --------------------- | ------ | ---------------------------- | --------------------------------------------- |
| `EMBEDDING_API_KEY` | Non | *(revient à `JINA_API_KEY`)* | Clé API pour le fournisseur d'intégration |
| `EMBEDDING_BASE_URL` | Non | `https://api.jina.ai/v1` | URL de base pour le fournisseur d'intégration |
| `EMBEDDING_MODEL` | Non | `jina-embeddings-v3` | Identifiant du modèle |
| `EMBEDDING_DIMENSION` | Non | `1024` | Dimension du vecteur |
**Exemples de fournisseurs** — définissez simplement les trois variables pour basculer :
| Fournisseur | `EMBEDDING_BASE_URL` | `EMBEDDING_MODEL` | `EMBEDDING_DIMENSION` |
| ----------------------- | ----------------------------- | ------------------------ | --------------------- |
| **Jina** *(par défaut)* | `https://api.jina.ai/v1` | `jina-embeddings-v3` | `1024` |
| **OpenAI** | `https://api.openai.com/v1` | `text-embedding-3-small` | `1536` |
| **Voyage** | `https://api.voyageai.com/v1` | `voyage-3` | `1024` |
| **Ollama** *(local)* | `http://localhost:11434/v1` | `nomic-embed-text` | `768` |
**Modifier le modèle d'intégration ou la dimension invalide tous les vecteurs de base de connaissances existants.** Les anciens vecteurs ont été calculés dans un espace d'intégration différent — la précision de la récupération se dégradера silencieusement. Vous devez **reconstruire tous les index de base de connaissances** après le basculement.
### Récupération
| Variable | Requis | Par défaut | Description |
| ---------------- | ------ | ----------- | ----------------------------------------------------------------------------------------------- |
| `RETRIEVAL_MODE` | Non | `grounding` | `grounding` (pipeline complet avec citations et scoring de confiance) ou `simple` (RAG basique) |
### Réorganiseur
Le réorganiseur reclasse les documents récupérés pour améliorer la pertinence. Trois fournisseurs sont pris en charge — sélectionnez via `RERANKER_PROVIDER` ou laissez le système détecter automatiquement à partir des clés API disponibles.
| Variable | Requis | Par défaut | Description |
| ----------------------- | ------ | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| `RERANKER_PROVIDER` | Non | *(auto-détection)* | `jina` / `cohere` / `openai`. Si non défini : utilise Cohere si `COHERE_API_KEY` est défini, sinon Jina |
| `RERANKER_MODEL` | Non | `jina-reranker-v2-base-multilingual` | Identifiant du modèle (s'applique aux fournisseurs Jina et OpenAI) |
| `COHERE_API_KEY` | Non | — | Clé API Cohere (sélectionne automatiquement le réorganiseur Cohere quand défini et `RERANKER_PROVIDER` n'est pas défini) |
| `COHERE_RERANKER_MODEL` | Non | `rerank-multilingual-v3.0` | Modèle de réorganiseur spécifique à Cohere |
> **Jina** utilise `JINA_API_KEY` (à partir des outils Web ci-dessus). **OpenAI** réutilise `LLM_API_KEY` / `LLM_BASE_URL` — aucune clé supplémentaire nécessaire. **Cohere** nécessite sa propre `COHERE_API_KEY`.
> Le réorganiseur est **optionnel** — la recherche de base de connaissances fonctionne sans lui en utilisant le score de fusion. L'intégration est **recommandée** pour les fonctionnalités de base de connaissances.
### Magasin vectoriel
| Variable | Requis | Par défaut | Description |
| ------------------ | ------ | --------------------- | --------------------------------------------------------------------------------------------------- |
| `VECTOR_STORE_DIR` | Non | `./data/vector_store` | Répertoire pour les données du magasin vectoriel LanceDB (basé sur fichier, zéro services externes) |
***
## Exécution de Code
| Variable | Requis | Défaut | Description |
| ---------------------- | ------ | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CODE_EXEC_BACKEND` | Non | `local` | `local` (exécution directe sur l'hôte) ou `docker` (conteneurs isolés) |
| `DOCKER_PYTHON_IMAGE` | Non | `python:3.11-slim` | Image Docker pour l'exécution Python |
| `DOCKER_NODE_IMAGE` | Non | `node:20-slim` | Image Docker pour l'exécution Node.js |
| `DOCKER_SHELL_IMAGE` | Non | `python:3.11-slim` | Image Docker pour l'exécution shell |
| `DOCKER_MEMORY` | Non | *(défaut Docker)* | Limite de RAM par conteneur (ex. `256m`, `512m`, `1g`) |
| `DOCKER_CPUS` | Non | *(défaut Docker)* | Quota CPU par conteneur (ex. `0.5`, `1.0`) |
| `SANDBOX_TIMEOUT` | Non | `120` | Délai d'exécution par défaut en secondes |
| `DOCKER_HOST_DATA_DIR` | Non | *(non défini)* | Chemin absolu côté hôte du montage de volume `./data`. Requis pour les déploiements DooD (Docker-outside-of-Docker) ; `docker-compose.yml` le définit automatiquement via `${PWD}/data`. |
> **Sécurité** : Le mode `local` exécute le code généré par l'IA directement sur l'hôte. Pour les déploiements accessibles sur Internet ou multi-utilisateurs, définissez toujours `CODE_EXEC_BACKEND=docker`.
## Artefacts d'outil
Limites de taille pour les fichiers produits par l'exécution d'outils (exécution de code, rendu de modèle, génération d'image).
| Variable | Requis | Par défaut | Description |
| --------------------- | ------ | ------------------ | ---------------------------------------------------------- |
| `MAX_ARTIFACT_SIZE` | Non | `10485760` (10 MB) | Taille maximale d'un fichier artefact unique en octets |
| `MAX_ARTIFACTS_TOTAL` | Non | `52428800` (50 MB) | Taille totale maximale des artefacts par session en octets |
***
## Traitement des documents (Optionnel)
Contrôle le traitement des fichiers PDF/DOCX téléchargés pour la consommation par LLM. Les modèles compatibles avec la vision (GPT-4o, Claude 3/4, Gemini) peuvent recevoir les pages PDF sous forme d'images rendues pour une meilleure fidélité.
| Variable | Requis | Par défaut | Description |
| --------------------------- | ------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `DOCUMENT_PROCESSING_MODE` | Non | `auto` | `auto` (vision si le modèle la supporte), `vision` (toujours rendre les pages), `text` (toujours extraire le texte uniquement) |
| `DOCUMENT_VISION_DPI` | Non | `150` | DPI pour le rendu des pages PDF. Plus élevé = meilleure qualité, plus de tokens |
| `DOCUMENT_VISION_MAX_PAGES` | Non | `20` | Nombre maximum de pages à rendre sous forme d'images par PDF |
> **Remarque** : Le support de la vision par modèle est configuré via le bouton `supports_vision` dans Admin → Models. Lorsqu'il n'est pas explicitement défini, le système détecte automatiquement la capacité de vision à partir du nom du modèle.
## Génération d'images (Optionnel)
| Variable | Requis | Par défaut | Description |
| -------------------- | ------ | -------------------------------- | -------------------------------------------------------------------------------------------------- |
| `IMAGE_GEN_PROVIDER` | Non | `google` | `google` (API native Gemini) ou `openai` (API compatible OpenAI `/v1/images/generations`) |
| `IMAGE_GEN_API_KEY` | Non | — | Clé Google AI Studio (`google`) ou clé proxy/OpenAI (`openai`) |
| `IMAGE_GEN_MODEL` | Non | `gemini-3.1-flash-image-preview` | Modèle de génération d'images (par ex. `dall-e-3`, `gemini-nano-banana-2`) |
| `IMAGE_GEN_BASE_URL` | Non | *(par fournisseur)* | Google : `https://generativelanguage.googleapis.com/v1beta` ; OpenAI : `https://api.openai.com/v1` |
***
## Email (SMTP) (Recommandé)
Enregistre automatiquement l'outil intégré `email_send` lorsque `SMTP_HOST`, `SMTP_USER` et `SMTP_PASS` sont tous définis.
| Variable | Requis | Par défaut | Description |
| ------------------------ | ------ | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SMTP_HOST` | Cond. | — | Nom d'hôte du serveur SMTP |
| `SMTP_PORT` | Non | `465` | Port SMTP |
| `SMTP_SSL` | Non | `ssl` | Mode TLS : `ssl` (port 465) / `tls` (STARTTLS, port 587) / `none` ou `""` (plain, identifiants envoyés en clair). Toute autre valeur est rejetée plutôt que de revenir silencieusement au mode plain. |
| `SMTP_USER` | Cond. | — | Nom d'utilisateur de connexion SMTP |
| `SMTP_PASS` | Cond. | — | Mot de passe de connexion SMTP |
| `SMTP_FROM` | Non | *(utilise `SMTP_USER`)* | Adresse de l'expéditeur affichée dans l'en-tête From |
| `SMTP_FROM_NAME` | Non | — | Nom d'affichage affiché dans l'en-tête From |
| `SMTP_REPLY_TO` | Non | — | Adresse Reply-To ; les réponses vont ici au lieu de `SMTP_FROM` |
| `SMTP_ALLOWED_DOMAINS` | Non | — | Liste d'autorisation de domaines séparés par des virgules (ex. `example.com,corp.io`) ; bloque les destinataires en dehors des domaines listés |
| `SMTP_ALLOWED_ADDRESSES` | Non | — | Liste d'autorisation d'adresses exactes séparées par des virgules ; combinée avec `SMTP_ALLOWED_DOMAINS` ; laissez les deux non définis pour autoriser n'importe quel destinataire (non recommandé pour les boîtes aux lettres partagées) |
***
## Connecteurs
| Variable | Requis | Par défaut | Description |
| ------------------------------ | ------ | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CONNECTOR_RESPONSE_MAX_CHARS` | Non | `50000` | Nombre maximum de caractères pour les réponses de connecteur JSON non-tableau / texte brut |
| `CONNECTOR_RESPONSE_MAX_ITEMS` | Non | `10` | Nombre maximum d'éléments de tableau à conserver lorsque la réponse du connecteur est un tableau JSON |
| `CREDENTIAL_ENCRYPTION_KEY` | Non | *(non défini)* | Clé de chiffrement Fernet pour les blobs d'identifiants de connecteur. Lorsqu'elle est définie, les jetons d'authentification stockés dans `connector_credentials` sont chiffrés au repos. Si elle n'est pas définie, les identifiants sont stockés en JSON en texte brut (rétrocompatible). La modification de cette clé invalide tous les identifiants chiffrés existants. |
| `CONNECTOR_TOOL_MODE` | Non | `progressive` | Comment les outils de connecteur sont exposés aux agents. `progressive` : un seul `ConnectorMetaTool` avec les sous-commandes `discover`/`execute` (\~30 jetons/connecteur). `classic` : un outil par action (hérité, \~250 jetons/action). |
| `DATABASE_TOOL_MODE` | Non | `progressive` | Comment les outils de connecteur de base de données sont exposés aux agents. `progressive` : un seul `DatabaseMetaTool` avec les sous-commandes `list_tables`/`discover`/`query`. `legacy` : un outil par action par connecteur de base de données (3 outils chacun). |
| `MCP_TOOL_MODE` | Non | `progressive` | Comment les outils du serveur MCP sont exposés aux agents. `progressive` : un seul `MCPServerMetaTool` avec les sous-commandes `discover`/`call`. `legacy` : un outil par action du serveur MCP (outils individuels originaux). |
***
## Platform
| Variable | Required | Default | Description |
| -------------------------------- | -------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DATABASE_URL` | No | `sqlite+aiosqlite:///./data/fim_one.db` | Chaîne de connexion à la base de données. **SQLite** (zéro configuration) : `sqlite+aiosqlite:///./data/fim_one.db`. **PostgreSQL** (production) : `postgresql+asyncpg://user:pass@localhost:5432/fim_one`. Docker Compose configure automatiquement PostgreSQL. |
| `JWT_SECRET_KEY` | No | `CHANGE_ME` | Clé secrète pour la signature des jetons JWT. La valeur par défaut `CHANGE_ME` (ou tout autre défaut hérité) déclenche la génération automatique d'une clé aléatoire sécurisée de 256 bits au premier démarrage, qui est écrite dans `.env`. Définissez explicitement en production pour maintenir la validité des jetons lors des redémarrages et des répliques. |
| `FIM_BCRYPT_COST` | No | `12` | Facteur de travail bcrypt pour le hachage des mots de passe, limité à 4-31. La valeur par défaut 12 coûte environ 200ms par hachage sur les processeurs modernes ; réduisez-la sur du matériel faible, augmentez-la pour les déploiements renforcés en sécurité. |
| `CORS_ORIGINS` | No | — | Liste séparée par des virgules des origines CORS supplémentaires autorisées au-delà des entrées localhost par défaut. Requis lorsque le frontend s'exécute sur un domaine non-localhost (par ex. `https://app.example.com`). |
| `UPLOADS_DIR` | No | `./uploads` | Répertoire pour les fichiers téléchargés |
| `MAX_UPLOAD_SIZE_MB` | No | `50` | Taille maximale de téléchargement de fichier en mégaoctets (application backend) |
| `NEXT_PUBLIC_MAX_UPLOAD_SIZE_MB` | No | `50` | Taille maximale de téléchargement affichée dans l'interface utilisateur frontend. **Variable de temps de construction** — doit correspondre à `MAX_UPLOAD_SIZE_MB`. |
| `MCP_SERVERS` | No | — | Tableau JSON des configurations de serveur MCP (nécessite `uv sync --extra mcp`) |
| `ALLOW_STDIO_MCP` | No | `false` | Autoriser les serveurs MCP stdio. Définissez `true` uniquement pour les déploiements locaux de confiance |
| `ALLOWED_STDIO_COMMANDS` | No | `npx,uvx,node,python,python3,deno,bun` | Liste séparée par des virgules des commandes de base autorisées pour les serveurs MCP stdio. Effectif uniquement lorsque `ALLOW_STDIO_MCP=true` |
| `LOG_LEVEL` | No | `INFO` | Niveau de journalisation : `DEBUG` / `INFO` / `WARNING` / `ERROR` / `CRITICAL` |
| `REDIS_URL` | No | — | URL de connexion Redis pour le relais d'interruption inter-worker. **Requis lorsque `WORKERS>1`** — sans cela, les demandes d'interruption/injection en cours de flux peuvent atteindre un worker différent et échouer silencieusement. Auto-configuré par Docker Compose. |
| `WORKERS` | No | `1` | Processus worker Uvicorn. `1` est sûr et ne nécessite aucun service externe. Pour la production multi-worker, utilisez PostgreSQL (SQLite est single-writer). SQLite fonctionne pour le développement local sous charge légère. L'authentification, OAuth et les opérations de fichiers sont entièrement multi-worker sûrs (basés sur JWT). Docker Compose configure automatiquement PostgreSQL et Redis. |
**Liste de contrôle multi-worker** (`WORKERS>1`) :
* **Stop (arrêter le streaming)** — fonctionne toujours, aucune configuration supplémentaire nécessaire (le signal voyage sur la même connexion TCP).
* **Inject (suivi en cours de flux)** — **nécessite `REDIS_URL`**. Sans Redis, la demande d'injection peut atterrir sur un worker différent qui n'a aucune connaissance de l'exécution en cours, ce qui provoque un échec silencieux.
* **Production** : utilisez PostgreSQL (`DATABASE_URL`). Le verrou single-writer de SQLite peut causer de la contention lors d'écritures concurrentes.
* **Développement local** : SQLite + multi-worker est correct pour une utilisation légère ; ajoutez simplement `REDIS_URL` si vous utilisez la fonctionnalité d'injection.
## Workflow Run Retention
Background cleanup task that automatically purges old workflow runs. Per-workflow overrides (configured in the workflow settings UI) take priority over these global defaults.
| Variable | Required | Default | Description |
| ------------------------------------- | -------- | ------- | --------------------------------------------------------------- |
| `WORKFLOW_RUN_MAX_AGE_DAYS` | No | `30` | Delete workflow runs older than this many days |
| `WORKFLOW_RUN_MAX_PER_WORKFLOW` | No | `100` | Keep at most this many runs per workflow (oldest deleted first) |
| `WORKFLOW_RUN_CLEANUP_INTERVAL_HOURS` | No | `24` | How often the background cleanup task runs, in hours |
### Expiration des demandes de confirmation de canal
Sweeper en arrière-plan qui marque les demandes d'approbation en attente obsolètes (produites par des hooks de canal comme `FeishuGateHook` ou le Playground d'approbation) comme expirées. Garantit qu'un clic quelques jours plus tard sur une carte oubliée ne bascule pas l'état de l'agent qui a déjà été démantelé.
| Variable | Requis | Par défaut | Description |
| --------------------------------------------- | ------ | ---------- | ----------------------------------------------------------------------------------------------------------- |
| `CHANNEL_CONFIRMATION_TTL_MINUTES` | Non | `1440` | Les confirmations en attente plus anciennes que ceci sont automatiquement expirées (par défaut : 24 heures) |
| `CHANNEL_CONFIRMATION_SWEEP_INTERVAL_SECONDS` | Non | `600` | Fréquence d'exécution du sweeper d'expiration (par défaut : toutes les 10 minutes) |
## OAuth (Optionnel)
Quand `CLIENT_ID` et `CLIENT_SECRET` sont tous les deux définis pour un fournisseur, la page de connexion affiche automatiquement le bouton OAuth correspondant.
| Variable | Requis | Par défaut | Description |
| ----------------------- | -------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GITHUB_CLIENT_ID` | Non | — | ID client de l'application GitHub OAuth. Créer sur [github.com/settings/developers](https://github.com/settings/developers) → OAuth Apps |
| `GITHUB_CLIENT_SECRET` | Non | — | Secret client de l'application GitHub OAuth |
| `GOOGLE_CLIENT_ID` | Non | — | ID client Google OAuth. Créer sur [console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials) |
| `GOOGLE_CLIENT_SECRET` | Non | — | Secret client Google OAuth |
| `DISCORD_CLIENT_ID` | Non | — | ID client Discord OAuth2. Créer sur [discord.com/developers](https://discord.com/developers/applications) |
| `DISCORD_CLIENT_SECRET` | Non | — | Secret client Discord OAuth2 |
| `FEISHU_APP_ID` | Non | — | ID d'application Feishu (Lark). Créer sur [open.feishu.cn](https://open.feishu.cn/app). Nécessite la permission `contact:user.email:readonly` |
| `FEISHU_APP_SECRET` | Non | — | Secret d'application Feishu (Lark) |
| `FRONTEND_URL` | **Prod** | `http://localhost:3000` | Où le navigateur arrive après la fin d'OAuth. Doit être défini en production (ex. `https://yourdomain.com`) |
| `API_BASE_URL` | **Prod** | `http://localhost:8000` | URL du backend accessible de l'extérieur, utilisée pour construire les URLs de rappel OAuth. Doit être défini en production |
| `NEXT_PUBLIC_API_URL` | **Prod** | *(détecté automatiquement comme `:8000`)* | URL de base de l'API côté navigateur pour les redirections OAuth. **C'est une variable de temps de construction du frontend** — définissez-la dans `frontend/.env.local` pour le développement local, ou passez-la comme argument de construction Docker pour les déploiements de production personnalisés. La détection automatique fonctionne pour les configurations de proxy inverse standard (port 80/443). |
> **Prod** = optionnel localement (les valeurs par défaut fonctionnent), mais **requis pour tout déploiement accessible sur Internet**.
### URLs de rappel OAuth à enregistrer auprès de chaque fournisseur
Le backend construit les URLs de rappel comme : `{API_BASE_URL}/api/auth/oauth/{provider}/callback`
| Fournisseur | URL de rappel à enregistrer |
| ----------- | -------------------------------------------------------- |
| GitHub | `https://yourdomain.com/api/auth/oauth/github/callback` |
| Google | `https://yourdomain.com/api/auth/oauth/google/callback` |
| Discord | `https://yourdomain.com/api/auth/oauth/discord/callback` |
***
## Tunnel Cloudflare (Optionnel)
Acheminez tout le trafic via le réseau de Cloudflare au lieu d'exposer directement les ports. Élimine le besoin de Nginx, de certificats SSL et de règles de pare-feu ouvertes. Consultez la section [Déploiement en Production](/quickstart#cloudflare-tunnel) pour les instructions de configuration.
**Utilisateurs de la Chine continentale** : Les plans Cloudflare Free/Pro/Business n'ont pas de PoPs en Chine continentale. Le trafic est acheminé vers des edges à l'étranger, causant des erreurs 502 fréquentes. N'utilisez pas ceci si vos utilisateurs principaux sont en Chine continentale, sauf si vous disposez de Cloudflare Enterprise avec China Network.
| Variable | Requis | Par défaut | Description |
| ------------------------- | --------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CLOUDFLARE_TUNNEL_TOKEN` | **Oui** (si vous utilisez Tunnel) | — | Jeton de Cloudflare Zero Trust → Networks → Tunnels → votre tunnel → Configure. Commence par `eyJ...`. Requis par le sidecar `cloudflared` dans `docker-compose.tunnel.yml`. |
***
## Analyse (Optionnel)
Tous les fournisseurs d'analyse sont optionnels. Définissez n'importe quelle combinaison — tous les fournisseurs actifs se chargent simultanément. Laissez tous les champs vides pour désactiver complètement l'analyse (recommandé pour le développement local).
| Variable | Requis | Par défaut | Description |
| ---------------------------------- | ------ | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `NEXT_PUBLIC_GA_MEASUREMENT_ID` | Non | — | ID de mesure Google Analytics 4 (par exemple `G-XXXXXXXXXX`). Obtenez le vôtre sur [analytics.google.com](https://analytics.google.com) |
| `NEXT_PUBLIC_UMAMI_SCRIPT_URL` | Non | — | URL du script d'analyse Umami (par exemple `https://your-umami.com/script.js`). Alternative auto-hébergée et respectueuse de la vie privée — [umami.is](https://umami.is) |
| `NEXT_PUBLIC_UMAMI_WEBSITE_ID` | Non | — | ID du site web Umami. Requis lorsque `NEXT_PUBLIC_UMAMI_SCRIPT_URL` est défini |
| `NEXT_PUBLIC_PLAUSIBLE_DOMAIN` | Non | — | Domaine d'analyse Plausible (par exemple `yourdomain.com`). Léger et respectueux de la vie privée — [plausible.io](https://plausible.io) |
| `NEXT_PUBLIC_PLAUSIBLE_SCRIPT_URL` | Non | `https://plausible.io/js/script.js` | URL de script Plausible personnalisée pour les instances auto-hébergées |
> Toutes les variables d'analyse `NEXT_PUBLIC_*` sont au **moment de la compilation** — les modifications nécessitent une reconstruction du frontend pour prendre effet.
## Stripe Billing (Optional)
Stripe powers Pro subscriptions. Leave all three variables blank to disable billing — the rest of FIM One works unchanged. **Both** `STRIPE_SECRET_KEY` **and** `STRIPE_WEBHOOK_SECRET` must be set together; partial config raises an error at first use.
| Variable | Required | Default | Description |
| --------------------------- | -------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `STRIPE_SECRET_KEY` | No | — | Stripe API secret key. Must start with `sk_test_` / `sk_live_` (full access) or `rk_test_` / `rk_live_` (restricted key). Get yours from the Stripe Dashboard → Developers → API keys. Never commit a `sk_live_*` key to source. |
| `STRIPE_WEBHOOK_SECRET` | No | — | Stripe webhook signing secret (`whsec_*`). Created when you register the webhook endpoint in Stripe Dashboard → Developers → Webhooks → Add endpoint. Required to verify inbound webhook payloads. |
| `STRIPE_BILLING_RETURN_URL` | No | `http://localhost:3000/settings?tab=billing` | URL Stripe redirects users to after Checkout / Customer Portal sessions. Set this to your production billing settings page (e.g. `https://your-domain.com/settings?tab=billing`). |