dynamo_async_openai/types/batch.rs
1// SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2// SPDX-License-Identifier: Apache-2.0
3//
4// Based on https://github.com/64bit/async-openai/ by Himanshu Neema
5// Original Copyright (c) 2022 Himanshu Neema
6// Licensed under MIT License (see ATTRIBUTIONS-Rust.md)
7//
8// Modifications Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES.
9// Licensed under Apache 2.0
10
11use std::collections::HashMap;
12
13use derive_builder::Builder;
14use serde::{Deserialize, Serialize};
15
16use crate::error::OpenAIError;
17
18#[derive(Debug, Serialize, Default, Clone, Builder, PartialEq, Deserialize)]
19#[builder(name = "BatchRequestArgs")]
20#[builder(pattern = "mutable")]
21#[builder(setter(into, strip_option), default)]
22#[builder(derive(Debug))]
23#[builder(build_fn(error = "OpenAIError"))]
24pub struct BatchRequest {
25 /// The ID of an uploaded file that contains requests for the new batch.
26 ///
27 /// See [upload file](https://platform.openai.com/docs/api-reference/files/create) for how to upload a file.
28 ///
29 /// Your input file must be formatted as a [JSONL file](https://platform.openai.com/docs/api-reference/batch/request-input), and must be uploaded with the purpose `batch`. The file can contain up to 50,000 requests, and can be up to 100 MB in size.
30 pub input_file_id: String,
31
32 /// The endpoint to be used for all requests in the batch. Currently `/v1/chat/completions`, `/v1/embeddings`, and `/v1/completions` are supported. Note that `/v1/embeddings` batches are also restricted to a maximum of 50,000 embedding inputs across all requests in the batch.
33 pub endpoint: BatchEndpoint,
34
35 /// The time frame within which the batch should be processed. Currently only `24h` is supported.
36 pub completion_window: BatchCompletionWindow,
37
38 /// Optional custom metadata for the batch.
39 pub metadata: Option<HashMap<String, serde_json::Value>>,
40}
41
42#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, Default)]
43pub enum BatchEndpoint {
44 #[default]
45 #[serde(rename = "/v1/chat/completions")]
46 V1ChatCompletions,
47 #[serde(rename = "/v1/embeddings")]
48 V1Embeddings,
49 #[serde(rename = "/v1/completions")]
50 V1Completions,
51}
52
53#[derive(Debug, Clone, PartialEq, Serialize, Default, Deserialize)]
54pub enum BatchCompletionWindow {
55 #[default]
56 #[serde(rename = "24h")]
57 W24H,
58}
59
60#[derive(Debug, Deserialize, Clone, PartialEq, Serialize)]
61pub struct Batch {
62 pub id: String,
63 /// The object type, which is always `batch`.
64 pub object: String,
65 /// The OpenAI API endpoint used by the batch.
66 pub endpoint: String,
67 pub errors: Option<BatchErrors>,
68 /// The ID of the input file for the batch.
69 pub input_file_id: String,
70 /// The time frame within which the batch should be processed.
71 pub completion_window: String,
72 /// The current status of the batch.
73 pub status: BatchStatus,
74 /// The ID of the file containing the outputs of successfully executed requests.
75 pub output_file_id: Option<String>,
76 /// The ID of the file containing the outputs of requests with errors.
77 pub error_file_id: Option<String>,
78 /// The Unix timestamp (in seconds) for when the batch was created.
79 pub created_at: u32,
80 /// The Unix timestamp (in seconds) for when the batch started processing.
81 pub in_progress_at: Option<u32>,
82 /// The Unix timestamp (in seconds) for when the batch will expire.
83 pub expires_at: Option<u32>,
84 /// The Unix timestamp (in seconds) for when the batch started finalizing.
85 pub finalizing_at: Option<u32>,
86 /// The Unix timestamp (in seconds) for when the batch was completed.
87 pub completed_at: Option<u32>,
88 /// The Unix timestamp (in seconds) for when the batch failed.
89 pub failed_at: Option<u32>,
90 /// he Unix timestamp (in seconds) for when the batch expired.
91 pub expired_at: Option<u32>,
92 /// The Unix timestamp (in seconds) for when the batch started cancelling.
93 pub cancelling_at: Option<u32>,
94 /// The Unix timestamp (in seconds) for when the batch was cancelled.
95 pub cancelled_at: Option<u32>,
96 /// The request counts for different statuses within the batch.
97 pub request_counts: Option<BatchRequestCounts>,
98 /// Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format. Keys can be a maximum of 64 characters long and values can be a maximum of 512 characters long.
99 pub metadata: Option<HashMap<String, serde_json::Value>>,
100}
101
102#[derive(Debug, Deserialize, Clone, PartialEq, Serialize)]
103pub struct BatchErrors {
104 /// The object type, which is always `list`.
105 pub object: String,
106 pub data: Vec<BatchError>,
107}
108
109#[derive(Debug, Deserialize, Clone, PartialEq, Serialize)]
110pub struct BatchError {
111 /// An error code identifying the error type.
112 pub code: String,
113 /// A human-readable message providing more details about the error.
114 pub message: String,
115 /// The name of the parameter that caused the error, if applicable.
116 pub param: Option<String>,
117 /// The line number of the input file where the error occurred, if applicable.
118 pub line: Option<u32>,
119}
120
121#[derive(Debug, Deserialize, Clone, PartialEq, Serialize)]
122#[serde(rename_all = "snake_case")]
123pub enum BatchStatus {
124 Validating,
125 Failed,
126 InProgress,
127 Finalizing,
128 Completed,
129 Expired,
130 Cancelling,
131 Cancelled,
132}
133
134#[derive(Debug, Deserialize, Clone, PartialEq, Serialize)]
135pub struct BatchRequestCounts {
136 /// Total number of requests in the batch.
137 pub total: u32,
138 /// Number of requests that have been completed successfully.
139 pub completed: u32,
140 /// Number of requests that have failed.
141 pub failed: u32,
142}
143
144#[derive(Debug, Deserialize, Clone, PartialEq, Serialize)]
145pub struct ListBatchesResponse {
146 pub data: Vec<Batch>,
147 pub first_id: Option<String>,
148 pub last_id: Option<String>,
149 pub has_more: bool,
150 pub object: String,
151}
152
153#[derive(Debug, Deserialize, Clone, PartialEq, Serialize)]
154#[serde(rename_all = "UPPERCASE")]
155pub enum BatchRequestInputMethod {
156 POST,
157}
158
159/// The per-line object of the batch input file
160#[derive(Debug, Deserialize, Clone, PartialEq, Serialize)]
161pub struct BatchRequestInput {
162 /// A developer-provided per-request id that will be used to match outputs to inputs. Must be unique for each request in a batch.
163 pub custom_id: String,
164 /// The HTTP method to be used for the request. Currently only `POST` is supported.
165 pub method: BatchRequestInputMethod,
166 /// The OpenAI API relative URL to be used for the request. Currently `/v1/chat/completions`, `/v1/embeddings`, and `/v1/completions` are supported.
167 pub url: BatchEndpoint,
168 pub body: Option<serde_json::Value>,
169}
170
171#[derive(Debug, Deserialize, Clone, PartialEq, Serialize)]
172pub struct BatchRequestOutputResponse {
173 /// The HTTP status code of the response
174 pub status_code: u16,
175 /// An unique identifier for the OpenAI API request. Please include this request ID when contacting support.
176 pub request_id: String,
177 /// The JSON body of the response
178 pub body: serde_json::Value,
179}
180
181#[derive(Debug, Deserialize, Clone, PartialEq, Serialize)]
182pub struct BatchRequestOutputError {
183 /// A machine-readable error code.
184 pub code: String,
185 /// A human-readable error message.
186 pub message: String,
187}
188
189/// The per-line object of the batch output and error files
190#[derive(Debug, Deserialize, Clone, PartialEq, Serialize)]
191pub struct BatchRequestOutput {
192 pub id: String,
193 /// A developer-provided per-request id that will be used to match outputs to inputs.
194 pub custom_id: String,
195 pub response: Option<BatchRequestOutputResponse>,
196 /// For requests that failed with a non-HTTP error, this will contain more information on the cause of the failure.
197 pub error: Option<BatchRequestOutputError>,
198}