# Cinematic Workflow Enhancement

## Overview

The Contaigents CLI now includes an enhanced cinematic workflow that automatically handles:

1. **Automatic Image Generation** - Generates visual sketches for scene descriptions
2. **Version Control** - Backs up old versions before updates
3. **Rollback Capability** - Restores previous versions if generation fails
4. **Smart Detection** - Automatically detects cinematic script files

## Features

### 🎨 Automatic Image Generation

When you create or update cinematic script files, the system automatically:
- Extracts visual descriptions from `## Visual Sketch Description` sections
- Generates cinematic images for each visual element
- Saves images to an `images/` folder alongside your script
- Uses enhanced prompts optimized for cinematic rendering

### 📦 Version Control

- **Automatic Backups**: Old versions are saved to `old_versions/` folder with timestamps
- **Safe Updates**: Creates backup before any modification
- **Rollback Protection**: If image generation fails, the file is automatically restored

### 🔄 Rollback Capability

- **Automatic Rollback**: Failed updates are automatically reverted
- **Manual Rollback**: Use the `rollback_scene` operation to restore specific versions
- **Version History**: All previous versions are preserved with timestamps

## How It Works

### Automatic Detection

The system automatically detects cinematic scripts based on:

**File Path Patterns:**
- Files containing: `script`, `scene`, `film`, `movie`, `cinematic`, `screenplay`, `short_film`

**Content Patterns:**
- `## SCENE X:` headers
- `### Scene Description` sections
- `### Visual Sketch Description` sections
- Cinematic formatting like `**WIDE SHOT**`, `**CLOSE-UP**`, etc.

### Enhanced File Operations

When you use standard file operations (`write_file`) on detected script files, they automatically use the cinematic workflow:

```bash
# This will automatically trigger cinematic workflow
contaigents chat
> "Create a new scene file called 'my_script.md' with a space battle scene"
```

## Usage Examples

### 1. Creating a New Script

```bash
contaigents chat
> "Create a 3-scene short film script about time travel"
```

**What happens:**
1. Script file is created with proper formatting
2. Visual descriptions are extracted
3. Cinematic images are generated automatically
4. Images saved to `images/` folder

### 2. Updating an Existing Script

```bash
contaigents chat
> "Update the second scene in my_script.md to add more dramatic lighting"
```

**What happens:**
1. Current version backed up to `old_versions/`
2. Script is updated with new content
3. New images generated for updated visual descriptions
4. If generation fails, file is automatically rolled back

### 3. Manual Cinematic Operations

You can also use the cinematic workflow tool directly:

```bash
# Generate images for existing script
contaigents chat
> "Use cinematic_workflow tool to generate images for my_script.md"

# Rollback to previous version
contaigents chat
> "Use cinematic_workflow tool to rollback my_script.md to the previous version"
```

## File Structure

After using the cinematic workflow, your project structure will look like:

```
your_project/
├── my_script.md                    # Main script file
├── images/                         # Generated images
│   ├── scene_1_timestamp.png
│   ├── scene_2_timestamp.png
│   └── scene_3_timestamp.png
└── old_versions/                   # Version backups
    ├── my_script.md.2024-10-09T22-30-15-123Z
    └── my_script.md.2024-10-09T22-25-10-456Z
```

## Script Format for Best Results

To get the best automatic image generation, structure your scripts like this:

```markdown
# MY FILM TITLE
## A Short Film

**Logline:** Brief description of your story

---

## SCENE 1: SCENE TITLE

**Duration:** X minutes
**Location:** LOCATION NAME
**Time:** TIME PERIOD

### Scene Description
Narrative description of what happens in the scene...

### Visual Sketch Description
- **WIDE SHOT**: Description of wide establishing shot
- **MEDIUM SHOT**: Description of medium shot
- **CLOSE-UP**: Description of close-up shot
- **INSERT**: Description of insert shot
- **LIGHTING**: Description of lighting setup
- **SOUND**: Description of sound design

### Key Dialogue
CHARACTER: "Dialogue here"
CHARACTER 2: "Response here"

### Story Function
- Purpose of this scene in the story
- Character development notes
- Plot advancement notes

---

## SCENE 2: NEXT SCENE TITLE
[Same structure...]
```

## Configuration Options

### Image Generation Settings

- **Style Options**: `cinematic`, `concept_art`, `storyboard`, `photographic`
- **Default Resolution**: 1920x1080 (cinematic aspect ratio)
- **Auto-generation**: Enabled by default, can be disabled

### Version Control Settings

- **Backup Location**: `old_versions/` folder (relative to script file)
- **Timestamp Format**: ISO format with safe filename characters
- **Retention**: All versions are kept (no automatic cleanup)

## Troubleshooting

### Images Not Generated

1. **Check Visual Descriptions**: Ensure you have `## Visual Sketch Description` sections
2. **Check API Keys**: Verify your image generation provider is configured
3. **Check File Detection**: Ensure your file matches the detection patterns

### Rollback Issues

1. **Check Backup Folder**: Verify `old_versions/` folder exists and contains backups
2. **Check Permissions**: Ensure write permissions for backup operations
3. **Manual Restore**: You can manually copy files from `old_versions/` if needed

### Performance Considerations

- **Image Generation Time**: Each image takes 10-30 seconds to generate
- **File Size**: Generated images are typically 1-5MB each
- **API Limits**: Respect your image generation provider's rate limits

## Advanced Usage

### Custom Workflow Operations

```bash
# Create scene with custom settings
contaigents chat
> "Use cinematic_workflow with operation 'create_scene', scene_file_path 'epic_battle.md', auto_generate_images true, image_style 'concept_art'"

# Generate images only (no file changes)
contaigents chat
> "Use cinematic_workflow with operation 'generate_scene_images', scene_file_path 'my_script.md', image_style 'storyboard'"

# Rollback to specific version
contaigents chat
> "Use cinematic_workflow with operation 'rollback_scene', scene_file_path 'my_script.md', rollback_version '2024-10-09T22-25-10-456Z'"
```

## Integration with Other Tools

The cinematic workflow integrates seamlessly with:

- **Audio Generation**: Generate voiceovers for your scenes
- **Video Tools**: Use generated images as storyboard references
- **Text-to-Image**: Additional custom image generation
- **Memory System**: Store project context and preferences

## Best Practices

1. **Descriptive Visual Sections**: Write detailed visual descriptions for better image generation
2. **Consistent Formatting**: Use the recommended script format for reliable detection
3. **Regular Backups**: The system creates backups, but consider additional version control
4. **Review Generated Images**: Check generated images and regenerate if needed
5. **Organize Projects**: Keep related scripts in dedicated folders

## Future Enhancements

Planned features include:
- **Batch Processing**: Generate images for multiple scripts at once
- **Style Templates**: Predefined visual styles for different genres
- **Video Generation**: Automatic video creation from scripts and images
- **Collaboration**: Multi-user script editing with conflict resolution
- **Export Options**: Export to industry-standard screenplay formats

---

The cinematic workflow transforms your script writing experience from text-only to a rich, visual creative process. Start creating your cinematic stories today!