Complete exception hierarchy with indexed field names and simplified fromMissingData method

Author: Mohamed Khaled

src/Providers/Http/Exception/ResponseException.php

@@ -24,16 +24,11 @@ class ResponseException extends RuntimeException
      *
      * @param string $apiName The name of the API/provider.
      * @param string $fieldName The field that was expected but missing.
-     * @param string $context Additional context about where the field was expected.
      * @return self
      */
-    public static function fromMissingData(string $apiName, string $fieldName, string $context = ''): self
+    public static function fromMissingData(string $apiName, string $fieldName): self
     {
-        $message = sprintf('Unexpected %s API response: Missing the "%s" key', $apiName, $fieldName);
-        if ($context !== '') {
-            $message .= ' in ' . $context;
-        }
-        $message .= '.';
+        $message = sprintf('Unexpected %s API response: Missing the "%s" key.', $apiName, $fieldName);
 
         return new self($message);
     }

src/Providers/OpenAiCompatibleImplementation/AbstractOpenAiCompatibleImageGenerationModel.php

@@ -361,10 +361,9 @@ protected function parseResponseChoiceToCandidate(
         } elseif (isset($choiceData['b64_json']) && is_string($choiceData['b64_json'])) {
             $imageFile = new File($choiceData['b64_json'], $expectedMimeType);
         } else {
-            throw ResponseException::fromMissingData(
+            throw ResponseException::fromInvalidData(
                 $this->providerMetadata()->getName(),
-                'url or b64_json',
-                'choice data'
+                'Each choice must contain either a url or b64_json key with a string value.'
             );
         }
 

src/Providers/OpenAiCompatibleImplementation/AbstractOpenAiCompatibleTextGenerationModel.php

@@ -566,15 +566,15 @@ protected function parseResponseToGenerativeAiResult(Response $response): Genera
         }
 
         $candidates = [];
-        foreach ($responseData['choices'] as $choiceData) {
+        foreach ($responseData['choices'] as $index => $choiceData) {
             if (!is_array($choiceData) || array_is_list($choiceData)) {
                 throw ResponseException::fromInvalidData(
                     $this->providerMetadata()->getName(),
                     'Each element in the choices key must be an associative array.'
                 );
             }
 
-            $candidates[] = $this->parseResponseChoiceToCandidate($choiceData);
+            $candidates[] = $this->parseResponseChoiceToCandidate($choiceData, $index);
         }
 
         $id = isset($responseData['id']) && is_string($responseData['id']) ? $responseData['id'] : '';
@@ -611,10 +611,11 @@ protected function parseResponseToGenerativeAiResult(Response $response): Genera
      * @since 0.1.0
      *
      * @param ChoiceData $choiceData The choice data from the API response.
+     * @param int $index The index of the choice in the choices array.
      * @return Candidate The parsed candidate.
      * @throws RuntimeException If the choice data is invalid.
      */
-    protected function parseResponseChoiceToCandidate(array $choiceData): Candidate
+    protected function parseResponseChoiceToCandidate(array $choiceData, int $index): Candidate
     {
         if (
             !isset($choiceData['message']) ||
@@ -623,16 +624,14 @@ protected function parseResponseChoiceToCandidate(array $choiceData): Candidate
         ) {
             throw ResponseException::fromMissingData(
                 $this->providerMetadata()->getName(),
-                'message',
-                'choice data'
+                "choices[{$index}].message"
             );
         }
 
         if (!isset($choiceData['finish_reason']) || !is_string($choiceData['finish_reason'])) {
             throw ResponseException::fromMissingData(
                 $this->providerMetadata()->getName(),
-                'finish_reason',
-                'choice data'
+                "choices[{$index}].finish_reason"
             );
         }