just-genetics-chat

Genetics LLM agent to answer questions about your genetic data and genetics.

Genetics Features

This fork of the just-chat repository adds specialized functionality for genetic analysis:

• Genetics Genie Agent: A dedicated assistant that can analyze and explain genetic variants and their potential health implications
• Genetic Analysis Tools: Built-in tools for querying information about:
  • SNPs (rsIDs) and their associations with diseases
  • Gene information and pathways
  • Coronary disease, thrombophilia, lipid metabolism, and longevity markers
  • DisGeNET database integration for comprehensive disease-gene-variant associations

File Upload for Genetic Analysis

Users can upload their genetic data files directly in the UI for personalized analysis:

1. Generate a genetic report from our oakvar deployment or your own deployment
2. Export the interesting for you part of the report as a CSV file
3. Upload the file in the just-genetics-chat interface after activating the "Genetics Genie" agent
4. Chat with the Genetics Genie to interpret your genetic data and understand potential health implications

Genetic Databases

The project includes several specialized genetic databases in the data/genetics/ directory that power the genetic analysis tools:

• coronary.sqlite: Database of coronary disease-related genetic variants and their associations
• thrombophilia.sqlite: Database of thrombophilia-related genetic variants and their clinical implications
• lipid_metabolism.sqlite: Database of genetic variants related to lipid metabolism pathways
• longevitymap.sqlite: Database mapping genetic variants to longevity and aging-related traits
• disgenet_2020.sqlite: Comprehensive database of gene-disease-variant associations from DisGeNET
• disease_names.csv: Reference file for disease name standardization and fuzzy matching
• dna_sequencing.txt: Information about DNA sequencing technologies and methodologies

These databases are accessed through specialized Python tools in the agent_tools/ directory:

• coronary.py: Query coronary disease-related genetic information
• thrombophilia.py: Query thrombophilia-related genetic information
• lipidmetabolism.py: Query lipid metabolism-related genetic information
• longevitymap.py: Query longevity-related genetic information
• disgenet.py: Query comprehensive disease-gene-variant associations
• links.py: Helper functions to generate links to external resources (NCBI, PubMed)
• dna-sequencing.py: Retrieve information about DNA sequencing technologies

Using the Genetic Tools

The Genetics Genie agent is configured to use these tools automatically. When you ask questions about specific genes, variants (rsIDs), or diseases, the agent will query the appropriate databases and return relevant information.

Important Note on API Keys

The default free Groq API key included in this repository has token limitations that prevent it from handling CSV file analysis effectively. For analyzing genetic data files, we strongly recommend:

1. Obtaining your own Groq API key with higher token limits
2. Adding your personal key to the .env.keys file in the project root directory:

   GROQ_API_KEY=your_personal_key_here
   MISTRAL_API_KEY=your_personal_key_here
   OPENAI_API_KEY=your_personal_key_here
   HUGGINGFACEHUB_API_KEY=your_personal_key_here
   

This is a fork of just-chat project Everything below is from the original just-chat README.md file. There you can find more information about deployment.

---

just-chat

Make your LLM agent and chat with it simple and fast!

Setting up your agent and your chat in few clicks

just-chat

Make your LLM agent and chat with it simple and fast!

Setting up your agent and your chat in few clicks

Quick start

Just clone repository and run docker-compose!

git clone https://github.com/winternewt/just-chat.git
USER_ID=$(id -u) GROUP_ID=$(id -g) docker compose up

And the chat with your agent is ready to go! Open http://localhost:3000 in your browser and start chatting with your agent! Note: container will be started with the user and group of the host machine to avoid permission issues. If you want to change this, you can modify the USER_ID and GROUP_ID variables in the docker-compose.yml file.

If you prefer Podman or use RPM-based distro where it is the default option, you can use alternative Podman installation:

git clone https://github.com/winternewt/just-chat.git
podman-compose up 

Unlike Docker, Podman is rootless-by-design maps user and group id automatically. NB! Ubuntu 22 contains podman v.3 which is not fully compatible with this setup, assume podman v4.9.3 or higher is required.

You can customize your setup by:

1. Editing chat_agent_profiles.yaml to customize your agent
2. Adding tools to /agent_tools directory to empower your agent
3. Modifying docker-compose.yml for advanced settings (optional)

The only requirement is Docker (or Podman, both are supported)! We provide detailed installation instructions for both Linux and Windows in the Installation section. Also check the notes section for further information.

What can you do with Just-Chat?

• 🚀 Start chatting with one command ( docker compose up )
• 🤖 Customize your AI assistant using a YAML file (can be edited with a text editor)
• 🛠️ Add new capabilities with Python tools (can add additional functions and libraries)
• 🌐 Talk with agent with a chat web interface at 0.0.0.0:3000
• 🐳 Run everything in Docker containers
• 📦 Works without Python or Node.js on your system

We use just-agents library to initialize agents from YAML, so most of the modern models ( DeepSeek Reasoner, ChatGPT, LLAMA3.3, etc.) are supported. However, you might need to add your own keys to the environment variables. We provide a free Groq key by default but it is very rate-limited. We recommend getting your own keys, Groq can be a good place to start as it is free and contains many open-source models.

Project Structure

• chat_agent_profiles.yaml - Configure your agents, their personalities and capabilities, example agents provided.
• /agent_tools/ - Python tools to extend agent capabilities. Contains example tools and instructions for adding your own tools with custom dependencies.
• /data/ - Application data storage if you want to let your agent work with additional data.
• docker-compose.yml - Container orchestration and service configuration.
• /env/ - Environment configuration files and settings.
• images/ - Images for the README.
• /logs/ - Application logs.
• /scripts/ - Utility scripts including Docker installation helpers.
• /volumes/ - Docker volume mounts for persistent storage.
• /logs/ - Application logs. We use eliot library for logging

Note: Each folder contains additional README file with more information about the folder contents!

Installation

Just-Chat is a containerized application. To run it you can use either Docker or Podman. You can skip this section if you already have any of them installed. If you do not have a preference we recommend Podman as more modern and secure container engine.

Detailed docker instructions:

Docker Installation on Linux

Install Docker and Docker-compose Standalone

Refer to the official guides:

• Docker Installation Guide.
• Docker-compose Standalone Installation Guide.

For Ubuntu users, you can review and use the provided convenience.sh script:

./scripts/install_docker_ubuntu.sh

Or follow these manual steps:

Setup Docker's apt repository

# Add Docker's official GPG key:
sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Add the repository to Apt sources:
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update

Install latest Docker packages

sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
curl -SL https://github.com/docker/compose/releases/download/v2.32.4/docker-compose-linux-$(uname -m) -o /usr/local/bin/docker-compose
chmod +x /usr/local/bin/docker-compose
sudo ln -sf /usr/local/bin/docker-compose /usr/bin/docker-compose

Docker Installation on Windows

Prerequisites

• Windows 10 (Pro, Enterprise, Education) Version 1909 or later
• Windows 11 (any edition)
• WSL 2 (Windows Subsystem for Linux) enabled (recommended) - WSL Installation Guide
• Hyper-V enabled (if using Windows 10 Pro/Enterprise)
• At least 4GB of RAM (recommended)

Installation Steps

1. Download Docker Desktop
2. Run the installer and follow the prompts
3. Restart your PC
4. Launch Docker Desktop
5. Docker Compose is included with Docker Desktop

For detailed instructions and troubleshooting, see the official Windows installation guide.

Details

If you prefer Podman, you can use the following instructions:

Podman Installation on Linux

For Ubuntu users (especially Ubuntu 24.04+):

# Install Podman
sudo apt-get update
sudo apt-get install -y podman

# Install Python3 and pip if not already installed
sudo apt-get install -y python3 python3-pip

# Install Podman Compose
pip3 install podman-compose

For legacy Ubuntu users (22.04 LTS): You will have, sadly, to build podman from source. Due to outdated go-lang version in Ubuntu 22.04 LTS, you will have to add ppa repository and install a newer version of go-lang as a prerequisite and a bunch of libraries:

sudo add-apt-repository ppa:longsleep/golang-backports
sudo apt update
sudo sysctl kernel.unprivileged_userns_clone=1
sudo apt install git build-essential btrfs-progs gcc git golang-go go-md2man iptables libassuan-dev libbtrfs-dev libc6-dev libdevmapper-dev libglib2.0-dev libgpgme-dev libgpg-error-dev libprotobuf-dev libprotobuf-c-dev libseccomp-dev libselinux1-dev libsystemd-dev make containernetworking-plugins pkg-config uidmap
sudo apt install runc # only if you don't have docker installed

Clone the podman repository and checkout the latest stable version from 24 LTS:

git clone https://github.com/containers/podman.git
cd podman/
git checkout v4.9.3
make
sudo make install
podman --version

For other Linux distributions, refer to:

• Podman Installation Guide
• Podman Compose Installation Guide

Podman Installation on Windows

Prerequisites

• Windows 10/11
• WSL 2 enabled
• 4GB RAM (recommended)

Installation Steps

1. Download and install Podman Desktop
2. Initialize Podman:

podman machine init
podman machine start

3. Install Podman Compose:

pip3 install podman-compose

For detailed instructions, see the official Podman documentation.

Clone Just-Chat repository

git clone https://github.com/winternewt/just-chat.git

Start the application

docker compose up

Some notes

0. Be sure to use docker pull (or podman pull if you use Podman) from time to time since the containers do not always automatically update when image was called with :latest It might even cause errors in running - so keep this in mind.

1. After the application is started, you can access the chat interface at 0.0.0.0:3000

2. Key settings in docker-compose.yml (or podman-compose.yml if you use Podman):

   • UI Port: 0.0.0.0:3000 (under huggingchat-ui service)
   • Agent Port: 127.0.0.1:8089:8089 (under just-chat-ui-agents service)
   • MongoDB Port: 27017 (under chat-mongo service)
   • Container image versions:
     • just-chat-ui-agents: ghcr.io/longevity-genie/just-agents/chat-ui-agents:main
     • chat-ui: ghcr.io/longevity-genie/chat-ui/chat-ui:sha-325df57
     • mongo: latest

3. Troubleshooting container conflicts:

   • Check running containers: docker ps (or podman ps if you use Podman)
   • Stop conflicting containers:

     cd /path/to/container/directory
     docker compose down

   Note: Depending on your system and installation, you might need to use docker-compose (with dash) instead of docker compose (without dash).

4. Best practices for container management:

   • Always stop containers when done using either:
     • docker compose down (or docker-compose down)
     • Ctrl+C followed by docker compose down
   • To run in background mode, use:
     • docker compose up -d
   • This prevents port conflicts in future sessions

5. for editing the model used in chat_agent_profiles.yaml , the types are found here It is the just-agents library

Environment Variables & API Keys Configuration

The application uses environment variables to store API keys for various Language Model providers. A default configuration file is created under env/.env.keys during the initialization process. You can customize these keys to enable integrations with your preferred LLM providers.

Included and Supported Providers

• GROQ: A default API key is provided on the first run if no keys are present. However, this key is shared with other users and is rate-limited (you can get rate limit errors from time to time). We recommend getting your own key from Groq. For additional LLM providers and their respective key configurations, please refer to the LiteLLM Providers Documentation.

Logging and Observability

• By default, the application logs to the console and to timestamped files in the /logs directory.
• In case you run the application in background mode, you can still access and review the console logs by running: docker compose logs -f just-chat-ui-agents.
• Langfuse: Uncomment and fill in your credentials in env/.env.keys to enable additional observability for LLM calls.
• Note: Langfuse is not enabled by default.
• NB! docker compose down will flush the container logs, but application logs will still be available in the /logs directory unless you delete them manually.

How to Update the API Keys

1. Editing the API Keys File:
   The API keys are stored in /app/env/.env.keys. You can update this file manually or run the initialization script located at scripts/init_env.py to automatically add commented hints for missing keys.

2. Using Environment Variables:
   When running the application via Docker, these keys are automatically loaded into the container's environment. Feel free to use other means to populate the environment variables as long as the application can access them.

3. Restart the Application:
   After updating the API keys, restart your Docker containers to apply the new settings, you may need to stop and start the containers to ensure the new keys are loaded:

   docker compose down
   docker compose up

Happy chatting!

Acknowledgments

This project is supported by:

HEALES - Healthy Life Extension Society

and

IBIMA - Institute for Biostatistics and Informatics in Medicine and Ageing Research