openai_interface/batches/
mod.rs

1//! The Batches API: run async batch processing jobs over collections of
2//! requests via `/batches`.
3//!
4//! > ![warn] This module is untested!
5//! > If you encounter any issues, please report them on the repository.
6//!
7//! A batch job reads a JSONL file of requests (uploaded through the
8//! [`files`](crate::files) API), processes all of them within the
9//! completion window, and writes the results to an output file. See
10//! [the OpenAI Batch API guide](https://platform.openai.com/docs/guides/batch).
11//!
12//! Submodules: [`create`], [`retrieve`], [`list`], [`cancel`].
13
14pub mod cancel;
15pub mod create;
16pub mod list;
17pub mod retrieve;
18
19/// The lifecycle status of a batch job.
20#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Deserialize)]
21#[serde(rename_all = "snake_case")]
22pub enum BatchStatus {
23    /// The input file is being validated.
24    Validating,
25    /// Validation failed; see the `errors` field.
26    Failed,
27    /// The batch is currently being processed.
28    InProgress,
29    /// The batch finished processing and the output file is being
30    /// prepared.
31    Finalizing,
32    /// The batch completed and the output file is ready.
33    Completed,
34    /// The batch could not complete within the completion window.
35    Expired,
36    /// The batch is being cancelled.
37    Cancelling,
38    /// The batch was cancelled.
39    Cancelled,
40}
41
42/// The per-request result counts of a batch job.
43#[derive(Debug, Clone, serde::Deserialize)]
44pub struct BatchRequestCounts {
45    /// The total number of requests in the input file.
46    pub total: u64,
47    /// The number of requests that completed successfully.
48    pub completed: u64,
49    /// The number of requests that failed.
50    pub failed: u64,
51}
52
53/// An error entry attached to a batch job.
54#[derive(Debug, Clone, serde::Deserialize)]
55pub struct BatchError {
56    /// An error code identifying the failure mode.
57    #[serde(default)]
58    pub code: Option<String>,
59    /// A human-readable error message.
60    #[serde(default)]
61    pub message: Option<String>,
62    /// The request this error refers to, if applicable. Parameters
63    /// follow the JSONL line format of the input file.
64    #[serde(default)]
65    pub param: Option<serde_json::Value>,
66    /// The JSONL line of the input file this error refers to, if
67    /// applicable.
68    #[serde(default)]
69    pub line: Option<u64>,
70}
71
72/// The error list of a batch job.
73#[derive(Debug, Clone, serde::Deserialize)]
74pub struct BatchErrors {
75    /// Always `list`, when present.
76    #[serde(default)]
77    pub object: Option<String>,
78    /// The individual errors.
79    #[serde(default)]
80    pub data: Vec<BatchError>,
81}
82
83/// A batch processing job.
84#[derive(Debug, Clone, serde::Deserialize)]
85pub struct Batch {
86    /// The batch ID, e.g. `batch_...`.
87    pub id: String,
88    /// The object type, always `batch`.
89    #[serde(default)]
90    pub object: Option<String>,
91    /// The API endpoint the batch runs against, e.g.
92    /// `/v1/chat/completions`.
93    pub endpoint: String,
94    /// Errors of the batch, if any.
95    #[serde(default)]
96    pub errors: Option<BatchErrors>,
97    /// The ID of the input JSONL file.
98    pub input_file_id: String,
99    /// The time window within which the batch should be processed,
100    /// e.g. `24h`.
101    pub completion_window: String,
102    /// The current lifecycle status.
103    pub status: BatchStatus,
104    /// The ID of the output JSONL file, once the batch completes.
105    #[serde(default)]
106    pub output_file_id: Option<String>,
107    /// The ID of the JSONL file carrying the per-request errors, when
108    /// some requests failed.
109    #[serde(default)]
110    pub error_file_id: Option<String>,
111    /// Unix timestamp (seconds) of when the batch was created.
112    pub created_at: u64,
113    /// Unix timestamp (seconds) of when the batch started processing.
114    #[serde(default)]
115    pub in_progress_at: Option<u64>,
116    /// Unix timestamp (seconds) of when the batch expires if not
117    /// completed.
118    #[serde(default)]
119    pub expires_at: Option<u64>,
120    /// Unix timestamp (seconds) of when the batch started finalizing.
121    #[serde(default)]
122    pub finalizing_at: Option<u64>,
123    /// Unix timestamp (seconds) of when the batch completed.
124    #[serde(default)]
125    pub completed_at: Option<u64>,
126    /// Unix timestamp (seconds) of when the batch failed.
127    #[serde(default)]
128    pub failed_at: Option<u64>,
129    /// Unix timestamp (seconds) of when the batch expired.
130    #[serde(default)]
131    pub expired_at: Option<u64>,
132    /// Unix timestamp (seconds) of when the batch started cancelling.
133    #[serde(default)]
134    pub cancelling_at: Option<u64>,
135    /// Unix timestamp (seconds) of when the batch was cancelled.
136    #[serde(default)]
137    pub cancelled_at: Option<u64>,
138    /// Per-request result counts, once available.
139    #[serde(default)]
140    pub request_counts: Option<BatchRequestCounts>,
141    /// Arbitrary key-value metadata attached to the batch.
142    #[serde(default)]
143    pub metadata: Option<std::collections::HashMap<String, String>>,
144}
145
146crate::impl_from_str!(Batch);
openai_interface/batches/mod.rs

openai_interface/batches/
mod.rs
