Riddler - AI-Powered Riddle Generation System

Riddler is an advanced AI system that generates interactive riddles with video and voice capabilities, perfect for educational content and social media.

🚀 Quick Start

Prerequisites

• Python 3.8+
• FFmpeg 4.2+
• API keys for OpenAI, ElevenLabs, and Pexels

Installation

# Clone repository
git clone <repository-url>
cd riddler

# Set up environment
./setup.sh

# Add your API keys to .env file

Basic Usage

# Generate 2 medium difficulty geography riddles
python main.py -c geography -d medium -n 2 -o output

📚 Documentation

For complete documentation, see the docs directory.

Key documentation files:

• Getting Started
• Configuration
• Features
• Troubleshooting
• Development Guidelines

🔑 Features

• AI-powered riddle generation across multiple categories
• Text-to-speech voice synthesis
• Dynamic video generation with text overlays
• Smart caching system
• TikTok-optimized video output

📋 Categories

• geography
• math
• physics
• history
• logic
• wordplay
• biker mechanic

🛠️ Configuration

Configuration is managed through config/config.json. See configuration documentation for details.

📝 License

This work is licensed under a Creative Commons Attribution-NonCommercial 4.0 International License. Copyright (c) 2025 Riddler.