Chroniclues 🗝️📜

A Wikipedia-grounded history escape room powered by Google Gemini, Flask, and mechanically validated Cryptic clues.

Selected Challenge Theme: Creative Industries

Chroniclues was developed for the IBM July Challenge theme Creative Industries.

The project applies AI to interactive storytelling, educational game design, and procedural content creation. It transforms historical source material into a playable narrative experience by combining:

• AI-assisted historical storytelling
• Procedural wordplay generation
• Source-grounded educational content
• Dynamic fact and narrative reveals

AI is not used only to summarize information. It acts as a creative production partner that helps transform historical reference material into an original interactive learning experience.

---

Problem Statement

Many history-learning tools rely on passive summaries, flashcards, or direct trivia questions. These formats can make it difficult for learners to actively process historical information or understand how people, institutions, events, and consequences connect within a larger narrative.

Creating a historically grounded educational game manually is also time-intensive. An educator or designer must:

1. Research the topic.
2. Identify important historical concepts.
3. Write an accurate narrative.
4. Design solvable clues.
5. Verify the clue mechanics.
6. Connect each answer back to the historical explanation.

Chroniclues addresses this problem by generating interactive, source-grounded history escape rooms that combine historical narratives with mechanically validated wordplay puzzles.

---

Solution

Chroniclues is an AI-assisted history escape-room generator.

A user enters a historical topic and an optional year. The application retrieves relevant Wikipedia content, creates a concise historical narrative, selects three meaningful terms from that narrative, and converts those terms into Parswords-style wordplay clues.

As the player solves each clue:

• A historical fact is unlocked.
• The solved word fills a blank in the story.
• The final narrative becomes complete.

Unlike a conventional history quiz, Chroniclues separates the puzzle mechanic from the factual explanation. The clue is solved through wordplay, while the historical context is revealed after the answer is submitted.

---

Core Experience

User enters a topic and year
            ↓
Wikipedia API retrieves historical context
            ↓
Gemini creates a grounded historical summary
            ↓
Three important terms are selected from that summary
            ↓
Gemini drafts Cryptic clues using dataset examples
            ↓
Python validates each clue mechanically
            ↓
The player solves the clues and unlocks historical facts
            ↓
The answers complete the final historical narrative

---

AI Approach and Architecture

Chroniclues uses a hybrid architecture that combines retrieval, generative AI, few-shot prompting, deterministic validation, and fallback generation.

1. Wikipedia retrieval

The Flask backend sends the user's topic to the Wikipedia API and retrieves the best-matching article and plaintext extract.

Wikipedia provides the grounding source for the historical narrative. The retrieved text is passed to Gemini so that the generated summary and facts remain tied to a public reference source.

2. AI-assisted story planning

Google Gemini receives:

• The user's topic
• The optional year
• The Wikipedia article title
• The retrieved article extract
• A requested narrative style

Gemini is instructed to:

• Produce a connected four-to-five-sentence historical summary
• Ground each factual statement in the retrieved text
• Select exactly three distinct one-word terms from its own summary
• Provide a short definition and historical fact for each term

The backend then verifies that every selected term appears as a standalone word in the summary before replacing those terms with puzzle blanks.

3. Dataset-guided clue generation

The application loads curated Parswords-style examples from:

cryptic_parseword_combined.csv

The dataset contains seven blocks of 100 examples, grouped by operation. The clue trainer normalizes the data, checks its structure, and provides few-shot examples for prompt construction.

For each generated room, the application selects three distinct supported operations and gives Gemini examples from the matching operation categories.

4. Mechanical validation

Python validates every generated clue before it reaches the player.

Depending on the operation, the validator checks whether:

• A hidden answer occurs as a contiguous substring
• Reversing the source produces the answer
• An anagram contains exactly the same letters
• Removing the first letter produces the answer
• Selected initial letters spell the answer
• A source word appears properly inside the answer
• The clue contains an accepted operation indicator
• The clue ends with the correct letter count
• The clue is not phrased as a direct trivia question

5. Deterministic fallback

If Gemini produces a clue that fails validation, Chroniclues replaces it with a deterministic Python-generated clue.

This hybrid design preserves the creativity of generative AI while preventing mechanically invalid clues from reaching the player.

Architecture Diagram

Browser
   ↓
Flask API
   ├── Wikipedia API
   │      └── Grounded historical source
   │
   ├── Google Gemini
   │      ├── Historical summary
   │      ├── Key-term selection
   │      ├── Historical facts
   │      └── Dataset-guided clue drafts
   │
   ├── Curated CSV dataset
   │      └── Few-shot Parswords examples
   │
   └── Python validation layer
          ├── Mechanical checks
          └── Deterministic fallback clues
   ↓
Interactive escape-room interface

---

How IBM Bob Was Used

IBM Bob was used as the primary development assistant throughout the design, implementation, debugging, and refinement of Chroniclues.

IBM Bob supported the project by helping with:

• Planning the Flask application structure and API workflow
• Organizing the Wikipedia retrieval and Gemini generation pipeline
• Designing prompt structures for summary generation, term selection, and clue generation
• Developing the dataset loader and operation-based few-shot example system
• Implementing clue validation and deterministic fallback logic
• Debugging backend response structures and frontend rendering issues
• Refining the HTML, CSS, and JavaScript escape-room experience
• Improving error handling, logging, duplicate-request protection, and application reliability
• Preparing the application structure for deployment on Render
• Reviewing the README and project documentation against the challenge requirements

IBM Bob was used iteratively rather than for a single code-generation step. The workflow involved describing intended behavior, reviewing generated or modified code, testing the application, reporting failures, and refining the implementation until the complete pipeline worked end to end.

The final product decisions and validation requirements remained developer-directed, while IBM Bob accelerated implementation and iteration across the software-development lifecycle.

---

Supported Clue Operations

The deployed clue-generation pool currently uses six mechanically validated operations.

Operation	Rule	Simple example
Hidden word	The answer appears inside a source phrase	STEAM inside STEAMENGINE
Deletion	Remove the first letter of the source	FLIGHT → LIGHT
Reverse	Reverse the source word	RATS → STAR
Anagram	Rearrange the source letters	ICEMAN → CINEMA
Container	Place one string inside another	I inside BRAN is BRAIN
Selection	Take the initial letters of a phrase	Stories Tell Ancient Records → STAR

The dataset also contains homophone examples, but homophone generation is not currently included in the random operation pool used by the deployed room generator.

Example

Clue: Factory power, initially seen through engines across mills (5)
Answer: STEAM
Operation: selection
Wordplay: Take the first letters of Seen Through Engines Across Mills.

Unlocked fact:

Steam power helped transform factories, mining, and transportation during the Industrial Revolution.

Project Structure

IBMJulyChallenge/
├── puzzle.py
│   └── Flask backend, Wikipedia retrieval, Gemini calls,
│       story planning, clue generation, validation, and API routes
│
├── clue_trainer.py
│   └── Dataset loading, structural validation, operation grouping,
│       and few-shot example construction
│
├── cryptic_parseword_combined.csv
│   └── Curated two-column Parswords-style clue dataset
│
├── templates/
│   └── index.html
│       └── Main single-page application shell
│
├── static/
│   ├── app.js
│   │   └── Escape-room flow, clue display, answer checking,
│   │       fact unlocks, and final story rendering
│   ├── style.css
│   │   └── Chroniclues interface styling
│   └── scene.js
│       └── Optional visual and background effects
│
├── requirements.txt
├── Procfile
├── render.yaml
├── .python-version
├── .gitignore
└── README.md

Getting Started Locally

1. Clone the repository

git clone https://github.com/AryaGavande/IBMJulyChallenge.git
cd IBMJulyChallenge

2. Create a virtual environment

macOS or Linux:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -r requirements.txt

Windows PowerShell:

py -3 -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -r requirements.txt

3. Add credentials

Create a file named:

namr_api.env

Add:

GEMINI_API_KEY=your_google_gemini_api_key

Optional configuration:

GEMINI_MODEL=gemini-2.0-flash
PORT=5001
MAX_PER_OP_BLOCK=3
MAX_PER_OP_FORMULA=5
MAX_DATASET_EXAMPLES_PER_OP=5
GENERATION_CACHE_TTL_SECONDS=15
GENERATION_WAIT_TIMEOUT_SECONDS=300

Do not commit arya_api.env.

4. Confirm the dataset

Ensure this file is in the project root:

cryptic_parseword_combined.csv

The loader expects exactly:

• 700 data rows
• Two columns: input-text and target-text
• Seven consecutive operation blocks of 100 rows

5. Run the application

python puzzle.py

Open:

http://localhost:5001

To use another port:

PORT=5050 python puzzle.py

---

Deploying to Render

1. Sign in to Render with GitHub.
2. Select New → Web Service.
3. Choose the IBMJulyChallenge repository.
4. Confirm the branch and instance type.
5. Add the environment variable:

GEMINI_API_KEY

6. Add GEMINI_MODEL only when overriding the application default.
7. Deploy the service.

Render can use the repository's render.yaml or Procfile configuration.

---

Reliability and Safety Controls

Chroniclues includes several controls to reduce unreliable generated output:

• Wikipedia grounding for historical context
• Strict JSON response formats
• Verification that selected terms occur in the generated summary
• Exactly three distinct answer terms
• Answer-length and stop-word checks
• Mechanical clue validation
• Rejection of trivia-question phrasing
• Required operation indicators
• Required answer-length notation
• Deterministic clue fallback
• Deterministic Wikipedia-summary fallback
• Duplicate-request locking and short-term caching
• Dataset structural validation at startup

These controls do not guarantee that every historical interpretation is perfect. Users should follow the displayed Wikipedia source link when they need additional context or verification.

---

Future Improvements

Improvement	Description
Visible source panel	Display the Wikipedia source more prominently inside the interface
Animated story completion	Fill story blanks dynamically as each clue is solved
Difficulty levels	Add easy, medium, and hard clue modes
Multiple-source retrieval	Ground rooms with several related sources
Teacher mode	Allow instructors to define topics and learning objectives
Save progress	Resume unfinished rooms
Expanded dataset	Add more validated clue examples
Operation balancing	Control the mix of mechanics by difficulty
Historical verification layer	Add citation-level support for individual facts
Accessibility review	Improve keyboard, screen-reader, and contrast support

---

Built for the IBM July Challenge
Developed with IBM Bob
Powered by Google Gemini
Grounded with Wikipedia