Fixed typo and added fastembed instructions to README.md
A Fast, Simple, Experimental Chatbot Framework Using IRIS Vector Search.
Can we create a framework for Object Script and Embedded Python that allows us to perform
actions and request information that feels more like a conversation (i.e. chatbot) instead
of traditional menu-driven interfaces?
The core EasyBot framework does the heavy lifting of mapping user prompts to targeted
actions. Custom actions (and groups of actions) are easy for developers to install
and develop.
This library was originally created/published for the InterSystems AI Programming Contest: Vector Search, GenAI and AI Agents.
There are several methods for installing this library:
Download the most recent exports/easybot.Export.xml
from the repository.
Import easybot.Export.xml
into your IRIS instance using the Import button found on the System Operation > Classes page in your Management Portal.
If you prefer loading easybot.Export.xml
from an IRIS terminal:
USER>do $system.OBJ.Load("/path/to/easybot.Export.xml", "cuk")
You will also need the Python fastembed
module installed:
pip install fastembed
If you prefer, you can load the library with docker, run the built-in tests, and experiment with the easybot
classes.
First, download/clone the repo to your local computer:
git clone git@github.com:jamerfort/iris-easybot.git
Build and connect to your instance:
cd ./iris-easybot
Rebuild/start the image
docker compose up --build -d
Connect to your instance
docker exec -it iris-easybot-iris-1 iris terminal IRIS
Load EasyBot classes
USER>zn "IRISAPP"
IRISAPP>do $system.OBJ.LoadDir("/home/irisowner/dev/src/cls","cuk",,1)Load EasyBot Agents
IRISAPP>do ##class(easybot.core.Loader).Load()
Enjoy EasyBot
IRISAPP>do ##class(easybot.core.Shell).Run()
How can I help you?list namespaces
| Choose one of these options...1. List Namespaces (.86) 2. Namespaces Menu (.86) 3. Filter Namespaces (.82)
1
| Here are the namespaces I found:
|
| - Namespace1
| - Namespace2
| - Namespace3Stop your containers
docker compose down
To verify installation, run the following commands:
USER>do ##class(easybot.core.Shell).Run()
How can I help you?
>>> I need help with namespaces
| Choose one of these options...
1. List Namespaces (.86)
2. Namespaces Menu (.85)
3. Filter Namespaces (.82)
>>> 3
| Here are the filtered namespaces:
|
| - FilteredNS1
| - FilteredNS3
>>>
When researching the current landscape of AI and RAG (Retrieval-Augmented Generation), it seemed that a core requirement is the ability to map phrases, sentences, and documents to a vector. This process of mapping inputs to a vector is called embedding.
Realizing that embedding is critical to AI solutions, I began to experiment with the idea of creating a chat bot/agent built solely on text embedding (without relying on large language models (LLMs)).
After a couple of successful experiments, EasyBot was born!
Menu-driven interfaces are the inspiration for EasyBot’s functionality. By tying keywords to specially crafted ObjectScript classes and methods, EasyBot is able to use vector searching to determine which method to call when a user submits a prompt. This allows EasyBot to be constrained (like a menu-driven interface) to only perform the actions of registered “agents”, while providing responses to a wide range of free-text prompts.
One of the main goals of EasyBot is to promote simple, easy customization through custom ObjectScript methods.
To customize EasyBot:
easybot.core.Agent
./// Display: EasyBot uses 'Display' whenever it needs to display this fuction.
/// Keywords: The 'Keywords' lines are used to index/embed this method.
/// Keywords: 'Keywords' are used by EasyBot to find the user's desired action.
/// Keywords: You can have multiple 'Keywords' lines. They will be joined together to index/embed.
Method MethodName(ByRef prompt As easybot.core.Prompt, ByRef response As easybot.core.ShellResponse)
Here’s an example custom Agent class:
easybot.core.Agent
Notice that the DaysOfTheWeekAgent
method contains the Display
and Keywords
labels in the comments. This tells EasyBot to index/embed this method when load
is called later.
Class easybot.bots.CustomAgent Extends easybot.core.Agent {
/// Display: List the days of the week
/// Keywords: days of the week, weekend, weekday, holiday
Method DaysOfTheWeekAgent(ByRef prompt As easybot.core.Prompt, ByRef response As easybot.core.ShellResponse)
{
do response.Respond("Here is information I have on the days of the week...")// gather information on days of the week
// ...somehow...
set days = $LB("Sun","Mon","Tue","Wed","Thu","Fri","Sat")for i=1:1:$LISTLENGTH(days) {
set day = $LISTGET(days, i)
do response.ListItem(day)
}
}
}
Now, let’s load this (and all other available agents) into IRIS. This step will take the keywords from each
method it finds, embed the keyword text, and save it into the easybot.store.Targets
table in IRIS. EasyBot compares user prompts with the entries in this table.
IRISAPP>do ##class(easybot.core.Shell).Run()
How can I help you?
>>> load
Reloading
Loading easybot.bots.CustomAgent
Loading easybot.bots.DatabaseAgent
Loading easybot.bots.EnsAgent
Loading easybot.bots.HelpAgent
Loading easybot.bots.NamespaceAgent
Now let’s ask EasyBot about days of the week. In this example, EasyBot was able to confidently determine the Agent method to call. In this case, EasyBot will go ahead and call our method!
>>> tell me about days this week
| Here is information I have on the days of the week...
| - Sun
| - Mon
| - Tue
| - Wed
| - Thu
| - Fri
| - Sat
When EasyBot is unable to determine the Agent method to call with confidence, it provides a list of possibly-related methods for the user to choose. Notice that this matches the Display
comment of the method.
>>> help days
| Choose one of these options...
1. List the days of the week (.73)
2. List Bots, Agents, and Commands (.66)
>>> 1
| Here is information I have on the days of the week...
| - Sun
| - Mon
| - Tue
| - Wed
| - Thu
| - Fri
| - Sat
Here are a list of current-planned features that should be easy to implement:
easybot.bots.CustomAgent
easybot.bots.DatabaseAgent
easybot.bots.EnsAgent
easybot.bots.HelpAgent
easybot.bots.JournalAgent
easybot.bots.NamespaceAgent