> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devinenterprise.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK Python

> Consultez les analyses et gérez les groupes et les plafonds d’ACU depuis la ligne de commande avec le SDK Python.

<Info>
  Cette documentation concerne les déploiements fédéraux de Devin. [Retour à la documentation Devin](/fr/get-started/devin-intro)
</Info>

Le SDK Python (`windsurf_analytics.py`) est un client en ligne de commande pour les endpoints de l’[API fédérale](/fr/federal/api/overview) : rapports d’utilisation, [consommation d’ACU](/fr/federal/api/acu-consumption), [gestion des groupes](/fr/federal/api/group-management) et [plafonds d’ACU par utilisateur](/fr/federal/api/acu-caps). Contactez votre représentant Cognition pour obtenir le script correspondant à votre déploiement.

<div id="requirements">
  ## Prérequis
</div>

* Python 3
* La bibliothèque `requests` : `pip install requests`

<div id="authentication">
  ## Authentification
</div>

Chaque commande accepte les indicateurs communs suivants :

| Indicateur      | Description                                                                                                                         |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `--service-key` | Clé de service pour l’authentification. Peut également être définie à l’aide de la variable d’environnement `WINDSURF_SERVICE_KEY`. |
| `--api-url`     | URL de base du serveur d’API de votre déploiement (`https://<your-server>`). HTTPS est requis.                                      |

Le rôle associé à la clé de service doit disposer de l’autorisation requise pour chaque commande ; consultez le [tableau des autorisations](/fr/federal/api/overview#required-permissions). Toutes les commandes d’analyse nécessitent également un niveau Team donnant accès à l’API d’analyse.

<div id="commands">
  ## Commandes
</div>

| Commande               | Endpoint                                   | Autorisation requise |
| ---------------------- | ------------------------------------------ | -------------------- |
| `usage` (par défaut)   | `/UserPageAnalytics` + `/CascadeAnalytics` | Teams Read-Only      |
| `acu-consumption`      | `/Analytics`                               | Analytics Read       |
| `list-groups`          | `/ListGroups`                              | Teams Read-Only      |
| `get-group`            | `/GetGroup`                                | Teams Read-Only      |
| `create-group`         | `/CreateGroup`                             | Teams Update         |
| `update-group`         | `/UpdateGroup`                             | Teams Update         |
| `delete-group`         | `/DeleteGroup`                             | Teams Update         |
| `list-group-members`   | `/ListGroupMembers`                        | Teams Read-Only      |
| `add-group-members`    | `/AddGroupMembers`                         | Teams Update         |
| `remove-group-members` | `/RemoveGroupMembers`                      | Teams Update         |
| `get-user-acu-cap`     | `/GetUserAcuCap`                           | Teams Read-Only      |
| `update-user-acu-cap`  | `/UpdateUserAcuCap`                        | Teams Update         |

L’exécution du script sans spécifier de commande (l’invocation d’origine) génère le rapport `usage`.

<div id="output-and-errors">
  ## Sortie et erreurs
</div>

Toutes les commandes écrivent du JSON sur stdout. Les résultats paginés (lignes de consommation d’ACU par utilisateur, `list-groups`, `list-group-members`) sont automatiquement récupérés jusqu’à la dernière page et regroupés en une seule réponse. Les erreurs d’API sont écrites sur stderr au format `code: message`, et le script se termine avec le code de sortie `1`.

<div id="examples">
  ## Exemples
</div>

<div id="per-user-usage-report">
  ### Rapport d’utilisation par utilisateur
</div>

```bash theme={null}
python windsurf_analytics.py \
    --service-key YOUR_SERVICE_KEY \
    --api-url https://your-server.com \
    --start 2025-01-01T00:00:00Z \
    --end 2025-03-31T23:59:59Z
```

<div id="acu-consumption">
  ### Consommation d’ACU
</div>

```bash theme={null}
# Total d'ACU de la Team, plus les lignes par utilisateur, pour le cycle de facturation en cours
python windsurf_analytics.py acu-consumption \
    --api-url https://your-server.com \
    --current-cycle --include-team-total --team-user-rows

# Répartition historique par groupe (la fenêtre ne doit pas dépasser 90 jours),
# avec les lignes par utilisateur pour un groupe
python windsurf_analytics.py acu-consumption \
    --api-url https://your-server.com \
    --start 2025-01-01T00:00:00Z --end 2025-03-31T23:59:59Z \
    --group-id GROUP_A_ID --group-user-rows GROUP_A_ID
```

Options de `acu-consumption` : `--current-cycle` ou `--start`/`--end` sélectionnent la période ; `--include-team-total`, `--group-id` répétable (100 maximum) et `--team-user-rows` / `--group-user-rows GROUP_ID`, qui s’excluent mutuellement, sélectionnent les données ; `--page-size` règle la taille des pages par requête (toutes les pages sont récupérées dans tous les cas). Au moins une option de sélection des données est requise. Une clé limitée à un groupe ne peut sélectionner que le groupe qui lui est attribué et ne peut pas demander les totaux de l’équipe ni les lignes par utilisateur de l’équipe.

<div id="group-management">
  ### Gestion des groupes
</div>

```bash theme={null}
# Lister les groupes et consulter un groupe
python windsurf_analytics.py list-groups --api-url https://your-server.com
python windsurf_analytics.py get-group --api-url https://your-server.com \
    --group-id GROUP_ID

# Créer un groupe, configurer ses modèles et son plafond d'ACU
python windsurf_analytics.py create-group --api-url https://your-server.com \
    --name Engineering
python windsurf_analytics.py update-group --api-url https://your-server.com \
    --group-id GROUP_ID \
    --cascade-models MODEL_UID_1,MODEL_UID_2 \
    --set-cycle-acu-limit 50

# Supprimer la restriction de modèles ou le plafond d'ACU d'un groupe. L'API du service exige
# une valeur positive lors de la définition d'un plafond de groupe ; la suppression est une opération distincte.
python windsurf_analytics.py update-group --api-url https://your-server.com \
    --group-id GROUP_ID --clear-cascade-models --clear-cycle-acu-limit

# Gérer les membres (e-mails séparés par des virgules, 1000 max.)
python windsurf_analytics.py add-group-members --api-url https://your-server.com \
    --group-id GROUP_ID --emails dev@agency.gov,lead@agency.gov
python windsurf_analytics.py remove-group-members --api-url https://your-server.com \
    --group-id GROUP_ID --emails dev@agency.gov

# Supprimer un groupe (idempotent)
python windsurf_analytics.py delete-group --api-url https://your-server.com \
    --group-id GROUP_ID
```

<div id="user-acu-caps">
  ### Plafonds d’ACU par utilisateur
</div>

```bash theme={null}
# Lire le plafond configuré et effectif d'un utilisateur (sélection par --email ou --user-id)
python windsurf_analytics.py get-user-acu-cap --api-url https://your-server.com \
    --email dev@agency.gov

# Définir un plafond (0 bloque l'utilisateur) ou supprimer la dérogation
python windsurf_analytics.py update-user-acu-cap --api-url https://your-server.com \
    --email dev@agency.gov --set-cycle-acu-limit 25
python windsurf_analytics.py update-user-acu-cap --api-url https://your-server.com \
    --email dev@agency.gov --clear-cycle-acu-limit
```