Quick Start

Introduce you how to run quelmap on your machine.

Ensure Docker is installed and running on your system.

Clone the quelmap repository:

git clone https://github.com/quelmap-inc/quelmap.git

After cloning, navigate to the directory containing the project files.
```
cd quelmap
```
Starting up application
```
docker compose up --build -d
```
This command sets up 3 containers(Application, Python Sandbox, PostgresDB). Wait for starting up all containers, Access "http://localhost:3030".
You can use any LLM provider’s model by setting the base_url and api_key from the settings icon in the top right (by default, Ollama is used).
If you set an LLM provider such as OpenAI or Groq, your data schema will be sent. If you want to run everything completely locally, please proceed to the LLM setup steps below.

LLM Setup

Install ollama (Skip if you already installed)
https://ollama.com/
Download model (Lightning-4b)
Lightning-4b is lightweight model specially trained to use in quelmap. This model offers greater stability than models with 50 times more parameters in common analytical tasks.
Detail of Lightning 4b

- Laptop (ex. mac book air 16GB) - 4bit Quantization + 10240 Context Window
```
ollama pull hf.co/quelmap/Lightning-4b-GGUF-short-ctx:Q4_K_M
```
- Gaming Laptop - 4bit Quantization + 40960 Context Window
```
ollama pull hf.co/quelmap/Lightning-4b-GGUF:Q4_K_M
```
- Powerfull PC with GPU - No Quantization + 40960 Context Window
```
ollama pull hf.co/quelmap/Lightning-4b-GGUF:F16
```
(You can use another model like qwen3-next if you have enough GPU.)

If you feel response is too slow, add "/no_think" or "Do not think." in your query and It will generate python code immediately.

After download model, hit reload button on yor browser and you can choose the model in UI.
If no model appeared, chack ollama port is 11434. If not, modify port of base_url from the settings icon in the top right.

Sample Dataset & Query

For those who don’t have data on hand to analyze, we’ve prepared a sample dataset to try out quelmap. Please download the CSV file from this link berow and upload it using the “new tables” button.
employee-attrition-dataset

Sample queries:

Apply One-Hot Encoding to the BusinessTravel column.
Create a scatter plot of Age versus Total Working Years.
Use a Chi-square test to examine whether there is a difference in business travel frequency between single and married employees.
Visualize the relationship between Performance Rating and Number of Training Sessions attended last year.
Use a boxplot to show the relationship between Attrition and Monthly Income, and check whether employees who left tend to have lower monthly income.
Analyze the correlation between Relationship Satisfaction with Manager and Years with Current Manager.
Perform a t-test to test whether there is a difference in Job Satisfaction between employees who have worked at one or more previous companies and those who have worked at none.

Connect to Database with connection string (Preview)

Normally, uploaded data is stored in the volume of the Postgres container, but you can also execute SQL directly against an external database. A connection string with read permissions is required. (Since unexpected changes may occur, it is recommended to use a user with read-only permissions.)

Stop containers if running
```
docker compose down -v
```

Set connection string in .env file

echo "USER_DATABASE_URL=postgresql://postgres:mysecretpassword@localhost:5432/mydatabase" >> .env

Start container
```
docker compose up --build -d
```

Contribution

If you find bugs or have ideas, please share them in via GitHub Issues. For more information on contributing to quelmap you can read the CONTRIBUTING.md file to learn more about quelmap and how you can contribute to it.