## 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
<?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
<?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
<?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](partials.md) for more information on how to get partial updates and streaming of sequences.
