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"

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,
    ) {}
}

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,
    ) {}
}

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,
    ) {}
}

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,
    ) {}
}

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,
    ) {}
}

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,
    ) {}
}

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,
    ) {}
}

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,
    ) {}
}

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"

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

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";
}

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,
    ) {}
}

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();
    }
}

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();

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.

// Good
public readonly string $customerEmailAddress;

// Less clear
public readonly string $email;

2. Add Detailed Descriptions¶

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

public function __construct(
    /**
     * The product SKU in format XXX-YYYY-ZZZ
     * Example: ABC-1234-XYZ
     */
    public readonly string $sku,
) {}

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.

// 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;

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.

// Required
public readonly string $name,

// Optional
public readonly ?string $nickname = null,

5. Use Readonly Properties¶

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

// Immutable -- recommended
public readonly string $name;

// Mutable -- avoid unless necessary
public string $name;

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,
    ) {}
}

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,
    ) {}
}

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,
    ) {}
}