eastworld

💬 Get help on discord

eastworld 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 API

https://github.com/mluogh/eastworld/assets/8098155/6ed272f0-64d2-458e-bb8a-27a1e0741a9b

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 and async LLM completions
• supports local models out of the box with LocalAI
• simple deploy - only requires redis

Installation

Prerequisites

The framework and server requires Python 3.10+, PDM package manager, 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

Linux

1. Install Redis, if you don't already have it. Most distros should come with it.
2. Install our package manager PDM
3. Install Node

Windows

1. Install Redis
2. Install our package manager PDM
3. Install Node for Windows

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] uselocalllm = false openaiapikey = sk-myopenaikey

# 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.

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

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 to understand Agent Studio workflow.

Using agents in your games

• Generate a client for your language. You can install OpenAPI generator or language-specific generator

  • The language specific ones seem to generate more idiomatic clients
  • e.g. We used this one for python, this one 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 for examples.

Coming Soon: SDKs for Game & Visual Novel Engines:

Have requests for one in particular? Ask in the discord

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) or docker

• Install LocalAI and follow the instructions

• You will need two models that are compatible with LocalAI. Most GGML models are compatible. If you want Agents to take actions, you need a function-calling compatible model

  • you need a chat-tuned LLM - e.g. WizardLM 13b uncensored
  • you need an embedding model - follow the guide to create a config
  • NOTE: follow the instructions to set name: text-embedding-ada-002.

• Change config.ini

``` [llm] uselocalllm = true openaiapikey = dummy_value

# I'm jealous of people with enough compute to run local models! chatmodel = mylocalmodelname embeddingsize = dimsofmyembedding_model ```

• Restart the server to test it out!

Recipes

TypeScript

Using this generator 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 for Python.

```python from game_client import Client

apiclient = Client(baseurl="http://localhost:8000")

...

sessionuuid = create.sync( gameuuid=gameuuid, client=apiclient )

...

response = chat.sync( sessionuuid=sessionuuid, client=client, agent="Agent Name", message=message )

do something with response

```