Skip to main content

​
Extracting Sequences of Objects

Sequence is a wrapper class that can be used to represent a list of objects to be extracted by Instructor from provided context. It is usually more convenient not create a dedicated class with a single array property just to handle a list of objects of a given class. 
<?php
class Person
{
    public string $name;
    public int $age;
}

$text = <<<TEXT
    Jason is 25 years old. Jane is 18 yo. John is 30 years old
    and Anna is 2 years younger than him.
TEXT;

$list = (new StructuredOutput)
    ->withResponseClass(Sequence::of(Person::class))
    ->with(
        messages: [['role' => 'user', 'content' => $text]],
    )->get();
// @doctest id="80c1"

​
Streaming Sequences

Additional, unique feature of sequences is that they can be streamed per each completed item in a sequence, rather than on any property update.
NOTE This feature requires the stream option to be set to true.
To receive sequence updates provide a callback via Instructor’s onSequenceUpdate() that will be called each time a new item is received from LLM. The callback provided a full sequence that has been retrieved so far. You can get the last added object from the sequence via $sequence->last(). Remember that while the sequence is being updated, the data is not validated - only when the sequence is fully extracted, the objects are validated and a full sequence is returned (see example below). 
<?php
class Person
{
    public string $name;
    public int $age;
}

function updateUI(Person $person) {
    // add newly extracted person to the UI list
    $this->ui->appendToList($person);
    // remember those objects are not validated yet
}

$text = <<<TEXT
    Jason is 25 years old. Jane is 18 yo. John is 30 years old
    and Anna is 2 years younger than him.
TEXT;

$list = (new StructuredOutput)
    ->onSequenceUpdate(
        fn($sequence) => updateUI($sequence->last()) // get last added object
    )
    ->withResponseClass(Sequence::of(Person::class))
    ->with(
        messages: [['role' => 'user', 'content' => $text]],
        options: ['stream' => true]
    )
    ->get();

// now the list is fully extracted and validated
foreach ($list as $person) {
    // do something with each person
    $this->db->save($person);
}
// @doctest id="be83"

​
Working with Sequences

Sequences offer array access (via ArrayAccess) and convenience methods to work with the list of extracted objects. 
<?php
$sequence->count();   // returns the number of extracted items
$sequence->first();   // returns the first extracted item
$sequence->last();    // returns the last extracted item
$sequence->get(1);    // returns the second extracted item
$sequence->toArray(); // returns the list of extracted items as an array
// @doctest id="e136"

​
Streaming sequence updates

See: Streaming and partial updates for more information on how to get partial updates and streaming of sequences.