Upload folder using huggingface_hub

.gitignore

@@ -0,0 +1,213 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be added to the global gitignore or merged into this project gitignore.  For a PyCharm
+#  project, it is recommended to ignore the entire .idea directory.
+.idea/
+
+# VS Code
+.vscode/
+
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Windows
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+
+# Linux
+*~
+
+# Temporary files
+*.tmp
+*.temp
+*.swp
+*.swo
+
+# Logs
+*.log
+
+# Database files
+*.db
+*.sqlite
+*.sqlite3
+
+# Model files (often large)
+*.pkl
+*.pickle
+*.joblib
+*.h5
+*.hdf5
+*.pt
+*.pth
+*.onnx
+
+# Data files
+data/
+datasets/
+*.csv
+*.json
+*.xml
+*.parquet
+
+# Output directories
+output/
+outputs/
+results/
+checkpoints/

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,12 +1,323 @@
 ---
-title: Dspy Example
-emoji: 👁
-colorFrom: yellow
-colorTo: red
+title: dspy-example
+app_file: gradio_interface.py
 sdk: gradio
 sdk_version: 5.38.2
-app_file: app.py
-pinned: false
 ---
+# 🎬 DSPy Director Bake-Off: A Beginner's Guide to DSPy Programming
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+Welcome to the **DSPy Director Bake-Off**! This project demonstrates core DSPy concepts through a fun, practical example: comparing how different movie directors would approach filming the same video idea.
+
+## 🎯 What You'll Learn
+
+This tutorial teaches you the fundamental concepts of **DSPy** (Declarative Self-improving Python) through hands-on examples:
+
+1. **Signatures** - Define input/output interfaces for LLM tasks
+2. **Modules** - Combine multiple signatures into complex workflows  
+3. **Structured Output** - Use Pydantic models for reliable data extraction
+4. **Async Processing** - Handle multiple LLM calls efficiently
+5. **Chain of Thought** - Enable reasoning for complex decisions
+
+## 🚀 Quick Start
+
+### Prerequisites
+
+- Python 3.8+
+- An OpenRouter API key (free tier available)
+
+### Installation
+
+1. **Clone or download this project**
+2. **Install dependencies:**
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+3. **Set up your API key:**
+   Create a `.env` file in the project directory:
+   ```
+   OPENROUTER_API_KEY=your_api_key_here
+   ```
+
+4. **Run the demo:**
+   ```bash
+   python director_bake_off.py
+   ```
+
+5. **Try the web interface:**
+   ```bash
+   python gradio_interface.py
+   ```
+   Then open http://localhost:7860 in your browser.
+
+## 🎭 How It Works
+
+The Director Bake-Off follows this workflow:
+
+1. **User Input**: You provide a video idea and list of directors
+2. **AI Suggestion**: DSPy suggests an additional director perfect for your idea
+3. **Parallel Generation**: Each director's unique interpretation is generated simultaneously
+4. **Intelligent Ranking**: An AI judge ranks all interpretations and explains the reasoning
+5. **Beautiful Results**: View the winner and detailed breakdowns
+
+## 📚 Understanding the Code Structure
+
+### 🏗️ Project Architecture
+
+```
+director_bake_off.py    # Main DSPy implementation (heavily commented)
+gradio_interface.py     # Beautiful web interface
+requirements.txt        # Python dependencies
+.env                   # Your API keys (create this)
+README.md              # This guide
+```
+
+### 🔍 Code Walkthrough
+
+The `director_bake_off.py` file is organized into clear sections:
+
+#### **Section 1: LLM Setup**
+```python
+def setup_dspy_provider():
+    # Configure DSPy with your chosen LLM provider
+    # Supports OpenAI, Anthropic, OpenRouter, and more
+```
+
+#### **Section 2: Data Structures**
+```python
+class DirectorCut(BaseModel):
+    # Pydantic model defining the structure of cinematic prompts
+    # Ensures consistent, validated output from the LLM
+```
+
+#### **Section 3: DSPy Signatures**
+```python
+class FindDirector(dspy.Signature):
+    # Defines what inputs the LLM expects and what outputs it should produce
+    # Think of these as "contracts" between your code and the LLM
+```
+
+#### **Section 4: DSPy Module**
+```python
+class DirectorBakeOff(dspy.Module):
+    # Combines multiple signatures into a complete workflow
+    # Orchestrates the entire director comparison process
+```
+
+#### **Section 5: Main Functions**
+```python
+def run_bake_off(video_idea, directors):
+    # Easy-to-use interface that handles everything
+    # This is what external code calls to use our system
+```
+
+## 🎓 DSPy Concepts Explained
+
+### What is DSPy?
+
+**DSPy** is a framework for programming with Large Language Models (LLMs). Instead of writing prompts as strings, you define structured interfaces that make your LLM applications more reliable, maintainable, and powerful.
+
+### 🔥 Key Concepts
+
+#### 1. **Signatures** - The Heart of DSPy
+
+Signatures define the interface between your code and the LLM:
+
+```python
+class GenerateDirectorCut(dspy.Signature):
+    """Transform a video idea into a cinematic prompt in a director's style."""
+    
+    # What goes IN to the LLM
+    video_idea = dspy.InputField(desc="A simple video concept")
+    director = dspy.InputField(desc="The director's name")
+    
+    # What comes OUT of the LLM  
+    director_cut: DirectorCut = dspy.OutputField(desc="Structured cinematic prompt")
+```
+
+**Why this is powerful:**
+- Clear contracts between code and LLM
+- Automatic prompt generation
+- Type safety and validation
+- Reusable across different models
+
+#### 2. **Structured Output with Pydantic**
+
+Instead of parsing messy text, get structured data:
+
+```python
+class DirectorCut(BaseModel):
+    director: str
+    subject_description: str
+    action_description: str
+    setting_description: str
+    # ... more fields
+    
+    def assemble_prompt(self) -> str:
+        # Combine all parts into a complete prompt
+        return ", ".join([self.subject_description, self.action_description, ...])
+```
+
+**Benefits:**
+- Guaranteed data format
+- Automatic validation
+- Easy to work with in code
+- No more regex parsing!
+
+#### 3. **Modules** - Complex Workflows
+
+Modules combine multiple signatures into sophisticated workflows:
+
+```python
+class DirectorBakeOff(dspy.Module):
+    def __init__(self):
+        self.findDirector = dspy.Predict(FindDirector)
+        self.genDirectorCut = dspy.Predict(GenerateDirectorCut)
+        self.directorJudge = dspy.ChainOfThought(DirectorJudge)
+    
+    async def aforward(self, video_idea, directors):
+        # Orchestrate multiple LLM calls
+        # 1. Find additional director
+        # 2. Generate interpretations (in parallel!)
+        # 3. Judge and rank results
+```
+
+#### 4. **Different Predictor Types**
+
+- **`dspy.Predict`**: Basic, fast predictions
+- **`dspy.ChainOfThought`**: Enables step-by-step reasoning
+- **`dspy.ReAct`**: Combines reasoning with actions
+- **`dspy.ProgramOfThought`**: For mathematical/logical problems
+
+#### 5. **Async Processing**
+
+Handle multiple LLM calls efficiently:
+
+```python
+# Instead of calling one by one (slow):
+for director in directors:
+    result = self.genDirectorCut(video_idea=idea, director=director)
+
+# Call them all at once (fast!):
+results = await asyncio.gather(
+    *[self.genDirectorCut.acall(video_idea=idea, director=d) for d in directors]
+)
+```
+
+## 🛠️ Building Your Own DSPy Applications
+
+### Step 1: Define Your Data Structure
+
+Start with a Pydantic model for your expected output:
+
+```python
+class MyOutput(BaseModel):
+    field1: str = Field(..., description="What this field should contain")
+    field2: int = Field(..., description="A number representing...")
+    # Add more fields as needed
+```
+
+### Step 2: Create Signatures
+
+Define the interface for each LLM task:
+
+```python
+class MyTask(dspy.Signature):
+    """Clear description of what this task should do."""
+    
+    # Inputs
+    user_input = dspy.InputField(desc="What the user provides")
+    
+    # Outputs  
+    result: MyOutput = dspy.OutputField(desc="The structured result")
+```
+
+### Step 3: Build a Module
+
+Combine signatures into a workflow:
+
+```python
+class MyModule(dspy.Module):
+    def __init__(self):
+        self.task = dspy.Predict(MyTask)
+    
+    def forward(self, user_input):
+        return self.task(user_input=user_input)
+```
+
+### Step 4: Configure and Run
+
+```python
+# Configure DSPy with your LLM
+dspy.configure(lm=dspy.LM("openrouter/model-name", api_key="your-key"))
+
+# Use your module
+module = MyModule()
+result = module.forward("user input here")
+print(result.result.field1)  # Access structured output
+```
+
+## 🎨 Customization Ideas
+
+Try modifying the Director Bake-Off to explore DSPy further:
+
+### 🎬 **Different Creative Domains**
+- **Music Producer Bake-Off**: Compare how different producers would approach a song
+- **Chef Bake-Off**: See how famous chefs would prepare the same dish
+- **Architect Bake-Off**: Compare building designs for the same space
+
+### 🔧 **Technical Enhancements**
+- **Add More Signatures**: Include budget estimation, casting suggestions
+- **Different Predictors**: Try `dspy.ReAct` for more complex reasoning
+- **Optimization**: Use DSPy's optimization features to improve performance
+- **Multiple Models**: Compare results from different LLMs
+
+### 🎯 **New Applications**
+- **Content Planning**: Generate social media strategies
+- **Product Design**: Compare design approaches for products
+- **Educational Content**: Create lesson plans in different teaching styles
+
+## 🔗 Useful Resources
+
+### DSPy Documentation
+- [Official DSPy Documentation](https://dspy-docs.vercel.app/)
+- [DSPy GitHub Repository](https://github.com/stanfordnlp/dspy)
+- [DSPy Paper](https://arxiv.org/abs/2310.03714)
+
+### LLM Providers
+- [OpenRouter](https://openrouter.ai/) - Access to many models through one API
+- [OpenAI](https://platform.openai.com/) - GPT models
+- [Anthropic](https://www.anthropic.com/) - Claude models
+
+### Learning More
+- [Pydantic Documentation](https://docs.pydantic.dev/) - For data validation
+- [Gradio Documentation](https://gradio.app/docs/) - For building web interfaces
+- [Python Asyncio](https://docs.python.org/3/library/asyncio.html) - For async programming
+
+## 🤝 Contributing
+
+Found this helpful? Here are ways to contribute:
+
+1. **Try it out** and share your results
+2. **Create variations** for different domains
+3. **Improve the documentation** with your learnings
+4. **Share examples** of your own DSPy applications
+
+## 📝 License
+
+This project is open source and available under the MIT License.
+
+## 🎉 What's Next?
+
+After mastering this example, you'll be ready to:
+
+- Build production DSPy applications
+- Optimize prompts automatically with DSPy's built-in tools
+- Create complex multi-step reasoning systems
+- Integrate DSPy into larger applications
+
+**Happy coding with DSPy!** 🚀
+
+---
+
+*This tutorial was created to make DSPy accessible to beginners. The heavily commented code and step-by-step explanations should help you understand not just how to use DSPy, but why it's such a powerful framework for LLM programming.*

director_bake_off.py

@@ -0,0 +1,506 @@
+#!/usr/bin/env python3
+"""
+DSPy Director Bake-Off: A Beginner's Guide to DSPy Programming
+
+This script demonstrates core DSPy concepts through a fun example:
+comparing how different movie directors would approach filming the same video idea.
+
+Key DSPy Concepts Demonstrated:
+1. Signatures - Define input/output interfaces for LLM tasks
+2. Modules - Combine multiple signatures into complex workflows
+3. Structured Output - Use Pydantic models for reliable data extraction
+4. Async Processing - Handle multiple LLM calls efficiently
+5. Chain of Thought - Enable reasoning for complex decisions
+
+Author: DSPy Learning Example
+"""
+
+# Standard library imports
+import os
+import sys
+import asyncio
+from typing import List
+
+# Third-party imports
+import dspy                    # The main DSPy framework for LLM programming
+from dotenv import load_dotenv # For loading environment variables from .env file
+from pydantic import BaseModel, Field  # For structured data validation
+
+# Load environment variables from .env file (contains API keys)
+load_dotenv()
+
+# Global variable to store our configured language model
+# This will be set up once and reused throughout the application
+lm = None
+
+
+# ==========================================================================
+# SECTION 1: LLM SETUP AND CONFIGURATION
+# ==========================================================================
+
+def setup_dspy_provider():
+    """
+    Configure DSPy with an available LLM provider.
+    
+    DSPy supports many providers (OpenAI, Anthropic, OpenRouter, etc.)
+    This function tries to connect to OpenRouter, which provides access
+    to many different models through a single API.
+    
+    Returns:
+        str: The name of the provider that was successfully configured
+    """
+    global lm  # We'll modify the global lm variable
+
+    # Check if we have an OpenRouter API key in our environment variables
+    if os.getenv('OPENROUTER_API_KEY'):
+        print("✅ Configuring DSPy with OpenRouter...")
+        
+        # Create a DSPy Language Model object
+        # Format: "provider/model_name"
+        # Here we use a free model from Moonshot AI via OpenRouter
+        lm = dspy.LM(
+            model="openrouter/moonshotai/kimi-k2:free", 
+            api_key=os.getenv('OPENROUTER_API_KEY')
+        )
+        
+        # Configure DSPy to use this language model globally
+        dspy.configure(lm=lm)
+        return "openrouter"
+    else:
+        print("❌ No OpenRouter API key found in environment variables.")
+        print("Please add OPENROUTER_API_KEY to your .env file")
+        sys.exit(1)
+
+
+# ==========================================================================
+# SECTION 2: DATA STRUCTURES (PYDANTIC MODELS)
+# ==========================================================================
+
+class DirectorCut(BaseModel):
+    """
+    🎬 PYDANTIC MODEL: Structured Data for Cinematic Prompts
+    
+    This is a Pydantic model that defines the structure of our data.
+    Pydantic ensures that the LLM returns data in exactly the format we expect.
+    
+    Think of this as a "template" that the LLM must fill out completely.
+    Each field has a description that helps the LLM understand what to generate.
+    
+    Why use Pydantic with DSPy?
+    - Guarantees consistent output format
+    - Automatic validation of LLM responses
+    - Type safety for your Python code
+    - Clear documentation of expected data structure
+    """
+    
+    # Basic information (echoed from input)
+    director: str = Field(
+        ..., 
+        description="The director sent as part of input, echoed in the output."
+    )
+    video_idea: str = Field(
+        ..., 
+        description="The video idea sent as part of input, echoed in the output."
+    )
+    
+    # The seven components of a cinematic prompt
+    # Each field uses Field(...) where ... means "required"
+    subject_description: str = Field(
+        ..., 
+        description="A detailed description of the main subject or character."
+    )
+    action_description: str = Field(
+        ..., 
+        description="A description of the specific action the subject is performing."
+    )
+    setting_description: str = Field(
+        ..., 
+        description="A rich description of the environment, location, and time of day."
+    )
+    cinematic_style: str = Field(
+        ..., 
+        description="The overall visual style or medium (e.g., 'Photorealistic, 8K')."
+    )
+    shot_and_framing: str = Field(
+        ..., 
+        description="The specific camera shot type and framing (e.g., 'Medium shot')."
+    )
+    camera_movement: str = Field(
+        ..., 
+        description="The movement of the camera during the shot (e.g., 'Slow dolly shot')."
+    )
+    lighting_and_color: str = Field(
+        ..., 
+        description="The lighting style and color palette that sets the mood."
+    )
+
+    def assemble_prompt(self) -> str:
+        """
+        Combines all cinematic components into a single, formatted prompt.
+        
+        This method takes all the individual pieces and creates a complete
+        prompt that could be used with video generation AI models.
+        
+        Returns:
+            str: A complete, formatted cinematic prompt
+        """
+        # Collect all the cinematic components (excluding director and video_idea)
+        components = [
+            self.subject_description,
+            self.action_description,
+            self.setting_description,
+            self.cinematic_style,
+            self.shot_and_framing,
+            self.camera_movement,
+            self.lighting_and_color,
+        ]
+        
+        # Join components with commas, filtering out empty strings
+        prompt_string = ", ".join(filter(None, [c.strip() for c in components if c]))
+        
+        # Return empty string if no components
+        if not prompt_string:
+            return ""
+            
+        # Capitalize first letter and add period
+        return prompt_string[0].upper() + prompt_string[1:] + "."
+
+    def pretty_print(self):
+        """
+        Displays the director's interpretation in a nice format.
+        
+        This is a helper method to make the output more readable
+        when we're testing or debugging our code.
+        """
+        print(f"--- Director {self.director} ---")
+        print(f"{self.assemble_prompt()}")
+        print("--------------------------------")
+
+
+class ResultClass:
+    """
+    📦 SIMPLE DATA CONTAINER: Holds All Results
+    
+    This is a simple class to package up all our results.
+    We could use a Pydantic model here too, but since this is just
+    for internal use (not LLM output), a simple class works fine.
+    """
+    def __init__(self, additional_director, director_ideas, director_ranks):
+        self.additional_director = additional_director  # The AI-suggested director
+        self.director_ideas = director_ideas            # List of all DirectorCut objects
+        self.director_ranks = director_ranks            # Ranking results from the judge
+
+
+# ==========================================================================
+# SECTION 3: DSPY SIGNATURES (THE HEART OF DSPY)
+# ==========================================================================
+
+"""
+🔥 WHAT ARE DSPY SIGNATURES?
+
+DSPy Signatures are like "function signatures" but for LLM tasks.
+They define:
+1. What inputs the LLM should expect
+2. What outputs the LLM should produce
+3. The task description (in the docstring)
+
+Think of them as contracts between your code and the LLM.
+The LLM will try to fulfill this contract every time.
+
+Key Components:
+- InputField: Data going INTO the LLM
+- OutputField: Data coming OUT of the LLM
+- Docstring: Instructions for the LLM about what to do
+"""
+
+class FindDirector(dspy.Signature):
+    """
+    🎯 SIGNATURE 1: Find Additional Director
+    
+    This signature asks the LLM to suggest one additional director
+    who would be perfect for the given video idea, but isn't already
+    in the user's list.
+    
+    This demonstrates how DSPy can handle creative, open-ended tasks
+    where there's no single "correct" answer.
+    """
+    
+    # === INPUTS ===
+    video_idea = dspy.InputField(
+        desc="A simple, high-level user idea or concept for a video."
+    )
+    director_list: List[str] = dspy.InputField(
+        desc="The names of directors the user wants to use."
+    )
+
+    # === OUTPUTS ===
+    additonal_director: str = dspy.OutputField(
+        desc="The best possible director based on the wanted video idea, that is not already in the provided director list."
+    )
+
+
+class GenerateDirectorCut(dspy.Signature):
+    """
+    🎬 SIGNATURE 2: Generate Cinematic Interpretation
+    
+    This is the core signature that transforms a simple video idea
+    into a detailed cinematic prompt in the style of a specific director.
+    
+    Notice how the output is a Pydantic model (DirectorCut).
+    DSPy will automatically ensure the LLM returns data in exactly
+    that structure, with all required fields filled out.
+    
+    This demonstrates DSPy's structured output capabilities.
+    """
+    
+    # === INPUTS ===
+    video_idea = dspy.InputField(
+        desc="A simple, high-level user idea or concept for a video."
+    )
+    director = dspy.InputField(
+        desc="The name of the director to generate a cinematic prompt for (optional).",
+        default=None,
+        optional=True
+    )
+
+    # === OUTPUTS ===
+    director_cut: DirectorCut = dspy.OutputField(
+        desc="A structured object containing all seven deconstructed cinematic aspects."
+    )
+
+
+class DirectorJudge(dspy.Signature):
+    """
+    ⚖️ SIGNATURE 3: Judge and Rank Director Ideas
+    
+    This signature handles the complex task of comparing multiple
+    creative interpretations and ranking them objectively.
+    
+    Notice this takes a List[DirectorCut] as input and returns
+    both rankings AND an explanation. This shows how DSPy can
+    handle complex, multi-part outputs.
+    
+    This demonstrates DSPy's ability to handle reasoning tasks.
+    """
+    
+    # === INPUTS ===
+    director_ideas: List[DirectorCut] = dspy.InputField(
+        desc="A list of director interpretations to be ranked"
+    )
+    
+    # === OUTPUTS ===
+    director_rankings: List[int] = dspy.OutputField(
+        description="Rank between 1, 2, 3 ... N where 1 is best"
+    )
+    explanation: str = dspy.OutputField(
+        description="Explain why the ranking was given and the winner selected. Format your response with clear sections for each director using HTML formatting: use <h4> tags for director names with their rank, <p> tags for paragraphs, and <br> tags for line breaks. Make it well-structured and easy to read."
+    )
+
+
+# ==========================================================================
+# SECTION 4: DSPY MODULE (COMBINING SIGNATURES INTO WORKFLOWS)
+# ==========================================================================
+
+class DirectorBakeOff(dspy.Module):
+    """
+    🏗️ DSPY MODULE: The Complete Workflow
+    
+    A DSPy Module combines multiple Signatures into a complete workflow.
+    Think of it like a class that orchestrates several LLM calls to solve
+    a complex problem.
+    
+    This module demonstrates:
+    1. How to combine multiple signatures
+    2. Different types of DSPy predictors (Predict vs ChainOfThought)
+    3. Async processing for efficiency
+    4. Complex workflow orchestration
+    
+    The workflow:
+    1. Find an additional director suggestion
+    2. Generate cinematic interpretations for all directors (in parallel)
+    3. Judge and rank all interpretations
+    4. Return the best result with explanations
+    """
+    
+    def __init__(self):
+        """
+        Initialize the module with three different DSPy predictors.
+        
+        Notice the different types:
+        - dspy.Predict: Basic prediction (fast, direct)
+        - dspy.ChainOfThought: Reasoning-enabled prediction (slower, more thoughtful)
+        """
+        # Basic predictor for finding additional director
+        self.findDirector = dspy.Predict(FindDirector)
+        
+        # Basic predictor for generating director cuts
+        self.genDirectorCut = dspy.Predict(GenerateDirectorCut)
+        
+        # Chain-of-thought predictor for complex ranking decisions
+        # This will make the LLM "think step by step" before ranking
+        self.directorJudge = dspy.ChainOfThought(DirectorJudge)
+
+    async def aforward(self, video_idea: str, directors: List[str] = ["Quentin Tarantino", "Alfred Hitchcock", "Richard Curtis"]):
+        """
+        🚀 ASYNC FORWARD: The Main Workflow
+        
+        This is where the magic happens! This method orchestrates the entire
+        director bake-off process using multiple LLM calls.
+        
+        Key DSPy concepts demonstrated:
+        1. Sequential LLM calls (find director first)
+        2. Parallel LLM calls (generate all director cuts simultaneously)
+        3. Complex data flow between signatures
+        4. Async processing for efficiency
+        
+        Args:
+            video_idea: The user's video concept
+            directors: List of director names to compare
+            
+        Returns:
+            ResultClass: Complete results including rankings and explanations
+        """
+        
+        # === STEP 1: Display user input ===
+        print("\n🎬 User Wanted Directors:")
+        for director in directors:
+            print(f"   - {director}")
+
+        # === STEP 2: Find additional director suggestion ===
+        print("\n🤖 Finding AI-suggested director...")
+        additional_director_result = self.findDirector(
+            video_idea=video_idea, 
+            director_list=directors
+        )
+        additional_director = additional_director_result.additonal_director
+        print(f"   ✨ DSPy Suggested Director: {additional_director}")
+
+        # === STEP 3: Generate director interpretations (IN PARALLEL!) ===
+        print("\n⚡ Generating director interpretations in parallel...")
+        
+        # Combine user directors + AI suggestion
+        all_directors = directors + [additional_director]
+        
+        # Use asyncio.gather to run multiple LLM calls simultaneously
+        # This is much faster than calling them one by one!
+        director_ideas = await asyncio.gather(
+            *[self.genDirectorCut.acall(video_idea=video_idea, director=director) 
+              for director in all_directors]
+        )
+        
+        # Display all generated ideas
+        print("\n🎭 Generated Director Ideas:")
+        for idea in director_ideas:
+            idea.director_cut.pretty_print()
+
+        # === STEP 4: Judge and rank all interpretations ===
+        print("\n⚖️ Judging and ranking director ideas...")
+        
+        # Extract just the DirectorCut objects for judging
+        director_cuts = [idea.director_cut for idea in director_ideas]
+        
+        # Use Chain-of-Thought for complex ranking decision
+        director_ranks = self.directorJudge(director_ideas=director_cuts)
+
+        # === STEP 5: Display rankings ===
+        print("\n🏆 Director Rankings:")
+        for rank, idea in zip(director_ranks.director_rankings, director_ideas):
+            print(f"   Rank {rank}: {idea.director_cut.director}")
+
+        # === STEP 6: Find and display the winner ===
+        best_rank = min(director_ranks.director_rankings)
+        best_index = director_ranks.director_rankings.index(best_rank)
+        best_idea = director_ideas[best_index]
+        
+        print("\n🥇 WINNER - Best Ranked Director Idea:")
+        best_idea.director_cut.pretty_print()
+        
+        print(f"\n💭 Judge's Reasoning:")
+        print(f"   {director_ranks.explanation}")
+        print("=" * 50)
+
+        # === STEP 7: Return complete results ===
+        return ResultClass(
+            additional_director=additional_director,
+            director_ideas=director_ideas,
+            director_ranks=director_ranks
+        )
+
+
+# ==========================================================================
+# SECTION 5: MAIN FUNCTIONS AND ENTRY POINT
+# ==========================================================================
+
+def run_bake_off(video_idea: str, directors: str = None) -> ResultClass:
+    """
+    🎯 MAIN FUNCTION: Easy-to-use interface for the Director Bake-Off
+    
+    This function provides a simple interface that handles:
+    1. LLM setup and configuration
+    2. Input validation and parsing
+    3. Running the complete workflow
+    4. Error handling
+    
+    This is the function that external code (like our Gradio interface)
+    calls to use our DSPy system.
+    
+    Args:
+        video_idea: A description of the video concept
+        directors: Comma-separated string of director names (optional)
+        
+    Returns:
+        ResultClass: Complete results from the bake-off
+    """
+    
+    print("🚀 Running Director Bake-Off...")
+    
+    # === STEP 1: Ensure LLM is configured ===
+    global lm
+    if not lm:
+        provider = setup_dspy_provider()
+        print(f"   ✅ DSPy configured with {provider} provider.")
+    
+    # === STEP 2: Parse and validate director input ===
+    if not (isinstance(directors, str) and directors.strip()):
+        # Use default directors if none provided
+        directors = ["Quentin Tarantino", "Alfred Hitchcock", "Richard Curtis"]
+        print("   📝 Using default directors")
+    else:
+        # Parse comma-separated string into list
+        directors = [d.strip() for d in directors.split(",") if d.strip()]
+        if not directors:
+            # Fallback to defaults if parsing failed
+            directors = ["Quentin Tarantino", "Alfred Hitchcock", "Richard Curtis"]
+            print("   📝 Parsing failed, using default directors")
+
+    # === STEP 3: Create and run the bake-off ===
+    bake_off = DirectorBakeOff()
+    result_class = asyncio.run(bake_off.aforward(video_idea=video_idea, directors=directors))
+    
+    return result_class
+
+
+# ==========================================================================
+# SECTION 6: SCRIPT ENTRY POINT
+# ==========================================================================
+
+if __name__ == "__main__":
+    """
+    🎬 DEMO: Run the script directly to see it in action!
+    
+    This section only runs when you execute this file directly
+    (not when it's imported as a module).
+    
+    Try running: python director_bake_off.py
+    """
+    print("🎭 DSPy Director Bake-Off Demo")
+    print("=" * 40)
+    
+    # Run with a sample video idea
+    sample_idea = "A futuristic cityscape with flying cars and neon lights."
+    print(f"📝 Sample Video Idea: {sample_idea}")
+    
+    result = run_bake_off(sample_idea)
+    
+    print("\n🎉 Demo completed! Check the output above to see how each director")
+    print("   would approach filming this futuristic cityscape.")

gradio_interface.py

@@ -0,0 +1,421 @@
+#!/usr/bin/env python3
+
+import gradio as gr
+import asyncio
+from director_bake_off import run_bake_off
+import traceback
+
+# Swedish-inspired color palette and styling
+SWEDISH_CSS = """
+/* Swedish Minimalist Design */
+:root {
+    --primary-white: #FFFFFF;
+    --soft-gray: #F5F5F5;
+    --muted-blue: #4A90A4;
+    --warm-beige: #E8DCC6;
+    --charcoal: #2C2C2C;
+    --light-blue: #E8F4F8;
+    --accent-gold: #D4AF37;
+    --success-green: #7FB069;
+    --border-gray: #E0E0E0;
+}
+
+/* Global styling */
+.gradio-container {
+    font-family: 'Inter', 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif !important;
+    background: linear-gradient(135deg, var(--soft-gray) 0%, var(--primary-white) 100%) !important;
+    min-height: 100vh;
+}
+
+/* Header styling */
+.main-header {
+    text-align: center;
+    padding: 2rem 0;
+    background: var(--primary-white);
+    border-bottom: 1px solid var(--border-gray);
+    margin-bottom: 2rem;
+}
+
+.main-title {
+    font-size: 2.5rem;
+    font-weight: 300;
+    color: var(--charcoal);
+    margin-bottom: 0.5rem;
+    letter-spacing: -0.02em;
+}
+
+.main-subtitle {
+    font-size: 1.1rem;
+    color: var(--muted-blue);
+    font-weight: 400;
+    margin-bottom: 0;
+}
+
+/* Input section styling */
+.input-section {
+    background: var(--primary-white);
+    border-radius: 12px;
+    padding: 2rem;
+    box-shadow: 0 2px 20px rgba(0,0,0,0.05);
+    border: 1px solid var(--border-gray);
+    margin-bottom: 2rem;
+}
+
+.input-label {
+    font-size: 1rem;
+    font-weight: 500;
+    color: var(--charcoal);
+    margin-bottom: 0.5rem;
+    display: block;
+}
+
+/* Button styling */
+.submit-btn {
+    background: linear-gradient(135deg, var(--muted-blue) 0%, #5BA0B5 100%) !important;
+    border: none !important;
+    border-radius: 8px !important;
+    padding: 12px 32px !important;
+    font-weight: 500 !important;
+    font-size: 1rem !important;
+    color: white !important;
+    transition: all 0.3s ease !important;
+    box-shadow: 0 4px 15px rgba(74, 144, 164, 0.3) !important;
+}
+
+.submit-btn:hover {
+    transform: translateY(-2px) !important;
+    box-shadow: 0 6px 25px rgba(74, 144, 164, 0.4) !important;
+}
+
+/* Results section */
+.results-container {
+    background: var(--primary-white);
+    border-radius: 12px;
+    padding: 2rem;
+    box-shadow: 0 2px 20px rgba(0,0,0,0.05);
+    border: 1px solid var(--border-gray);
+    margin-top: 2rem;
+}
+
+.director-card {
+    background: var(--light-blue);
+    border-radius: 10px;
+    padding: 1.5rem;
+    margin-bottom: 1.5rem;
+    border-left: 4px solid var(--muted-blue);
+    transition: all 0.3s ease;
+}
+
+.director-card:hover {
+    transform: translateY(-2px);
+    box-shadow: 0 8px 25px rgba(0,0,0,0.1);
+}
+
+.rank-badge {
+    display: inline-block;
+    background: var(--accent-gold);
+    color: white;
+    padding: 4px 12px;
+    border-radius: 20px;
+    font-size: 0.85rem;
+    font-weight: 600;
+    margin-bottom: 0.5rem;
+}
+
+.rank-1 { background: var(--accent-gold); }
+.rank-2 { background: #C0C0C0; }
+.rank-3 { background: #CD7F32; }
+
+.director-name {
+    font-size: 1.3rem;
+    font-weight: 600;
+    color: var(--charcoal);
+    margin-bottom: 1rem;
+}
+
+.prompt-text {
+    font-size: 1rem;
+    line-height: 1.6;
+    color: var(--charcoal);
+    background: var(--primary-white);
+    padding: 1rem;
+    border-radius: 8px;
+    border: 1px solid var(--border-gray);
+    margin-bottom: 1rem;
+}
+
+.additional-director {
+    background: var(--warm-beige);
+    border-radius: 10px;
+    padding: 1.5rem;
+    margin-bottom: 2rem;
+    border-left: 4px solid var(--success-green);
+}
+
+.explanation-section {
+    background: var(--soft-gray);
+    border-radius: 10px;
+    padding: 1.5rem;
+    margin-top: 2rem;
+    border-left: 4px solid var(--muted-blue);
+}
+
+.section-title {
+    font-size: 1.2rem;
+    font-weight: 600;
+    color: var(--charcoal);
+    margin-bottom: 1rem;
+}
+
+/* Loading animation */
+.loading {
+    text-align: center;
+    padding: 2rem;
+    color: var(--muted-blue);
+}
+
+/* Responsive design */
+@media (max-width: 768px) {
+    .main-title {
+        font-size: 2rem;
+    }
+    
+    .input-section, .results-container {
+        padding: 1.5rem;
+        margin: 1rem;
+    }
+    
+    .director-card {
+        padding: 1rem;
+    }
+}
+
+/* Custom textbox styling */
+.gr-textbox {
+    border-radius: 8px !important;
+    border: 1px solid var(--border-gray) !important;
+}
+
+.gr-textbox:focus {
+    border-color: var(--muted-blue) !important;
+    box-shadow: 0 0 0 3px rgba(74, 144, 164, 0.1) !important;
+}
+"""
+
+def format_results_html(result):
+    """Format the results into beautiful HTML with Swedish design."""
+    if not result:
+        return "<div class='loading'>No results to display.</div>"
+    
+    try:
+        # Header with additional director suggestion
+        html = f"""
+        <div class="results-container">
+            <div class="additional-director">
+                <div class="section-title">🎬 AI Suggested Director</div>
+                <div style="font-size: 1.1rem; color: var(--charcoal);">
+                    <strong>{result.additional_director}</strong> - A perfect match for your vision!
+                </div>
+            </div>
+        """
+        
+        # Director ideas with rankings
+        html += '<div class="section-title">🏆 Director Interpretations (Ranked)</div>'
+        
+        # Sort director ideas by ranking
+        ranked_ideas = []
+        for i, idea in enumerate(result.director_ideas):
+            rank = result.director_ranks.director_rankings[i]
+            ranked_ideas.append((rank, idea.director_cut))
+        
+        ranked_ideas.sort(key=lambda x: x[0])  # Sort by rank (1 is best)
+        
+        for rank, director_cut in ranked_ideas:
+            rank_class = f"rank-{min(rank, 3)}"  # Use rank-1, rank-2, rank-3 classes
+            
+            html += f"""
+            <div class="director-card">
+                <div class="rank-badge {rank_class}">#{rank}</div>
+                <div class="director-name">{director_cut.director}</div>
+                <div class="prompt-text">{director_cut.assemble_prompt()}</div>
+                
+                <details style="margin-top: 1rem;">
+                    <summary style="cursor: pointer; font-weight: 500; color: var(--muted-blue);">
+                        View Detailed Breakdown
+                    </summary>
+                    <div style="margin-top: 1rem; padding: 1rem; background: var(--soft-gray); border-radius: 6px;">
+                        <div style="margin-bottom: 0.8rem;"><strong>Subject:</strong> {director_cut.subject_description}</div>
+                        <div style="margin-bottom: 0.8rem;"><strong>Action:</strong> {director_cut.action_description}</div>
+                        <div style="margin-bottom: 0.8rem;"><strong>Setting:</strong> {director_cut.setting_description}</div>
+                        <div style="margin-bottom: 0.8rem;"><strong>Style:</strong> {director_cut.cinematic_style}</div>
+                        <div style="margin-bottom: 0.8rem;"><strong>Shot & Framing:</strong> {director_cut.shot_and_framing}</div>
+                        <div style="margin-bottom: 0.8rem;"><strong>Camera Movement:</strong> {director_cut.camera_movement}</div>
+                        <div style="margin-bottom: 0.8rem;"><strong>Lighting & Color:</strong> {director_cut.lighting_and_color}</div>
+                    </div>
+                </details>
+            </div>
+            """
+        
+        # Explanation section with HTML formatting from DSPy
+        html += f"""
+            <div class="explanation-section">
+                <div class="section-title">🤔 Judge's Reasoning</div>
+                <div style="line-height: 1.8; color: var(--charcoal); font-size: 1rem;">
+                    {result.director_ranks.explanation}
+                </div>
+            </div>
+        </div>
+        """
+        
+        return html
+        
+    except Exception as e:
+        return f"""
+        <div class="results-container">
+            <div style="color: #e74c3c; padding: 1rem; background: #fdf2f2; border-radius: 8px;">
+                <strong>Error formatting results:</strong> {str(e)}
+            </div>
+        </div>
+        """
+
+def run_director_bakeoff(video_idea, directors):
+    """Run the director bake-off and return formatted results."""
+    if not video_idea or not video_idea.strip():
+        return "<div class='loading'>Please enter a video idea to get started!</div>"
+    
+    try:
+        # Initial loading message with expectations
+        yield """
+        <div class='loading' style='background: var(--light-blue); padding: 2rem; border-radius: 12px; border-left: 4px solid var(--muted-blue);'>
+            <div style='font-size: 1.3rem; font-weight: 600; color: var(--charcoal); margin-bottom: 1rem;'>
+                🎬 Director Bake-Off in Progress...
+            </div>
+            <div style='font-size: 1rem; color: var(--muted-blue); margin-bottom: 1.5rem; line-height: 1.6;'>
+                Please be patient, this may take some minutes...<br>
+                We're consulting with legendary directors to bring your vision to life!<br>
+                <strong>This process typically takes 30-60 seconds.</strong><br>
+                ✨
+            </div>
+            <div style='background: var(--primary-white); padding: 1rem; border-radius: 8px; border-left: 3px solid var(--accent-gold);'>
+                <div style='font-size: 0.9rem; color: var(--charcoal);'>
+                    <strong>What's happening:</strong><br>
+                    • Finding the perfect additional director for your concept<br>
+                    • Generating unique interpretations from each director<br>
+                    • Ranking all concepts to find the best match<br>
+                </div>
+            </div>
+        </div>
+        """
+        
+        # Run the bake-off
+        result = run_bake_off(video_idea, directors)
+        
+        # Format and return results
+        formatted_html = format_results_html(result)
+        yield formatted_html
+        
+    except Exception as e:
+        error_html = f"""
+        <div class="results-container">
+            <div style="color: #e74c3c; padding: 1.5rem; background: #fdf2f2; border-radius: 8px; border-left: 4px solid #e74c3c;">
+                <div style="font-weight: 600; margin-bottom: 0.5rem;">Something went wrong!</div>
+                <div style="margin-bottom: 1rem;">{str(e)}</div>
+                <details>
+                    <summary style="cursor: pointer; color: #c0392b;">View technical details</summary>
+                    <pre style="margin-top: 1rem; font-size: 0.85rem; background: #f8f8f8; padding: 1rem; border-radius: 4px; overflow-x: auto;">
+{traceback.format_exc()}
+                    </pre>
+                </details>
+            </div>
+        </div>
+        """
+        yield error_html
+
+# Create the Gradio interface
+def create_interface():
+    with gr.Blocks(css=SWEDISH_CSS, title="Director Bake-Off Studio") as interface:
+        # Header
+        gr.HTML("""
+        <div class="main-header">
+            <h1 class="main-title">Director Bake-Off Studio</h1>
+            <p class="main-subtitle">Let legendary directors compete to bring your vision to life</p>
+        </div>
+        """)
+        
+        # How it Works section - moved to top
+        gr.HTML("""
+        <div style="background: var(--light-blue); padding: 1.5rem; border-radius: 10px; margin-bottom: 2rem; border-left: 4px solid var(--muted-blue);">
+            <h3 style="margin-top: 0; color: var(--charcoal);">How it works:</h3>
+            <ol style="color: var(--charcoal); line-height: 1.6;">
+                <li>Enter your video idea in the text area below</li>
+                <li>List your favorite directors (or use our defaults)</li>
+                <li>Our AI will suggest an additional director perfect for your vision</li>
+                <li>Watch as each director creates their unique interpretation</li>
+                <li>See them ranked by how well they match your concept!</li>
+            </ol>
+        </div>
+        """)
+        
+        # Results section - will only show content when there are actual results
+        results_html = gr.HTML(
+            value="",
+            elem_classes=["results-display"],
+            visible=False
+        )
+        
+        with gr.Row():
+            with gr.Column(scale=1):
+                # Input section
+                
+                video_idea = gr.Textbox(
+                    label="🎥 Your Video Idea",
+                    placeholder="Describe your video concept... (e.g., 'A futuristic cityscape with flying cars and neon lights')",
+                    lines=4,
+                    elem_classes=["input-field"]
+                )
+                
+                directors = gr.Textbox(
+                    label="🎬 Directors (comma-separated)",
+                    placeholder="e.g., Quentin Tarantino, Alfred Hitchcock",
+                    value="Quentin Tarantino, Alfred Hitchcock",
+                    lines=2,
+                    elem_classes=["input-field"]
+                )
+                
+                submit_btn = gr.Button(
+                    "🚀 Start the Bake-Off!",
+                    elem_classes=["submit-btn"],
+                    variant="primary"
+                )
+                        
+        # Set up the interaction - removed show_progress=True to eliminate progress bar
+        def handle_submit(video_idea, directors):
+            # Make results visible and update content
+            for result in run_director_bakeoff(video_idea, directors):
+                yield gr.update(value=result, visible=True)
+        
+        submit_btn.click(
+            fn=handle_submit,
+            inputs=[video_idea, directors],
+            outputs=[results_html]
+        )
+        
+        # Footer
+        gr.HTML("""
+        <div style="text-align: center; padding: 2rem; color: var(--muted-blue); font-size: 0.9rem;">
+            <p>Powered by DSPy and the creative genius of legendary directors 🎬</p>
+        </div>
+        """)
+    
+    return interface
+
+if __name__ == "__main__":
+    # Create and launch the interface
+    interface = create_interface()
+    interface.launch(
+        server_name="0.0.0.0",
+        server_port=7860,
+        share=False,
+        show_error=True,
+        debug=True
+    )

requirements.txt

@@ -0,0 +1,4 @@
+pydantic
+python-dotenv
+dspy
+gradio