Quickstart

Clone the lettuce repository

git clone https://github.com/Health-Informatics-UoN/lettuce.git
cd lettuce

Set Up Your Environment

Lettuce can be configured through environment variables. These are the defaults for the configurable options:

DB_HOST="localhost"
DB_USER="postgres"
DB_PASSWORD="password" 
DB_NAME="omop"
DB_PORT="5432" 
DB_SCHEMA="cdm"
DB_VECTABLE="embeddings"
DB_VECSIZE="384"
LLM_MODEL="LLAMA_3_1_8B"
TEMPERATURE="0"
EMBEDDING_MODEL="BGESMALL"
EMBEDDING_TOP_K="5"

If you need to change the settings from the defaults, Lettuce will read from a .env file. Create a file called “.env” in the lettuce directory and specify the options you wish to change as above. Any variables you wish to keep the same can be omitted from the .env file. More details can be found in the base_options documentation

Install dependencies

Dependencies are handled with uv, and first have to be installed from the pyproject.toml via:

uv sync

This will install the dependencies for running Lettuce with the LLM running in an Ollama server. For this to work, you’ll have to have an Ollama server running, and make requests to a model that you have previously pulled to Ollama. For example, if you specify LLM_MODEL="gemma3n:e4b" in lettuce, you will need to have previously run

ollama pull gemma3n:e4b

Lettuce can also be run without Ollama, instead using Llama.cpp for inference.

The dependencies for running inference in Llama.cpp are installed using the --extra flag, e.g.

uv sync --extra llama-cpp

This will try to build Llama.cpp on your machine. There are a few pitfalls here. On Windows, you will need to have Visual Code set up correctly. On Apple silicon, this seems fairly bulletproof, but on other operating systems we have also had issues with the installation not correctly recognising GPUs. Workarounds can be found on the Llama.cpp repository. These seem to change fairly often, so caveat developer!

As an alternative, we provide the option of using precompiled wheels as dependencies.

Run the CLI

Once this is complete, you can run lettuce-cli

uv run lettuce-cli --no-use-llm --no-vector-search "acetaminophen" 

The flags in this command disable the vector search and LLM, just querying the database for “acetaminophen”. Running the LLM will download a model, and vector search use the embeddings table to perform and semantic search on the search term, so these flags can be omitted when you’re ready to take these steps.