Home

Awesome

RasaGPT Logo

<br/><br/>

šŸ  Overview

šŸ’¬ RasaGPT is the first headless LLM chatbot platform built on top of Rasa and Langchain. It is boilerplate and a reference implementation of Rasa and Telegram utilizing an LLM library like Langchain for indexing, retrieval and context injection.

<br/>

<br/><br/>

RasaGPT Youtube Video

<br/><br/>

šŸ’¬ What is Rasa?

In their own words:

šŸ’¬ Rasa is an open source (Python) machine learning framework to automate text- and voice-based conversations: NLU, dialogue management, connect to Slack, Facebook, and more - Create chatbots and voice assistants

<br/>

In my words: <br/>

Rasa is a very popular (dare I say de facto?) and easy-enough to use chatbot framework with built in NLU ML pipelines that are obsolete and a conceptual starting point for a reimagined chatbot framework in a world of LLMs.

<br/><br/>

šŸ’ā€ā™€ļø Why RasaGPT?

RasaGPT works out of the box. A lot of the implementing headaches were sorted out so you donā€™t have to, including:

The backstory is familiar. A friend came to me with a problem. I scoured Google and Github for a decent reference implementation of LLMā€™s integrated with Rasa but came up empty-handed. I figured this to be a great opportunity to satiate my curiosity and 2 days later I had a proof of concept, and a week later this is what I came up with.

<br/>

āš ļø Caveat emptor: This is far from production code and rife with prompt injection and general security vulnerabilities. I just hope someone finds this useful šŸ˜Š

<br/><br/>

āœØĀ Quick start

Getting started is easy, just make sure you meet the dependencies below.

<br/>

āš ļøāš ļøāš ļø ** ATTENTION NON-MACOS USERS: ** If you are using Linux or Windows, you will need to change the image name from khalosa/rasa-aarch64:3.5.2 to rasa/rasa:latest in docker-compose.yml on line #64 and in the actions Dockerfile on line #1 here

<br/>
# Get the code
git clone https://github.com/paulpierre/RasaGPT.git
cd RasaGPT

## Setup the .env file
cp .env-example .env

# Edit your .env file and add all the necessary credentials
make install

# Type "make" to see more options
make

<br/><br/>

šŸ”„Ā Features

Full Application and API

Rasa integration

Flexibility

<br/><br/>

šŸ§‘ā€šŸ’»Ā Installing

Requirements

<br/>

Setup

git clone https://github.com/paulpierre/RasaGPT.git
cd RasaGPT
cp .env-example .env

# Edit your .env file and all the credentials

<br/>

At any point feel free to just type in make and it will display the list of options, mostly useful for debugging:

<br/>

Makefile main

<br/>

Docker-compose

The easiest way to get started is using the Makefile in the root directory. It will install and run all the services for RasaGPT in the correct order.

make install

# This will automatically install and run RasaGPT
# After installation, to run again you can simply run

make run
<br/>

Local Python Environment

This is useful if you wish to focus on developing on top of the API, a separate Makefile was made for this. This will create a local virtual environment for you.

# Assuming you are already in the RasaGPT directory
cd app/api
make install

# This will automatically install and run RasaGPT
# After installation, to run again you can simply run

make run
<br/>

Similarly, enter make to see a full list of commands

Makefile API

<br/>

Installation process

Installation should be automated should look like this:

Installation

šŸ‘‰Ā Full installation log:Ā https://app.warp.dev/block/vflua6Eue29EPk8EVvW8Kd

<br/>

The installation process for Docker takes the following steps at a high level

  1. Check to make sure you have .env available
  2. Database is initialized with pgvector
  3. Database models create the database schema
  4. Trains the Rasa model so it is ready to run
  5. Sets up ngrok with Rasa so Telegram has a webhook back to your API server
  6. Sets up the Rasa actions server so Rasa can talk to the RasaGPT API
  7. Database is populated with dummy data via seed.py

<br/><br/>

ā˜‘ļøĀ Next steps

<br/>

šŸ’¬Ā Start chatting

You can start chatting with your bot by visiting šŸ‘‰ https://t.me/yourbotsname

Telegram

<br/><br/>

šŸ‘€Ā View logs

You can view all of the log by visiting šŸ‘‰ https://localhost:9999/ which will displaying real-time logs of all the docker containers

Dozzle

<br/><br/>

šŸ“–Ā API documentation

View the API endpoint docs by visiting šŸ‘‰ https://localhost:8888/docs

In this page you can create and update entities, as well as upload documents to the knowledge base.

Swagger Docs

<br/><br/>

āœļøĀ Examples

The bot is just a proof-of-concept and has not been optimized for retrieval. It currently uses 1000 character length chunking for indexing and basic euclidean distance for retrieval and quality is hit or miss.

You can view example hits and misses with the bot in the RESULTS.MD file. Overall I estimate index optimization and LLM configuration changes can increase output quality by more than 70%.

<br/>

šŸ‘‰Ā Click to see the Q&A results of the demo data inĀ RESULTS.MD

<br/><br/>

šŸ’»Ā API Architecture and Usage

The REST API is straight forward, please visit the documentation šŸ‘‰Ā http://localhost:8888/docs

The entities below have basic CRUD operations and return JSON

<br/><br/>

Organization

This can be thought of as a company that is your client in a SaaS / multi-tenant world. By default a list of dummy organizations have been provided

Screenshot 2023-05-05 at 8.45.28 AM.png

[
  {
    "id": 1,
    "uuid": "d2a642e6-c81a-4a43-83e2-22cee3562452",
    "display_name": "Pepe Corp.",
    "namespace": "pepe",
    "bot_url": null,
    "created_at": "2023-05-05T10:42:45.933976",
    "updated_at": "2023-05-05T10:42:45.933979"
  },
  {
    "id": 2,
    "uuid": "7d574f88-6c0b-4c1f-9368-367956b0e90f",
    "display_name": "Umbrella Corp",
    "namespace": "acme",
    "bot_url": null,
    "created_at": "2023-05-05T10:43:03.555484",
    "updated_at": "2023-05-05T10:43:03.555488"
  },
  {
    "id": 3,
    "uuid": "65105a15-2ef0-4898-ac7a-8eafee0b283d",
    "display_name": "Cyberdine Systems",
    "namespace": "cyberdine",
    "bot_url": null,
    "created_at": "2023-05-05T10:43:04.175424",
    "updated_at": "2023-05-05T10:43:04.175428"
  },
  {
    "id": 4,
    "uuid": "b7fb966d-7845-4581-a537-818da62645b5",
    "display_name": "Bluth Companies",
    "namespace": "bluth",
    "bot_url": null,
    "created_at": "2023-05-05T10:43:04.697801",
    "updated_at": "2023-05-05T10:43:04.697804"
  },
  {
    "id": 5,
    "uuid": "9283d017-b24b-4ecd-bf35-808b45e258cf",
    "display_name": "Evil Corp",
    "namespace": "evil",
    "bot_url": null,
    "created_at": "2023-05-05T10:43:05.102546",
    "updated_at": "2023-05-05T10:43:05.102549"
  }
]
<br/>

Project

This can be thought of as a product that belongs to a company. You can view the list of projects that belong to an organizations like so:

org-projects.png

[
  {
    "id": 1,
    "documents": [
      {
        "id": 1,
        "uuid": "92604623-e37c-4935-bf08-0e9efa8b62f7",
        "display_name": "project-pepetamine.md",
        "node_count": 3
      }
    ],
    "document_count": 1,
    "uuid": "44a4b60b-9280-4b21-a676-00612be9aa87",
    "display_name": "Pepetamine",
    "created_at": "2023-05-05T10:42:46.060930",
    "updated_at": "2023-05-05T10:42:46.060934"
  },
  {
    "id": 2,
    "documents": [
      {
        "id": 2,
        "uuid": "b408595a-3426-4011-9b9b-8e260b244f74",
        "display_name": "project-frogonil.md",
        "node_count": 3
      }
    ],
    "document_count": 1,
    "uuid": "5ba6b812-de37-451d-83a3-8ccccadabd69",
    "display_name": "Frogonil",
    "created_at": "2023-05-05T10:42:48.043936",
    "updated_at": "2023-05-05T10:42:48.043940"
  },
  {
    "id": 3,
    "documents": [
      {
        "id": 3,
        "uuid": "b99d373a-3317-4699-a89e-90897ba00db6",
        "display_name": "project-kekzal.md",
        "node_count": 3
      }
    ],
    "document_count": 1,
    "uuid": "1be4360c-f06e-4494-bf20-e7c73a56f003",
    "display_name": "Kekzal",
    "created_at": "2023-05-05T10:42:49.092675",
    "updated_at": "2023-05-05T10:42:49.092678"
  },
  {
    "id": 4,
    "documents": [
      {
        "id": 4,
        "uuid": "94da307b-5993-4ddd-a852-3d8c12f95f3f",
        "display_name": "project-memetrex.md",
        "node_count": 3
      }
    ],
    "document_count": 1,
    "uuid": "1fd7e772-365c-451b-a7eb-4d529b0927f0",
    "display_name": "Memetrex",
    "created_at": "2023-05-05T10:42:50.184817",
    "updated_at": "2023-05-05T10:42:50.184821"
  },
  {
    "id": 5,
    "documents": [
      {
        "id": 5,
        "uuid": "6deff180-3e3e-4b09-ae5a-6502d031914a",
        "display_name": "project-pepetrak.md",
        "node_count": 4
      }
    ],
    "document_count": 1,
    "uuid": "a389eb58-b504-48b4-9bc3-d3c93d2fbeaa",
    "display_name": "PepeTrak",
    "created_at": "2023-05-05T10:42:51.293352",
    "updated_at": "2023-05-05T10:42:51.293355"
  },
  {
    "id": 6,
    "documents": [
      {
        "id": 6,
        "uuid": "2e3c2155-cafa-4c6b-b7cc-02bb5156715b",
        "display_name": "project-memegen.md",
        "node_count": 5
      }
    ],
    "document_count": 1,
    "uuid": "cec4154f-5d73-41a5-a764-eaf62fc3db2c",
    "display_name": "MemeGen",
    "created_at": "2023-05-05T10:42:52.562037",
    "updated_at": "2023-05-05T10:42:52.562040"
  },
  {
    "id": 7,
    "documents": [
      {
        "id": 7,
        "uuid": "baabcb6f-e14c-4d59-a019-ce29973b9f5c",
        "display_name": "project-neurokek.md",
        "node_count": 5
      }
    ],
    "document_count": 1,
    "uuid": "4a1a0542-e314-4ae7-9961-720c2d092f04",
    "display_name": "Neuro-kek",
    "created_at": "2023-05-05T10:42:53.689537",
    "updated_at": "2023-05-05T10:42:53.689539"
  },
  {
    "id": 8,
    "documents": [
      {
        "id": 8,
        "uuid": "5be007ec-5c89-4bc4-8bfd-448a3659c03c",
        "display_name": "org-about_the_company.md",
        "node_count": 5
      },
      {
        "id": 9,
        "uuid": "c2b3fb39-18c0-4f3e-9c21-749b86942cba",
        "display_name": "org-board_of_directors.md",
        "node_count": 3
      },
      {
        "id": 10,
        "uuid": "41aa81a9-13a9-4527-a439-c2ac0215593f",
        "display_name": "org-company_story.md",
        "node_count": 4
      },
      {
        "id": 11,
        "uuid": "91c59eb8-8c05-4f1f-b09d-fcd9b44b5a20",
        "display_name": "org-corporate_philosophy.md",
        "node_count": 4
      },
      {
        "id": 12,
        "uuid": "631fc3a9-7f5f-4415-8283-78ff582be483",
        "display_name": "org-customer_support.md",
        "node_count": 3
      },
      {
        "id": 13,
        "uuid": "d4c3d3db-6f24-433e-b2aa-52a70a0af976",
        "display_name": "org-earnings_fy2023.md",
        "node_count": 5
      },
      {
        "id": 14,
        "uuid": "08dd478b-414b-46c4-95c0-4d96e2089e90",
        "display_name": "org-management_team.md",
        "node_count": 3
      }
    ],
    "document_count": 7,
    "uuid": "1d2849b4-2715-4dcf-aa68-090a221942ba",
    "display_name": "Pepe Corp. (company)",
    "created_at": "2023-05-05T10:42:55.258902",
    "updated_at": "2023-05-05T10:42:55.258904"
  }
]
<br/>

Document

This can be thought of as an artifact related to a product, like an FAQ page or a PDF with financial statement earnings. You can view all the Documents associated with an Organizationā€™s Project like so:

documents.png

{
  "id": 1,
  "uuid": "44a4b60b-9280-4b21-a676-00612be9aa87",
  "organization": {
    "id": 1,
    "uuid": "d2a642e6-c81a-4a43-83e2-22cee3562452",
    "display_name": "Pepe Corp.",
    "bot_url": null,
    "status": 2,
    "created_at": "2023-05-05T10:42:45.933976",
    "updated_at": "2023-05-05T10:42:45.933979",
    "namespace": "pepe"
  },
  "document_count": 1,
  "documents": [
    {
      "id": 1,
      "uuid": "92604623-e37c-4935-bf08-0e9efa8b62f7",
      "organization_id": 1,
      "project_id": 1,
      "display_name": "project-pepetamine.md",
      "url": "",
      "data": "# Pepetamine\n\nProduct Name: Pepetamine\n\nPurpose: Increases cognitive focus just like the Limitless movie\n\n**How to Use**\n\nPepetamine is available in the form of rare Pepe-coated tablets. The recommended dosage is one tablet per day, taken orally with a glass of water, preferably while browsing your favorite meme forum for maximum cognitive enhancement. For optimal results, take Pepetamine 30 minutes before engaging in mentally demanding tasks, such as decoding ancient Pepe hieroglyphics or creating your next viral meme masterpiece.\n\n**Side Effects**\n\nSome potential side effects of Pepetamine may include:\n\n1. Uncontrollable laughter and a sudden appreciation for dank memes\n2. An inexplicable desire to collect rare Pepes\n3. Enhanced meme creation skills, potentially leading to internet fame\n4. Temporary green skin pigmentation, resembling the legendary Pepe himself\n5. Spontaneously speaking in \"feels good man\" language\n\nWhile most side effects are generally harmless, consult your memologist if side effects persist or become bothersome.\n\n**Precautions**\n\nBefore taking Pepetamine, please consider the following precautions:\n\n1. Do not use Pepetamine if you have a known allergy to rare Pepes or dank memes.\n2. Pepetamine may not be suitable for individuals with a history of humor deficiency or meme intolerance.\n3. Exercise caution when driving or operating heavy machinery, as Pepetamine may cause sudden fits of laughter or intense meme ideation.\n\n**Interactions**\n\nPepetamine may interact with other substances, including:\n\n1. Normie supplements: Combining Pepetamine with normie supplements may result in meme conflicts and a decreased sense of humor.\n2. Caffeine: The combination of Pepetamine and caffeine may cause an overload of energy, resulting in hyperactive meme creation and potential internet overload.\n\nConsult your memologist if you are taking any other medications or substances to ensure compatibility with Pepetamine.\n\n**Overdose**\n\nIn case of an overdose, symptoms may include:\n\n1. Uncontrollable meme creation\n2. Delusions of grandeur as the ultimate meme lord\n3. Time warps into the world of Pepe\n\nIf you suspect an overdose, contact your local meme emergency service or visit the nearest meme treatment facility. Remember, the key to enjoying Pepetamine is to use it responsibly, and always keep in mind the wise words of our legendary Pepe: \"Feels good man.\"",
      "hash": "fdee6da2b5441080dd78e7850d3d2e1403bae71b9e0526b9dcae4c0782d95a78",
      "version": 1,
      "status": 2,
      "created_at": "2023-05-05T10:42:46.755428",
      "updated_at": "2023-05-05T10:42:46.755431"
    }
  ],
  "display_name": "Pepetamine",
  "created_at": "2023-05-05T10:42:46.060930",
  "updated_at": "2023-05-05T10:42:46.060934"
}
<br/>

Node

Although this is not exposed in the API, a node is a chunk of a document which embeddings get generated for. Nodes are used for retrieval search as well as context injection. A node belongs to a document.

<br/>

User

A user represents the person talking to a bot. Users do not necessarily belong to an org or product, but this relationship is captured in ChatSession below.

<br/>

ChatSession

Not exposed via API, but this represent a question and answer between the User and a bot. Each of these objects can be flexibly identified by a session_id which gets automatically generated. Chat Sessions contain rich metadata that can be used for training and optimization. ChatSessions via the /chat endpoint ARE in fact associated with organization (for multi-tenant security purposes)

<br/><br/>

šŸ“šĀ How it works

<br/>

Rasa

  1. Rasa handles integration with the communication channel, in this case Telegram.
    • It specifically handles submitting the target webhook user feedback should go through. In our case it is our FastAPI server via /webhooks/{channel}/webhook
  2. Rasa has two components, the coreĀ Rasa appĀ and an RasaĀ actions serverĀ that runs separately
  3. Rasa must be configured (done already) via a few yaml files:
    • config.ymlĀ - contains NLU pipeline and policy configuration. What matters is setting theĀ FallbackClassifierĀ threshold
    • credentials.ymlĀ - contains the path to our webhook and Telegram credentials. This will get updated by the helper serviceĀ rasa-credentialsĀ viaĀ app/rasa-credentials/main.py
    • domain.ymlĀ - This contains the chat entrypoint logic configuration like intent and the action to take against the intent. Here we add theĀ action_gpt_fallbackĀ action which will trigger ourĀ actions server
    • endpoints.ymlĀ - This is where we set our custom action end-point for Rasa to trigger our fallback
    • nlu.ymlĀ - this is where we set our intentĀ out_of_scope
    • rules.ymlĀ - we set a rule for this intent that it should trigger the actionĀ action_gpt_fallback
    • actions.pyĀ - this is where we define and express our action via theĀ ActionGPTFallbackĀ class. The methodĀ nameĀ returns the action we defined for our intent above
  4. Rasa's NLU models must be trained which can be done via CLI withĀ rasa trainĀ . This is done automatically for you when you runĀ make install
  5. Rasa's core must be ran viaĀ rasa runĀ after training
  6. Rasa's action server must be ran separately withĀ rasa run actions
<br/>

Telegram

  1. Rasa automatically updates the Telegram Bot API with your callback webhook fromĀ credentials.yml.
  2. By default this is static. Since we are running on our local machine, we leverageĀ NgrokĀ to generate a publically accessible URL and reverse tunnel into our docker container
  3. rasa-credentialsĀ service takes care of this process for you. Ngrok runs as a service, once it is readyĀ rasa-credentialsĀ calls the local ngrok API to retrieve the tunnel URL and updates theĀ credentials.ymlĀ file and restarts Rasa for you
  4. The webhook Telegram will send messages to will be our FastAPI server. Why this instead of Rasa? Because we want flexibility to capture metadata which Rasa makes a PITA and centralizing to the API server is ideal
  5. The FastAPI server forwards this to the Rasa webhook
  6. Rasa will then determine what action to take based on the user intent. Since the intents have been nerfed for this demo, it will go to the fallback action running in actions.py
  7. The custom action will capture the metadata and forward the response from FastAPI to the user
<br/>

PGVector

pgvectorĀ is a plugin for Postgres and automatically installed enabling your to store and calculate vector data types. We have our own implementation because the Langchain PGVector class is not flexible to adapt to our schema and we want flexibility.

  1. By default in postgres, any files in the container's pathĀ /docker-entry-initdb.dĀ get run if the database has not been initialized. In theĀ postgres DockerfileĀ we copyĀ create_db.shĀ which createsĀ the db and user for our database
  2. In theĀ modelsĀ commandĀ in theĀ Makefile, we run theĀ models.pyĀ in the API container which creates the tables from the models.
  3. TheĀ enable_vectorĀ methodĀ enables the pgvector extension in the database
<br/>

Langchain

  1. The training data gets loaded in the database
  2. The data is indexedĀ if the index doesn't existĀ andĀ stored in a file namedĀ index.json
  3. LlamaIndex uses a basicĀ GPTSimpleVectorIndexĀ to find the relevant data andĀ injects it into a prompt.
  4. Guard rails via prompts are used to keep the conversation focused
<br/>

Bot flow

  1. The user will chat in Telegram and the message will be filtered forĀ existing intents
  2. If it detects there is no intent match but instead matches theĀ out_of_scope,Ā based on rules.ymlĀ it will trigger theĀ action_gpt_fallbackĀ action
  3. TheĀ ActionGPTFallbackĀ functionĀ will then call theĀ FastAPI API server
  4. the API using LlamaIndex will find the relevant indexed content and inject it into a prompt to send to OpenAI for inference
  5. The prompt contains conversational guardrails including:
    • Requests data be returned in JSON
    • Create categorical tags based on what the user's question
    • Return a boolean if the conversation should be escalated to a human (if there is no context match)

<br/><br/>

šŸ“Ā TODO

<br/><br/>

šŸ”Ā Troubleshooting

In general, check your docker container logs by simply going to šŸ‘‰Ā http://localhost:9999/

<br/>

Ngrok issues

Always check that your webhooks with ngrok and Telegram match. Simply do this by

curl -sS "https://api.telegram.org/bot<your-bot-secret-token>/getWebhookInfo" | json_pp
<br/>

.. should return this:

{
    "ok": true,
    "result": {
        "url": "https://b280-04-115-40-112.ngrok-free.app/webhooks/telegram/webhook",
        "has_custom_certificate": false,
        "pending_update_count": 0,
        "max_connections": 40,
        "ip_address": "1.2.3.4"
    }
}
<br/>

.. which should match the URL in your credentials.yml file or visit the Ngrok admin UI šŸ‘‰Ā http://localhost:4040/status

ngrok-admin.png

<br/>

Looks like it is a match. If not, restart everything by running:

make restart

<br/><br/>

šŸ’ŖĀ Contributing / Issues

<br/><br/>

thumbsup <br/> Congratulations, all your base are belong to us! kthxbye

<br/><br/>

šŸŒŸ Star History

Star History Chart

šŸ“œĀ Open source license

Copyright (c) 2023 Paul Pierre. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the ā€œSoftwareā€), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED ā€œAS ISā€, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.