# 🎮 LLMAdventure - AI-Powered Text Adventure Game
[](https://pypi.org/project/llmadventure/)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://pepy.tech/project/llmadventure)
[](https://github.com/SoftwareApkDev/llmadventure)
> **Create infinite stories with AI-powered procedural generation** 🚀
**LLMAdventure** is the ultimate CLI text adventure game that uses Google's Gemini 2.5 Flash to generate unique, dynamic stories, worlds, and characters. Every playthrough is different, every choice matters, and every adventure is unforgettable.
## ✨ Why Choose LLMAdventure?
- 🎯 **Infinite Content**: AI generates unique stories, quests, and worlds
- 🎮 **Rich Gameplay**: Combat, exploration, character progression, and more
- 🎨 **Beautiful CLI**: Stunning terminal interface with colors and animations
- 🔌 **Extensible**: Plugin system for custom content and mods
- 🌐 **Multi-Platform**: Works on Windows, macOS, and Linux
- 📚 **Educational**: Learn AI, game development, and storytelling
- 🚀 **Fast**: Optimized for performance and responsiveness
## 🚀 Quick Start
```bash
# Install from PyPI
pip install llmadventure
# Start your adventure
llmadventure
```
**That's it!** No complex setup, no dependencies to manage. Just pure adventure.
## 🎯 Features
### 🧠 AI-Powered Storytelling
- **Dynamic Narrative Generation**: Every story is unique and adaptive
- **Context-Aware Responses**: AI remembers your choices and adapts the story
- **Procedural World Building**: Infinite worlds with unique locations and lore
- **Character Generation**: Rich NPCs with personalities and backstories
### ⚔️ Rich Gameplay Systems
- **Combat System**: Turn-based combat with strategy and tactics
- **Character Progression**: Level up, gain abilities, and evolve your character
- **Inventory Management**: Collect, use, and trade items
- **Quest System**: Dynamic quests that adapt to your choices
- **Exploration**: Discover hidden locations and secrets
### 🎨 Beautiful Interface
- **Rich Terminal UI**: Colors, progress bars, and animations
- **Responsive Design**: Works on any terminal size
- **Accessibility**: High contrast modes and screen reader support
- **Customizable**: Themes and appearance options
### 🔌 Extensible Architecture
- **Plugin System**: Create custom content and mods
- **API Access**: Integrate with other applications
- **Web Interface**: Optional web-based UI
- **Multiplayer Support**: Play with friends (coming soon)
## 📖 Examples
### Basic Usage
```python
from llmadventure import Game
# Start a new adventure
game = Game()
game.start_new_game("Hero", "warrior")
# Explore the world
game.move("north")
game.look_around()
game.attack("dragon")
```
### Custom Plugin
LLMAdventure supports a flexible plugin system. To create a plugin, inherit from the `Plugin` base class and use the `register_plugin` decorator from `llmadventure.plugins`:
```python
from llmadventure.plugins import Plugin, register_plugin
@register_plugin
class MyCustomPlugin(Plugin):
name = "My Custom Plugin"
version = "1.0.0"
description = "A custom plugin for LLMAdventure"
def on_combat_start(self, player, enemy):
# Add custom combat mechanics
pass
def on_quest_complete(self, player, quest):
# Give custom rewards
pass
```
### Web Integration
```python
from llmadventure.web import WebServer
# Start web interface
server = WebServer()
server.start(host="0.0.0.0", port=8000)
```
## 🛠️ Installation
### From PyPI (Recommended)
```bash
pip install llmadventure
```
### With Optional Dependencies
```bash
# Full installation with all features
pip install "llmadventure[full]"
# Web interface
pip install "llmadventure[web]"
# AI/ML features
pip install "llmadventure[ai]"
# Data analysis
pip install "llmadventure[data]"
```
### From Source
```bash
git clone https://github.com/SoftwareApkDev/llmadventure.git
cd llmadventure
pip install -e .
```
## 🔧 Configuration
### API Key Setup
1. Get a Google AI API key from [Google AI Studio](https://makersuite.google.com/app/apikey)
2. Set your API key:
```bash
# Environment variable
export GOOGLE_API_KEY=your_key_here
# Or in .env file
echo "GOOGLE_API_KEY=your_key_here" > .env
```
### Configuration File
Create `~/.config/llmadventure/config.yaml`:
```yaml
api:
provider: "google"
model: "gemini-2.5-flash"
game:
auto_save: true
difficulty: "normal"
theme: "dark"
ui:
colors: true
animations: true
sound: false
```
## 🎮 Game Controls
| Command | Action | Aliases |
|-------------------|-----------------|--------------------|
| `n`, `north` | Move north | `up`, `u` |
| `s`, `south` | Move south | `down`, `d` |
| `e`, `east` | Move east | `right`, `r` |
| `w`, `west` | Move west | `left`, `l` |
| `look` | Look around | `l`, `examine` |
| `inventory` | Show inventory | `i`, `inv` |
| `attack <target>` | Attack creature | `fight`, `hit` |
| `use <item>` | Use item | `consume`, `equip` |
| `talk <npc>` | Talk to NPC | `speak`, `chat` |
| `save` | Save game | `s` |
| `quit` | Quit game | `exit`, `q` |
| `help` | Show help | `h`, `?` |
## 🏗️ Architecture
```
llmadventure/
├── core/ # Core game logic (game, player, world, combat, inventory, quest, evolution, creature)
├── engine/ # AI, LLM interface, memory, procedural generation, prompt templates
├── cli/ # Command line interface (display, menus)
├── utils/ # Utilities (config, file_ops, logger)
├── plugins/ # Plugin system
├── web/ # Web interface (if enabled)
main.py # Entry point
requirements.txt # Python dependencies
pyproject.toml # Build system and metadata
README.md # Project documentation
```
## 🔌 Plugin Development
Create custom content with our plugin system:
```python
from llmadventure.plugins import Plugin, register_plugin
@register_plugin
class MyPlugin(Plugin):
name = "My Custom Plugin"
version = "1.0.0"
def on_game_start(self, game):
# Add custom game mechanics
pass
def on_combat_turn(self, player, enemy):
# Modify combat behavior
pass
```
## 🌐 Web Interface
Start the web interface for a graphical experience:
```bash
# Install web dependencies
pip install "llmadventure[web]"
# Start web server
llmadventure --web
# Or programmatically
from llmadventure.web import start_web_server
start_web_server(port=8000)
```
## 📊 Analytics & Insights
Track your adventures with built-in analytics:
```python
from llmadventure.analytics import AdventureTracker
tracker = AdventureTracker()
stats = tracker.get_player_stats()
print(f"Adventures completed: {stats['adventures']}")
print(f"Creatures defeated: {stats['creatures_defeated']}")
print(f"Distance traveled: {stats['distance_traveled']}")
```
## 🧪 Testing
Run the comprehensive test suite:
```bash
# Install test dependencies
pip install "llmadventure[dev]"
# Run tests
pytest
# Run with coverage
pytest --cov=llmadventure
# Run specific test categories
pytest -m "not slow"
pytest -m integration
```
## 🤝 Contributing
We welcome contributions! Here's how to get started:
1. **Fork** the repository
2. **Create** a feature branch
3. **Make** your changes
4. **Add** tests for new features
5. **Submit** a pull request
### Development Setup
```bash
git clone https://github.com/SoftwareApkDev/llmadventure.git
cd llmadventure
pip install -e ".[dev]"
pre-commit install
```
### Code Quality
We use several tools to maintain code quality:
- **Black**: Code formatting
- **isort**: Import sorting
- **flake8**: Linting
- **mypy**: Type checking
- **pytest**: Testing
## 📈 Performance
LLMAdventure is optimized for performance:
- **Fast Startup**: < 1 second to begin playing
- **Responsive UI**: Real-time updates and animations
- **Efficient AI**: Optimized prompts and caching
- **Memory Efficient**: Minimal resource usage
## 📚 Documentation
- **[User Guide](https://docs.llmadventure.com/user-guide)**: Complete game manual
- **[API Reference](https://docs.llmadventure.com/api)**: Developer documentation
- **[Plugin Guide](https://docs.llmadventure.com/plugins)**: Creating custom content
- **[Tutorials](https://docs.llmadventure.com/tutorials)**: Step-by-step guides
## 🆘 Support
- **📧 Email**: softwareapkdev2022@gmail.com
- **🐛 Issues**: [GitHub Issues](https://github.com/SoftwareApkDev/llmadventure/issues)
## 🙏 Acknowledgments
- **Google Gemini 2.5 Flash** for AI capabilities
- **Rich** library for beautiful CLI interfaces
- **Typer** for command-line interface
- **Pydantic** for data validation
- **The open-source community** for inspiration and support
## 🌟 Star History
[](https://star-history.com/#llmadventure/llmadventure&Date)
---
**Ready for your next adventure?** 🗡️⚔️🏰
```bash
pip install llmadventure
llmadventure
```
*Join thousands of adventurers creating infinite stories with AI!* 🚀
Raw data
{
"_id": null,
"home_page": null,
"name": "llmadventure",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "SoftwareApkDev <softwareapkdev2022@gmail.com>",
"keywords": "ai, game, adventure, cli, text-adventure, gemini, llm, rpg, storytelling, procedural-generation, interactive-fiction, terminal-game, ai-gaming, machine-learning, natural-language",
"author": null,
"author_email": "SoftwareApkDev <softwareapkdev2022@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/c3/f4/e2bb56fcfa31e28c15b1020dca18c05a5ba7372191584337d28a283a4944/llmadventure-1.0.4.tar.gz",
"platform": null,
"description": "# \ud83c\udfae LLMAdventure - AI-Powered Text Adventure Game\n\n[](https://pypi.org/project/llmadventure/)\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n[](https://pepy.tech/project/llmadventure)\n[](https://github.com/SoftwareApkDev/llmadventure)\n\n> **Create infinite stories with AI-powered procedural generation** \ud83d\ude80\n\n**LLMAdventure** is the ultimate CLI text adventure game that uses Google's Gemini 2.5 Flash to generate unique, dynamic stories, worlds, and characters. Every playthrough is different, every choice matters, and every adventure is unforgettable.\n\n## \u2728 Why Choose LLMAdventure?\n\n- \ud83c\udfaf **Infinite Content**: AI generates unique stories, quests, and worlds\n- \ud83c\udfae **Rich Gameplay**: Combat, exploration, character progression, and more\n- \ud83c\udfa8 **Beautiful CLI**: Stunning terminal interface with colors and animations\n- \ud83d\udd0c **Extensible**: Plugin system for custom content and mods\n- \ud83c\udf10 **Multi-Platform**: Works on Windows, macOS, and Linux\n- \ud83d\udcda **Educational**: Learn AI, game development, and storytelling\n- \ud83d\ude80 **Fast**: Optimized for performance and responsiveness\n\n## \ud83d\ude80 Quick Start\n\n```bash\n# Install from PyPI\npip install llmadventure\n\n# Start your adventure\nllmadventure\n```\n\n**That's it!** No complex setup, no dependencies to manage. Just pure adventure.\n\n## \ud83c\udfaf Features\n\n### \ud83e\udde0 AI-Powered Storytelling\n- **Dynamic Narrative Generation**: Every story is unique and adaptive\n- **Context-Aware Responses**: AI remembers your choices and adapts the story\n- **Procedural World Building**: Infinite worlds with unique locations and lore\n- **Character Generation**: Rich NPCs with personalities and backstories\n\n### \u2694\ufe0f Rich Gameplay Systems\n- **Combat System**: Turn-based combat with strategy and tactics\n- **Character Progression**: Level up, gain abilities, and evolve your character\n- **Inventory Management**: Collect, use, and trade items\n- **Quest System**: Dynamic quests that adapt to your choices\n- **Exploration**: Discover hidden locations and secrets\n\n### \ud83c\udfa8 Beautiful Interface\n- **Rich Terminal UI**: Colors, progress bars, and animations\n- **Responsive Design**: Works on any terminal size\n- **Accessibility**: High contrast modes and screen reader support\n- **Customizable**: Themes and appearance options\n\n### \ud83d\udd0c Extensible Architecture\n- **Plugin System**: Create custom content and mods\n- **API Access**: Integrate with other applications\n- **Web Interface**: Optional web-based UI\n- **Multiplayer Support**: Play with friends (coming soon)\n\n## \ud83d\udcd6 Examples\n\n### Basic Usage\n\n```python\nfrom llmadventure import Game\n\n# Start a new adventure\ngame = Game()\ngame.start_new_game(\"Hero\", \"warrior\")\n\n# Explore the world\ngame.move(\"north\")\ngame.look_around()\ngame.attack(\"dragon\")\n```\n\n### Custom Plugin\n\nLLMAdventure supports a flexible plugin system. To create a plugin, inherit from the `Plugin` base class and use the `register_plugin` decorator from `llmadventure.plugins`:\n\n```python\nfrom llmadventure.plugins import Plugin, register_plugin\n\n@register_plugin\nclass MyCustomPlugin(Plugin):\n name = \"My Custom Plugin\"\n version = \"1.0.0\"\n description = \"A custom plugin for LLMAdventure\"\n\n def on_combat_start(self, player, enemy):\n # Add custom combat mechanics\n pass\n \n def on_quest_complete(self, player, quest):\n # Give custom rewards\n pass\n```\n\n### Web Integration\n\n```python\nfrom llmadventure.web import WebServer\n\n# Start web interface\nserver = WebServer()\nserver.start(host=\"0.0.0.0\", port=8000)\n```\n\n## \ud83d\udee0\ufe0f Installation\n\n### From PyPI (Recommended)\n\n```bash\npip install llmadventure\n```\n\n### With Optional Dependencies\n\n```bash\n# Full installation with all features\npip install \"llmadventure[full]\"\n\n# Web interface\npip install \"llmadventure[web]\"\n\n# AI/ML features\npip install \"llmadventure[ai]\"\n\n# Data analysis\npip install \"llmadventure[data]\"\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/SoftwareApkDev/llmadventure.git\ncd llmadventure\npip install -e .\n```\n\n## \ud83d\udd27 Configuration\n\n### API Key Setup\n\n1. Get a Google AI API key from [Google AI Studio](https://makersuite.google.com/app/apikey)\n2. Set your API key:\n\n```bash\n# Environment variable\nexport GOOGLE_API_KEY=your_key_here\n\n# Or in .env file\necho \"GOOGLE_API_KEY=your_key_here\" > .env\n```\n\n### Configuration File\n\nCreate `~/.config/llmadventure/config.yaml`:\n\n```yaml\napi:\n provider: \"google\"\n model: \"gemini-2.5-flash\"\n \ngame:\n auto_save: true\n difficulty: \"normal\"\n theme: \"dark\"\n \nui:\n colors: true\n animations: true\n sound: false\n```\n\n## \ud83c\udfae Game Controls\n\n| Command | Action | Aliases |\n|-------------------|-----------------|--------------------|\n| `n`, `north` | Move north | `up`, `u` |\n| `s`, `south` | Move south | `down`, `d` |\n| `e`, `east` | Move east | `right`, `r` |\n| `w`, `west` | Move west | `left`, `l` |\n| `look` | Look around | `l`, `examine` |\n| `inventory` | Show inventory | `i`, `inv` |\n| `attack <target>` | Attack creature | `fight`, `hit` |\n| `use <item>` | Use item | `consume`, `equip` |\n| `talk <npc>` | Talk to NPC | `speak`, `chat` |\n| `save` | Save game | `s` |\n| `quit` | Quit game | `exit`, `q` |\n| `help` | Show help | `h`, `?` |\n\n## \ud83c\udfd7\ufe0f Architecture\n\n```\nllmadventure/\n\u251c\u2500\u2500 core/ # Core game logic (game, player, world, combat, inventory, quest, evolution, creature)\n\u251c\u2500\u2500 engine/ # AI, LLM interface, memory, procedural generation, prompt templates\n\u251c\u2500\u2500 cli/ # Command line interface (display, menus)\n\u251c\u2500\u2500 utils/ # Utilities (config, file_ops, logger)\n\u251c\u2500\u2500 plugins/ # Plugin system\n\u251c\u2500\u2500 web/ # Web interface (if enabled)\n\nmain.py # Entry point\nrequirements.txt # Python dependencies\npyproject.toml # Build system and metadata\nREADME.md # Project documentation\n```\n\n## \ud83d\udd0c Plugin Development\n\nCreate custom content with our plugin system:\n\n```python\nfrom llmadventure.plugins import Plugin, register_plugin\n\n@register_plugin\nclass MyPlugin(Plugin):\n name = \"My Custom Plugin\"\n version = \"1.0.0\"\n \n def on_game_start(self, game):\n # Add custom game mechanics\n pass\n \n def on_combat_turn(self, player, enemy):\n # Modify combat behavior\n pass\n```\n\n## \ud83c\udf10 Web Interface\n\nStart the web interface for a graphical experience:\n\n```bash\n# Install web dependencies\npip install \"llmadventure[web]\"\n\n# Start web server\nllmadventure --web\n\n# Or programmatically\nfrom llmadventure.web import start_web_server\nstart_web_server(port=8000)\n```\n\n## \ud83d\udcca Analytics & Insights\n\nTrack your adventures with built-in analytics:\n\n```python\nfrom llmadventure.analytics import AdventureTracker\n\ntracker = AdventureTracker()\nstats = tracker.get_player_stats()\nprint(f\"Adventures completed: {stats['adventures']}\")\nprint(f\"Creatures defeated: {stats['creatures_defeated']}\")\nprint(f\"Distance traveled: {stats['distance_traveled']}\")\n```\n\n## \ud83e\uddea Testing\n\nRun the comprehensive test suite:\n\n```bash\n# Install test dependencies\npip install \"llmadventure[dev]\"\n\n# Run tests\npytest\n\n# Run with coverage\npytest --cov=llmadventure\n\n# Run specific test categories\npytest -m \"not slow\"\npytest -m integration\n```\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! Here's how to get started:\n\n1. **Fork** the repository\n2. **Create** a feature branch\n3. **Make** your changes\n4. **Add** tests for new features\n5. **Submit** a pull request\n\n### Development Setup\n\n```bash\ngit clone https://github.com/SoftwareApkDev/llmadventure.git\ncd llmadventure\npip install -e \".[dev]\"\npre-commit install\n```\n\n### Code Quality\n\nWe use several tools to maintain code quality:\n\n- **Black**: Code formatting\n- **isort**: Import sorting\n- **flake8**: Linting\n- **mypy**: Type checking\n- **pytest**: Testing\n\n## \ud83d\udcc8 Performance\n\nLLMAdventure is optimized for performance:\n\n- **Fast Startup**: < 1 second to begin playing\n- **Responsive UI**: Real-time updates and animations\n- **Efficient AI**: Optimized prompts and caching\n- **Memory Efficient**: Minimal resource usage\n\n## \ud83d\udcda Documentation\n\n- **[User Guide](https://docs.llmadventure.com/user-guide)**: Complete game manual\n- **[API Reference](https://docs.llmadventure.com/api)**: Developer documentation\n- **[Plugin Guide](https://docs.llmadventure.com/plugins)**: Creating custom content\n- **[Tutorials](https://docs.llmadventure.com/tutorials)**: Step-by-step guides\n\n## \ud83c\udd98 Support\n\n- **\ud83d\udce7 Email**: softwareapkdev2022@gmail.com\n- **\ud83d\udc1b Issues**: [GitHub Issues](https://github.com/SoftwareApkDev/llmadventure/issues)\n\n## \ud83d\ude4f Acknowledgments\n\n- **Google Gemini 2.5 Flash** for AI capabilities\n- **Rich** library for beautiful CLI interfaces\n- **Typer** for command-line interface\n- **Pydantic** for data validation\n- **The open-source community** for inspiration and support\n\n## \ud83c\udf1f Star History\n\n[](https://star-history.com/#llmadventure/llmadventure&Date)\n\n---\n\n**Ready for your next adventure?** \ud83d\udde1\ufe0f\u2694\ufe0f\ud83c\udff0\n\n```bash\npip install llmadventure\nllmadventure\n```\n\n*Join thousands of adventurers creating infinite stories with AI!* \ud83d\ude80\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "\ud83c\udfae AI-Powered CLI Text Adventure Game - Create infinite stories with LLM",
"version": "1.0.4",
"project_urls": {
"Repository": "https://github.com/SoftwareApkDev/llmadventure"
},
"split_keywords": [
"ai",
" game",
" adventure",
" cli",
" text-adventure",
" gemini",
" llm",
" rpg",
" storytelling",
" procedural-generation",
" interactive-fiction",
" terminal-game",
" ai-gaming",
" machine-learning",
" natural-language"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4c53747d0c4d7f5c3e0da176095f16a1eb3f7bb7c4f4cabe8e79196088c9ac28",
"md5": "a278a3fc55c774cda7f9d9e269ac9809",
"sha256": "814560b2460907493aa125b587e2dd1adaa431bc99f0b96fa2b5908c68acd004"
},
"downloads": -1,
"filename": "llmadventure-1.0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a278a3fc55c774cda7f9d9e269ac9809",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 47798,
"upload_time": "2025-08-03T11:27:34",
"upload_time_iso_8601": "2025-08-03T11:27:34.839651Z",
"url": "https://files.pythonhosted.org/packages/4c/53/747d0c4d7f5c3e0da176095f16a1eb3f7bb7c4f4cabe8e79196088c9ac28/llmadventure-1.0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c3f4e2bb56fcfa31e28c15b1020dca18c05a5ba7372191584337d28a283a4944",
"md5": "074da6b1012c47a436693bb21761302b",
"sha256": "f282ba50160c4f1b9f5344b4041e2684148b4c2b310d882a2192f6d9e8c4b05e"
},
"downloads": -1,
"filename": "llmadventure-1.0.4.tar.gz",
"has_sig": false,
"md5_digest": "074da6b1012c47a436693bb21761302b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 48299,
"upload_time": "2025-08-03T11:27:36",
"upload_time_iso_8601": "2025-08-03T11:27:36.128992Z",
"url": "https://files.pythonhosted.org/packages/c3/f4/e2bb56fcfa31e28c15b1020dca18c05a5ba7372191584337d28a283a4944/llmadventure-1.0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-03 11:27:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "SoftwareApkDev",
"github_project": "llmadventure",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "google-generativeai",
"specs": [
[
">=",
"0.3.0"
]
]
},
{
"name": "rich",
"specs": [
[
">=",
"13.0.0"
]
]
},
{
"name": "click",
"specs": [
[
">=",
"8.0.0"
]
]
},
{
"name": "pydantic",
"specs": [
[
">=",
"2.0.0"
]
]
},
{
"name": "typer",
"specs": [
[
">=",
"0.9.0"
]
]
},
{
"name": "colorama",
"specs": [
[
">=",
"0.4.6"
]
]
},
{
"name": "pyyaml",
"specs": [
[
">=",
"6.0"
]
]
},
{
"name": "python-dotenv",
"specs": [
[
">=",
"1.0.0"
]
]
}
],
"lcname": "llmadventure"
}
JSON
