Add free version using Groq AI and Pollinations.AI

.gitignore

@@ -3,7 +3,20 @@ secrets.py
 __pycache__/
 *.pyc
 popcorn_output/
+popcorn_output_simple/
+popcorn_output_free/
 sequence_*/
 .DS_Store
 .vscode/
 .idea/
+
+# Virtual environment
+venv/
+env/
+ENV/
+.venv/
+
+# Generated images
+*.png
+*.jpg
+*.jpeg

CONTRIBUTING.md

@@ -0,0 +1,61 @@
+# Contributing to Open Higgsfield Popcorn
+
+Thanks for your interest in contributing!
+
+## How to Contribute
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/your-feature`)
+3. Make your changes
+4. Test your changes
+5. Commit with clear messages (`git commit -m "Add: feature description"`)
+6. Push to your fork (`git push origin feature/your-feature`)
+7. Open a Pull Request
+
+## Development Setup
+
+```bash
+# Clone your fork
+git clone https://github.com/YOUR_USERNAME/Open-Higgsfield-Popcorn.git
+cd Open-Higgsfield-Popcorn
+
+# Create virtual environment
+python -m venv venv
+source venv/bin/activate  # Windows: venv\Scripts\activate
+
+# Install dependencies
+pip install pydantic aiohttp python-dotenv
+
+# Add API keys to secrets.py
+# Get free Groq key: https://console.groq.com/keys
+```
+
+## Testing Your Changes
+
+```bash
+# Test the free version
+python popcorn_free.py --prompt "test scene" --frames 3
+
+# Test the paid version (if you have MuAPI key)
+python popcorn_storyboard.py --prompt "test scene" --frames 3
+```
+
+## Code Guidelines
+
+- Follow existing code style
+- Add comments for complex logic
+- Keep functions focused and readable
+- Test before submitting
+
+## Ideas for Contributions
+
+- Add support for more free AI providers
+- Improve shot planning algorithms
+- Add video compilation from frames
+- Create web UI
+- Improve documentation
+- Add more examples
+
+## Questions?
+
+Open an issue for discussion!

README.md

@@ -22,34 +22,48 @@ An open-source alternative to **Higgsfield Popcorn**, designed to generate consi
 ## Installation
 
 1.  Clone this repository.
-2.  Install dependencies:
+2.  Create virtual environment (recommended):
     ```bash
-    pip install requests python-dotenv pydantic aiohttp
+    python -m venv venv
+    source venv/bin/activate  # On Windows: venv\Scripts\activate
     ```
-3.  Configure your API keys:
-    *   Rename `secrets.py` or edit it directly.
-    *   Add your **MuAPI** key (`MUAPIAPP_API_KEY`). You can get one from [muapi.ai](https://muapi.ai).
+3.  Install dependencies:
+    ```bash
+    pip install pydantic aiohttp python-dotenv
+    ```
+4.  Configure API keys in `secrets.py`:
+    *   **Option A (FREE)**: Add `GROQ_API_KEY` from [console.groq.com](https://console.groq.com/keys)
+    *   **Option B (Paid)**: Add `MUAPIAPP_API_KEY` from [muapi.ai](https://muapi.ai)
 
 ## Usage
 
-### Auto Mode
-Generate a sequence from a single prompt. The AI will plan the shots for you.
+### FREE Version (Groq + Pollinations.AI)
+
+Generate storyboards using free APIs:
 
 ```bash
-python popcorn_storyboard.py --prompt "A cyberpunk hacker breaking into a secure server room" --frames 6 --style "cyberpunk neon"
-```
+# Auto mode - AI plans the shots
+python popcorn_free.py --prompt "A cyberpunk hacker breaking into a secure server room" --frames 6 --style "cyberpunk neon"
 
-### Manual Mode
-Define exactly what happens in each frame.
+# Manual mode - you control each shot
+python popcorn_free.py --manual_shots "wide shot of a spooky house" "close up of a hand opening the door" --style "horror"
 
-```bash
-python popcorn_storyboard.py --manual_shots "wide shot of a spooky house" "close up of a hand opening the door" "interior view of a dusty hallway" --style "horror"
+# With reference images
+python popcorn_free.py --prompt "A knight fighting a dragon" --references https://example.com/knight.png --frames 4
 ```
 
-### Using References
-Upload reference images (e.g., your main character or a specific location) to guide the AI.
+### Paid Version (MuAPI)
+
+For higher quality and faster generation:
 
 ```bash
+# Auto mode
+python popcorn_storyboard.py --prompt "A cyberpunk hacker breaking into a secure server room" --frames 6 --style "cyberpunk neon"
+
+# Manual mode
+python popcorn_storyboard.py --manual_shots "wide shot of a spooky house" "close up of a hand opening the door" --style "horror"
+
+# With references
 python popcorn_storyboard.py --prompt "A knight fighting a dragon" --references https://example.com/knight.png https://example.com/dragon.png
 ```
 
@@ -62,6 +76,19 @@ python popcorn_storyboard.py --prompt "A knight fighting a dragon" --references
 *   `--references`: URLs or paths to reference images (Up to 4 recommended).
 *   `--output`: Directory to save the results.
 
+## Version Comparison
+
+| Feature | FREE (Groq + Pollinations) | Paid (MuAPI) |
+|---------|---------------------------|--------------|
+| Cost | FREE | $10+ |
+| AI Planning | ✅ Advanced (Groq Llama 3.3) | ✅ Advanced (GPT-5-mini) |
+| Image Generation | ✅ Good (Pollinations) | ✅ Excellent (nano-banana) |
+| Reference Images | ✅ Supported | ✅ Supported |
+| Vision Analysis | ⚠️ Text-based | ✅ Full vision |
+| Character Consistency | Good | Excellent |
+| Speed | ~60s/frame | ~3s/frame |
+| Setup | Get free Groq key | Requires payment |
+
 ## License
 
 This project is open-source and available under the MIT License.