feat(openrouter): Include raw API response context in structured decoding exceptions. (#824)

Author: pocketarc

src/Providers/OpenRouter/Handlers/Structured.php

@@ -6,6 +6,7 @@
 
 use Illuminate\Http\Client\PendingRequest;
 use Prism\Prism\Exceptions\PrismException;
+use Prism\Prism\Exceptions\PrismStructuredDecodingException;
 use Prism\Prism\Providers\OpenRouter\Concerns\BuildsRequestOptions;
 use Prism\Prism\Providers\OpenRouter\Concerns\MapsFinishReason;
 use Prism\Prism\Providers\OpenRouter\Concerns\ValidatesResponses;
@@ -109,6 +110,17 @@ protected function createResponse(Request $request, array $data): StructuredResp
 
         $this->responseBuilder->addStep($step);
 
-        return $this->responseBuilder->toResponse();
+        try {
+            return $this->responseBuilder->toResponse();
+        } catch (PrismStructuredDecodingException $e) {
+            $context = sprintf(
+                "\nModel: %s\nFinish reason: %s\nRaw choices: %s",
+                data_get($data, 'model', 'unknown'),
+                data_get($data, 'choices.0.finish_reason', 'unknown'),
+                json_encode(data_get($data, 'choices'), JSON_PRETTY_PRINT)
+            );
+
+            throw new PrismStructuredDecodingException($e->getMessage().$context);
+        }
     }
 }

tests/Fixtures/openrouter/structured-empty-content-1.json

@@ -0,0 +1,17 @@
+{
+    "id": "gen-structured-empty",
+    "model": "anthropic/claude-3.5-sonnet",
+    "choices": [
+        {
+            "message": {
+                "role": "assistant",
+                "content": null
+            },
+            "finish_reason": "stop"
+        }
+    ],
+    "usage": {
+        "prompt_tokens": 100,
+        "completion_tokens": 0
+    }
+}

tests/Providers/OpenRouter/StructuredTest.php

@@ -5,6 +5,7 @@
 use Illuminate\Http\Client\Request;
 use Illuminate\Support\Facades\Http;
 use Prism\Prism\Enums\Provider;
+use Prism\Prism\Exceptions\PrismStructuredDecodingException;
 use Prism\Prism\Facades\Prism;
 use Prism\Prism\Schema\BooleanSchema;
 use Prism\Prism\Schema\ObjectSchema;
@@ -154,3 +155,53 @@
             && $payload['verbosity'] === 'medium';
     });
 });
+
+it('throws enriched exception when content is empty', function (): void {
+    FixtureResponse::fakeResponseSequence('v1/chat/completions', 'openrouter/structured-empty-content');
+
+    $schema = new ObjectSchema(
+        'output',
+        'the output object',
+        [
+            new StringSchema('data', 'Some data'),
+        ],
+        ['data']
+    );
+
+    expect(fn () => Prism::structured()
+        ->withSchema($schema)
+        ->using(Provider::OpenRouter, 'anthropic/claude-3.5-sonnet')
+        ->withPrompt('Give me some data')
+        ->asStructured()
+    )->toThrow(PrismStructuredDecodingException::class);
+});
+
+it('includes raw response context in decoding exception', function (): void {
+    FixtureResponse::fakeResponseSequence('v1/chat/completions', 'openrouter/structured-empty-content');
+
+    $schema = new ObjectSchema(
+        'output',
+        'the output object',
+        [
+            new StringSchema('data', 'Some data'),
+        ],
+        ['data']
+    );
+
+    try {
+        Prism::structured()
+            ->withSchema($schema)
+            ->using(Provider::OpenRouter, 'anthropic/claude-3.5-sonnet')
+            ->withPrompt('Give me some data')
+            ->asStructured();
+
+        $this->fail('Expected PrismStructuredDecodingException to be thrown');
+    } catch (PrismStructuredDecodingException $e) {
+        expect($e->getMessage())
+            ->toContain('Structured object could not be decoded')
+            ->toContain('Model: anthropic/claude-3.5-sonnet')
+            ->toContain('Finish reason: stop')
+            ->toContain('Raw choices:')
+            ->toContain('"content": null');
+    }
+});