Project: Creative Apps Github Copilot - Puzzle Generator #124
Description
Track
Creative Apps (GitHub Copilot)
Project Name
Puzzle Generator
GitHub Username
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