sequences.md

Sequences

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.

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).

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.

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