asherfeldman/Keeper-of-Elysium

Keeper of Elysium ⚔️📜

Keeper of Elysium is a Gradio-powered chat interface that lets your D&D party consult an "Ancient Celestial of Undetermined Alignment"—a sarcastic, millennia-old being who mocks your adventurers while still giving (mostly) useful answers.

The agent is primed with two context files:

1. 1.context_party_members_and_familiars.json – a structured export of character sheets & familiars.
2. 2.context_party_journal.txt – a running log of the party's exploits.

Every user question is answered in-character, then reviewed by a lightweight evaluator model. If the response isn't snarky, accurate, or disdainful enough, it gets automatically rewritten until it passes muster.

✨ Demo

A HuggingFace Space will be published soon — stay tuned! (Until then just run it locally as shown below.)

📜 Table of Contents

• —Features
• —Tech Stack
• —Quick Start
• —How It Works
• —Project Structure
• —Roadmap
• —Contributing
• —License

🚀 Features

• —In-Character Q&A – Ask lore questions, plan heists, or request prophecy; the Celestial always answers with biting sarcasm.
• —Context Awareness – The agent has full knowledge of party members, familiars, and the shared journal.
• —Automated Quality Gate – Responses are vetted by an O3-mini "director" model that shouts revision notes if the performance is off.
• —Pig Latin Easter Egg – Mention "patent" to force the Celestial to speak in Pig Latin. 🐷
• —Modern UI – Built with Gradio 4 for a clean, responsive chat experience.

🛠 Tech Stack

• —🐍 Python 3.10+
• —🤗 Gradio 4.44 for the web front-end
• —🦜🔗 OpenAI GPT-4o-mini for generation, O3-mini for evaluation
• —🔑 python-dotenv for environment management All dependencies live in `requirements.txt`.

⚡️ Quick Start

1. 1.Clone & install

   git clone https://github.com/asherfeldman/Keeper-of-Elysium.git
   cd Keeper-of-Elysium
   pip install -r requirements.txt

1. 1.Add your API key

   echo "OPENAI_API_KEY=sk-..." > .env

1. 1.Run locally

   python app.py

1. 1.Open your browser at the printed URL (defaults to http://localhost:7860) and start chatting!

🧠 How It Works

flowchart TD
    A[User Question] --> B{Chat LLM (GPT-4o-mini)}
    B --> C[Draft Answer]
    C --> D{Evaluator LLM (O3-mini)}
    D -- Acceptable --> E[Show Answer]
    D -- Needs Fix --> F[Rewrite Prompt With Feedback]
    F --> B

1. 1.A user sends a question.
2. 2.The main LLM drafts an answer using both context files.
3. 3.The evaluator model scores the reply for sarcasm, lore consistency, and theatrical flair.
4. 4.If the score is low, feedback is injected and the response is regenerated; otherwise it is returned.

📁 Project Structure

Keeper-of-Elysium/
├── app.py                       # Main Gradio app & chat logic
├── context_party_journal.txt    # Party adventure log
├── context_party_members_and_familiars.json
├── requirements.txt             # Pinned dependencies
├── README.md
└── ...

🗺 Roadmap

• —[ ] Vector-store retrieval for deeper lore look-ups.
• —[ ] Multi-modal support (upload party maps & handouts).
• —[ ] CI/CD workflow to auto-deploy to HuggingFace Spaces.

🤝 Contributing

Pull requests are welcome! Please file an issue first if you plan a large change.

1. 1.Fork the repo
2. 2.Create your feature branch (git checkout -b feat/my-feature)
3. 3.Commit your changes (git commit -m 'feat: add my feature')
4. 4.Push to the branch (git push origin feat/my-feature)
5. 5.Open a pull request

Please follow Conventional Commits and run pre-commit before pushing.

🪪 License

Released under the MIT License.

<p align="center"> Made with 💫 and a dash of eldritch sarcasm by <a href="https://www.linkedin.com/in/asherfeldman/">Asher Feldman</a> </p>