{"id":17454071,"url":"https://github.com/igorbenav/clientai-dungeon-master","last_synced_at":"2025-04-09T15:51:48.651Z","repository":{"id":258133941,"uuid":"872785377","full_name":"igorbenav/clientai-dungeon-master","owner":"igorbenav","description":"Text-based role-playing game (RPG) where the game's content is dynamically generated by AI models","archived":false,"fork":false,"pushed_at":"2024-11-01T00:27:59.000Z","size":31,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-06T06:48:19.790Z","etag":null,"topics":["chatgpt","clientai","llms","ollama","openai"],"latest_commit_sha":null,"homepage":"","language":"Python","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/igorbenav.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"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}},"created_at":"2024-10-15T04:25:50.000Z","updated_at":"2024-11-01T00:28:03.000Z","dependencies_parsed_at":"2024-10-20T06:29:56.928Z","dependency_job_id":null,"html_url":"https://github.com/igorbenav/clientai-dungeon-master","commit_stats":null,"previous_names":["igorbenav/clientai-dungeon-master"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/igorbenav%2Fclientai-dungeon-master","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/igorbenav%2Fclientai-dungeon-master/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/igorbenav%2Fclientai-dungeon-master/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/igorbenav%2Fclientai-dungeon-master/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/igorbenav","download_url":"https://codeload.github.com/igorbenav/clientai-dungeon-master/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248064062,"owners_count":21041854,"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":["chatgpt","clientai","llms","ollama","openai"],"created_at":"2024-10-18T01:04:09.474Z","updated_at":"2025-04-09T15:51:48.620Z","avatar_url":"https://github.com/igorbenav.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AI Dungeon Master\n\n\u003cp align=\"center\"\u003e\n  \u003ci\u003eAn AI-powered text-based RPG adventure guided by multiple AI models.\u003c/i\u003e\n\u003c/p\u003e\n\nAI Dungeon Master is a text-based role-playing game (RPG) where the game's content is dynamically generated by AI models. This project utilizes the ClientAI package to interact seamlessly with multiple AI providers like OpenAI, Replicate, and Ollama. The game offers infinite replayability and unique experiences for each player by generating story elements, NPC dialogues, and dynamic environments on the fly.\n\n## Features\n\n- 🎮 **Dynamic Storytelling**: Experience unique adventures every time you play.\n- 🤖 **Multiple AI Providers**: Leverage the strengths of different AI models.\n- 🗣️ **Interactive NPCs**: Engage in conversations with AI-generated characters.\n- 🌐 **Rich Environments**: Explore AI-generated settings and scenarios.\n- 🔄 **Replayability**: Infinite possibilities for stories and outcomes.\n- 💡 **Example Project**: Demonstrates how to use the ClientAI package in a practical application.\n\n## Requirements\n\nBefore installing and running AI Dungeon Master, ensure you have the following:\n\n- Python: Version 3.11 or newer.\n- ClientAI: Installed with support for all providers.\n- API Keys: Valid API keys for OpenAI and Replicate.\n- Ollama: Installed for running local AI models.\n- Additional Dependencies: See Installation for details.\n\n## Installation\n\nYou can choose to install and run the project using either pip or Poetry.\n\n### Option 1: Using pip\n\n1. Clone the Repository\n\n```bash\ngit clone https://github.com/yourusername/ai_dungeon_master.git\ncd ai_dungeon_master\n```\n\n2. Set Up a Virtual Environment (Optional but Recommended)\n\n```bash\npython -m venv venv\nsource venv/bin/activate  # On Windows use: venv\\Scripts\\activate\n```\n\n3. Install Dependencies\n\nInstall required Python packages:\n\n```bash\npip install clientai[all] requests python-decouple\n```\n\n### Option 2: Using Poetry\n\n1. Install Poetry (if not already installed):\n\n```bash\ncurl -sSL https://install.python-poetry.org | python3 -\n```\n\n2. Clone the Repository:\n\n```bash\ngit clone https://github.com/igorbenav/ai_dungeon_master.git\ncd ai_dungeon_master\n```\n\n3. Install Dependencies:\n\n```bash\npoetry install\n```\n\nThis will create a virtual environment and install all required dependencies.\n\n### Common Steps for Both Options\n\n4. Install Ollama\n\nFor macOS or Linux:\n\n```bash\ncurl -fsSL https://ollama.ai/install.sh | bash\n```\n\nFor Windows:\n\nDownload the installer from the Ollama GitHub releases page and follow the installation instructions.\n\n5. Pull the Llama 3 Model\n\nAfter installing Ollama, download the Llama 3 model:\n\n```bash\nollama pull llama3\n```\n\nNote: The download may take some time depending on your internet connection.\n\n6. Set Up API Keys\n\nCreate a `.env` file in the project's root directory to store your API keys:\n\n```plaintext\nOPENAI_API_KEY=your_openai_api_key_here\nREPLICATE_API_KEY=your_replicate_api_key_here\n```\n\nReplace `your_openai_api_key_here` and `your_replicate_api_key_here` with your actual API keys.\n\n7. Ensure .env is Ignored by Git\n\nMake sure your `.env` file is listed in your `.gitignore` to prevent accidental commits:\n\n```plaintext\n# .gitignore\n.env\n```\n\n## Running the Game\n\n### Option 1: Using pip\n\nTo start your AI-powered adventure, run the following command from the project's root directory:\n\n```bash\npython ai_dungeon_master/main.py\n```\n\nIf you set up a virtual environment, ensure it's activated before running the command.\n\n### Option 2: Using Poetry\n\nTo start your AI-powered adventure using Poetry, run the following command from the project's root directory:\n\n```bash\npoetry run python ai_dungeon_master/main.py\n```\n\nThis command activates the Poetry virtual environment and runs the main script.\n\n## Project Structure\n\n```\nai_dungeon_master/\n├── ai_dungeon_master/\n│   ├── __init__.py\n│   ├── main.py\n│   ├── ai/\n│   │   ├── __init__.py\n│   │   ├── ai_providers.py\n│   │   └── ollama_server.py\n│   ├── game/\n│   │   ├── __init__.py\n│   │   ├── character.py\n│   │   ├── dungeon_master.py\n│   │   └── game_state.py\n│   └── utils/\n│       ├── __init__.py\n│       └── text_utils.py\n├── .env\n├── .gitignore\n├── README.md\n└── pyproject.toml\n```\n\n## Usage\n\nWhen you run the game, you'll be greeted by the AI Dungeon Master who will guide you through character creation and immerse you in a dynamically generated world.\n\n- Character Creation: Provide your character's name; the AI will generate the rest.\n- Gameplay: Type commands to interact with the environment, such as \"look around,\" \"talk to the innkeeper,\" or \"explore the forest.\"\n- Quitting: You can type \"quit\" at any time to exit the game.\n\n## About ClientAI\n\nThis project is an example of how to use the ClientAI package to interact with multiple AI providers seamlessly.\n\nClientAI is a Python package that provides a unified interface for interacting with various AI models. It simplifies the process of switching between different AI providers and managing API interactions.\n\n- Documentation: [https://igorbenav.github.io/clientai/](https://igorbenav.github.io/clientai/)\n- Repository: [https://github.com/igorbenav/clientai](https://github.com/igorbenav/clientai)\n\n## Tutorial\n\nFor a detailed walkthrough of how this project was built, including explanations of the code and design decisions, refer to the tutorial:\n\n[Creating an AI Dungeon Master with ClientAI](https://igorbenav.github.io/clientai/examples/ai_dungeon_master/)\n\nThis tutorial covers:\n\n- Setting up the project environment.\n- Integrating multiple AI providers.\n- Developing game logic and AI interactions.\n- Managing conversation history and game state.\n- Enhancements and potential improvements.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Contact\n\nIgor Magalhaes – [@igormagalhaesr](https://twitter.com/igormagalhaesr) – igormagalhaesr@gmail.com\n[github.com/igorbenav](https://github.com/igorbenav/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Figorbenav%2Fclientai-dungeon-master","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Figorbenav%2Fclientai-dungeon-master","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Figorbenav%2Fclientai-dungeon-master/lists"}