contaigents

# 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!