LAIQA - Local Artificial Intelligence for Qualitative Analysis

This repository contains a framework for applying local LLMs (via Ollama) to the task of labeling and analyzing qualitative interviews.

1. Setup .envs Create a .env file in the backend/ directory. This file manages your API connections and security.

# Ollama Configuration
OLLAMA_BASE_URL=http://localhost:11434 #or whatever port your ollama instance uses
OLLAMA_URL=http://localhost:11434/api/generate
OLLAMA_PORT=11434

# Security & Auth
SECRET_KEY="super-secret-string"
ALGORITHM="HS256"


# Initial Database Admin (Automatically seeded on first run)
SEED_ADMIN_USER=adminuser
SEED_ADMIN_PASSWORD=admin123

2. Install Python dependencies by cd into root dir and running:

pip install -r requirements.txt

3. Install and run Ollama

Make sure you have Ollama installed and at least one model pulled. We recommend gemma3:12b (or any Gemma3 model that fits your hardware):

ollama pull gemma3:12b

4. Set up the database

The database is created automatically when you first run the backend. No extra steps needed. 5. Start the backend

cd backend
uvicorn api.main:app --host 0.0.0.0 --port 8002 --reload

6. Start the frontend

In another terminal:

cd frontend
npm install   # only the first time
npm install papaparse
npm run dev -- --host 0.0.0.0 --port 3000

6. Create your first user

We've included a handy script to create users and select access:

python utility/register_users.py

Add yourself and your users. Then open your browser at http://localhost:3000 and log in. Admin access + some clever pathing to support authorization for seperate parts of the application included. check backend/routes/route_protection.py for the paths

How to Use LAIQA: Step-by-Step Workflow

LAIQA’s workflow is divided into three distinct stages, designed to keep the researcher in control of the meaning-making process while leveraging your selected closed circut AI .

Stage 1: Label Generation (Inductive Coding)

In this phase, you will set up your project and generate an initial pool of specific text labels based on a subset of your documents.

1. Create a project and upload the complete corpus of documents you wish to analyze (must be .docx format).

2. Configure your model by selecting a locally installed Ollama model. At this step, you can also customize the default prompt template, temperature, and maximum output tokens.

3. Select seed documents that will form the basis of your initial labels. You can hand-pick a diverse subset of documents or let LAIQA randomize the selection for you.

4. Choose a segmentation mode for how LAIQA should parse your texts:

   • Dynamic (Default): Prioritizes longer paragraphs while keeping balanced document coverage. Recommended for interviews.

   • Sentence: Samples paragraphs with uniform probability, ensuring equal representation across all document sections regardless of length.

   • Strict Sentence: Samples individual sentences using standard delimiters (., !, ?) for highly text-close, fine-grained analysis.

5. Start the labeling process. LAIQA will generate a context summary of your seed documents and begin proposing initial labels (the default is 42 labels per document, which you can adjust). Feel free to leave the page while this runs.

6. Review the proposed labels. Once finished, review the generated labels, their descriptions, the exact text segments that prompted them, and the LLM's probability scores. You can manually add, modify, or delete any labels before moving on.

Stage 2: Codebook Consolidation

Here, your initial, instance-level labels are grouped and refined into overarching analytical codes to build your final codebook.

1. Initiate consolidation. Go to your newly generated codebook and click "Consolidate".

2. Wait for the automated grouping. LAIQA runs a 3-round "tournament" behind the scenes: it groups batches of labels using semantic similarity (0.94 threshold), merges true synonyms into master codes using the LLM, and performs a final cleanup pass.

3. Review the consolidation plan. You will be presented with a preview of the suggested master codes and their grouped labels.

4. Refine your codebook. You have full editorial control here. You can:

   • Accept the suggested merges.

   • Manually move, merge, or delete codes (working tabula rasa if preferred).

   • Edit code names and descriptions directly.

   • Ask the LLM to suggest a new name and description for a newly merged group of codes.

5. Commit the codebook. Once satisfied, approve the plan. LAIQA validates the hierarchy (preventing circular relationships) and saves a complete audit trail of what was merged.

Stage 3: Application & Export (Deductive Coding)

Finally, you will apply your newly consolidated codebook to the rest of your corpus and export your data.

1. Start the application. Access your consolidated codebook and click "Apply". (Note: This stage cannot be started until Stage 2 is complete).

2. Run the coding process. Enter your own prompt or use the default. LAIQA will segment your remaining, unseen documents using your previously chosen algorithm and ask the LLM to assign the best-fitting code to each segment (skipping segments where no code fits).

3. Final human review. Review the newly coded documents. You can correct any labels applied by the LLM, adjust the text segments, or manually add your own codes if a new pattern emerges.

4. Export your data. Extract your finalized project as a .csv file. This export includes every unique application of a label along with comprehensive metadata (text position, document source, LLM vs. human source, merge history, and log probabilities) for your final analysis.