feat: type BatchStatus for all possible states

[tucnak]

The OpenAI API reference on Batch API is peculiar insofar it doesn't enumerate possible states for batch status. I was surprised to learn that neither did this library (which is surprising considering it's defining EmbeddingModel among other things) so I simply used the enumeration from OpenAI's Python SDK.

    status: Literal[
        "validating", "failed", "in_progress", "finalizing", "completed", "expired", "cancelling", "cancelled"
    ]
    """The current status of the batch."""

This PR introduces a breaking change: Batch.Status before a string now a BatchStatus.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 98.69%. Comparing base (774fc9d) to head (f180ab5).
Report is 73 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #907      +/-   ##
==========================================
+ Coverage   98.46%   98.69%   +0.23%     
==========================================
  Files          24       26       +2     
  Lines        1364     1758     +394     
==========================================
+ Hits         1343     1735     +392     
- Misses         15       16       +1     
- Partials        6        7       +1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[sashabaranov]

@tucnak thank you for the PR!

[sashabaranov]

@tucnak, Could you please re-format this PR? Such huge diffs are very hard to review — I need to write a script to verify that no fields are getting removed.

With a single field's type changed, the diff shouldn't be much larger than an example below:

diff --git a/batch.go b/batch.go
index 3c1a9d0..07d394d 100644
--- a/batch.go
+++ b/batch.go
@@ -59,19 +59,25 @@ func (r BatchEmbeddingRequest) MarshalBatchLineItem() []byte {
 	return marshal
 }
 
+type BatchStatus string
+
+const (
+	BatchStatusValidating BatchStatus = "validating"
+	BatchStatusFailed     BatchStatus = "failed"
+	BatchStatusInProgress BatchStatus = "in_progress"
+	BatchStatusFinalizing BatchStatus = "finalizing"
+	BatchStatusCompleted  BatchStatus = "completed"
+	BatchStatusExpired    BatchStatus = "expired"
+	BatchStatusCancelling BatchStatus = "cancelling"
+	BatchStatusCancelled  BatchStatus = "cancelled"
+)
+
+
 type Batch struct {
 	ID       string        `json:"id"`
 	Object   string        `json:"object"`
 	Endpoint BatchEndpoint `json:"endpoint"`
-	Errors   *struct {
-		Object string `json:"object,omitempty"`
-		Data   []struct {
-			Code    string  `json:"code,omitempty"`
-			Message string  `json:"message,omitempty"`
-			Param   *string `json:"param,omitempty"`
-			Line    *int    `json:"line,omitempty"`
-		} `json:"data"`
-	} `json:"errors"`
+	Errors           *BatchErrors       `json:"errors,omitempty"`
 	InputFileID      string             `json:"input_file_id"`
 	CompletionWindow string             `json:"completion_window"`
 	Status           string             `json:"status"`
@@ -90,6 +96,20 @@ type Batch struct {
 	Metadata         map[string]any     `json:"metadata"`
 }
 
+
+type BatchErrors struct {
+	Object string       `json:"object,omitempty"`
+	Data   []BatchError `json:"data"`
+}
+
+type BatchError struct {
+	Code    string `json:"code,omitempty"`
+	Message string `json:"message,omitempty"`
+	Param   string `json:"param,omitempty"`
+	Line    int    `json:"line,omitempty"`
+}
+
+
 type BatchRequestCounts struct {
 	Total     int `json:"total"`
 	Completed int `json:"completed"`

[tucnak]

Oh, I'm sorry I had accidentally cherry-picked a different commit into this branch.

I can rebase the last commit away, which is what brings most changes, but what do you think in general, is it perhaps worth merging either way? The Errors field is currently inline, & it was a serious issue for me when implementing a batching proxy (as I need to manually aggregate the errors.)

I also felt the optional timestamps are better served with omitempty (int64 zero is non-ambiguous) and it's really tedious to handle int64 pointers in general (as opposed to timestamps.) FWIW, I also have this type which is based on time.Time implementing json.Marshaler and json.Unmarshaler on integers. Don't know how willing you are to introduce breaking changes for future major versions, but I think that one is marginally worth it: handling time.Time conversions is quite tedious, and having a type is beneficial to that end, as both functional time.Time and JSON-transparent (you get int64 in and out.)