Response Models¶

Response models define the structure of data you want to extract from text. They are PHP classes with typed properties that guide the LLM in generating structured output.

Creating Response Models¶

Using Artisan Command¶

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

# Collection response model
php artisan make:response-model ProductList --collection

# Nested objects response model
php artisan make:response-model CompanyProfile --nested

# With description
php artisan make:response-model Invoice --description="Invoice extracted from PDF"

Manual Creation¶

Create a class in app/ResponseModels/:

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

Property Types¶

Basic Types¶

final class BasicTypes
{
    public function __construct(
        public readonly string $text,
        public readonly int $count,
        public readonly float $price,
        public readonly bool $isActive,
    ) {}
}

Nullable Properties¶

final class WithOptional
{
    public function __construct(
        public readonly string $required,
        public readonly ?string $optional = null,
        public readonly ?int $maybeNumber = null,
    ) {}
}

Arrays¶

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¶

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¶

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¶

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¶

Property descriptions in docblocks guide the LLM:

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 simple cases, you can use an array schema instead of a class:

$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¶

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

// Wrap in array for multiple items
$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¶

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¶

use Cognesy\Instructor\Validation\Contracts\CanValidateObject;

class AgeValidator implements CanValidateObject
{
    public function validate(object $object): array
    {
        $errors = [];

        if ($object->age < 0) {
            $errors[] = 'Age cannot be negative';
        }

        return $errors;
    }
}

// Use the validator
$user = StructuredOutput::with(
    messages: 'User: John, age -5',
    responseModel: UserData::class,
)
->withValidators(AgeValidator::class)
->get();

Best Practices¶

1. Use Descriptive Property Names¶

// Good
public readonly string $customerEmailAddress;

// Less clear
public readonly string $email;

2. Add Detailed Descriptions¶

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

3. Use Appropriate Types¶

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

// Required
public readonly string $name,

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

5. Use Readonly Properties¶

// Immutable - recommended
public readonly string $name;

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

Generated Stubs¶

The make:response-model command generates these stub types:

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