> ## Documentation Index
> Fetch the complete documentation index at: https://docs.instructorphp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Partials

Streaming lets you receive partial updates as the LLM generates its response, rather than waiting for the complete result. This is useful for improving perceived latency in user interfaces -- you can render data progressively as it arrives.

## Basic Streaming

Call `stream()` instead of `get()` to receive a `StructuredOutputStream`. The `partials()` method yields parsed partial objects as the response is built.

```php theme={null}
use Cognesy\Instructor\StructuredOutput;

$stream = (new StructuredOutput)
    ->with(messages: $text, responseModel: Person::class)
    ->stream();

foreach ($stream->partials() as $partial) {
    // $partial is a Person object with fields populated so far
    updateUI($partial);
}
// @doctest id="4e2a"
```

Instructor is smart about updates. It calculates and compares hashes of the previous and newly deserialized version of the model, so your callback only fires when a property actually changes -- not on every token received.

Partial updates are deserialized but **not validated**. Only the final result returned by `finalValue()` is fully validated, making it safe to persist or process further.

## Explicit Streaming Control

You can also enable streaming with `withStreaming()` and then call `get()`, which internally drains the stream and returns the final value.

```php theme={null}
$person = (new StructuredOutput)
    ->withResponseClass(Person::class)
    ->withStreaming()
    ->with(messages: $text)
    ->get();
// @doctest id="b49f"
```

## StructuredOutputStream Methods

The `StructuredOutputStream` class provides several ways to consume the stream.

### Iteration Methods

| Method        | Description                                                                                               |
| ------------- | --------------------------------------------------------------------------------------------------------- |
| `partials()`  | Yields parsed partial values. Only the final update is validated; earlier partials are only deserialized. |
| `sequence()`  | For `Sequence` response models -- yields only completed items. See [Sequences](sequences).                |
| `responses()` | Yields `StructuredOutputResponse` snapshots as they arrive.                                               |

### Result Access Methods

| Method            | Description                                                         |
| ----------------- | ------------------------------------------------------------------- |
| `finalValue()`    | Drains the stream and returns the final parsed, validated result.   |
| `finalResponse()` | Drains the stream and returns the final `StructuredOutputResponse`. |
| `lastUpdate()`    | Returns the most recently received parsed value.                    |
| `lastResponse()`  | Returns the most recently received `StructuredOutputResponse`.      |

### Utility Methods

| Method    | Description                                          |
| --------- | ---------------------------------------------------- |
| `usage()` | Returns the latest token usage data from the stream. |

## Example: Streaming with Final Retrieval

A common pattern is to stream partials for UI updates, then use the final validated value for persistence.

```php theme={null}
$stream = (new StructuredOutput)->with(
    messages: "His name is Jason, he is 28 years old.",
    responseModel: Person::class,
)->stream();

foreach ($stream->partials() as $update) {
    $view->updateView($update);
}

// Final validated object
$person = $stream->finalValue();
$db->savePerson($person);
// @doctest id="20d8"
```

## Example: Streaming Sequence Items

When using a `Sequence` response model, you can stream completed items individually rather than waiting for the entire list.

```php theme={null}
use Cognesy\Instructor\Extras\Sequence\Sequence;

$stream = (new StructuredOutput)
    ->with(
        messages: "Jason is 28. Amanda is 26. John is 40.",
        responseModel: Sequence::of(Person::class),
    )
    ->stream();

foreach ($stream->sequence() as $person) {
    $view->appendPerson($person);
}

$people = $stream->finalValue();
$db->savePeople($people->toArray());
// @doctest id="d5cd"
```

## Streaming with Output Formats

Streaming works with all output formats. During streaming, partials are always objects regardless of your chosen output format. The final value respects the format you specified. See [Output Formats](output_formats) for details.