fix(OpenAI): Handle diarized json response in TranscriptionResponseSegment (#706)

Co-authored-by: Olivier Drieux <olivier.drieux@linkweb.fr>

Author: olivier-drieux

src/Responses/Audio/TranscriptionResponse.php

@@ -12,12 +12,12 @@
 use OpenAI\Testing\Responses\Concerns\Fakeable;
 
 /**
- * @implements ResponseContract<array{task: ?string, language: ?string, duration: ?float, segments: array<int, array{id: int, seek: int, start: float, end: float, text: string, tokens: array<int, int>, temperature: float, avg_logprob: float, compression_ratio: float, no_speech_prob: float, transient?: bool}>, words: array<int, array{word: string, start: float, end: float}>, text: string}>
+ * @implements ResponseContract<array{task: ?string, language: ?string, duration: ?float, segments: array<int, array{id: int|string, start: float, end: float, text: string, seek?: int, tokens?: array<int, int>, temperature?: float, avg_logprob?: float, compression_ratio?: float, no_speech_prob?: float, transient?: bool, speaker?: string, type?: string}>, words: array<int, array{word: string, start: float, end: float}>, text: string}>
  */
 final class TranscriptionResponse implements ResponseContract, ResponseHasMetaInformationContract
 {
     /**
-     * @use ArrayAccessible<array{task: ?string, language: ?string, duration: ?float, segments: array<int, array{id: int, seek: int, start: float, end: float, text: string, tokens: array<int, int>, temperature: float, avg_logprob: float, compression_ratio: float, no_speech_prob: float, transient?: bool}>, words: array<int, array{word: string, start: float, end: float}>, text: string}>
+     * @use ArrayAccessible<array{task: ?string, language: ?string, duration: ?float, segments: array<int, array{id: int|string, start: float, end: float, text: string, seek?: int, tokens?: array<int, int>, temperature?: float, avg_logprob?: float, compression_ratio?: float, no_speech_prob?: float, transient?: bool, speaker?: string, type?: string}>, words: array<int, array{word: string, start: float, end: float}>, text: string}>
      */
     use ArrayAccessible;
 
@@ -41,7 +41,7 @@ private function __construct(
     /**
      * Acts as static factory, and returns a new Response instance.
      *
-     * @param  array{task: ?string, language: ?string, duration: ?float, segments: array<int, array{id: int, seek: int, start: float, end: float, text: string, tokens: array<int, int>, temperature: float, avg_logprob: float, compression_ratio: float, no_speech_prob: float, transient?: bool}>, words: array<int, array{word: string, start: float, end: float}>, text: string}|string  $attributes
+     * @param  array{task: ?string, language: ?string, duration: ?float, segments: array<int, array{id: int|string, start: float, end: float, text: string, seek?: int, tokens?: array<int, int>, temperature?: float, avg_logprob?: float, compression_ratio?: float, no_speech_prob?: float, transient?: bool, speaker?: string, type?: string}>, words: array<int, array{word: string, start: float, end: float}>, text: string}|string  $attributes
      */
     public static function from(array|string $attributes, MetaInformation $meta): self
     {

src/Responses/Audio/TranscriptionResponseSegment.php

@@ -8,51 +8,56 @@
 use OpenAI\Responses\Concerns\ArrayAccessible;
 
 /**
- * @implements ResponseContract<array{id: int, seek: int, start: float, end: float, text: string, tokens: array<int, int>, temperature: float, avg_logprob: float, compression_ratio: float, no_speech_prob: float, transient?: bool}>
+ * @implements ResponseContract<array{id: int|string, start: float, end: float, text: string, seek?: int, tokens?: array<int, int>, temperature?: float, avg_logprob?: float, compression_ratio?: float, no_speech_prob?: float, transient?: bool, speaker?: string, type?: string}>
  */
 final class TranscriptionResponseSegment implements ResponseContract
 {
     /**
-     * @use ArrayAccessible<array{id: int, seek: int, start: float, end: float, text: string, tokens: array<int, int>, temperature: float, avg_logprob: float, compression_ratio: float, no_speech_prob: float, transient?: bool}>
+     * @use ArrayAccessible<array{id: int|string, start: float, end: float, text: string, seek?: int, tokens?: array<int, int>, temperature?: float, avg_logprob?: float, compression_ratio?: float, no_speech_prob?: float, transient?: bool, speaker?: string, type?: string}>
      */
     use ArrayAccessible;
 
     /**
+     * @param  int|string  $id  string in case of diarization, int otherwise
      * @param  array<int, int>  $tokens
      */
     private function __construct(
-        public readonly int $id,
-        public readonly int $seek,
+        public readonly int|string $id,
         public readonly float $start,
         public readonly float $end,
         public readonly string $text,
-        public readonly array $tokens,
-        public readonly float $temperature,
-        public readonly float $avgLogprob,
-        public readonly float $compressionRatio,
-        public readonly float $noSpeechProb,
+        public readonly ?int $seek,
+        public readonly ?array $tokens,
+        public readonly ?float $temperature,
+        public readonly ?float $avgLogprob,
+        public readonly ?float $compressionRatio,
+        public readonly ?float $noSpeechProb,
         public readonly ?bool $transient,
+        public readonly ?string $speaker,
+        public readonly ?string $type,
     ) {}
 
     /**
      * Acts as static factory, and returns a new Response instance.
      *
-     * @param  array{id: int, seek: int, start: float, end: float, text: string, tokens: array<int, int>, temperature: float, avg_logprob: float, compression_ratio: float, no_speech_prob: float, transient?: bool}  $attributes
+     * @param  array{id: int|string, start: float, end: float, text: string, seek?: int, tokens?: array<int, int>, temperature?: float, avg_logprob?: float, compression_ratio?: float, no_speech_prob?: float, transient?: bool, speaker?: string, type?: string}  $attributes
      */
     public static function from(array $attributes): self
     {
         return new self(
             $attributes['id'],
-            $attributes['seek'],
             $attributes['start'],
             $attributes['end'],
             $attributes['text'],
-            $attributes['tokens'],
-            $attributes['temperature'],
-            $attributes['avg_logprob'],
-            $attributes['compression_ratio'],
-            $attributes['no_speech_prob'],
+            $attributes['seek'] ?? null,
+            $attributes['tokens'] ?? null,
+            $attributes['temperature'] ?? null,
+            $attributes['avg_logprob'] ?? null,
+            $attributes['compression_ratio'] ?? null,
+            $attributes['no_speech_prob'] ?? null,
             $attributes['transient'] ?? null,
+            $attributes['speaker'] ?? null,
+            $attributes['type'] ?? null,
         );
     }
 
@@ -63,21 +68,47 @@ public function toArray(): array
     {
         $data = [
             'id' => $this->id,
-            'seek' => $this->seek,
             'start' => $this->start,
             'end' => $this->end,
             'text' => $this->text,
-            'tokens' => $this->tokens,
-            'temperature' => $this->temperature,
-            'avg_logprob' => $this->avgLogprob,
-            'compression_ratio' => $this->compressionRatio,
-            'no_speech_prob' => $this->noSpeechProb,
         ];
 
+        if ($this->seek !== null) {
+            $data['seek'] = $this->seek;
+        }
+
+        if ($this->tokens !== null) {
+            $data['tokens'] = $this->tokens;
+        }
+
+        if ($this->temperature !== null) {
+            $data['temperature'] = $this->temperature;
+        }
+
+        if ($this->avgLogprob !== null) {
+            $data['avg_logprob'] = $this->avgLogprob;
+        }
+
+        if ($this->compressionRatio !== null) {
+            $data['compression_ratio'] = $this->compressionRatio;
+        }
+
+        if ($this->noSpeechProb !== null) {
+            $data['no_speech_prob'] = $this->noSpeechProb;
+        }
+
         if ($this->transient !== null) {
             $data['transient'] = $this->transient;
         }
 
+        if ($this->speaker !== null) {
+            $data['speaker'] = $this->speaker;
+        }
+
+        if ($this->type !== null) {
+            $data['type'] = $this->type;
+        }
+
         return $data;
     }
 }

tests/Fixtures/Audio.php

@@ -12,10 +12,10 @@ function audioTranscriptionVerboseJson(): array
         'segments' => [
             [
                 'id' => 0,
-                'seek' => 0,
                 'start' => 0.0,
                 'end' => 4.0,
                 'text' => ' Hello, how are you?',
+                'seek' => 0,
                 'tokens' => [
                     50364,
                     2425,
@@ -59,6 +59,29 @@ function audioTranscriptionVerboseJson(): array
     ];
 }
 
+/**
+ * @return array<string, mixed>
+ */
+function audioTranscriptionDiarizedJson(): array
+{
+    return [
+        'task' => 'transcribe',
+        'language' => 'english',
+        'duration' => 2.95,
+        'segments' => [
+            [
+                'id' => 'seg_0',
+                'start' => 0.0,
+                'end' => 4.0,
+                'text' => ' Hello, how are you?',
+                'speaker' => 'A',
+                'type' => 'transcript.text.segment',
+            ],
+        ],
+        'text' => 'Hello, how are you?',
+    ];
+}
+
 /**
  * @return array<string, string>
  */

tests/Responses/Audio/TranscriptionResponse.php

@@ -37,6 +37,23 @@
         ->meta()->toBeInstanceOf(MetaInformation::class);
 });
 
+test('from diarized json', function () {
+    $transcription = TranscriptionResponse::from(audioTranscriptionDiarizedJson(), meta());
+
+    expect($transcription)
+        ->toBeInstanceOf(TranscriptionResponse::class)
+        ->task->toBe('transcribe')
+        ->language->toBe('english')
+        ->duration->toBe(2.95)
+        ->segments->toBeArray()
+        ->segments->toHaveCount(1)
+        ->segments->each->toBeInstanceOf(TranscriptionResponseSegment::class)
+        ->words->toBeArray()
+        ->words->toHaveCount(0)
+        ->text->toBe('Hello, how are you?')
+        ->meta()->toBeInstanceOf(MetaInformation::class);
+});
+
 test('from text', function () {
     $transcription = TranscriptionResponse::from(audioTranscriptionText(), meta());
 

tests/Responses/Audio/TranscriptionResponseSegment.php

@@ -19,7 +19,31 @@
         ->avgLogprob->toBe(-0.45045216878255206)
         ->compressionRatio->toBe(0.7037037037037037)
         ->noSpeechProb->toBe(0.1076972484588623)
-        ->transient->toBeFalse();
+        ->transient->toBeFalse()
+        // Test that diarization-specific properties are null
+        ->type->toBeNull()
+        ->speaker->toBeNull();
+});
+
+test('from diarized', function () {
+    $result = TranscriptionResponseSegment::from(audioTranscriptionDiarizedJson()['segments'][0]);
+
+    expect($result)
+        ->toBeInstanceOf(TranscriptionResponseSegment::class)
+        ->id->toBe('seg_0')
+        ->start->toBe(0.0)
+        ->end->toBe(4.0)
+        ->text->toBe(' Hello, how are you?')
+        ->speaker->toBe('A')
+        ->type->toBe('transcript.text.segment')
+        // Test that non-diarization-specific properties are null
+        ->tokens->toBeNull()
+        ->seek->toBeNull()
+        ->temperature->toBeNull()
+        ->avgLogprob->toBeNull()
+        ->compressionRatio->toBeNull()
+        ->noSpeechProb->toBeNull()
+        ->transient->toBeNull();
 });
 
 test('to array', function () {