// TODO: generated - needs revision

## `Script` Class

### Overview

The Script class serves as a flexible and dynamic container for managing, hydrating, and rendering sets of message sequences before they are translated to the native format of any supported LLM API.


### Key Concepts

 - Script: The main container holding one or more Sections.
 - Section: Contain sets of OpenAI-style messages exchanged between the user and the AI assistant.
 - Message: Represent individual message entries with a role (user or assistant) and content (which can be a string or an object).


### Features

 - Flexibility: Adapt and manage conversation structures for different LLM API providers.
 - Dynamic Reordering: Rearrange sections dynamically as needed.
 - Template Functionality: Use Script as a template for complex, multi-turn prompts with dynamic parameters.
 - Multimodal Support: Include objects like images in chat entries for processing using LLM's multimodal capabilities.


### Basic Usage

#### Creating a Script

```php
<?php
use Cognesy\Instructor\Data\Messages\Script;
use Cognesy\Instructor\Data\Messages\Section;

// Create sections
$section1 = new Section('introduction');
$section2 = new Section('qna');

// Initialize Script with sections
$script = new Script($section1, $section2);
```

#### Accessing and Manipulating Sections

```php
<?php
// Check if a section exists
$hasIntroduction = $script->hasSection('introduction');

// Retrieve a section by name
$introSection = $script->section('introduction');

// Get all section names
$sectionNames = $script->sectionNames();
```

#### Converting to Messages

```php
<?php
use Cognesy\Instructor\Data\Messages\Messages;

// Convert Script to Messages
$messages = $script->toMessages();
```


### Advanced Usage

#### Dynamic Parameters Injection

```php
<?php
use Cognesy\Instructor\Data\Messages\ScriptParameters;

// Create and set parameters
$parameters = new ScriptParameters(['userName' => 'John Doe']);
$script->withParameters($parameters);

// Set individual parameter
$script->setParameter('userRole', 'admin');

// Unset a parameter
$script->unsetParameter('userRole');
```


#### Using Templates within Sections

```php
<?php
// Create a section with template content
$templateSection = new Section('template_section');
$templateSection->appendMessages(Messages::fromString('Hello, {{userName}}!'));

// Add section to Script and set parameters
$script->appendSection($templateSection);
$script->setParameter('userName', 'John Doe');

// Convert Script to Messages with template rendered
$messages = $script->toMessages();
?>
```

### Customization

#### Creating Script from an Array

```php
<?php
use Cognesy\Instructor\Data\Messages\Script;

$sectionsArray = [
    'introduction' => 'Welcome to the session.',
    'qna' => ['What is your name?', 'My name is AI.']
];

// Create Script from array
$scriptFromArray = (new Script)->fromArray($sectionsArray);
```

#### Merging and Overriding Scripts

```php
<?php
// Merge another Script into the current one
$script->mergeScript($anotherScript);

// Override the current Script with another one
$script->overrideScript($anotherScript);
```

#### Reordering Sections

```php
<?php
// Reorder sections
$orderedScript = $script->reorder(['qna', 'introduction']);

// Reverse the order of sections
$reversedScript = $script->reverse();
```

### Internal Mechanics

The Script class uses several internal traits to handle various aspects of its functionality:

 - HandlesAccess: Methods for accessing and querying sections.
 - HandlesParameters: Methods for managing parameters.
 - HandlesConversion: Methods for converting Script to various formats.
 - HandlesCreation: Methods for creating Script instances from arrays or other Scripts.
 - HandlesMutation: Methods for mutating sections and parameters.
 - HandlesReordering: Methods for reordering and reversing sections.
 - HandlesTransformation: Methods for transforming Scripts into different structures.

#### Example: Complex Conversation Template

```php
<?php
use Cognesy\Instructor\Data\Messages\Script;use Cognesy\Instructor\Data\Messages\ScriptParameters;use Cognesy\Instructor\Data\Messages\Section;use Cognesy\Instructor\Extras\LLM\Enums\LLMProviderType;

// Define sections
$intro = (new Section('introduction'))
    ->appendMessages(Messages::fromString('Hello, welcome to our service.'));
$qna = (new Section('qna'))
    ->appendMessages(Messages::fromString('What is your name?'))
    ->appendMessages(Messages::fromString('My name is <|userName|>.'));

// Create Script
$script = new Script($intro, $qna);

// Set dynamic parameters
$parameters = new ScriptParameters(['userName' => 'Alice']);
$script->withParams($parameters);

```
