Response Models

Response models define the structure of data you want to extract from unstructured text. They are plain PHP classes with typed constructor properties that serve a dual purpose: they tell the LLM what data to produce (via the generated JSON Schema), and they provide a strongly typed container for the extracted result.

Creating Response Models

Using Artisan Command

The make:response-model command generates a ready-to-use response model class with the correct namespace, typed properties, and docblock descriptions.

# Basic response model
php artisan make:response-model PersonData

# Collection response model (model with an array of child items)
php artisan make:response-model ProductList --collection

# Nested objects response model (model with child object properties)
php artisan make:response-model CompanyProfile --nested

# With a custom description in the class docblock
php artisan make:response-model Invoice --description="Invoice extracted from PDF"
# @doctest id="a3aa"

Manual Creation

Create a class in app/ResponseModels/ (or any namespace you prefer):

<?php

namespace App\ResponseModels;

final class PersonData
{
    public function __construct(
        /** The person's full name */
        public readonly string $name,

        /** The person's age in years */
        public readonly int $age,

        /** The person's email address */
        public readonly ?string $email = null,
    ) {}
}
// @doctest id="9116"

The class requires no base class, interface, or attribute — any PHP class with typed constructor properties works. The package inspects the constructor signature and docblocks at runtime to build the JSON Schema that guides the LLM.

Property Types

Basic Types

PHP’s scalar types map directly to JSON Schema types. The LLM receives clear instructions about the expected data type for each field.

final class BasicTypes
{
    public function __construct(
        public readonly string $text,
        public readonly int $count,
        public readonly float $price,
        public readonly bool $isActive,
    ) {}
}
// @doctest id="d495"

Nullable Properties

Mark optional fields as nullable with a default of null. The LLM is allowed to omit these fields, and the resulting object will have null for any missing values.

final class WithOptional
{
    public function __construct(
        public readonly string $required,
        public readonly ?string $optional = null,
        public readonly ?int $maybeNumber = null,
    ) {}
}
// @doctest id="2fbf"

Arrays

Use @var docblocks to specify the element type for array properties. This information is included in the generated schema and helps the LLM produce correctly typed array elements.

final class WithArrays
{
    public function __construct(
        /** @var string[] List of tags */
        public readonly array $tags,

        /** @var int[] List of scores */
        public readonly array $scores,
    ) {}
}
// @doctest id="bfdf"

Enums

Backed enums map to their underlying scalar type in the schema. The LLM receives the list of allowed values, which significantly improves extraction accuracy for categorical fields.

enum Priority: string
{
    case Low = 'low';
    case Medium = 'medium';
    case High = 'high';
}

final class Task
{
    public function __construct(
        public readonly string $title,
        public readonly Priority $priority,
    ) {}
}
// @doctest id="e106"

Nested Objects

Use another response model class as a property type to create hierarchical structures. The package generates nested schemas automatically.

final class Address
{
    public function __construct(
        public readonly string $street,
        public readonly string $city,
        public readonly string $country,
    ) {}
}

final class Person
{
    public function __construct(
        public readonly string $name,
        public readonly Address $address,
    ) {}
}
// @doctest id="c659"

Collections

Combine nested objects with typed arrays for collections of structured items. The @var docblock on the array property tells the package which class each element should be deserialized into.

final class OrderItem
{
    public function __construct(
        public readonly string $product,
        public readonly int $quantity,
        public readonly float $price,
    ) {}
}

final class Order
{
    public function __construct(
        public readonly string $orderId,

        /** @var OrderItem[] */
        public readonly array $items,

        public readonly float $total,
    ) {}
}
// @doctest id="3bc4"

Property Descriptions

Docblock comments on constructor properties serve as field-level instructions for the LLM. Clear, specific descriptions dramatically improve extraction accuracy — they are included verbatim in the JSON Schema sent to the model.

final class ProductReview
{
    public function __construct(
        /** The overall sentiment: positive, negative, or neutral */
        public readonly string $sentiment,

        /** A score from 1-5 indicating review quality */
        public readonly int $rating,

        /** Key points mentioned in the review */
        public readonly array $highlights,

        /** Any concerns or complaints raised */
        public readonly ?array $concerns = null,
    ) {}
}
// @doctest id="ae36"

Using Response Models

Basic Extraction

use Cognesy\Instructor\Laravel\Facades\StructuredOutput;
use App\ResponseModels\PersonData;

$person = StructuredOutput::with(
    messages: 'John Smith is a 30-year-old developer at john@example.com',
    responseModel: PersonData::class,
)->get();

echo $person->name;  // "John Smith"
echo $person->age;   // 30
echo $person->email; // "john@example.com"
// @doctest id="5873"

With Array Schema

For quick prototyping or one-off extractions, you can pass a raw JSON Schema array instead of a class. The result is returned as an associative array rather than a typed object.

$person = StructuredOutput::with(
    messages: 'John is 30 years old',
    responseModel: [
        'type' => 'object',
        'properties' => [
            'name' => ['type' => 'string', 'description' => 'Person name'],
            'age' => ['type' => 'integer', 'description' => 'Person age'],
        ],
        'required' => ['name', 'age'],
    ],
)->get();

echo $person['name']; // "John"
echo $person['age'];  // 30
// @doctest id="bb9d"

Extracting Collections

To extract a list of objects from a single input, wrap the response model class in an array schema descriptor.

final class Product
{
    public function __construct(
        public readonly string $name,
        public readonly float $price,
    ) {}
}

$products = StructuredOutput::with(
    messages: 'Products: iPhone $999, MacBook $1299, AirPods $199',
    responseModel: [
        'type' => 'array',
        'items' => Product::class,
    ],
)->get();

foreach ($products as $product) {
    echo "{$product->name}: \${$product->price}\n";
}
// @doctest id="3343"

Validation

Using Symfony Validator

Add Symfony Validator constraint attributes to your properties for automatic validation. When the LLM’s response violates a constraint, the package sends the validation errors back to the model and retries (up to max_retries times).

use Symfony\Component\Validator\Constraints as Assert;

final class UserRegistration
{
    public function __construct(
        #[Assert\NotBlank]
        #[Assert\Length(min: 2, max: 100)]
        public readonly string $name,

        #[Assert\NotBlank]
        #[Assert\Email]
        public readonly string $email,

        #[Assert\Range(min: 18, max: 120)]
        public readonly int $age,
    ) {}
}
// @doctest id="38b2"

Custom Validation

Implement the CanValidateObject contract for business-rule validation that goes beyond simple type and format checks. The validate method must return a ValidationResult instance.

use Cognesy\Instructor\Validation\Contracts\CanValidateObject;
use Cognesy\Instructor\Validation\ValidationResult;

class AgeValidator implements CanValidateObject
{
    public function validate(object $dataObject): ValidationResult
    {
        if ($dataObject->age < 0) {
            return ValidationResult::fieldError(
                field: 'age',
                value: $dataObject->age,
                message: 'Age cannot be negative',
            );
        }

        return ValidationResult::valid();
    }
}
// @doctest id="5e1a"

Custom validators are registered on the StructuredOutputRuntime, not on the facade directly:

use Cognesy\Instructor\StructuredOutputRuntime;
use Cognesy\Polyglot\Inference\LLMProvider;

$runtime = StructuredOutputRuntime::fromProvider(LLMProvider::new())
    ->withValidator(new AgeValidator());

$user = StructuredOutput::withRuntime($runtime)->with(
    messages: 'User: John, age -5',
    responseModel: UserData::class,
)->get();
// @doctest id="004e"

Best Practices

1. Use Descriptive Property Names

Property names are part of the schema the LLM sees. Clear names reduce ambiguity and improve extraction accuracy.

final class CustomerContactData
{
    // Good
    public readonly string $customerEmailAddress;

    // Less clear
    public readonly string $email;
}
// @doctest id="45ef"

2. Add Detailed Descriptions

Docblock descriptions are your primary tool for steering the LLM. Be specific about formats, ranges, and edge cases.

final class ProductData
{
    public function __construct(
        /**
         * The product SKU in format XXX-YYYY-ZZZ
         * Example: ABC-1234-XYZ
         */
        public readonly string $sku,
    ) {}
}
// @doctest id="7cad"

3. Use Appropriate Types

Choose the most specific type available. Enums are preferable to free-form strings for fields with a fixed set of values.

final class OrderLineData
{
    // Use int for counts
    public readonly int $quantity;

    // Use float for prices
    public readonly float $price;

    // Use enums for fixed options
    public readonly Status $status;
}
// @doctest id="dcbe"

4. Make Optional Properties Nullable

Distinguish between required and optional fields clearly. Required properties should not have defaults; optional ones should be nullable with a null default.

final class PersonData
{
    public function __construct(
        // Required
        public readonly string $name,
        // Optional
        public readonly ?string $nickname = null,
    ) {}
}
// @doctest id="7343"

5. Use Readonly Properties

Readonly properties enforce immutability, which prevents accidental mutation of extracted data. This is the recommended approach for all response models.

final class ImmutablePersonData
{
    // Immutable -- recommended
    public readonly string $name;
}

final class MutablePersonData
{
    // Mutable -- avoid unless necessary
    public string $name;
}
// @doctest id="d087"

Generated Stubs

The make:response-model command generates from these stub types. Publish them with php artisan vendor:publish --tag=instructor-stubs to customize.

Basic Stub

final class {{ class }}
{
    public function __construct(
        /** The name of the person */
        public readonly string $name,

        /** The age of the person in years */
        public readonly int $age,

        /** Optional email address */
        public readonly ?string $email = null,
    ) {}
}
// @doctest id="24e1"

Collection Stub (`--collection`)

final class {{ class }}
{
    public function __construct(
        /** List of extracted items */
        public readonly array $items,
    ) {}
}

final class {{ class }}Item
{
    public function __construct(
        public readonly string $name,
        public readonly ?string $description = null,
    ) {}
}
// @doctest id="54cc"

Nested Stub (`--nested`)

final class {{ class }}
{
    public function __construct(
        public readonly string $title,
        public readonly {{ class }}Contact $contact,
        public readonly ?{{ class }}Address $address = null,
    ) {}
}

final class {{ class }}Contact
{
    public function __construct(
        public readonly string $name,
        public readonly string $email,
    ) {}
}

final class {{ class }}Address
{
    public function __construct(
        public readonly string $street,
        public readonly string $city,
        public readonly string $country,
    ) {}
}
// @doctest id="c3ce"

​Response Models

​Creating Response Models

​Using Artisan Command

​Manual Creation

​Property Types

​Basic Types

​Nullable Properties

​Arrays

​Enums

​Nested Objects

​Collections

​Property Descriptions

​Using Response Models

​Basic Extraction

​With Array Schema

​Extracting Collections

​Validation

​Using Symfony Validator

​Custom Validation

​Best Practices

​1. Use Descriptive Property Names

​2. Add Detailed Descriptions

​3. Use Appropriate Types

​4. Make Optional Properties Nullable

​5. Use Readonly Properties

​Generated Stubs

​Basic Stub

​Collection Stub (--collection)

​Nested Stub (--nested)