Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

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

Awesome Lists containing this project

README 

        


  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



  
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 Client



api_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



```