Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mluogh/eastworld
Framework for Generative Agents in Games
https://github.com/mluogh/eastworld
generative-agents
Last synced: 3 months ago
JSON representation
Framework for Generative Agents in Games
- Host: GitHub
- URL: https://github.com/mluogh/eastworld
- Owner: mluogh
- License: apache-2.0
- Created: 2023-08-24T13:06:29.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2023-11-13T13:40:26.000Z (12 months ago)
- Last Synced: 2024-05-14T00:50:41.585Z (6 months ago)
- Topics: generative-agents
- Language: Python
- Homepage:
- Size: 4.92 MB
- Stars: 181
- Watchers: 6
- Forks: 15
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
- awesome-ai-tools-for-game-dev - eastworld - of-the-box with capabilites like taking actions in your world (AI NPC)
README
eastworldeastworld is an open-source, language-agnostic framework for adding Generative
Agents to your video games, visual novels, and other forms of interactive media.This framework has two goals
- To abstract away the complexities of prompt-engineering detailed Agents and
elaborate Storylines using an easy to use no-code dashboard- To enable a variety of user-agent interactions out of the box beyond just
chat - Agent Actions, Emotion Queries, Player Guardrails, etc. - and expose it
in a simple small APIhttps://github.com/mluogh/eastworld/assets/8098155/6ed272f0-64d2-458e-bb8a-27a1e0741a9b
A
playable murder mystery game whose Agents were made with eastworld
See how you can add an agent to your game in ~5 minutes
# Features
### Agents
- Agents can perform user-defined actions, not just chat:
- e.g. Player: "I'm going to attack you!" -> Agent: RunAway(speed=fast)
- includes guardrails to ask players to stay in character
- i.e. block players trying to jailbreak or from anachronistic behaviour like
asking for a phone in a medieval game
- query agent's inner thoughts and emotions mid-conversation
- e.g. (to agent) "How suspicious are you that {player} suspects you as the
murderer?" -> very
- can trigger events in your game based off of this
- set manner of speech, dialect, and accents
- e.g. Peasant: "Just workin', yer Majesty. Fields ain't gonna plow 'emselves,
are they?"
- selective memory to cut down on LLM inference costs
- i.e. vector embedding based retrieval of memories
- and more!### Agent Studio
No-code tool to simplify Agent and Story prompt-engineering.
- construct characters' biographies, core beliefs, dialects, etc
- manage who knows which aspects of your world's Shared Lore to keep storylines
consistent
- define Actions (function completions) that Agents can take
- use the chatbox with built-in debugging tools to quickly iterate on Agents### Server
NOTE: _not prod ready yet - lacks client authentication_
- exposes OpenAPI spec so **high quality clients can be autogenerated in any
language**
- blazing fast with [FastAPI](https://github.com/tiangolo/fastapi) and async LLM
completions
- supports local models out of the box with
[LocalAI](https://github.com/go-skynet/LocalAI)
- simple deploy - only requires redis# Installation
## Prerequisites
The framework and server requires Python 3.10+,
[PDM package manager](https://github.com/pdm-project/pdm), and Redis.The Agent Studio tool requires Node 19+.
##### MacOS
```
brew install redis pdm node
```If later on you get SSL certification issues with OpenAI, see
[this](https://stackoverflow.com/questions/27835619/urllib-and-ssl-certificate-verify-failed-error)### Linux
1. [Install Redis](https://redis.io/docs/getting-started/installation/install-redis-on-linux/),
if you don't already have it. Most distros should come with it.
2. Install our [package manager PDM](https://pdm.fming.dev/latest/)
3. Install
[Node](https://nodejs.org/en/download/package-manager#debian-and-ubuntu-based-linux-distributions)### Windows
1. [Install Redis](https://redis.io/docs/getting-started/installation/install-redis-on-windows/)
2. Install our [package manager PDM](https://pdm.fming.dev/latest/)
3. Install
[Node for Windows](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm#windows-node-version-managers)## Install packages
Enter the repo and run:
```
pdm install
```Install the frontend tooling:
```
cd app && npm install
```# Run
**IMPORTANT: Copy the example configuration file to config.ini**
In main folder:
```
cp example_config.ini config.ini
```### Set up your LLM
_(Easier)_ Setting up an OpenAI model:
In `config.ini`, make sure the the following is set (especially the
`openai_api_key`!):```
[llm]
use_local_llm = false
openai_api_key = sk-my_openai_key# Takes either {gpt-3.5-turbo, gpt-4} (or timestamped versions thereof)
# gpt-3.5-turbo is enough to produce very believable characters
# gpt-4 is amazing, but extremely expensive right now
chat_model = gpt-3.5-turbo# text-embedding-ada-002
embedding_size = 1536
```_(Harder)_ To connect to a locally running model,
[see below](#using-local-models).## Start
For the backend, in separate terminal windows, run:
```
redis-server
``````
pdm run uvicorn server.main:app --reload
```By default, the server runs on `http://localhost:8000`
For the Agent Studio tool:
```
cd app && npm start
```This runs by default on `http://localhost:8000`
# Play Example Game
We have an example game that you can play to get your bearings and see what the
framework is capable of.[nob hill noir](https://github.com/mluogh/grontown)
# Create
### Creating games
There is a demo game included with the Agent Studio when you run it for the
first time. You can look through it and mess around with it to understand the
framework.We recommend looking at
[this video](https://www.youtube.com/watch?v=VSqIzjOk5p4) to understand Agent
Studio workflow.### Using agents in your games
- Generate a client for your language. You can
[install OpenAPI generator](https://github.com/OpenAPITools/openapi-generator)
or language-specific generator- The language specific ones seem to generate more idiomatic clients
- e.g. We used
[this one](https://github.com/openapi-generators/openapi-python-client)
for python,
[this one](https://github.com/ferdikoomen/openapi-typescript-codegen) for
TypeScript
- point the generator to `http://localhost:8000/openapi.json`- Direct the client's to your server (during development this should be
`http://localhost:8000`)- The core API consists of:
```
createSession() // call it to initiate an instance of the game
startChat() // starts a new chat and clears old conversation
chat() // Agent says something
interact() // Agent may chat or perform an Action
action() // ask Agent to perform an Action
query() // emotional queries into Agent's inner thoughts
guardrail() // make sure player respects tone/time period/etc of game
```- Read the more detailed Swagger documentation at
http://localhost:8000/docs#/Game%20Sessions. The `Game Sessions` API is what
you need for your game.
- See [Recipes](#recipes) for examples.### Coming Soon: SDKs for Game & Visual Novel Engines:
Have requests for one in particular? Ask in
[the discord](https://discord.gg/9V5URE9f4T)# Misc
### Contributing tips:
- we use prettier and eslint for `app/`
- we use ruff and black-formatter for python code
- if you change a Pydantic schema, you need to
`cd app && npm run generate-client` to reflect those changes in the frontend
client.### Using local models:
Note that as of writing, agents are of much higher quality using GPT-3.5 or
GPT-4 than any other model we tested.- Install
[docker-compose (recommended)](https://docs.docker.com/compose/install) or
[docker](https://docs.docker.com/engine/install)- [Install LocalAI](https://localai.io/basics/getting_started) and follow the
instructions- You will need two models that are
[compatible with LocalAI](https://localai.io/model-compatibility/). Most GGML
models are compatible. If you want Agents to take actions, you need a
[function-calling compatible model](https://localai.io/features/openai-functions/index.html)- you need a chat-tuned LLM - e.g.
[WizardLM 13b uncensored](https://huggingface.co/TheBloke/Wizard-Vicuna-13B-Uncensored-GGML)
- you need an [embedding model](https://localai.io/features/embeddings) -
follow the guide to create a config
- NOTE: follow the instructions to set `name: text-embedding-ada-002`.- Change `config.ini`
```
[llm]
use_local_llm = true
openai_api_key = dummy_value# I'm jealous of people with enough compute to run local models!
chat_model = my_local_model_name
embedding_size = dims_of_my_embedding_model
```- Restart the server to test it out!
### Recipes
#### TypeScript
Using
[this generator](https://github.com/ferdikoomen/openapi-typescript-codegen) for
TypeScript.```typescript
// in app.tsx
import { OpenAPI } from "client";
...
OpenAPI.BASE = "http://localhost:8000";// in interact.tsx
const sessUuid = await GameSessionsService.createSession(
params.gameUuid!,
);
...
const emptyChat = { conversation: { correspondent: MyCharacter } , history: [] };
await GameSessionsService.startChat(
sessionUuid!,
params.agentUuid!,
emptyChat,
);...
const interact = await GameSessionsService.interact(
sessionUuid!,
params.agentUuid!,
text,
);if (isAction(interact)) {
// Character.actions[...]()
} else {
// render message
}
```#### Python
We used
[this generator](https://github.com/openapi-generators/openapi-python-client)
for Python.```python
from game_client import Clientapi_client = Client(base_url="http://localhost:8000")
# ...
session_uuid = create.sync(
game_uuid=game_uuid,
client=api_client
)# ...
response = chat.sync(
session_uuid=session_uuid,
client=client,
agent="Agent Name",
message=message
)# do something with response
```