{"id":17780715,"url":"https://github.com/dimzachar/parthenon-rag-game","last_synced_at":"2025-03-15T22:31:20.771Z","repository":{"id":258003513,"uuid":"866280590","full_name":"dimzachar/Parthenon-RAG-Game","owner":"dimzachar","description":"2D pixel-art RPG with AI-powered NPCs. Learn about Movementlabs through gameplay! ","archived":false,"fork":false,"pushed_at":"2025-02-11T16:32:18.000Z","size":21278,"stargazers_count":4,"open_issues_count":4,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-02-27T04:23:48.458Z","etag":null,"topics":["ai","blockchain","docker","elasticsearch","fastapi","grafana","llm","nextjs","phaser-js","postgresql","python","rag","react","typescript"],"latest_commit_sha":null,"homepage":"https://parthenon-rag.vercel.app/","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dimzachar.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"dimzachar","buy_me_a_coffee":"techietea"}},"created_at":"2024-10-02T00:47:45.000Z","updated_at":"2025-01-12T18:25:35.000Z","dependencies_parsed_at":"2024-10-18T21:54:15.896Z","dependency_job_id":null,"html_url":"https://github.com/dimzachar/Parthenon-RAG-Game","commit_stats":null,"previous_names":["dimzachar/parthenon-rag-game"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dimzachar%2FParthenon-RAG-Game","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dimzachar%2FParthenon-RAG-Game/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dimzachar%2FParthenon-RAG-Game/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dimzachar%2FParthenon-RAG-Game/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dimzachar","download_url":"https://codeload.github.com/dimzachar/Parthenon-RAG-Game/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243801600,"owners_count":20350105,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","blockchain","docker","elasticsearch","fastapi","grafana","llm","nextjs","phaser-js","postgresql","python","rag","react","typescript"],"created_at":"2024-10-27T03:03:38.800Z","updated_at":"2025-03-15T22:31:15.756Z","avatar_url":"https://github.com/dimzachar.png","language":"Jupyter Notebook","funding_links":["https://github.com/sponsors/dimzachar","https://buymeacoffee.com/techietea","https://www.buymeacoffee.com/techietea"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"images/parthlogo.png\" alt=\"Image description\" width=\"300\"/\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\" style=\"border-bottom: none\"\u003e\n    🏛️ Parthenon: A Gamified Web3 Learning Experience\n\u003c/h1\u003e\n\n\u003e [!NOTE]\n\u003e This project was created as part of [LLM Zoomcamp course](https://github.com/DataTalksClub/llm-zoomcamp/tree/main).\n\n\u003e Listen to an overview created by [NotebookLM](https://notebooklm.google/) \n\nhttps://github.com/user-attachments/assets/096f2b58-660e-4864-88a0-cedd308727e7\n\n\u003cdiv align=\"center\"\u003e\nIf you like this project, please consider giving it a ⭐️ **star** to help others discover it, or 🍴 **fork** it to contribute!\n\n[![GitHub Stars](https://img.shields.io/github/stars/dimzachar/Parthenon-RAG-Game.svg?style=social)](https://github.com/dimzachar/Parthenon-RAG-Game/stargazers)\n[![GitHub Forks](https://img.shields.io/github/forks/dimzachar/Parthenon-RAG-Game.svg?style=social)](https://github.com/dimzachar/Parthenon-RAG-Game/network/members)\n[![GitHub Issues](https://img.shields.io/github/issues/dimzachar/Parthenon-RAG-Game.svg)](https://github.com/dimzachar/Parthenon-RAG-Game/issues)\n[![Contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)](https://github.com/dimzachar/Parthenon-RAG-Game/issues)\n\u003cbr\u003e\n\u003ca href=\"https://parthenon-rag.vercel.app/\"\u003e\u003cimg src=\"https://img.shields.io/badge/Website-Parthenon RAG-192A4E?color=blueviolet\" alt=\"Parthenon RAG: A Gamified Web3 Learning Experience\"\u003e\u003c/a\u003e\n\u003c/div\u003e\n\n\n## Overview\n\nParthenon is an immersive 2D top-down pixel-art game that incorporates a RAG system, allowing players to have dynamic, knowledge-based interactions while exploring the virtual world. Players learn about [Movementlabs](https://movementlabs.xyz/), a Move-based blockchain network, and its ecosystem through engaging NPC interactions.\n\nThis project integrates several technologies to create a robust system for querying a knowledge base, building prompts, and interacting with a LLM. It features:\n\n- A backend with a RAG system, leveraging Elasticsearch for data retrieval and OpenAI language model for generating responses.\n- PostgreSQL for storing and managing data.\n- Grafana for monitoring key metrics such as user feedback, model costs, and other metrics.\n- A React frontend for the game interface, built using the [Phaser](https://phaser.io/) game framework.\n\n![Gameplay Demo](images/Parthenon.gif)\n\n## 📔 Problem Statement\n\nThe core challenge is creating an end-to-end RAG application that seamlessly integrates an AI-driven assistant into an interactive gamified environment. It aims to:\n\n1. Provide a smooth transition between gameplay and AI-assisted learning of the Movement ecosystem.\n2. Streamline the process of data ingestion, retrieval, and interaction.\n3. Deliver an accessible and user-friendly learning experience.\n\n## 📚 Table of Contents\n\n1. [Project Architecture \u0026 Technologies](#-project-architecture--technologies)\n2. [Dataset](#dataset)\n3. [Backend Overview](#backend-files-overview)\n4. [Setup Instructions](#-setup-instructions)\n5. [Running the Application](#running-the-application)\n6. [Using the Application](#using-the-application)\n7. [Monitoring](#monitoring)\n8. [Frontend](#-frontend)\n9. [FAQ](#-faq)\n10. [Contributing](#-contributing)\n11. [License](#-license)\n11. [Donations](#-donations)\n\n## 🏗️ Project Architecture \u0026 Technologies\n\n![architecture](images/architecture.png)\n\nParthenon is built on a modern, scalable architecture designed to deliver an engaging learning experience:\n\n🛠️ Backend\n\n- Language \u0026 Framework: Python 3.12 with FastAPI\n- Functionality: Handles API requests, orchestrates the RAG system, and manages data flow\n- Main Database: PostgreSQL for storing conversation data and user feedback\n- Vector Database: Elasticsearch for efficient search\n- LLM Integration: OpenAI API for powering AI-driven conversations\n\n🎮 Frontend\n\n- Framework: Next.js with TypeScript\n- Functionality: Renders the game world and handles user interactions\n- UI: React components styled with Tailwind CSS\n- Game Engine: Phaser.js for 2D game mechanics\n\n📊 Monitoring \u0026 DevOps\n\n- Visualization: Grafana for real-time metrics and user interaction insights\n- Containerization: Docker \u0026 Docker Compose for consistent deployment across environments\n\n### Dataset\n\nThe dataset, containing information about Movementlabs and its ecosystem, is located in [`data/json`](data/json).\n\n### Backend Files Overview\n\nThe backend of this application is structured to handle various aspects of the RAG flow, including data ingestion, retrieval, and interaction with the LLM. Below is an overview of the backend files:\n\n- [`app.py`](backend/app/app.py): This is the main entry point of the FastAPI application. It defines the API endpoints for querying the knowledge base and submitting feedback. It also includes CORS middleware configuration to allow cross-origin requests (so that the frontend fetches data from the backend). API Endpoints:\n\n\t- `/faq`: Retrieves FAQ questions from the [ground truth](data/ground-truth-retrieval.csv) file.\n\t- `/question`: Handles RAG queries and returns AI-generated responses.\n\t- `/feedback`: Receives and stores user feedback on conversations.\n\n- [`rag.py`](backend/app/rag.py): Contains the core logic for the RAG process. It handles querying Elasticsearch for relevant documents, building prompts for the LLM, and evaluating the relevance of the generated answers.\n\n- [`db.py`](backend/app/db.py): Manages database interactions using PostgreSQL. It includes functions to initialize the database schema and save conversation and feedback data.\n\n- [`prep.py`](backend/app/prep.py): Prepares the Elasticsearch index and initializes the database. It ingests documents into Elasticsearch and sets up the necessary index mappings.\n\n- [`ingest.py`](backend/app/ingest.py): Responsible for loading and processing documents from the data directory. It cleans and chunks the text data before indexing it into Elasticsearch.\n\n- [`init.py`](grafana/init.py): Script for initializing Grafana by creating API keys, setting up data sources, and configuring dashboards.\n\n## 🚀 Setup Instructions\n\n### Prerequisites\n\n- Docker and Docker Compose\n- Node.js (v14+)\n- Python 3.12\n- Git\n\n### Environment Configuration\n\n1. Clone the repository:\n\n```bash\ngit clone https://github.com/dimzachar/Parthenon-RAG-Game.git\ncd Parthenon-RAG-Game\n```\n\n### Environment Variables\n\n2. Configure environment:\n\n```bash\ncp .env.example .env\n```\n\nor rename `.env.example` in the root directory to `.env`. Key environment variables:\n\n- `ELASTIC_URL`: Elasticsearch connection URL\n- `POSTGRES_DB`, `POSTGRES_USER`, `POSTGRES_PASSWORD`: PostgreSQL connection details\n- `OPENAI_API_KEY`: Your OpenAI API key for LLM interactions\n- `INDEX_NAME`: Name of the Elasticsearch index for the knowledge base\n\nReplace `YOUR_KEY` with your Openai API key.\n\n### Dependency Installation\n\nInstall the project dependencies using `pipenv`:\n\n```bash\npip install pipenv\npipenv install --dev\n```\n\n### Experiments\n\nFor experiments, we use Jupyter notebook located in the [`notebooks`](notebooks/) folder. Check [`notebook.md`](notebook.md) for more details.\n\n\u003e Note: If an error occurs below (e.g., services take some time to fully start), wait a few seconds and try running it again.\n\n### Database Initialization\n\n1. Start the PostgreSQL service:\n\n```bash\ndocker-compose up -d postgres elasticsearch\n```\n\n2. In a new terminal, run the following commands to initialize the database:\n\n```bash\npipenv shell\ncd backend/app\nexport POSTGRES_HOST=localhost\nexport ELASTIC_URL=http://localhost:9200\npython prep.py\n```\n\nUpon success, you should see the following message:\n\n![alt text](images/image.png)\n\n### Running the Application\n\nYou have two options for running the application:\n\n**Option 1: Full Docker Compose Setup (Recommended)**\n\nIf you have any services running from the database initialization step, use Ctrl+C or run:\n\n```bash\ndocker-compose down\n```\n\nStart all services:\n\n```bash\ndocker-compose up\n```\n\n**Option 2: Running Components Separately**\n\nIf you have any services running, stop them:\n\n```bash\ndocker-compose down\n```\n\nStart only the necessary services:\n\n```bash\ndocker-compose up -d postgres grafana elasticsearch\n```\n\nRun the backend locally:\n\n```bash\npipenv shell\ncd backend/app\nexport POSTGRES_HOST=localhost\nexport ELASTIC_URL=http://localhost:9200\npython app.py\n```\n\nYou will see the following message:\n![alt text](images/image-1.png)\n\n## Using the Application\n\nUse the provided `test.py` script or curl commands to interact with the API:\n\n### Using `requests`\n\nWhen the application is running, you can use [requests](https://requests.readthedocs.io/en/latest/) to send questions to the provided [test.py](test.py) script.\n\nIn a new terminal, in root dir, interact with the application:\n\n```bash\npipenv run python test.py\n```\n\nIt sends a random question from the ground truth dataset to the app\n![requests1](images/image-2.png)\nand outputs an API response that contains several fields, including a `conversation_id`  and other relevant details.\n![requests2](images/image-3.png)\n\n### Using `CURL`\n\nUse `curl` to interact with the API:\n\nTo get a similar output install `jq`. For Windows (using Chocolatey):\n```bash\nchoco install jq\n```\n\nthen run the following command:\n\n```bash\ncurl -X POST http://localhost:5000/question -H \"Content-Type: application/json\" -d '{\"question\": \"Which platforms are referenced for deploying EVM contracts using Hardhat?\", \"selected_model\": \"gpt-4o-mini\"}' | jq '{\n  conversation_id, \n  question: .query, \n  answer, \n  response_time, \n  relevance, \n  model_used, \n  token_usage: {prompt_tokens, completion_tokens, total_tokens, eval_prompt_tokens, eval_completion_tokens, eval_total_tokens}, \n  openai_cost\n}'\n```\n\nThe output will look like this:\n\n![test curl](images/image-4.png)\n\n**Sending feedback:**\n\nAfter receiving an API response, you can send feedback on the conversation (copy-paste the following and hit enter):\n\n```bash\nID=\"d4b27893-c978-4bb5-b51a-bc6c75c9f629\"\nURL=http://localhost:5000\nFEEDBACK_DATA='{\n    \"conversation_id\": \"'${ID}'\",\n    \"feedback\": 1\n}'\n\ncurl -X POST \\\n    -H \"Content-Type: application/json\" \\\n    -d \"${FEEDBACK_DATA}\" \\\n    ${URL}/feedback\n```\n\nUpon successful submission, you'll receive an acknowledgment message similar to this:\n\n```json\n{\n    \"message\": \"Feedback received for conversation d4b27893-c978-4bb5-b51a-bc6c75c9f629: 1\"\n}\n```\n\n## Monitoring\n\nTo initialize the dashboard, first ensure Grafana is\nrunning (it starts automatically when you do `docker-compose up`).\n\n```bash\npipenv shell\ncd grafana\nenv | grep POSTGRES_HOST\npython init.py\n```\n\nYou'll receive a message confirming successful initialization.\n\n```bash\nDashboard created successfully\nInitialization complete. Datasource and dashboard created successfully.\n```\n\nAccess Grafana at [localhost:3000](http://localhost:3000) with the default credentials (admin/admin).\n\nGrafana dashboard provides visualizations for:\n\n- Last 5 conversations\n- User feedback statistics (thumbs up/down)\n- Total queries over time\n- Token usage and costs\n- LLM used\n- Query relevance scores\n- API response times\n\nThis allows you to monitor the performance and usage of the RAG system in real-time.\n\n![Monitoring Dashboard](images/image-5.png)\n\n## 💻 Frontend\n\nFor more detailed information about the game, please see the [Frontend](frontend.md) documentation.\n\n### Frontend Setup\n\nMake sure the backend services are up:\n\n```bash\ndocker-compose up\n```\n\n1. Install frontend dependencies:\n\n```bash\ncd frontend\nnpm install\n```\n\n2. Run the frontend development server:\n\n```bash\nnpm run dev\n```\n\n3. Access the application:\n\n- Open your browser and navigate to `http://localhost:3001` to load the landing page.\n- Click the `PLAY NOW` or `Launch Game` button to start.\n![alt text](images/image-6.png)\n\n- The game will open at `http://localhost:3001/game`\n![alt text](images/image-7.png)\n\n- Use the arrow keys to move the player character close to the NPC. Once a pop-up appears, press `E` to interact.\n![alt text](images/image-8.png)\n\n- A pop-up will appear with the following options:\n![alt text](images/image-9.png)\n\n- Share on Twitter\n- Copy the fact\n- Get a new fact\n- Open the chat interface (`InteractionPopup`)\n\n![alt text](images/image-10.png)\n\n- Close the pop-up when you're done\n\nThe `InteractionPopup` uses FAQ from the ground truth, where you can click on them and it pre-fills the chat.\n\n## 🤝 FAQ\n\nFor answers to commonly asked questions, please see the [FAQ document](faq.md).\n\n## 🙌 Contributing\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n6. Issue Tracker: Use GitHub Issues for bug reports and feature requests.\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 💖 Donations\n\nWe accept donations to help sustain our project. If you would like to contribute, you can use the following options:\n\n\u003cdiv align=\"center\"\u003e\n\n[![Sponsor dimzachar](https://img.shields.io/badge/Sponsor-dimzachar-pink?style=for-the-badge\u0026logo=github-sponsors)](https://github.com/sponsors/dimzachar)\n\n\u003ca href=\"https://www.buymeacoffee.com/techietea\" target=\"_blank\"\u003e\n  \u003cimg src=\"https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png\" alt=\"Buy Me A Coffee\" width=\"150\" \u003e\n\u003c/a\u003e\n\n\u003c/div\u003e\n\n**Ethereum Address:**\n```\n0xeB16AdBa798C64CFdb9A0A70C95e1231e4ADe124\n```\n\nYour generosity helps us continue improving Parthenon and creating more exciting features. Thank you for your support! 🙏\n\n## 📬 Contact\n\nFor questions, suggestions, or collaboration opportunities:\n\n[![LinkedIn](https://img.shields.io/badge/LinkedIn-0077B5?style=for-the-badge\u0026logo=linkedin\u0026logoColor=white)](https://www.linkedin.com/in/zacharenakis/)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdimzachar%2Fparthenon-rag-game","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdimzachar%2Fparthenon-rag-game","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdimzachar%2Fparthenon-rag-game/lists"}