Nisaba is an IRC bot written in Go, designed to interact with users in a chat channel, using llamafile for generating responses.
Nisaba is named after the Mesopotamian goddess of writing and grain.
This project began as a way to learn Go, aimed at creating a frontend for interacting with local OpenAI or similar endpoints.
Initially, the project used PrivateGPT as its backend for generating responses.
As the project evolved, the need for more flexible API options led to a transition to llamafile.
This switch was motivated by llamafile's ease of use and its API endpoint being llama.cpp compatible.
- Responds to messages directed at it by consulting llamafile for generating responses.
- Configurable customization options for the bot, such as setting a custom bot name.
- Supports dynamic loading of different API options for response generation.
- Ignores messages from users listed in a block list.
- Splits long messages to adhere to IRC's message length limits.
- Allows commands through IRC, such as clearing message history or loading new configuration options.
General (Automated Setup, Docker and Building)
These requirements apply to all setup methods.
- Linux, Mac, or Windows computer capable of running an LLM model for the AI backend.
- Fully configured llamafile API endpoint.
- This is automatically downloaded and configured by the setup script.
Buliding
To build the standalone Go binary, you will need the build requirements.
- Install Go
- Go Dependencies
Nisaba can be run either as a standalone application or within a Docker container.
Each method requires a configured config.json
file, and optionally options.json
, located in the ./config
directory.
- These files can be created automatically by the
setup.sh
orsetup.bat
script, explained in the Automated Setup instructions.
Choose one of the setup methods below and follow the directions to configure Nisaba.
Automated (Pre-Built) Setup - Simple setup using prepared scripts and binaries for Windows/Linux/Mac.
Follow these detailed steps to get Nisaba running quickly using the pre-built scripts included with the releases:
-
Download the Pre-Built Binary Archive
- Visit the Releases page on GitHub.
- Download the appropriate archive for your operating system:
nisaba-linux.tar.gz
for Linuxnisaba-mac.tar.gz
for Macnisaba-windows.zip
for Windows
-
Prepare the Setup Script
- For Linux or Mac:
- Extract the contents of the
.tar.gz
archive. - Open a terminal and navigate to the extracted directory.
- Make the setup script executable:
chmod +x setup.sh
- Extract the contents of the
- For Windows:
- Extract the contents of the
.zip
archive. - Open Command Prompt and navigate to the extracted directory.
- Extract the contents of the
- For Linux or Mac:
-
Run the Setup Script
- For Linux or Mac:
- In your terminal, execute the script by running:
./setup.sh
- In your terminal, execute the script by running:
- For Windows:
- In Command Prompt, execute the script by running:
setup.bat
- In Command Prompt, execute the script by running:
- Follow the on-screen prompts to configure your setup. The script will guide you through several steps:
- Download llamafile Binary: The script will ask if you want to download the llamafile binary required for the API endpoint. Answer
y
for yes. - Configure Requried Settings: You will be prompted to configure required settings to create a config.json file. Answer
y
to proceed. - Enter Configuration Details: The script will then prompt you to enter various configuration details such as nickname, server, port, etc. Press 'Enter' to accept default values or enter your custom settings.
- Choose API Endpoint Options: You'll have the option to select a default options preset for the API endpoint. Answer
y
and choose between provided presets like "LLaMA Precise" or "Divine Intellect". - Make the Binaries Executable: You will be prompted to make the binaries for Nisaba and llamafile executable. Answer
y
to proceed. - Model Download: Finally, the script will ask if you want to download a model and save it as
model.gguf
. Answery
and select the LLM model to download.
- Download llamafile Binary: The script will ask if you want to download the llamafile binary required for the API endpoint. Answer
- For Linux or Mac:
-
Run Nisaba and Llamafile
- After configuration, start the services:
- For Linux:
- Run the llamafile binary first to start the endpoint:
./llamafile -m model.gguf -ngl 0
- Then run the Nisaba binary:
./nisaba-linux-amd64.bin
- Run the llamafile binary first to start the endpoint:
- For Mac:
- Run the llamafile binary first to start the endpoint:
./llamafile -m model.gguf -ngl 0
- Then run the Nisaba binary:
./nisaba-mac-amd64.bin
- Run the llamafile binary first to start the endpoint:
- For Windows:
- Run the llamafile binary first to start the endpoint:
.\llamafile.exe -m model.gguf -ngl 0
- Then run the Nisaba binary:
.\nisaba-windows-amd64.exe
- Run the llamafile binary first to start the endpoint:
- For Linux:
- After configuration, start the services:
Building Instructions and Setup - Instructions for manually building and running Nisaba from source.
-
Install Go
- If you haven't already, follow the instructions on the official Go website.
-
Install Dependencies
- Install the IRC event package:
go get github.com/thoj/go-ircevent
- Install the IRC event package:
-
Configure the Bot
- Manually create a
config
directory in your project root and place yourconfig.json
file within this directory. Optionally, add anoptions.json
for API parameters.- Use the
setup.sh
orsetup.bat
script to generate these files automatically.
- Use the
- Example
config.json
andoptions.json
files are provided underconfig/
for reference including popular API presets:config.json.example
to reference required settings fileoptions.precise.json.example
for "LLaMA Precise"options.divine.json.example
for "Divine Intellect"options.json.example
to reference all available options
- Rename the relevant example file to
options.json
if you wish to use it.
- Manually create a
-
Build the Bot:
- Navigate to the project directory and run:
go build -o nisaba.bin .
- Navigate to the project directory and run:
-
Run the Bot:
- Ensure that you have a llamafile API endpoint running.
- Start the bot by running the binary:
./nisaba.bin
Docker Setup - Guide for deploying Nisaba with Docker, including llamafile.
-
Prepare Configurations
- Place
config.json
,options.json
(if used), andmodel.gguf
in a directory namedconfig
in the same directory as yourdocker-compose.yml
. - Example
config.json
andoptions.json
files are provided underconfig/
for reference including popular API presets:config.json.example
to reference required settings fileoptions.precise.json.example
for "LLaMA Precise"options.divine.json.example
for "Divine Intellect"options.json.example
to reference all available options
- Place
-
Build and Run with Docker Compose
- Ensure the Docker Compose file is set to mount the
config
directory correctly:version: '3.8' services: nisaba: build: . volumes: - ./model.gguf:/app/model.gguf - ./config:/app/config
- Run the following command in the directory containing
docker-compose.yml
:docker-compose up --build
- Ensure the Docker Compose file is set to mount the
These configuration files can be placed in the config/
directory, or the same directory as the Nisaba binary.
Configuration Files - Overview of various configuration files used by Nisaba.
- config.json: Required main configuration for the IRC bot, specifying connection details and API settings.
- options.json: Optional parameters file designed to adjust llamafile's behavior, with settings like
temperature
,top_k
, etc. - systemprompt.txt: System prompt for Nisaba sent to the llamafile endpoint.
- blocklist.txt: Blocks specific IRC nicknames from interacting with Nisaba.
- history.txt: Stores message context dynamically; should not be edited manually.
- llamafile_args.txt (Docker only): Custom arguments to replace default llamafile settings under Docker.
Basic Interaction - How to interact with Nisaba.
To get a response from Nisaba, simply prefix your message with the bot's name, followed by your query.
For example: Nisaba, how are you?
After you send a message or command, Nisaba will use the API endpoint to generate a response, and then send that response back to you in the designated IRC channel.
Using Commands - Commands available for controlling Nisaba.
Nisaba supports several commands that can be used to control the bot or modify its behavior dynamically.
These commands should be prefixed with the bot's name, optionally followed by a comma or colon, and the command:
- !clear: Clears the message history stored by the bot. Useful for resetting the context in "chat" mode.
Nisaba, !clear
- !options [filename]: Loads specific option settings from a file named
options.[filename].json
if present in theconfig
directory. This allows you to dynamically change how Nisaba interacts with the llamafile API without restarting the bot.Nisaba, !options precise
- !system [message]: Attaches a system prompt to the next message that Nisaba sends to the llamafile endpoint, affecting how responses are generated.
Nisaba, !system You will respond using 100 words or less.
Special thanks go to the following projects and their contributors.
-
- A powerful LLM backend used by Nisaba under Docker to host the API endpoint.
-
- An IRC event handling library in Go that enables Nisaba to connect and interact with IRC servers.
Software Disclaimer
The code in this repository is provided "as-is" without any warranty of any kind, either expressed or implied. It is intended for research and educational purposes only. The authors and contributors make no representations about the suitability of this software for any purpose and accept no liability for any consequences resulting directly or indirectly from the use of this software.
By using this software, you acknowledge and agree to assume all risks associated with its use, understanding that you are solely responsible for any damage to your computer system or loss of data that results from such activities. You also acknowledge that this software is not intended for use in production environments or for commercial purposes.