A fully-featured web-based lateral thinking puzzle game (also known as "Turtle Soup" or "Situation Puzzles") built with Python Flask and powered by DeepSeek AI. Players solve mysterious scenarios by asking yes/no questions to an AI Game Master.

• 🎮 Single-player gameplay with bilingual support (English & Chinese)
• 🤖 AI Game Master powered by DeepSeek Chat
• 💡 Intelligent hint system
• 📊 Performance grading system (S, A, B, C, D)
• ⏱️ Real-time timer and statistics
• 🎨 Beautiful, responsive web interface

• 🎤 Voice Mode: Ask questions using speech-to-text (OpenAI Whisper)
• 🔊 Text-to-Speech: Hear the story read aloud (ElevenLabs)
• ✨ AI Scenario Generator: Create new puzzles on-demand
• 🌐 Bilingual Support: Complete English and Chinese localization
• 🖼️ AI Image Generation: Automatic scenario images (Silicon Flow)
• ⭐ User Ratings: Rate scenarios after playing

• Backend: Python 3.x with Flask
• Frontend: HTML5, CSS3, Vanilla JavaScript
• AI Models:
  • DeepSeek Chat (Game Master, Hints, Scenario Generation)
  • OpenAI Whisper (Speech-to-Text)
  • ElevenLabs (Text-to-Speech)
  • Silicon Flow (Image Generation)
• Database: SQLite
• Deployment: Single Python server

• Python 3.7 or higher
• API Keys:
  • DeepSeek API (required) - Get from DeepSeek Platform
  • OpenAI API (optional, for voice mode) - Get from OpenAI Platform
  • ElevenLabs API (optional, for TTS) - Get from ElevenLabs

cd turtle-soup-demo

# On macOS/Linux
python3 -m venv venv
source venv/bin/activate

# On Windows
python -m venv venv
venv\Scripts\activate

pip install -r requirements.txt

Create or edit the .env file:

# Required
DEEPSEEK_API_KEY=your-deepseek-api-key-here

# Optional (for voice features)
OPENAI_API_KEY=your-openai-api-key-here
ELEVENLABS_API_KEY=your-elevenlabs-api-key-here

# Optional
SECRET_KEY=your-secret-key-here
DEBUG=True

python app.py

The application will start on http://localhost:5001

Note: If port 5001 is already in use, you can edit app.py and change the port number in the last line.

Navigate to http://localhost:5001 and start playing!

1. Choose a Mystery: Select from English or Chinese scenarios, filter by difficulty
2. Choose Input Mode:
   • Text Mode: Type yes/no questions
   • Voice Mode: Hold the microphone button and speak
3. Ask Questions: Gather information about the scenario
4. Get Hints: Request hints if you're stuck (impacts your grade)
5. Solve the Puzzle: Submit your solution when ready
6. Earn Your Grade: Get rated from S (perfect) to D (needs improvement)

Your performance is evaluated based on:

• Questions Asked: Fewer is better
• Hints Used: Each hint lowers your grade
• Time Taken: Faster solving improves your grade
• Solution Accuracy: Must explain the mystery correctly

Grade Scale:

• S: Perfect! Master Detective (≤3 questions, no hints, <5 min)
• A: Excellent! Great Detective (≤5 questions, 0-1 hints, <10 min)
• B: Good! Solid Detective (≤10 questions, 1-2 hints, <15 min)
• C: Fair! Developing Detective (≤15 questions, 2-3 hints, <20 min)
• D: Needs Practice (>15 questions or >3 hints or >20 min)

1. Switch to "Voice Mode" using the toggle
2. Press and hold the microphone button
3. Speak your yes/no question clearly
4. Release to submit
5. The AI will answer with voice synthesis

turtle-soup-demo/
├── app.py                    # Main Flask application
├── claude_manager.py         # DeepSeek API integration
├── game_logic.py            # Game mechanics and grading
├── database.py              # SQLite database operations
├── image_generator.py       # AI image generation
├── config.py                # Configuration and settings
├── requirements.txt         # Python dependencies
├── .env                     # Environment variables (API keys)
├── static/
│   ├── style.css           # CSS styling
│   ├── game.js             # Main game logic
│   ├── voice_simple.js     # Voice mode handler
│   └── scenario_images/    # Generated scenario images
├── templates/
│   └── index.html          # Single page application
├── data/
│   ├── scenarios.json      # English scenarios
│   └── scenarios_chinese.json  # Chinese scenarios
└── game.db                 # SQLite database (auto-created)

Click the "AI Generate" button to create new puzzles:

• Choose difficulty level
• AI generates unique scenarios
• Automatically saved to database
• Complete with title, story, and solution

Switch between English and Chinese:

• Separate scenario libraries
• Fully localized UI
• Language-specific AI generation
• Independent difficulty filters

Each scenario gets a unique AI-generated image:

• Generated automatically on first play
• Cached for future sessions
• Enhances visual storytelling

After solving (or revealing) a puzzle:

• Rate from 1-5 stars
• Average ratings tracked
• Helps identify best scenarios

See the "Public Access Setup" section below for detailed instructions on exposing port 5001 to the internet.

• Ensure your DeepSeek API key is correctly set in .env
• Verify the key has sufficient credits
• For voice features, check OpenAI and ElevenLabs keys

• Delete game.db and restart to reset the database
• Check file permissions in the project directory

• Change the port in app.py: app.run(debug=True, port=XXXX)

• Ensure browser has microphone permission
• Check that OpenAI API key is configured
• Use HTTPS for production (required for microphone access)

In claude_manager.py, you can adjust:

• model: Default is deepseek-chat
• temperature: Controls response randomness (0.1-0.8)
• max_tokens: Response length limit

Scenarios are categorized as:

• Easy: Simple puzzles, straightforward solutions
• Medium: Moderate complexity, some lateral thinking required
• Hard: Complex scenarios, significant lateral thinking needed

Edit data/scenarios.json or data/scenarios_chinese.json:

{
    "title": "Your Scenario Title",
    "category": "mystery",
    "difficulty": "medium",
    "surface_story": "The mysterious setup...",
    "full_story": "The actual solution...",
    "key_facts": [
        "Important fact 1",
        "Important fact 2"
    ]
}

Then delete game.db and restart the app to reload scenarios.

To expose your local server (port 5001) to the internet, you have several options:

1. Install ngrok:

   # macOS with Homebrew
   brew install ngrok
   
   # Or download from https://ngrok.com/download

2. Start your app:

   python app.py

3. In a new terminal, expose port 5001:

   ngrok http 5001

4. Copy the public URL (e.g., https://xxxx-xx-xx-xx.ngrok-free.app)

   • Share this URL with others
   • Free tier has session limits

1. Install cloudflared:

   # macOS
   brew install cloudflare/cloudflare/cloudflared
   
   # Or download from https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/installation/

2. Authenticate:

   cloudflared tunnel login

3. Create a tunnel:

   cloudflared tunnel create turtle-soup

4. Run the tunnel:

   cloudflared tunnel --url http://localhost:5001

5. Get your public URL from the output

# On your local machine
ssh -R 80:localhost:5001 serveo.net

# Or with a custom subdomain
ssh -R yourname:80:localhost:5001 serveo.net

For production deployment, consider:

• Heroku: Easy deployment, free tier available
• Railway: Modern platform, simple setup
• Render: Free tier with auto-deploys
• DigitalOcean: Full control, droplets from $5/mo
• AWS/GCP/Azure: Enterprise-grade, more complex

Important for Production:

• Use environment variables for all API keys
• Enable HTTPS (required for voice features)
• Set DEBUG=False in production
• Use a production WSGI server (gunicorn, waitress)
• Set up proper logging and monitoring

This implementation uses DeepSeek's OpenAI-compatible API:

• Fast responses: Optimized for speed
• Cost-effective: Very affordable pricing
• Reliable: Consistent yes/no/irrelevant answers
• OpenAI SDK: Easy integration using openai library

The SQLite database includes:

• scenarios table: Stores all puzzle scenarios
• game_results table: Tracks game statistics and grades
• scenario_ratings table: User ratings for scenarios

The app integrates multiple AI services:

1. DeepSeek: Game logic, hints, scenario generation
2. OpenAI Whisper: Speech-to-text transcription
3. ElevenLabs: High-quality text-to-speech
4. Silicon Flow: AI image generation

• User authentication and profiles
• Multiplayer support with shared game sessions
• Mobile app version (React Native or PWA)
• Leaderboard system
• Daily challenges
• More puzzle categories (horror, sci-fi, detective)
• Community-contributed scenarios
• Achievement system
• Social sharing of solutions

• AI Models: DeepSeek, OpenAI Whisper, ElevenLabs
• Puzzle Type: Lateral Thinking Puzzles (Turtle Soup)
• Framework: Flask (Python)
• Developer: Built with assistance from Claude Code

This is a demo project for educational purposes.

Enjoy solving mysteries! 🐢🍲 / 享受解谜的乐趣！