​
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 Instructor)->respond(

    messages: [['role' => 'user', 'content' => $text]],

    responseModel: Sequence::of(Person::class),

);

​
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 Instructor)->request(

    messages: [['role' => 'user', 'content' => $text]],

    responseModel: Sequence::of(Person::class),

    options: ['stream' => true]

)->onSequenceUpdate(

    fn($sequence) => updateUI($sequence->last()) // get last added object

)->get();



// now the list is fully extracted and validated

foreach ($list as $person) {

    // do something with each person

    $this->db->save($person);

}

​
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

​
Streaming sequence updates

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

PartialsStructures