aimo-client 0.4.0

AiMo Network REST API types and client
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
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
use aimo_core::{
    provider::{Model, ProviderMetadata},
    receipt::RequestReceipt,
};
use anyhow::{Context, Result};
use serde::{Deserialize, Serialize};

// Common pagination and filtering structures
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PaginationQuery {
    pub page: Option<String>,
    pub limit: Option<String>,
}

impl PaginationQuery {
    pub fn get_page(&self) -> u64 {
        self.page
            .as_ref()
            .and_then(|p| p.parse().ok())
            .unwrap_or(1)
            .max(1)
    }

    pub fn get_limit(&self) -> u64 {
        self.limit
            .as_ref()
            .and_then(|l| l.parse().ok())
            .unwrap_or(20)
            .min(100)
            .max(1)
    }
}

impl Default for PaginationQuery {
    fn default() -> Self {
        Self {
            page: Some("1".to_string()),
            limit: Some("20".to_string()),
        }
    }
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SortQuery {
    pub sort_by: Option<String>,
    pub sort_order: Option<SortOrder>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum SortOrder {
    Asc,
    Desc,
}

impl Default for SortOrder {
    fn default() -> Self {
        Self::Desc
    }
}

// User activity endpoint types
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct UserActivityQuery {
    #[serde(flatten)]
    pub pagination: PaginationQuery,
    #[serde(flatten)]
    pub sort: SortQuery,
    pub provider_id: Option<String>,
    pub model_name: Option<String>,
    pub from_timestamp: Option<String>,
    pub to_timestamp: Option<String>,
}

impl UserActivityQuery {
    pub fn get_from_timestamp(&self) -> Option<i64> {
        self.from_timestamp.as_ref().and_then(|t| t.parse().ok())
    }

    pub fn get_to_timestamp(&self) -> Option<i64> {
        self.to_timestamp.as_ref().and_then(|t| t.parse().ok())
    }
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct UserActivityItem {
    pub timestamp: i64,
    pub provider_id: String,
    pub model_name: Option<String>,
    pub prompt_tokens: u64,
    pub completion_tokens: u64,
    pub spending_token: String,
    pub spending_amount: u64,
    pub finish_reason: String,
    pub request_id: String,
    pub streamed: Option<bool>,
    pub latency: Option<i64>,
    pub generation_time: Option<i64>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct UserActivityResponse {
    pub items: Vec<UserActivityItem>,
    pub pagination: PaginationInfo,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PaginationInfo {
    pub page: u64,
    pub limit: u64,
    pub total_items: u64,
    pub total_pages: u64,
}

// Provider models endpoint types
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ProviderModelsQuery {
    #[serde(flatten)]
    pub pagination: PaginationQuery,
    #[serde(flatten)]
    pub sort: SortQuery,
    pub provider_id: Option<String>,
    pub provider_name: Option<String>,
    pub model_name: Option<String>,
    pub category: Option<String>,
    pub include_stats: Option<bool>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ProviderModelItem {
    pub provider_id: String,
    pub provider_name: String,
    pub category: String,
    pub model: Model,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub statistics: Option<ModelStatistics>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ModelStatistics {
    pub total_requests: u64,
    pub total_tokens: u64,
    pub avg_latency: f64,
    pub avg_generation_time: f64,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PriceInfo {
    pub token: String,
    pub input_price: u64,
    pub output_price: u64,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ProviderModelsResponse {
    pub items: Vec<ProviderModelItem>,
    pub pagination: PaginationInfo,
}

// New model format responses using ProviderModelMetadata
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ProviderModelItemV2 {
    pub provider_id: String,
    pub provider_name: String,
    pub category: String,
    pub model: crate::types::models::ProviderModelMetadata,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ProviderModelsResponseV2 {
    pub items: Vec<ProviderModelItemV2>,
    pub pagination: PaginationInfo,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ModelDetailV2 {
    pub provider_id: String,
    pub provider_name: String,
    pub category: String,
    pub model: crate::types::models::ProviderModelMetadata,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub statistics: Option<ModelStatistics>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ModelDetail {
    pub provider_id: String,
    pub provider_name: String,
    pub category: String,
    pub model: Model,
    pub statistics: Option<ModelStatistics>,
}

// Provider metadata endpoint types
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ProviderMetadataResponse {
    pub provider_id: String,
    pub provider_name: String,
    pub category: String,
    pub models: Vec<ModelInfo>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ModelInfo {
    pub name: String,
    pub pricing: Vec<PriceInfo>,
}

// User balance endpoint types
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct UserBalanceResponse {
    pub balance: Vec<UserBalanceItem>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct UserBalanceItem {
    pub token: String,
    pub available: u64,
    pub locked: u64,
    pub total: u64,
}

// Helper function to convert RequestSettled to UserActivityItem
impl UserActivityItem {
    pub fn from_request_settled(
        receipt: RequestReceipt,
        _provider_name: String,
        model_name: Option<String>,
    ) -> Self {
        Self {
            timestamp: receipt.timestamp,
            provider_id: receipt.service_id.to_string(),
            model_name,
            prompt_tokens: receipt.prompt_tokens,
            completion_tokens: receipt.completion_tokens,
            spending_token: receipt.token_mint.to_string(),
            spending_amount: receipt.amount,
            finish_reason: receipt.finish_reason,
            request_id: receipt.request_id.to_string(),
            streamed: receipt.streamed,
            latency: receipt.latency,
            generation_time: receipt.generation_time,
        }
    }
}

// Leaderboard endpoint types
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct LeaderboardQuery {
    pub start_date: Option<String>, // Format: YYYY-MM-DD, if not provided, use 30 days ago
    pub end_date: Option<String>,   // Format: YYYY-MM-DD, if not provided, use current date
}

impl LeaderboardQuery {
    pub fn get_date_range(&self) -> Result<(i64, i64)> {
        use chrono::{Days, NaiveDate, Utc};

        // Parse start date
        let start_date = if let Some(start_str) = &self.start_date {
            NaiveDate::parse_from_str(start_str, "%Y-%m-%d")
                .with_context(|| format!("Invalid start_date format: {}", start_str))?
        } else {
            // Default to 30 days ago
            Utc::now()
                .date_naive()
                .checked_sub_days(Days::new(30))
                .context("Failed to calculate default start date")?
        };

        // Parse end date
        let end_date = if let Some(end_str) = &self.end_date {
            NaiveDate::parse_from_str(end_str, "%Y-%m-%d")
                .with_context(|| format!("Invalid end_date format: {}", end_str))?
        } else {
            // Default to current date
            Utc::now().date_naive()
        };

        // Validate date range
        if start_date > end_date {
            anyhow::bail!("start_date must be before or equal to end_date");
        }

        // Convert to UTC timestamps
        let start_of_day = start_date
            .and_hms_opt(0, 0, 0)
            .context("Failed to create start time")?
            .and_utc()
            .timestamp_millis();

        let end_of_day = end_date
            .and_hms_opt(23, 59, 59)
            .context("Failed to create end time")?
            .and_utc()
            .timestamp_millis();

        Ok((start_of_day, end_of_day))
    }

    pub fn get_date_range_string(&self) -> Result<String> {
        use chrono::{Days, NaiveDate, Utc};

        let start_date = if let Some(start_str) = &self.start_date {
            NaiveDate::parse_from_str(start_str, "%Y-%m-%d")
                .with_context(|| format!("Invalid start_date format: {}", start_str))?
        } else {
            Utc::now()
                .date_naive()
                .checked_sub_days(Days::new(30))
                .context("Failed to calculate default start date")?
        };

        let end_date = if let Some(end_str) = &self.end_date {
            NaiveDate::parse_from_str(end_str, "%Y-%m-%d")
                .with_context(|| format!("Invalid end_date format: {}", end_str))?
        } else {
            Utc::now().date_naive()
        };

        if start_date == end_date {
            Ok(start_date.format("%Y-%m-%d").to_string())
        } else {
            Ok(format!(
                "{} to {}",
                start_date.format("%Y-%m-%d"),
                end_date.format("%Y-%m-%d")
            ))
        }
    }
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct DailyModelUsageItem {
    pub rank: u64,
    pub model_display_name: String,
    pub token_usage: u64,
    pub model_provider: String,
    pub api_provider: String,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct DailyModelUsageData {
    pub date: String, // YYYY-MM-DD format
    pub items: Vec<DailyModelUsageItem>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ModelUsageLeaderboardResponse {
    pub date_range: String,
    pub daily_data: Vec<DailyModelUsageData>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct DailyApiProviderUsageItem {
    pub rank: u64,
    pub api_provider_name: String,
    pub token_usage: u64,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct DailyApiProviderUsageData {
    pub date: String, // YYYY-MM-DD format
    pub items: Vec<DailyApiProviderUsageItem>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ApiProviderUsageLeaderboardResponse {
    pub date_range: String,
    pub daily_data: Vec<DailyApiProviderUsageData>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct DailyModelProviderUsageItem {
    pub rank: u64,
    pub model_provider_name: String,
    pub token_usage: u64,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct DailyModelProviderUsageData {
    pub date: String, // YYYY-MM-DD format
    pub items: Vec<DailyModelProviderUsageItem>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ModelProviderUsageLeaderboardResponse {
    pub date_range: String,
    pub daily_data: Vec<DailyModelProviderUsageData>,
}

// Helper function to convert ProviderMetadata to responses
impl ProviderModelItem {
    pub fn from_provider_metadata(
        provider_id: String,
        metadata: &ProviderMetadata,
        statistics: Option<ModelStatistics>,
    ) -> Vec<Self> {
        match metadata {
            ProviderMetadata::ModelProvider(model_provider) => {
                // Properly serialize the category to match the serde snake_case format
                let category = serde_json::to_value(&model_provider.category)
                    .ok()
                    .and_then(|v| v.as_str().map(|s| s.to_string()))
                    .unwrap_or_else(|| "unknown".to_string());

                model_provider
                    .models
                    .iter()
                    .map(|model| Self {
                        provider_id: provider_id.clone(),
                        provider_name: model_provider.name.clone(),
                        category: category.clone(),
                        model: model.clone(),
                        statistics: statistics.clone(),
                    })
                    .collect()
            }
        }
    }
}

impl ProviderMetadataResponse {
    pub fn from_provider_metadata(provider_id: String, metadata: ProviderMetadata) -> Self {
        match metadata {
            ProviderMetadata::ModelProvider(model_provider) => {
                // Properly serialize the category to match the serde snake_case format
                let category = serde_json::to_value(&model_provider.category)
                    .ok()
                    .and_then(|v| v.as_str().map(|s| s.to_string()))
                    .unwrap_or_else(|| "unknown".to_string());

                Self {
                    provider_id,
                    provider_name: model_provider.name,
                    category,
                    models: model_provider
                        .models
                        .into_iter()
                        .map(|model| ModelInfo {
                            name: model.name,
                            pricing: model
                                .pricing
                                .into_iter()
                                .map(|p| PriceInfo {
                                    token: p.token,
                                    input_price: p.input_price,
                                    output_price: p.output_price,
                                })
                                .collect(),
                        })
                        .collect(),
                }
            }
        }
    }
}