---
title: Alien Riddle
emoji: 👽
sdk: gradio
sdk_version: 6.16.0
app_file: app.py
pinned: true
hf_oauth: true
license: mit
hf_oauth_scopes:
- inference-api
tags:
  - track:wood
  - sponsor:modal
  - achievement:offbrand
---

# Alien Riddle

Video demo: [youtube](https://huggingface.co/gdejan100)

Team HuggingFace: 
- [gdejan100](https://huggingface.co/gdejan100)
- [huba179](https://huggingface.co/Huba179)

Social Media Post: [linkedin](https://www.linkedin.com/posts/chandraa17_alien-obfuscator-build-small-hackathon-share-7472299504717864960-Z4eh/?utm_source=share&utm_medium=member_desktop&rcm=ACoAAClgL5wBsZxQHEI7u4036mJ6LCHBciWvt-0)


An alien intelligence monitors all human communications. Resistance fighters encode messages as riddles drawn from ancient Earth texts — texts the alien cannot understand because they require *cultural context*, not decryption. The alien *sees* the riddle but can't *get* it. Humans can.

Built for the **HuggingFace Build Small Hackathon**.

## How to Play

1. **Encrypt** — Type a secret message and pick a theme (Greek Myth, Shakespeare, Grimm, Poetry, Chinese Classics). The AI will generate a poetic riddle that only humans can solve.
2. **Solve** — Paste a friend's riddle card and guess the answer. Unlimited retries!
3. **Challenge** — Race against the clock to solve as many auto-generated riddles as you can.

## Architecture

- **Gradio** UI with dark sci-fi theming
- **Modular LLM backend** — Mock (offline) or Hugging Face Inference API
- **Corpus Manager** — Curated public-domain excerpts per theme
- **Riddle Generator** — Prompt builder + JSON schema validation + retry logic
- **Game Engine** — Timer, scoring, streaks, high-score persistence

## Parameter Budget

- Primary LLM: up to 31B parameters (`google/gemma-4-31b-it`)
- Fallback: `google/gemma-4-26b-a4b-it` (MoE)
- Total: ≤ 32B limit

## Project Structure

```
alien-obfuscator/
├── app.py                  # Gradio UI (tabs, layout, callbacks)
├── src/alien_obfuscator/
│   ├── config.py           # Constants, model settings, paths
│   ├── corpus_manager.py   # Loads, selects, caches excerpts
│   └── riddle_generator.py # Prompt builder + LLM abstraction + validation
├── corpus/
│   ├── greek_myth.txt      # Curated excerpts
│   ├── shakespeare.txt
│   ├── grimm.txt
│   ├── poetry.txt
│   └── chinese_classics.txt
├── tests/
│   ├── test_corpus_manager.py
│   └── test_riddle_generator.py
├── requirements.txt
├── pyproject.toml
└── README.md
```

## Running Locally

```bash
# Install dependencies
uv sync

# Run the app
make start

# Run tests
make test

# Lint & type-check
make lint
make ty
```

## License

This project uses public-domain texts and is provided as-is for the hackathon.