Giuseppe Mattia Greco What if you could generate a fully playable, narrative-driven quest from a simple text prompt — guaranteeing not just a good story, but flawless logical consistency?
This project, developed alongside two of my colleagues as part of our Artificial Intelligence course at the University of Calabria, bridges a crucial gap in modern AI. We combined the creative power of Large Language Models (LLMs) with the rigorous constraints of formal automated planning (PDDL) to build QuestMaster AI.
Let’s explore the architecture behind it.
The Challenge: Creativity vs. Consistency
LLMs are excellent at writing engaging stories, but they lack true logical reasoning. If an LLM writes a quest where a player uses a key to open a chest, it might forget that the player never actually acquired the key.
To solve this, we used PDDL (Planning Domain Definition Language). By translating the narrative into a mathematical model of states, actions, preconditions, and effects, we can use formal planners to guarantee that the quest is actually solvable. The challenge was finding a way to translate natural language into valid PDDL dynamically, without losing the narrative flavor.
Grounding the Narrative with RAG
One of the core pillars of QuestMaster AI is its ability to adhere to pre-existing universes and rulesets. To prevent the LLM from hallucinating and to ensure the generated quests fit seamlessly into a specific lore, we built a robust Retrieval-Augmented Generation (RAG) pipeline.
Instead of relying solely on the model’s internal weights, the system ingests external PDF documents using PyPDFLoader. We carefully chunk this text — using 1000-character segments with a 200-character overlap to preserve local context — and convert it into vector embeddings via Google’s gemini-embedding-001. These embeddings are then indexed using FAISS to create a fast, local semantic search engine.
When a user inputs a prompt, the system instantly retrieves the three most relevant context chunks and injects them directly into the prompt for Google’s Gemini 2.5 Flash. By strictly limiting this injected context to 2000 characters, we managed to balance high contextual accuracy with low latency and API cost. This RAG approach acts as the anchor for the entire project, ensuring that the foundational JSON “lore” generated by the model is highly specific, context-aware, and ready for formal translation.
From Lore to Formal Planning
Once the context-aware lore is generated, the pipeline moves into its formal phase. Gemini translates the structured JSON into rigorous domain.pddl and problem.pddl files. This is where the Python backend orchestrates the heavy lifting: it spins up the Fast-Downward planner in a separate process, using the $A^*$ algorithm to search for a valid solution path. If a path is found, the VAL validator double-checks the plan step-by-step to ensure strict adherence to PDDL semantics.
Finally, the validated plan is fed back to Gemini, which transforms the abstract sequence of actions into an interactive, node-based narrative graph. This graph is then rendered by our Flask web interface, allowing the user to play through the quest directly in the browser.
The Secret Sauce: The Reflective Agent
Generating PDDL via LLMs is highly error-prone. Predicates get mixed up, types mismatch, or the problem is simply unsolvable.
To handle this without human intervention, we built a Reflective Agent. When Fast-Downward fails to find a path, or VAL detects a semantic violation, the agent intercepts the exact standard error output (stderr). It then feeds this error back to Gemini along with the faulty PDDL, asking for a targeted fix. This automated self-correction loop runs iteratively until a valid plan is found, effectively giving the system the ability to debug its own code.
Security & Human-in-the-Loop
We designed the system to be resilient and controllable. Defensive prompting shields the LLM from injection attacks (such as instructions to ignore previous rules), maintaining strict control over the PDDL generation structure. Furthermore, a Human-in-the-Loop mechanism pauses the pipeline at critical junctures. This allows users to review the generated JSON lore and the abstract plan, injecting manual corrections before the final interactive story is finalized.
What’s Next?
While QuestMaster AI successfully generates playable, logically sound quests, there is always room for optimization. Looking ahead, implementing intelligent caching could significantly reduce API costs and latency during the Reflective Agent’s debugging loop. Additionally, containerizing the entire stack via Docker would simplify the deployment of external dependencies like Fast-Downward, while fine-tuning a smaller, open-source model specifically for PDDL generation could eventually replace the reliance on commercial APIs.
QuestMaster AI proves that the future of procedural generation lies not just in better language models, but in successfully marrying their creativity with classic, deterministic computer science.
Contributing
You can review the code and contribute to it at the following link:
