opengatellm 0.1.0

Client Rust pour OpenGateLLM, l'API gateway open-source pour LLM self-hosted (DINUM / Etalab).
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
//! Endpoints self-service `/v1/me/*` : informations, clés d'API, usage.

use crate::client::Client;
use crate::common::EnvironmentalImpacts;
use crate::error::Error;
use serde::{Deserialize, Serialize};

/// Permission accordée à un utilisateur / une clé.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum PermissionType {
    /// Administration complète du gateway.
    Admin,
    /// Création de collections publiques.
    CreatePublicCollection,
    /// Lecture des métriques (`/metrics`).
    ReadMetric,
    /// Déclaration de modèles (provider).
    ProvideModels,
}

/// Type de limite de débit appliquée à un router (modèle).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
#[non_exhaustive]
pub enum LimitType {
    /// Tokens par minute.
    Tpm,
    /// Tokens par jour.
    Tpd,
    /// Requêtes par minute.
    Rpm,
    /// Requêtes par jour.
    Rpd,
}

/// Limite de débit sur un router (modèle) donné.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[non_exhaustive]
pub struct Limit {
    /// Identifiant du router (modèle) concerné.
    pub router_id: i64,
    /// Nature de la limite.
    #[serde(rename = "type")]
    pub kind: LimitType,
    /// Valeur de la limite (`None` = pas de plafond).
    #[serde(default)]
    pub value: Option<i64>,
}

/// Informations sur l'utilisateur courant (`GET /v1/me/info`).
#[derive(Debug, Clone, Serialize, Deserialize)]
#[non_exhaustive]
pub struct UserInfo {
    /// Identifiant interne.
    pub id: i64,
    /// Adresse e-mail.
    pub email: String,
    /// Nom d'affichage.
    #[serde(default)]
    pub name: Option<String>,
    /// Organisation de rattachement.
    #[serde(default)]
    pub organization: Option<i64>,
    /// Budget restant (unités OGL).
    #[serde(default)]
    pub budget: Option<f64>,
    /// Permissions accordées.
    #[serde(default)]
    pub permissions: Vec<PermissionType>,
    /// Limites de débit appliquées.
    #[serde(default)]
    pub limits: Vec<Limit>,
    /// Expiration du compte (timestamp Unix).
    #[serde(default)]
    pub expires: Option<i64>,
    /// Priorité d'ordonnancement des requêtes.
    #[serde(default)]
    pub priority: i64,
    /// Création du compte (timestamp Unix).
    pub created: i64,
    /// Dernière mise à jour (timestamp Unix).
    pub updated: i64,
}

/// Corps de `PATCH /v1/me/info` — champs à mettre à jour (tous optionnels).
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct UpdateUserInfo {
    /// Nouveau nom d'affichage.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub name: Option<String>,
    /// Nouvelle adresse e-mail.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub email: Option<String>,
    /// Mot de passe actuel (requis pour changer le mot de passe).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub current_password: Option<String>,
    /// Nouveau mot de passe.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub password: Option<String>,
}

impl UpdateUserInfo {
    /// Construit un patch vide (aucun champ modifié).
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    /// Définit le nouveau nom d'affichage.
    #[must_use]
    pub fn name(mut self, name: impl Into<String>) -> Self {
        self.name = Some(name.into());
        self
    }

    /// Définit la nouvelle adresse e-mail.
    #[must_use]
    pub fn email(mut self, email: impl Into<String>) -> Self {
        self.email = Some(email.into());
        self
    }

    /// Définit le couple (mot de passe actuel, nouveau mot de passe).
    #[must_use]
    pub fn password(mut self, current: impl Into<String>, new: impl Into<String>) -> Self {
        self.current_password = Some(current.into());
        self.password = Some(new.into());
        self
    }
}

/// Corps de `POST /v1/me/keys` — création d'une clé d'API.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CreateKey {
    /// Nom lisible de la clé.
    pub name: String,
    /// Expiration optionnelle (timestamp Unix).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub expires: Option<i64>,
}

impl CreateKey {
    /// Construit une demande de clé nommée, sans expiration.
    pub fn new(name: impl Into<String>) -> Self {
        Self {
            name: name.into(),
            expires: None,
        }
    }

    /// Définit une expiration (timestamp Unix).
    #[must_use]
    pub fn expires(mut self, expires: i64) -> Self {
        self.expires = Some(expires);
        self
    }
}

/// Réponse de `POST /v1/me/keys` : seule occasion où le token complet est révélé.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[non_exhaustive]
pub struct CreateKeyResponse {
    /// Identifiant de la clé créée.
    pub id: i64,
    /// Token complet — à stocker immédiatement (non récupérable ensuite).
    pub token: String,
}

/// Une clé d'API de l'utilisateur.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[non_exhaustive]
pub struct Key {
    /// Identifiant de la clé.
    pub id: i64,
    /// Nom lisible.
    pub name: String,
    /// Token de la clé (le gateway renvoie le token complet).
    pub token: String,
    /// Expiration (timestamp Unix), si définie.
    #[serde(default)]
    pub expires: Option<i64>,
    /// Création (timestamp Unix).
    pub created: i64,
}

/// Réponse de `GET /v1/me/keys` : liste des clés.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[non_exhaustive]
pub struct Keys {
    /// Clés de l'utilisateur.
    pub data: Vec<Key>,
}

/// Métriques de latence d'une ligne d'usage.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
#[non_exhaustive]
pub struct MetricsUsage {
    /// Latence totale (ms).
    #[serde(default)]
    pub latency: Option<i64>,
    /// Time-to-first-token (ms).
    #[serde(default)]
    pub ttft: Option<i64>,
}

/// Compteurs de tokens / coût / impacts d'une ligne d'usage.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[non_exhaustive]
pub struct UsageDetail {
    /// Tokens de prompt consommés.
    #[serde(default)]
    pub prompt_tokens: Option<i64>,
    /// Tokens de complétion générés.
    #[serde(default)]
    pub completion_tokens: Option<i64>,
    /// Total de tokens.
    #[serde(default)]
    pub total_tokens: Option<i64>,
    /// Coût estimé.
    #[serde(default)]
    pub cost: Option<f64>,
    /// Empreinte environnementale (toujours présente côté OGL).
    #[serde(default)]
    pub impacts: EnvironmentalImpacts,
    /// Métriques de latence (toujours présentes côté OGL).
    #[serde(default)]
    pub metrics: MetricsUsage,
}

/// Une ligne d'usage (`GET /v1/me/usage` → élément de `data`).
///
/// Les compteurs de tokens sont **imbriqués** sous [`UsageRecord::usage`] ;
/// `created` est le seul champ garanti par le schéma serveur.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[non_exhaustive]
pub struct UsageRecord {
    /// Modèle utilisé.
    #[serde(default)]
    pub model: Option<String>,
    /// Clé d'API utilisée.
    #[serde(default)]
    pub key: Option<String>,
    /// Endpoint appelé.
    #[serde(default)]
    pub endpoint: Option<String>,
    /// Méthode HTTP.
    #[serde(default)]
    pub method: Option<String>,
    /// Code de statut de la réponse.
    #[serde(default)]
    pub status: Option<i64>,
    /// Compteurs de tokens / coût / impacts de la ligne.
    #[serde(default)]
    pub usage: UsageDetail,
    /// Horodatage de la ligne (timestamp Unix, secondes).
    pub created: i64,
}

/// Réponse de `GET /v1/me/usage`.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[non_exhaustive]
pub struct Usages {
    /// Lignes d'usage.
    pub data: Vec<UsageRecord>,
}

/// Endpoint facturable, pour filtrer `GET /v1/me/usage`.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[non_exhaustive]
pub enum EndpointUsage {
    /// `/v1/audio/transcriptions`.
    #[serde(rename = "/v1/audio/transcriptions")]
    AudioTranscriptions,
    /// `/v1/chat/completions`.
    #[serde(rename = "/v1/chat/completions")]
    ChatCompletions,
    /// `/v1/embeddings`.
    #[serde(rename = "/v1/embeddings")]
    Embeddings,
    /// `/v1/ocr`.
    #[serde(rename = "/v1/ocr")]
    Ocr,
    /// `/v1/rerank`.
    #[serde(rename = "/v1/rerank")]
    Rerank,
    /// `/v1/search`.
    #[serde(rename = "/v1/search")]
    Search,
}

/// Paramètres de pagination / tri pour `GET /v1/me/keys`.
#[derive(Debug, Clone, Default, Serialize)]
pub struct KeysQuery {
    /// Décalage de pagination.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub offset: Option<u32>,
    /// Taille de page.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub limit: Option<u32>,
    /// Champ de tri.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub order_by: Option<String>,
    /// Direction de tri (`asc` / `desc`).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub order_direction: Option<String>,
}

impl KeysQuery {
    /// Construit des paramètres vides (aucun filtre).
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    /// Définit le décalage de pagination.
    #[must_use]
    pub fn offset(mut self, offset: u32) -> Self {
        self.offset = Some(offset);
        self
    }

    /// Définit la taille de page.
    #[must_use]
    pub fn limit(mut self, limit: u32) -> Self {
        self.limit = Some(limit);
        self
    }

    /// Définit le champ et la direction de tri.
    #[must_use]
    pub fn order(mut self, by: impl Into<String>, direction: impl Into<String>) -> Self {
        self.order_by = Some(by.into());
        self.order_direction = Some(direction.into());
        self
    }
}

/// Paramètres de filtrage pour `GET /v1/me/usage`.
#[derive(Debug, Clone, Default, Serialize)]
pub struct UsageQuery {
    /// Décalage de pagination.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub offset: Option<u32>,
    /// Taille de page.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub limit: Option<u32>,
    /// Borne basse de la fenêtre (timestamp Unix).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub start_time: Option<i64>,
    /// Borne haute de la fenêtre (timestamp Unix).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub end_time: Option<i64>,
    /// Restreint à un endpoint facturable donné.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub endpoint: Option<EndpointUsage>,
}

impl UsageQuery {
    /// Construit des paramètres vides (aucun filtre).
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    /// Définit le décalage de pagination.
    #[must_use]
    pub fn offset(mut self, offset: u32) -> Self {
        self.offset = Some(offset);
        self
    }

    /// Définit la taille de page.
    #[must_use]
    pub fn limit(mut self, limit: u32) -> Self {
        self.limit = Some(limit);
        self
    }

    /// Définit la fenêtre temporelle (timestamps Unix).
    #[must_use]
    pub fn time_range(mut self, start: i64, end: i64) -> Self {
        self.start_time = Some(start);
        self.end_time = Some(end);
        self
    }

    /// Restreint à un endpoint facturable.
    #[must_use]
    pub fn endpoint(mut self, endpoint: EndpointUsage) -> Self {
        self.endpoint = Some(endpoint);
        self
    }
}

impl Client {
    /// `GET /v1/me/info` — informations sur l'utilisateur courant.
    pub async fn me_info(&self) -> Result<UserInfo, Error> {
        let url = self.endpoint("/v1/me/info")?;
        self.get_json(url).await
    }

    /// `PATCH /v1/me/info` — met à jour le profil (renvoie `204 No Content`).
    pub async fn update_me_info(&self, update: &UpdateUserInfo) -> Result<(), Error> {
        let url = self.endpoint("/v1/me/info")?;
        self.patch_no_content(url, update).await
    }

    /// `POST /v1/me/keys` — crée une clé d'API et renvoie le token complet.
    pub async fn create_key(&self, key: &CreateKey) -> Result<CreateKeyResponse, Error> {
        let url = self.endpoint("/v1/me/keys")?;
        self.post_json(url, key).await
    }

    /// `GET /v1/me/keys` — liste les clés d'API de l'utilisateur.
    pub async fn keys(&self, query: &KeysQuery) -> Result<Keys, Error> {
        let url = self.endpoint("/v1/me/keys")?;
        self.get_json_with_query(url, query).await
    }

    /// `GET /v1/me/keys/{key}` — récupère une clé par identifiant.
    pub async fn key(&self, key_id: impl std::fmt::Display) -> Result<Key, Error> {
        let url = self.endpoint_with_segment("/v1/me/keys/", &key_id.to_string())?;
        self.get_json(url).await
    }

    /// `DELETE /v1/me/keys/{key}` — révoque une clé (renvoie `204 No Content`).
    pub async fn delete_key(&self, key_id: impl std::fmt::Display) -> Result<(), Error> {
        let url = self.endpoint_with_segment("/v1/me/keys/", &key_id.to_string())?;
        self.delete_no_content(url).await
    }

    /// `GET /v1/me/usage` — usage agrégé de l'utilisateur (tokens, coût, impacts).
    pub async fn usage(&self, query: &UsageQuery) -> Result<Usages, Error> {
        let url = self.endpoint("/v1/me/usage")?;
        self.get_json_with_query(url, query).await
    }
}