Aoandon, a new open-source web application, is redefining how developers and language learners interact with historical Japanese literature. Built for the Hacktoberfest Open-Source AI Challenge, the tool uses Gemma 4 to retell Lafcadio Hearn’s ghost stories at five distinct JLPT proficiency levels. The project transforms static, Meiji-era texts from Aozora Bunko into dynamic, level-adapted reading experiences, complete with interactive candle-blowing mechanics and Anki export capabilities.

The Technical Pipeline

The core of Aoandon is a rigorous generation and validation pipeline. The developer, who resides in Japan, utilized the 31B parameter version of Gemma 4 running on DigitalOcean serverless inference to generate 265 retellings across 53 scenes. The prompt explicitly frames the AI as Koizumi Setsu, Hearn’s wife, retelling stories to a learner. This output is not trusted blindly; it passes through a custom checker that splits Japanese into words using Kuromoji and validates every kanji against open JLPT vocabulary lists. The development process involved three distinct iterations to solve the 'false positive' problem in language leveling. Version 1 relied on word percentages, which masked the fact that complex kanji were being counted as easy words if their readings matched. Version 2 overcorrected by forcing hard kanji into kana, which ironically made the intermediate N3 level easier than N5. Version 3 finally succeeded by strictly adhering to cumulative JLPT kanji lists, ensuring that higher levels introduced more complex characters and longer sentence structures.

Infrastructure and Open Source Philosophy

From a DevOps perspective, Aoandon is a masterclass in lightweight architecture. The frontend is built with React and Vite, rendering the hundred-candle interface on a single canvas to maintain performance on mobile devices. The site is hosted as a static Render instance that redeploys on every GitHub push, requiring no backend, no API keys, and no user accounts. All generated story data is stored as plain files, ensuring the project remains free and accessible even if the hosting provider changes. The project also highlights the utility of local LLMs for testing, even if they aren't production-ready. The developer attempted to run the smaller Gemma 4 E2B model locally via Ollama. While it failed to produce coherent long-form text, getting stuck in repetitive loops, it served as a valuable sandbox for prompt engineering. The final stories were generated by the larger 31B model, but the local experiments allowed for rapid, cost-free iteration on the validation rules.

Key Takeaways

  • Strict Kanji Validation: The tool enforces cumulative JLPT kanji lists (79 for N5 up to 2,211 for N1), preventing the common AI pitfall of using complex characters in beginner texts.
  • Static-First Architecture: By generating content once and storing it as plain files, Aoandon eliminates runtime API costs and latency, making it a true 'free' tool for learners.
  • Iterative Correction: The pipeline uses a 'rewrite loop' where the model receives specific error messages from the validator, allowing it to self-correct vocabulary and grammar violations.
  • Open Data Dependency: The project relies entirely on open-source JLPT lists and Aozora Bunko texts, proving that community-maintained datasets are critical for accessible AI tools.

The Bottom Line

Aoandon proves that LLMs are most effective in developer tools when paired with strict, deterministic validators. By treating language leveling as a software testing problem rather than a pure generation task, the project delivers a reliable, open-source utility that avoids the 'hallucinated difficulty' common in AI-generated educational content.