Installation Guide

Want to run your own Vivia? This guide will show you how to do it.

Prerequisites

To get started, you'll need a device (Windows or Linux, Mac not tested) with the following software installed:

• Python. Vivia is tested with Python 3.10.6, but anything above 3.6 should work fine.
• pip. This should come with your Python installation.
• Git.

Note: For AI functionality, you'll want a fairly good GPU. You can run Vivia's AI on a CPU, but it's slow.

You'll also need a Discord account, obviously.

Preparing a Discord Application

Discord applications define a bot's account: its name, avatar, banner, About Me, etc. They also provide a bot token, which will be used by Vivia to connect to the bot account.

1. Go to the Discord Developer Portal. Log in with your Discord account if not already done.
2. Click "New Application".
3. Give your application a name and accept the ToS.
4. Go to the "Bot" section and create a bot.
5. (Optional) Customize your bot with an About Me, icon, and banner.
6. Click on "Reset Token" and confirm. Copy the newly generated token into Notepad for now.
7. Enable all privileged gateway intents. You don't usually need all of them by default, but some extensions may require them. Note that this will require you to verify your bot if it's in more than 100 servers.

Pulling Vivia

You'll want to pull this repository next.

7. Go to a directory where you want to place Vivia's files. Note that the repository will go into a "vivia" folder in this directory.
8. Open a terminal here and run git clone https://github.com/Starlii10/vivia.

Setting Up Vivia

Don't worry, the setup is fairly easy.

9. Go to the Vivia directory.
10. Create a file named "token.env" in this directory.
11. Paste your bot token into token.env, like this: token="YOUR_TOKEN_HERE"
12. Save and close token.env.
13. Open a new terminal in the Vivia directory.
14. Run pip with a command such as pip install -r requirements.txt. The actual command may vary depending on your system.

Running Vivia

Here comes the fun part: turning your newly-created Vivia on!

15. Open a new terminal in the Vivia directory.
16. Execute the bot.py script using Python. Once again, the command may vary.

If everything goes well, Vivia will start up. Once you see a "Vivia is all ready!" message, you're good to go!

Inviting Vivia to a Discord Server

Vivia currently isn't in any server and can't do much. Let's fix that!

17. Go to the Discord Developer Portal. Open the application you just made.
18. Go to the "Installation" section. Turn on "Guild Install", if not already done.
19. Under "Default Install Settings", turn on the applications.commands and bot scopes.
20. Copy your bot's install link and paste it into your browser.
21. Select the server you want to add Vivia to.
22. Click "Authorize".

Vivia will be added to the server and you'll be able to use her!

(Optional) AI Functionality

Giving Vivia AI will allow her to talk when you ping her!

23. Install llama-cpp-python. Pay close attention to the Installation Configuration section! Depending on the hardware you're running Vivia on, you may want to change settings; for example, those with NVIDIA GPUs may benefit from installing with CUDA support.
24. (Optional) Install pytesseract for OCR (image reading) support. This requires Google Tesseract OCR to also be installed on your computer.
25. Find a LLaMa-compatible model and download it. Many are available on Hugging Face.
26. Paste the model's .gguf file into (Vivia directory)/extras/models. Rename it to "llama-model.gguf".
27. Run Vivia and ensure AI functionality is working by pinging her.

(Optional) Installing Extensions

Extensions can allow Vivia to do more than what comes by default.

28. Find and download an extension. Extensions can come in the form of Python scripts (.py) or VSE files (.vse).
29. Copy the extension to the data/extensions folder in the Vivia directory.
30. Run Vivia and use v!extensions to see if it's loaded. If it failed to load, check the logs for information about what went wrong.