Intelligent Agents

About

Super Mind is a software that connects AI agents with a range of IM and VR software, making their deployment easier. You pick a bot, fill the account data and you're able to converse with a bot using SMS, Twitter or other social media.

Made in partnership with SuperReality, a free open source teaching platform for everyone.

Digital Being is written in Typescript and Python. Typescript is used for the clients of most known social networks, as well as XR-Engine, a 3D metaverse architecture. A layer that connects the AI agents is called the server, and is written in Python.

Digital Being supports:

The Client is using either the API for connecting to the different services like Discord, Messenger, etc, or Puppeteer for emulating the browser to connect to the XR-Engine and Zoom.

Out of the box, the server supports these AI bots:

DiaoloGPT
GPTNeo
Wizard of Wikipedia
OpenChat
GPT-j
Droidlet
Rasa
GPT-3 by OpenAI
AI agents by Metaintelligence
Thales Agent

The server can fetch chat history and transform it to a list.

The client is connected with the server using TCP sockets, sending JSON-encoded packets.

Right now these TCP packets may contain:

sendMessage - chat packet message
sendSlashCommand - Discord slash command - can be implemented to other clients too
sendUserUpdateEvent - on Discord join server, leave, on online, idle or offline, all events can be fed to agents
sendGetAgents - returns a list of the active agents
sendSetAgentsFields - this command can be used to update the context of an agent
sendPingSoloAgent - this command can be used to ping an agent directly, if many agents are active
sendMessageReaction - this command is sent when a user reacts to a message, currently implemented in Discord
sendMessageEdit - this command is sent when a message is edited, in order to update the agent’s response too
sendMetadata - this command is used to send the metadata of the current server - currently implemented in Discord and the XR-Engine

New packets can be implemented easily, the only thing to be noted is that the ID should be different from the old packets, also the packet should be sent as a JSON string, like the examples, to avoid any issues with the server. More info about Networking

Requirements

Digital Being requires the following to run:

Node.JS - version 16 or more
NPM - will be installed through Node.JS
Python - version 3.8 or more
Docker - makes the setup easy through using the containers

Setup

Docker (WSL/Linux):

Install Docker
Install docker-compose
Clone the repository and switch to its directory
Run the docker-compose build command to build the containers
In order to run the image you can use docker-compose up (if in Putty you can use docker-compose up -d to keep the image open after closing)
In order to close the image you can either use docker-compose down or Ctrl + Alt + C

Windows 10:

Install the requirements (Node.js, NPM https://npmjs.com/, Python)
Install Rust, which is needed in for the tokenizers library in requirements.txt
Install C++ build tools through Visual Studio Community
Clone the repository (git clone git@github.com:XRFoundation/DigitalBeing.git) and open the DigitalBeing directory
Run npm install
Run pip install -r requirements.txt
Rename the .env.default to .env (or make a new copy) and update the variables
Install PostgreSQL, setup the user and the database according to the parameters starting with PG* in an .env file and run the init.sql (root folder)
Run the bot in using npm run start in the command line

Without Docker (WSL/Linux):

Install the requirements (Node.JS, NPM and Python)
Run npm install
Run pip install -r requirements.txt
Install Postgres, setup the user and the database and run the init.sql (root folder)
Rename the .env.default to .env (or make a new copy) and update the variables
Run the bot in using npm run in the command line

Miscellaneous / Troubleshooting

Docker-compose up editor.sh error

If you get this error ERROR: for testbot_editor_1 Cannot start service editor: OCI runtime create failed: container_linux.go:380: starting container process caused: exec: "./editor.sh": permission denied: unknown before running the command docker-compose up run: chmod +x editor.sh in the root folder

How to install Postgres manual - without docker

sudo apt-get install postgresql - installs the postgresql service on the machine
sudo passwd postgres - the user postgres is created, with this command you can set a password, as the service runs on this user, close and reopen terminal if on WSL otherwise reboot
sudo service postgresql start - to start the postgres service
sudo -u postgres psql - to connect to postgres as the postgres user - the user can be changed to a custom user
if you want to run postgres on a different user you can use this command: sudo -u postgres createuser <username>
to change the user password you will need to connect to postgres as the main user (postgres) and run: alter user <username> with encrypted password '<password>';
use create database <dbname>; to create the new database for the bot
to grant all privilages to the new user, run: grant all privileges on database <dbname> to <username> ;
then use \c <dbname>
finally run the init.sql file that can be located in the root folder in order to create the database
Here you can find more detailed instructions

Changing active agents

Attention: applies to installed agent code.

Open server/agent_params.py and add / remove the SELECT_AGENTS list using the agent name string.

Selecting active clients

Attention: applies to the installed clients only.

Open src/initialize.ts and comment/uncomment the clients you need, if you need a client that uses a web server (Twilio, messenger), go to client/webserver.ts and uncomment line 17 otherwise you can leave it commented.

Selecting available agents

Go to server/agent_params.py and add the agent name in SELECTED_AGENTS array, or delete / comment unwanted agents, like this.

Selecting available clients

Go to the src/initialize.ts and comment/uncomment the needed clients, like this.

Port forwarding (used for Twilio)

Port forwarding is needed in order to enable public access to a service, like the database, web server or the bot manager. Twilio needs an access to notify the DigitalBeing about SMS events.

Public IP is available (Docker)

In order to expose a port in the public inside docker go to docker-compose.yaml, edit the contaier you want to change and add the port according to this syntax.

ports:
  - "HOST_PORT:CONTAINER_PORT"

Example:

More details on the syntax are available in Compose documentation.

Public IP is not available (

ngrok)

A software called ngrok may help if you are using a home network and are beyond the nat. It creates a tunnel that enables public access to your computer. In order to use ngrok, you will need to install it (it supports both windows and linux) and run ngrok http port through the command line. This command will generate a new URL that will be later use for public access.

This step can be used for the Editor, Twilio or Messenger, which needs public access to the computer.

Twilio setup

In order to run Twilio, you will need to have your ports forwarded. Puppeteer error, that it cant find Chrome: WSL can cause an error with puppeteer that it cant find chromium driver, in order to fix it you will need to install chrome manually, running the following commands:

wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.debsudo apt -y install ./google-chrome-stable_current_amd64.deb

XR-Engine Support:

DigitalBeing is able to connect to the XR-Engine using Puppeteer.

DigitalBeing is able to imitate a character in XR-engine and access its functions. It currently selects a random model. It works using a virtual headful client (runs like headless, but in headful mode virtual, as puppeteer doesn't support Audio and Video in headless mode) in the engine. Currently, DigitalBeing has a builtin support for the chat, which allows it to talk with users and use chat commands. It also has access to the client-logs, which have info about the bot, be it scene metadata or something else.

Available Commands - all commands start with a slash (/):

/move x,y,z moves to x,y,z position using navmesh
/metadata scene gets the scene metadata
/metadata world,max_distance (from bot) gets the world metadata (objects) around the bot
/listAllusers sends a client log with all users
/goTo landmark (based on world metadata) moves towards a landmark
/emote emote_name players an emote
/getPosition user get the position of a user
/getRotation user get the rotation of a user
/getScale user get the scale of a user
/getTransform user get the transform of a user (position, rotation, scale)
/subscribe system subscribe to chat system
/unsubscribe system unsubscribe from a chat system
/getSubscribed get the current subscribed chat systems
/follow user follow a user
/follow stop stop following a user
/getChatHistory get the recent chat history as client log
/getLocalUserId get the local user id as client log

Note: the xrengine-client.ts has all the functions needed to send commands or generally a chat message.

Scripts Structure:

The XR-Engine engine is one of the DB’s clients, it can handle multiple clients at once though.

There are multiple scripts for the xr-engine:

chatHistory.ts - has functions to handle the chat history messageHandler.ts - handles the chat messages and sends to the server side the needed messages Stt.ts - handles the speech to text engine Tts.ts - handles the text to speech engine UsersInRange.ts - holds lists of users around the bot Xrengine-client.ts - is the main script for the XR-Engine, it holds all the functions that use the puppeteer xrEnginePacketHandler.ts - handles the received packets from the python server

.env config file

The config file for a DigitalBeing is located in a root project directory and is called .env. It holds all the variables that are needed for configuration, they are added externally to support easy changes and avoid rebuilding docker if used.

Some values are the api keys, chat history length, editor values, ports used etc.

Common parameters

Common

BOT_NAME - the name of the Bot that is used globally in the chat history, so the bot understands easily if it sent by it
BOT_NAME_HANDLE - the name that is set for the bot in the chat history in the metaintelligence handler
BOT_NAME_REGEX - the regex for the bot name, which is used for the bot to understand that someone is starting a conversation with it
ENABLED_SERVICES - what clients to enable; case-insensitive. Possible options: Discord, Instagram, Messenger, Reddit, Telegram, Twilio, Twitter, Website-reader, Whatsapp, XR, Zoom.
TCP_PORT - the TCP port that is used to connect the typescript client with the Python server
EDIT_MESSAGES_MAX_COUNT - max message to be sent to agent if edited (older messages will be ignored)
CHAT_HISTORY_MESSAGES_COUNT - the count of chat history fetched in-case the agent needs them
OPENAI_OBSCENITY_DETECTOR - uses OpenAI for finding obscene messages if set as 1
WEBSERVER_PORT - the webserver port that is used for the webhooks (Twilio, Messenger)

Twitter

In order to get the Twitter API tokens a request will be needed to be made for a Twitter Developer Account, then the keys can be fetched this way after creating the Application inside the dev Portal.

TWITTER_BEARER_TOKEN
TWITTER_APP_TOKEN
TWITTER_APP_TOKEN_SECRET
TWITTER_ACCESS_TOKEN
TWITTER_Access_TOKEN_SECRET
TWITTER_ID - The name of the twitter account, e.x. DigitalBeing
TWITTER_TWEET_RULES - Rules (words) that are used to fetch Tweets, they are separated using semicolon (;), for example: digital being;digital;being

Discord

In order to fetch discord Tokens go to the Dev Portal and click New Application, select a name for the Application and click Create, select the Bot panel and create bot, Client_API_Token can be fetched from the Bot Tab and Client and Client_secret can be fetched from the OAuth2 tab. In the dev portal you in the bot tab you will need to enable these 2 options in order to make the bot crash.

A Discord user can be fetched by enabled the Developer Mode in discord, right click to the user and click "Copy ID", so it will be copied to the clipboard.

DISCORD_API_TOKEN
DISCORD_CLIENT_ID
DISCORD_CLIENT_SECRET
LOAD_DISCORD_LOGGER - whether or not to load the external Logger, which sends DMs with logs to a selected user
LOG_DM_USER_ID - The user that the Logs are sent to
DIGITAL_BEINGS_ONLY - This variable is a boolean, if set to true, the bot ignores channels that don't have DigitalBeing in their metadata (channel description).

Twilio

In order to use Twilio, you will need to create an account and create a new phone number (Twilio doesn’t receive SMS abroad, so the number should be better from your Region). Then you will need to port forward (if needed) the web server port, default is 65535 Update Twilio WebHooks for Messaging (SMS) with the your web server url ip:port/sms for the active number

TWILIO_ACCOUNT_SID
TWILIO_AUTH_TOKEN
TWILIO_PHONE_NUMBER

Telegram

In order to create a bot in telegram, you will need to install the APP in an Android or iOS device and login/register, then search for the BotFather bot (Should have a blue checkmark beside his name), click "Start" conversation to activate it and then follow his instructions.

TELEGRAM_BOT_TOKEN

XR-Engine

In order to use the xr-engine you will need to install the engine, then for the URL variable just apply the URL for the engine using the location you want the bot to enter, for example https://localhost:3000/location/test. This URL will make the bot to connect to the XR-engine that is setup locally on Port 3000 in the location test.

XRENGINE_URL

Whatsapp

CURRENTLY UNTESTED, API keys are unavailable.

WHATSAPP_BOT_NAME

Harmony

Harmony runs the same way with the XR-Engine, though the url is https://localhost:3000/harmony for a local test.

HARMONY_URL

Messenger by Facebook

Messenger is using the default Facebook API, it supports Direct Messages through a Facebook Page.

In order to set up the bot for facebook, you will need to go to the Facebook Dev, then create a new Application, set it up with your Page and add Messenger (it can work with Instagram too), then you will need to set a verify token to the .env (something like a password), run the bot, let it load, then go to the Messenger Dev Portal and in the Messenger APP go to callbacks, set your ip:port/webhook and for the next text field type the verify token you used to the .env, click verify and wait to load, then get the app token from the dev portal and update the .env.

MESSENGER_TOKEN
MESSENGER_VERIFY_TOKEN

Zoom

To use zoom, you will need to create a room and get the invitation link (for web), like this https://us04web.zoom.us/wc/join/id if the room needs a password, you will need to add it in the zoom_password variable or in the url.

ZOOM_INVITATION_LINK
ZOOM_PASSWORD

Reddit

For Reddit, you will need to create an app on its dev portal. Then you need to obtain the redirect URL at this page. After, visit the same URL and follow the steps to generate the OAUTH2 token and set up the variables in the .env with the needed values.

REDDIT_APP_ID
REDDIT_APP_SECRED_ID
REDDIT_USERNAME
REDDIT_PASSWORD
REDDIT_OATH_TOKEN - OAUTH2 token

Instagram

Instagram is the simplest to setup, there is no need of a dev account or dev application, just the account’s credentials for the bot to login in the account.

IG_USERNAME - the username for an Instagram bot account
IG_PASSWORD - the password

PostgreSQL database

The bot uses PostgreSQL locally to save chat history, user data, etc. It can be setup locally or in a different server.

PGUSER - username
PGHOST - host
PGPASSWORD - password
PGDATABASE - database name
PGPORT - port

In Linux, PostgreSQL should be available automatically for your package manager. For example, in Ubuntu you can install it with sudo apt install postgresql-server.

In Windows, you'll need to download it from the official server and follow the instructions.

Windows installation instructions instructions using WSL.

Manager

The Manager is a web interface to edit variables from the database for the bot.

BOT_MANAGER_IP
BOT_MANAGER_PORT
MANAGER_USERNAME - in order to use it there is a login screen on the start, to avoid others editing the bot
MANAGER_PASSWORD
BOT_MANAGER_SECRET_KEY - a custom secret key
AVAILABLE_AIS - Available agents in the bot, separated by the semicolons so spaces can be used, for example: gpt3;gpt2;test agent

Metaintelligence

METAINTELLIGENCE_CONNECTION_STRING - the connection string for the meta intelligence agent if used

Thales

THALES_CONNECTION_STRING - the connection string for the Thales agent if used

GPT-3 agent

OPENAI_API_KEY - OpenAI key that is needed for the GPT-3 bot to function

Super Mind

To create intelligent agents.

About

Our team

Contributors

Super Mind is all of us

Our contributors 1