Project: Creative Apps Github Copilot - Puzzle Generator

Track

Creative Apps (GitHub Copilot)

Project Name

Puzzle Generator

GitHub Username

@jgarcia92

Repository URL

https://github.com/jgarcia92/agentsleague-puzzle-generator

Project Description

It creates short, unique puzzles across logic, math, wordplay, and general topics. You can run it offline from templates or switch to AI mode to generate brand‑new puzzles using OpenAI or Gemini.

Demo Video or Screenshots

Demo Video:
https://youtu.be/lKc-OoMr4Xc

Live Demo
https://appapppy-8jz56v38ifx5eunkhdmork.streamlit.app/

Primary Programming Language

Python

Key Technologies Used

• OpenAI
• Streamlit UI
  -Python

Submission Type

Individual

Team Members

-- @jgarcia92 Developer

Submission Requirements

• My project meets the track-specific challenge requirements
• My repository includes a comprehensive README.md with setup instructions
• My code does not contain hardcoded API keys or secrets
• I have included demo materials (video or screenshots)
• My project is my own work with proper attribution for any third-party code
• I agree to the Code of Conduct
• I have read and agree to the Disclaimer
• My submission does NOT contain any confidential, proprietary, or sensitive information
• I confirm I have the rights to submit this content and grant the necessary licenses

Quick Setup Summary

Clone or create your workspace:

cd C:\Users\jaime\agentsleague-puzzle-generator
(Recommended) Create a virtual environment:

Windows (PowerShell)

python -m venv .venv
..venv\Scripts\Activate.ps1

macOS/Linux (bash/zsh)

python3 -m venv .venv
source .venv/bin/activate
Install dependencies:

python -m pip install -r requirements.txt
Configure environment:

cp .env.example .env

Edit .env (optional for basic demo)

Set MODEL_PROVIDER=openai or gemini

Add OPENAI_API_KEY=... or GOOGLE_API_KEY=...

Run the CLI demo:

python puzzle_generator.py --count 3 --difficulty medium
Run the Streamlit UI (optional):

Always use the venv's Python so the right packages/keys are used

python -m streamlit run streamlit_app.py

Technical Highlights

Generation Engine: Implemented a pool-based selector that samples puzzles without replacement, preferring exact (category+difficulty) matches, then same-difficulty, then any; final list is shuffled to avoid deterministic first items.

Clue Synthesis: Generates on-the-fly “clue images” with Pillow (gradient, emoji, readable typography) and randomized structural hints (starts/ends with, vowels/consonants, word/letter counts) — no external assets required.

AI Mode, Robust by Default: Optional OpenAI/Gemini path with explicit key usage (OpenAI client initialized with env key) and strict JSON mode (OpenAI response_format=json_object; Gemini response_mime_type=application/json).

Defensive JSON Parsing: Safe extractor handles fenced blocks, top-level objects with items[], and first-array recovery; dedupes by question and tops up with templates when the model returns fewer unique items.
Clear Source-of-Truth: Results banner shows “Source: AI (openai|gemini)” or “Templates (fallback)” so it’s obvious what generated the set; spinner indicates in-flight AI calls.

Diagnostics Panel: In-app checks confirm “SDK available” and “Key detected in session” to eliminate environment guesswork across machines.
Secure, Offline-First: Works entirely from local templates without network or keys; secrets live only in .env/session and are excluded from git.

Export & Interop: One-click JSON/CSV downloads for any generated set, enabling quick sharing, testing, or downstream tooling.

Polished UX: Sticky sidebar with env-driven defaults (PUZZLE_DIFFICULTY, PUZZLE_CATEGORY, PUZZLE_COUNT, OUTPUT_FORMAT), subtle confetti on success, clean answer expanders, and accessible layout/contrast.

Portability & Setup: Venv-first guidance with python -m pip and python -m streamlit ensures the correct interpreter and installed SDKs on any machine.

Reliability Choices: Dedup pipeline + fallback cascade prevent repeats and ensure complete results even when AI responds imperfectly.
Copilot Impact: Used GitHub Copilot to scaffold the CLI/UI, draft templates and hint logic, add Diagnostics, tighten JSON-mode integration, and refactor for clarity — accelerating iteration while keeping guardrails in place.

Challenges & Learnings

Biggest challenge: making AI generation reliable. Models sometimes returned prose or invalid JSON. I fixed it by forcing JSON mode, adding a robust parser, and falling back to templates with a clear “Source” label.

Repeats/ordering: small template pool caused duplicates and a fixed first item. I switched to sampling without replacement and shuffling the final list.

Environment drift: “openai not found” or keys not detected on new machines. I went venv‑first, ran python -m streamlit, added a Diagnostics panel, and initialized the client with the env key explicitly.

Key learning: add guardrails and visibility early—offline‑first defaults, explicit fallbacks, and simple diagnostics save tons of time and make the UX feel solid.

Contact Information

jg0592@gmail.com, jaime_sql@outlook.com

Country/Region

El Salvador

This is a project submission rather than a scoped change request. Start with the linked repository and its README.md, then inspect puzzle_generator.py and streamlit_app.py and run the setup commands described in the issue. A completion condition for additional work is not defined.