Structures¶

Structures allow dynamically define the shape of data to be extracted by LLM, e.g. during runtime.

Use Structure::define() to define the structure and pass it to Instructor as response model.

If Structure instance has been provided as a response model, Instructor returns an array in the shape you defined.

<?php
ini_set('display_errors', 1);
ini_set('display_startup_errors', 1);
error_reporting(E_ALL);

$loader = require 'vendor/autoload.php';
$loader->add('Cognesy\\Instructor\\', __DIR__ . '../../src/');

use Cognesy\Instructor\Extras\Structure\Field;
use Cognesy\Instructor\Extras\Structure\Structure;
use Cognesy\Instructor\Instructor;

enum Role : string {
    case Manager = 'manager';
    case Line = 'line';
}

$structure = Structure::define('person', [
    Field::string('name','Name of the person'),
    Field::int('age', 'Age of the person')->validIf(
        fn($value) => $value > 0, "Age has to be positive number"
    ),
    Field::structure('address', [
        Field::string('street', 'Street name')->optional(),
        Field::string('city', 'City name'),
        Field::string('zip', 'Zip code')->optional(),
    ], 'Address of the person'),
    Field::enum('role', Role::class, 'Role of the person'),
], 'A person object');

$text = <<<TEXT
    Jane Doe lives in Springfield, 50210. She is 25 years old and works as manager at McDonald's.
    McDonald's in Ney York is located at 456 Elm St, NYC, 12345.
    TEXT;

print("INPUT:\n$text\n\n");
$person = (new Instructor)->respond(
    messages: $text,
    responseModel: $structure,
);

print("OUTPUT:\n");
print("Name: " . $person->name . "\n");
print("Age: " . $person->age . "\n");
print("Address / city: " . $person->address->city . "\n");
print("Address / ZIP: " . $person->address->zip . "\n");
print("Role: " . $person->role->value . "\n");
?>