# Replay and conversation continuity

`boru/ai` includes a replay subsystem for rebuilding normalized conversation context from persisted turns.

For the full configuration shape, see `configuration.md`. For chat-oriented usage patterns, see `chat.md`.

## What replay means

Replay is a policy-level feature that tells a provider whether it should automatically use prior conversation context when resuming a conversation.

Different providers may implement that continuity differently:

- Gemini currently uses runtime-owned replayed messages for `generateContent`.
- OpenAI currently uses provider-native `previous_response_id` continuity for resumed conversations when replay is enabled.

So the policy is shared, while the implementation may differ by provider.

## Replay settings

Replay settings currently support:

- `replay.enabled`
- `replay.strategy`
- `replay.max_turns`
- `replay.summary.keep_turns`
- `replay.summary.max_chars`
- `replay.tool_data.enabled`
- `replay.tool_data.max_chars`
- `replay.tool_data.args_max_chars`
- `replay.tool_data.output_max_chars`

## Current strategies

- `full`
- `last_n_turns`
- `summarize_history`

## Example config

```php
$config->runtime(array(
    'replay' => array(
        'enabled' => false,
        'strategy' => 'full',
        'max_turns' => 10,
        'summary' => array(
            'keep_turns' => 3,
            'max_chars' => 4000,
        ),
        'tool_data' => array(
            'enabled' => false,
            'max_chars' => 2000,
            'args_max_chars' => 600,
            'output_max_chars' => 1000,
        ),
    ),
));

$config->provider('gemini', array(
    'replay' => array(
        'enabled' => true,
        'strategy' => 'summarize_history',
        'summary' => array(
            'keep_turns' => 2,
            'max_chars' => 1200,
        ),
        'tool_data' => array(
            'enabled' => true,
            'max_chars' => 1200,
            'args_max_chars' => 300,
            'output_max_chars' => 500,
        ),
    ),
));
```

## Using a conversation reference

To continue a conversation, reuse the same conversation reference:

```php
$ai = AI::provider('gemini')
    ->reference('customer_support_demo')
    ->addMessage('Summarize our prior discussion.')
    ->run();
```

If persistence and replay are enabled, the runtime/provider can rebuild or continue prior context from the stored conversation.

For persistence setup details, see `persistence.md`.

## Example: last N turns replay

See:

- `examples/replay_last_n_turns.php`

This demonstrates provider selection, replay strategy configuration, and resumed conversation behavior using `last_n_turns`.

## Example: summarize history replay

See:

- `examples/replay_summarize_history.php`

This demonstrates history compaction using `summarize_history` with the nested `replay.summary` config shape.

## Public replay helpers

The replay subsystem is centralized in `ConversationReplayService`, and runtime exposes helper access for building replay messages and requests.

This is intended to support future use cases such as:

- chat widgets
- transcript reconstruction
- replay strategies with bounded windows
- summarization/compaction strategies
- replaying tool activity with bounded budgets

## Design note

Replay policy is shared at the library level, but provider-specific continuity behavior is allowed where necessary.

That keeps the library provider-agnostic at the API level without pretending every provider resumes conversations in the exact same way.

## See also

- `configuration.md`
- `chat.md`
- `persistence.md`
- `architecture.md`
