Modify readme
#1
by
Agamador
- opened
- .gitattributes +0 -1
- README.md +4 -79
- app.py +4 -27
- media/architecture.png +0 -3
- media/reactAgent.png +0 -3
- prompt.txt +1 -1
.gitattributes
CHANGED
|
@@ -33,4 +33,3 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
|
|
| 33 |
*.zip filter=lfs diff=lfs merge=lfs -text
|
| 34 |
*.zst filter=lfs diff=lfs merge=lfs -text
|
| 35 |
*tfevents* filter=lfs diff=lfs merge=lfs -text
|
| 36 |
-
*.png filter=lfs diff=lfs merge=lfs -text
|
|
|
|
| 33 |
*.zip filter=lfs diff=lfs merge=lfs -text
|
| 34 |
*.zst filter=lfs diff=lfs merge=lfs -text
|
| 35 |
*tfevents* filter=lfs diff=lfs merge=lfs -text
|
|
|
README.md
CHANGED
|
@@ -1,87 +1,12 @@
|
|
| 1 |
---
|
| 2 |
-
title:
|
| 3 |
-
emoji:
|
| 4 |
colorFrom: yellow
|
| 5 |
colorTo: indigo
|
| 6 |
sdk: gradio
|
| 7 |
sdk_version: 5.32.1
|
| 8 |
app_file: app.py
|
| 9 |
-
|
| 10 |
-
- agent-demo-track
|
| 11 |
-
- mcp-server-track
|
| 12 |
---
|
| 13 |
|
| 14 |
-
|
| 15 |
-
Made by: [@Agamador](https://huggingface.co/Agamador) [@Javier-Jimenez99](https://huggingface.co/Javier-Jimenez99)
|
| 16 |
-
|
| 17 |
-
|
| 18 |
-
## 🎥 Video Demo
|
| 19 |
-
|
| 20 |
-
```html
|
| 21 |
-
<iframe width="560" height="315" src="https://www.youtube.com/embed/SlbW-kjekBg?si=r6x8GeVnKLipriZL" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
|
| 22 |
-
```
|
| 23 |
-
|
| 24 |
-
Video Demo: [https://www.youtube.com/watch?v=SlbW-kjekBg&ab_channel=AlejandroGarcíaAmador](https://www.youtube.com/watch?v=SlbW-kjekBg&ab_channel=AlejandroGarcíaAmador)
|
| 25 |
-
|
| 26 |
-
## 🧩 Complete Architecture Overview
|
| 27 |
-

|
| 28 |
-
|
| 29 |
-
## 🔗 Useful Links:
|
| 30 |
-
- [Owlbear Rodeo Chat Interface](https://github.com/Agamador/OwlBear-llm-chat)
|
| 31 |
-
- [MCP server](https://huggingface.co/spaces/Agents-MCP-Hackathon/LLM-GameMaster-MPC-Server)
|
| 32 |
-
- [Video Demo](https://www.youtube.com/watch?v=SlbW-kjekBg&ab_channel=AlejandroGarcíaAmador)
|
| 33 |
-
|
| 34 |
-
## 🌟 Introduction
|
| 35 |
-
|
| 36 |
-
The **LLM Game Master Agent** is a sophisticated AI system designed as a Game Master (GM) for solo medieval fantasy role-playing sessions. This cutting-edge application showcases the power of LangGraph React architecture combined with Model Context Protocol (MCP) technology, creating an immersive and highly adaptive gaming experience unlike anything seen before.
|
| 37 |
-
|
| 38 |
-
Unlike conventional chatbots, this intelligent agent generates dynamic and personalized narratives where YOU become the protagonist in epic fantasy stories. The application leverages state-of-the-art language models to deliver a gaming experience comparable to traditional sessions with a human Game Master, but with the added benefits of AI-powered adaptability and endless creative possibilities.
|
| 39 |
-
|
| 40 |
-
## 🧠 LangGraph React: The System Core
|
| 41 |
-
|
| 42 |
-
The LLM Game Master Agent utilizes [LangGraph](https://github.com/langchain-ai/langgraph) as the central component of its architecture, implementing the React pattern for complex task management.
|
| 43 |
-
|
| 44 |
-
The implementation uses LangGraph's `create_react_agent` function to create a reactive agent that can maintain conversation state, reason over multiple steps, and make informed decisions based on the complete tools execution trace.
|
| 45 |
-
|
| 46 |
-

|
| 47 |
-
|
| 48 |
-
## 🔌 MCP Client: Integration with External Tools
|
| 49 |
-
|
| 50 |
-
The system implements a [Model Context Protocol (MCP)](https://github.com/microsoft/model-context-protocol) client that connects to an external MCP server. This client-server architecture allows the agent to access specialized gaming tools without implementing them directly in the codebase.
|
| 51 |
-
|
| 52 |
-
The implementation uses MCP-specific adapters for LangChain that facilitate communication between the agent and the tools server.
|
| 53 |
-
|
| 54 |
-
This architecture separates the agent logic from the tool implementation, making the system more modular and easier to maintain. The agent can invoke tools as needed through the MCP connection, while focusing on its core narrative generation and decision-making capabilities.
|
| 55 |
-
|
| 56 |
-
## 🤖 Language Model Orchestration
|
| 57 |
-
|
| 58 |
-
The system uses [LangChain](https://www.langchain.com/) to orchestrate language models, offering compatibility with:
|
| 59 |
-
|
| 60 |
-
- **Anthropic Claude**: Claude 3 models via API
|
| 61 |
-
- **Ollama**: Local deployment of models for self-hosted scenarios
|
| 62 |
-
|
| 63 |
-
This flexibility allows selecting the most suitable model based on performance requirements and availability.
|
| 64 |
-
|
| 65 |
-
## 🖥️ Gradio User Interface
|
| 66 |
-
|
| 67 |
-
The application features a complete web interface built with Gradio, offering two main views:
|
| 68 |
-
|
| 69 |
-
1. **Complete View with History**: Shows the conversation along with detailed execution tracking including tools and agent messages.
|
| 70 |
-
2. **Original API**: A simpler interface for API access.
|
| 71 |
-
|
| 72 |
-
The interface includes features for:
|
| 73 |
-
|
| 74 |
-
- Tracking multiple sessions via tab IDs
|
| 75 |
-
- Detailed visualization of tool calls and their results
|
| 76 |
-
- Session management controls
|
| 77 |
-
- API key configuration
|
| 78 |
-
|
| 79 |
-
The execution history provides complete transparency into the agent's decision-making process, showing each step of the interaction between the user, agent, and tools.
|
| 80 |
-
|
| 81 |
-
|
| 82 |
-
## 🔗 Links & Resources
|
| 83 |
-
|
| 84 |
-
- [LangGraph Documentation](https://github.com/langchain-ai/langgraph)
|
| 85 |
-
- [Model Context Protocol (MCP)](https://github.com/microsoft/model-context-protocol)
|
| 86 |
-
- [LangChain](https://www.langchain.com/)
|
| 87 |
-
- [Gradio](https://www.gradio.app/)
|
|
|
|
| 1 |
---
|
| 2 |
+
title: OwlBear Agent
|
| 3 |
+
emoji: 📈
|
| 4 |
colorFrom: yellow
|
| 5 |
colorTo: indigo
|
| 6 |
sdk: gradio
|
| 7 |
sdk_version: 5.32.1
|
| 8 |
app_file: app.py
|
| 9 |
+
pinned: false
|
|
|
|
|
|
|
| 10 |
---
|
| 11 |
|
| 12 |
+
Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
app.py
CHANGED
|
@@ -11,7 +11,6 @@ import os
|
|
| 11 |
import json
|
| 12 |
from datetime import datetime
|
| 13 |
from typing import List, Any
|
| 14 |
-
import re
|
| 15 |
|
| 16 |
load_dotenv()
|
| 17 |
|
|
@@ -343,6 +342,7 @@ with gr.Blocks(title="OwlBear Agent - Complete History", theme=gr.themes.Default
|
|
| 343 |
show_api=False
|
| 344 |
)
|
| 345 |
|
|
|
|
| 346 |
api_demo = gr.Interface(
|
| 347 |
fn=chat,
|
| 348 |
inputs=[
|
|
@@ -353,34 +353,11 @@ api_demo = gr.Interface(
|
|
| 353 |
outputs="text", title="OwlBear Agent - Original API"
|
| 354 |
)
|
| 355 |
|
| 356 |
-
with open("README.md", "r", encoding="utf-8") as f:
|
| 357 |
-
readme = f.read()
|
| 358 |
-
if readme.startswith("---"):
|
| 359 |
-
parts = readme.split("---", 2)
|
| 360 |
-
if len(parts) >= 3:
|
| 361 |
-
readme = parts[2]
|
| 362 |
-
|
| 363 |
-
|
| 364 |
-
html_blocks = re.findall(r'```html\n(.*?)\n```', readme, re.DOTALL)
|
| 365 |
-
for i, html_block in enumerate(html_blocks):
|
| 366 |
-
readme = readme.replace(f"```html\n{html_block}\n```", f"{{HTML_BLOCK_{i}}}")
|
| 367 |
-
|
| 368 |
-
with gr.Blocks() as intro_demo:
|
| 369 |
-
parts = re.split(r'({HTML_BLOCK_\d+})', readme)
|
| 370 |
-
|
| 371 |
-
for part in parts:
|
| 372 |
-
if part.startswith("{HTML_BLOCK_"):
|
| 373 |
-
block_idx = int(part.replace("{HTML_BLOCK_", "").replace("}", ""))
|
| 374 |
-
gr.HTML(html_blocks[block_idx])
|
| 375 |
-
else:
|
| 376 |
-
if part.strip():
|
| 377 |
-
gr.Markdown(part)
|
| 378 |
-
|
| 379 |
# Combined interface with tabs
|
| 380 |
combined_demo = gr.TabbedInterface(
|
| 381 |
-
[
|
| 382 |
-
["
|
| 383 |
-
title="
|
| 384 |
)
|
| 385 |
|
| 386 |
if __name__ == "__main__":
|
|
|
|
| 11 |
import json
|
| 12 |
from datetime import datetime
|
| 13 |
from typing import List, Any
|
|
|
|
| 14 |
|
| 15 |
load_dotenv()
|
| 16 |
|
|
|
|
| 342 |
show_api=False
|
| 343 |
)
|
| 344 |
|
| 345 |
+
# Original API interface for backward compatibility
|
| 346 |
api_demo = gr.Interface(
|
| 347 |
fn=chat,
|
| 348 |
inputs=[
|
|
|
|
| 353 |
outputs="text", title="OwlBear Agent - Original API"
|
| 354 |
)
|
| 355 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 356 |
# Combined interface with tabs
|
| 357 |
combined_demo = gr.TabbedInterface(
|
| 358 |
+
[demo, api_demo],
|
| 359 |
+
["Complete View with History", "Original API"],
|
| 360 |
+
title="🦉 OwlBear Agent - Complete Interface"
|
| 361 |
)
|
| 362 |
|
| 363 |
if __name__ == "__main__":
|
media/architecture.png
DELETED
Git LFS Details
|
media/reactAgent.png
DELETED
Git LFS Details
|
prompt.txt
CHANGED
|
@@ -46,4 +46,4 @@ Silent Operation: You must manage all tools silently. Never announce tool creati
|
|
| 46 |
Never Break Character: If a tool fails or an error occurs (like overlapping tokens), handle it silently or incorporate it diegetically into the story (e.g., "A strange magical distortion makes the area difficult to discern") without ever mentioning the technical problem to the player. You are the GM, not a bot. Maintain your persona unconditionally.
|
| 47 |
Viewport: whenever you make a change to or around the player's tooken, you must use viewport tool to ensure the player sees it.
|
| 48 |
Roll: Whenever an action needs a roll, you must call the roll tool and narrate the result.
|
| 49 |
-
Switching Scenarios: If you need to switch scenarios, you must delete the previous map ("clean_map") and create a new one. You must also ensure that the player token appears in the new map.
|
|
|
|
| 46 |
Never Break Character: If a tool fails or an error occurs (like overlapping tokens), handle it silently or incorporate it diegetically into the story (e.g., "A strange magical distortion makes the area difficult to discern") without ever mentioning the technical problem to the player. You are the GM, not a bot. Maintain your persona unconditionally.
|
| 47 |
Viewport: whenever you make a change to or around the player's tooken, you must use viewport tool to ensure the player sees it.
|
| 48 |
Roll: Whenever an action needs a roll, you must call the roll tool and narrate the result.
|
| 49 |
+
Switching Scenarios: If you need to switch scenarios, you must delete the previous map ("clean_map") and create a new one. You must also ensure that the player token appears in the new map.
|