OpenAI Structured Output (#68)

Author: sixlive

Diff for: composer.json

@@ -37,7 +37,8 @@
     "projektgopher/whisky": "^0.7.0",
     "orchestra/testbench": "^9.4",
     "mockery/mockery": "^1.6",
-    "symplify/rule-doc-generator-contracts": "^11.2"
+    "symplify/rule-doc-generator-contracts": "^11.2",
+    "phpstan/phpdoc-parser": "^1.24"
   },
   "autoload-dev": {
     "psr-4": {

Diff for: docs/.vitepress/config.mts

@@ -94,6 +94,10 @@ export default defineConfig({
                 text: "Text Generation",
                 link: "/core-concepts/text-generation",
               },
+              {
+                text: "Structured Output",
+                link: "/core-concepts/structured-output",
+              },
               {
                 text: "Tool & Function Calling",
                 link: "/core-concepts/tools-function-calling",

Diff for: docs/core-concepts/structured-output.md

@@ -0,0 +1,185 @@
+# Structured Output
+
+Want your AI responses as neat and tidy as a Marie Kondo-approved closet? Structured output lets you define exactly how you want your data formatted, making it perfect for building APIs, processing forms, or any time you need data in a specific shape.
+
+## Quick Start
+
+Here's how to get structured data from your AI:
+
+```php
+use EchoLabs\Prism\Enums\Provider;
+use EchoLabs\Prism\Facades\Prism;
+use EchoLabs\Prism\Schema\ObjectSchema;
+use EchoLabs\Prism\Schema\StringSchema;
+
+$schema = new ObjectSchema(
+    name: 'movie_review',
+    description: 'A structured movie review',
+    properties: [
+        new StringSchema('title', 'The movie title'),
+        new StringSchema('rating', 'Rating out of 5 stars'),
+        new StringSchema('summary', 'Brief review summary')
+    ],
+    requiredFields: ['title', 'rating', 'summary']
+);
+
+$response = Prism::structured()
+    ->using(Provider::OpenAI, 'gpt-4o')
+    ->withSchema($schema)
+    ->withPrompt('Review the movie Inception')
+    ->generate();
+
+// Access your structured data
+$review = $response->object;
+echo $review['title'];    // "Inception"
+echo $review['rating'];   // "5 stars"
+echo $review['summary'];  // "A mind-bending..."
+```
+
+## Understanding Output Modes
+
+Different AI providers handle structured output in two main ways:
+
+1. **Structured Mode**: Some providers support strict schema validation, ensuring responses perfectly match your defined structure.
+2. **JSON Mode**: Other providers simply guarantee valid JSON output that approximately matches your schema.
+
+> [!NOTE]
+> Check your provider's documentation to understand which mode they support. Provider support can vary by model, so always verify capabilities for your specific use case.
+
+## Available Schema Types
+
+Build your schemas using these fundamental types:
+
+```php
+use EchoLabs\Prism\Schema\{
+    StringSchema,
+    NumberSchema,
+    BooleanSchema,
+    ArraySchema,
+    ObjectSchema,
+    EnumSchema
+};
+
+// String
+new StringSchema('name', 'description');
+
+// Number
+new NumberSchema('age', 'description');
+
+// Boolean
+new BooleanSchema('is_active', 'description');
+
+// Array
+new ArraySchema('tags', 'description', new StringSchema('tag', 'A single tag'));
+
+// Enum
+new EnumSchema('status', 'description', ['draft', 'published', 'archived']);
+
+// Object (nested structures)
+new ObjectSchema(
+    name: 'user',
+    description: 'User profile',
+    properties: [
+        new StringSchema('name', 'Full name'),
+        new NumberSchema('age', 'User age'),
+        new ArraySchema(
+            name: 'hobbies',
+            description: 'List of hobbies',
+            items: new StringSchema('hobby', 'A hobby name')
+        )
+    ],
+    requiredFields: ['name']
+);
+```
+
+## Provider-Specific Options
+
+Providers may offer additional options for structured output. For example, OpenAI supports a "strict mode" for even tighter schema validation:
+
+```php
+use EchoLabs\Prism\Enums\Provider;
+
+$response = Prism::structured()
+    ->withProviderMeta(Provider::OpenAI, [
+        'schema' => [
+            'strict' => true
+        ]
+    ])
+    // ... rest of your configuration
+```
+
+> [!TIP]
+> Check the provider-specific documentation pages for additional options and features that might be available for structured output.
+
+## Response Handling
+
+When working with structured responses, you have access to both the structured data and metadata about the generation:
+
+```php
+$response = Prism::structured()
+    ->withSchema($schema)
+    ->generate();
+
+// Access the structured data as a PHP array
+$data = $response->object;
+
+// Get the raw response text if needed
+echo $response->text;
+
+// Check why the generation stopped
+echo $response->finishReason->name;
+
+// Get token usage statistics
+echo "Prompt tokens: {$response->usage->promptTokens}";
+echo "Completion tokens: {$response->usage->completionTokens}";
+
+// Access provider-specific response data
+$rawResponse = $response->response;
+```
+
+> [!TIP]
+> Always validate the structured data before using it in your application:
+```php
+if ($response->object === null) {
+    // Handle parsing failure
+}
+
+if (!isset($response->object['required_field'])) {
+    // Handle missing required data
+}
+```
+
+## Common Settings
+
+Structured output supports all the same options as text generation, including:
+- Temperature control
+- Maximum tokens
+- Message history
+- Tools and function calling
+- System prompts
+
+See the [Text Generation](./text-generation.md) documentation for details on these common settings.
+
+## Error Handling
+
+When working with structured output, it's especially important to handle potential errors:
+
+```php
+use EchoLabs\Prism\Exceptions\PrismException;
+
+try {
+    $response = Prism::structured()
+        ->using('anthropic', 'claude-3-sonnet')
+        ->withSchema($schema)
+        ->withPrompt('Generate product data')
+        ->generate();
+} catch (PrismException $e) {
+    // Handle validation or generation errors
+    Log::error('Structured generation failed:', [
+        'error' => $e->getMessage()
+    ]);
+}
+```
+
+> [!IMPORTANT]
+> Always validate the structured response before using it in your application, as different providers may have varying levels of schema adherence.

Diff for: docs/core-concepts/testing.md

@@ -12,8 +12,7 @@ use EchoLabs\Prism\ValueObjects\Usage;
 use EchoLabs\Prism\Enums\FinishReason;
 use EchoLabs\Prism\Providers\ProviderResponse;
 
-public function test_can_generate_text(): void
-{
+it('can generate text', function () {
     // Create a fake provider response
     $fakeResponse = new ProviderResponse(
         text: 'Hello, I am Claude!',
@@ -33,17 +32,16 @@ public function test_can_generate_text(): void
         ->generate();
 
     // Make assertions
-    $this->assertEquals('Hello, I am Claude!', $response->text);
-}
+    expect($response->text)->toBe('Hello, I am Claude!');
+});
 ```
 
 ## Testing Multiple Responses
 
 When testing conversations or tool usage, you might need to simulate multiple responses:
 
 ```php
-public function test_can_handle_tool_calls(): void
-{
+it('can handle tool calls', function () {
     $responses = [
         new ProviderResponse(
             text: '',
@@ -68,24 +66,6 @@ public function test_can_handle_tool_calls(): void
     ];
 
     $fake = Prism::fake($responses);
-}
-```
-
-## Assertions
-
-Prism's fake implementation provides several helpful assertion methods:
-
-```php
-// Assert specific prompt was sent
-$fake->assertPrompt('Who are you?');
-
-// Assert number of calls made
-$fake->assertCallCount(2);
-
-// Assert detailed request properties
-$fake->assertRequest(function ($requests) {
-    $this->assertEquals('anthropic', $requests[0]->provider);
-    $this->assertEquals('claude-3-sonnet', $requests[0]->model);
 });
 ```
 
@@ -94,8 +74,7 @@ $fake->assertRequest(function ($requests) {
 When testing tools, you'll want to verify both the tool calls and their results. Here's a complete example:
 
 ```php
-public function test_can_use_weather_tool(): void
-{
+it('can use weather tool', function () {
     // Define the expected tool call and response sequence
     $responses = [
         // First response: AI decides to use the weather tool
@@ -142,21 +121,82 @@ public function test_can_use_weather_tool(): void
     $fake->assertCallCount(2);
 
     // Assert tool calls were made correctly
-    $this->assertCount(1, $response->steps[0]->toolCalls);
-    $this->assertEquals('weather', $response->steps[0]->toolCalls[0]->name);
-    $this->assertEquals(['city' => 'Paris'], $response->steps[0]->toolCalls[0]->arguments());
+    expect($response->steps[0]->toolCalls)->toHaveCount(1);
+    expect($response->steps[0]->toolCalls[0]->name)->toBe('weather');
+    expect($response->steps[0]->toolCalls[0]->arguments())->toBe(['city' => 'Paris']);
 
     // Assert tool results were processed
-    $this->assertCount(1, $response->toolResults);
-    $this->assertEquals(
-        'The weather in Paris is sunny with a temperature of 72°F',
-        $response->toolResults[0]->result
-    );
+    expect($response->toolResults)->toHaveCount(1);
+    expect($response->toolResults[0]->result)
+        ->toBe('The weather in Paris is sunny with a temperature of 72°F');
 
     // Assert final response
-    $this->assertEquals(
-        'Based on current conditions, the weather in Paris is sunny with a temperature of 72°F.',
-        $response->text
+    expect($response->text)
+        ->toBe('Based on current conditions, the weather in Paris is sunny with a temperature of 72°F.');
+});
+```
+
+## Testing Structured Output
+
+```php
+use EchoLabs\Prism\Facades\Prism;
+use EchoLabs\Prism\ValueObjects\Usage;
+use EchoLabs\Prism\Enums\FinishReason;
+use EchoLabs\Prism\Providers\ProviderResponse;
+use EchoLabs\Prism\Schema\ObjectSchema;
+use EchoLabs\Prism\Schema\StringSchema;
+
+it('can generate structured response', function () {
+    $schema = new ObjectSchema(
+        name: 'user',
+        description: 'A user object, because we love organizing things!',
+        properties: [
+            new StringSchema('name', 'The user\'s name (hopefully not "test test")'),
+            new StringSchema('bio', 'A brief bio (no novels, please)'),
+        ],
+        requiredFields: ['name', 'bio']
+    );
+
+    $fakeResponse = new ProviderResponse(
+        text: json_encode([
+            'name' => 'Alice Tester',
+            'bio' => 'Professional bug hunter and code wrangler'
+        ]),
+        toolCalls: [],
+        usage: new Usage(10, 20),
+        finishReason: FinishReason::Stop,
+        response: ['id' => 'fake-1', 'model' => 'fake-model']
     );
-}
+
+    $fake = Prism::fake([$fakeResponse]);
+
+    $response = Prism::structured()
+        ->using('anthropic', 'claude-3-sonnet')
+        ->withPrompt('Generate a user profile')
+        ->withSchema($schema)
+        ->generate();
+
+    // Assertions
+    expect($response->object)->toBeArray();
+    expect($response->object['name'])->toBe('Alice Tester')
+    expect($response->object['bio'])->toBe('Professional bug hunter and code wrangler');
+});
+```
+
+## Assertions
+
+Prism's fake implementation provides several helpful assertion methods:
+
+```php
+// Assert specific prompt was sent
+$fake->assertPrompt('Who are you?');
+
+// Assert number of calls made
+$fake->assertCallCount(2);
+
+// Assert detailed request properties
+$fake->assertRequest(function ($requests) {
+    expect($requests[0]->provider)->toBe('anthropic');
+    expect($requests[0]->model)->toBe('claude-3-sonnet');
+});
 ```

Diff for: docs/providers/openai.md

@@ -24,6 +24,17 @@ Tool::as('search') // [!code focus]
     ]); // [!code focus]
 ```
 
+### Strict Structured Output Schemas
+
+```php
+$response = Prism::structured()
+    ->withProviderMeta(Provider::OpenAI, [ // [!code focus]
+        'schema' => [ // [!code focus]
+            'strict' => true // [!code focus]
+        ] // [!code focus]
+    ]) // [!code focus]
+```
+
 ## Limitations
 ### Tool Choice