Skip to content

AI Setup

Note that the AI features in QualCoder are opt-in and disabled by default. After a fresh install, a wizard will appear that can guide you through the setup if you choose to enable them. You can restart it later by selecting the menu option "AI > Setup Wizard."

All AI-related options are located at the bottom of the settings dialog. Scroll down as needed.

Screenshot AI Settings

Steps of the setup wizard:

  1. Enable the AI integration by clicking the checkbox in the Settings dialog.
  2. Choose the AI model you want to use and configure it.
  3. The local AI memory is then set up and built automatically. Be patient, as this may take a while.
  4. After that, the AI agent in QualCoder is ready to use.

You might also want to read how to best prepare your project for AI use and our notes on data privacy below.

AI Model Selection

With QualCoder, you can choose from a wide range of commercial and non-commercial AI providers, and even use local models hosted on your own machine. Select one of the options in the "AI profile" drop-down in the Settings dialog.

Frontier Models from OpenAI, Anthropic, or Google

These large models deliver the most nuanced analysis of your empirical data and provide the smoothest overall experience. You have several options:

Access via API key

  • Set up an account with one of the providers, acquire an API key, and paste it into the QualCoder settings dialog.
    • OpenAI: Go to the OpenAI Platform, add billing details, then open Settings > API keys > Create new secret key.
    • Anthropic: Create an account in the Claude Console, add API credits or billing details, then go to Settings > API Keys > Create Key.
    • Google Gemini: Sign in to Google AI Studio, select or create a Google Cloud project, then choose Get API key. A limited free tier may be available for some models.
  • API access is pay-per-use. The provider will charge a small fee for each request. Typically, you purchase "credits" in advance, which are then consumed over time. Because qualitative research usually involves relatively small datasets, the cost of using AI in your analysis is typically modest.
  • Data privacy: Any information sent via the paid API interface is usually excluded from future model training and retained on the servers only for 30 to 50 days for billing and abuse monitoring. However, you should always check your provider's current data protection policy, as conditions may change.

ChatGPT Plus, Pro, or Team subscription

  • Since QualCoder version 4.0, you can also use your ChatGPT subscription (Plus, Pro, or Team) as an AI provider inside the app. In this case, usage in QualCoder is deducted from your account's general quota at no extra cost. As this is an experimental feature, future availability may vary.
  • To enable this option, select "OpenAI_ChatGPT_Login..." from the AI profile dropdown in the Settings dialog, then click on "Authenticate...". A ChatGPT login page will open in your default browser. Here, you must authorize QualCoder to use AI models from this account. This replaces the API key needed for other AI profiles.
  • If your authentication expires after a few weeks, return to the settings dialog to renew it.
  • Note that QualCoder has no access to any information in your ChatGPT account besides the raw AI models. This is also true in the other direction, as ChatGPT cannot access any data inside QualCoder.
  • Still, it is good practice to disable the option "Improve the model for everyone" in your ChatGPT profile's "Data Controls" settings. This prevents the content of your interactions with ChatGPT from being used for future AI model training.
  • QualCoder uses the same communication interface as OpenAI's programming assistant Codex. If your organization has disabled Codex in your ChatGPT account, you might not be able to use this integration with QualCoder.
  • For Anthropic Claude or Google Gemini subscriptions, connecting them to QualCoder is less straightforward. If you are technically inclined, you may still get it to work by using CLIProxyAPI as a bridge. If you go this route, add a custom AI profile in QualCoder and use http://localhost:8317/v1 as the "API Base URL" parameter.

Microsoft Azure

Microsoft hosts large AI models from OpenAI on its Azure cloud platform. This is especially useful if you want to ensure that your data is processed entirely in the EU or another specific geographic region. Azure offers special "Data zone" settings for this. Prices are slightly higher than with OpenAI directly, but still reasonable.

To use a model, you must first "deploy" it with your Azure account using the Azure AI Foundry. Search for tutorials on how to do that, or take a look at: https://www.youtube.com/watch?v=a2JtWKSKP4Q

To proceed, you will need the following information: - your deployment name, - the endpoint URL (it must look something like https://XXX.openai.azure.com/), and - your API key.

Go to "Project > Settings > AI Integration", click on "Advanced AI Options > New AI Profile", and give it a name. Then enter your API key in the corresponding field, your Azure deployment name in the fields "Large Model" and "Fast Model" (these can be identical), and the Azure endpoint URL in the field "api_base". You may also want to adjust the context window size depending on the model.

Academic AI Infrastructure

Non-profit academic AI infrastructure gives you access to medium-sized models while maintaining very high data privacy standards. These services are usually free of charge for eligible personnel. The output quality of such mid-size models has improved a lot lately and is good enough for most tasks in QualCoder. However, it is still not on the same level as the large commercial offerings. You may also encounter more hiccups when interacting with the AI agent, such as operational errors or malformed source references.

Blablador - free AI service provided by the German academic research agency Helmholtz Society.

Other Academic Options

Germany:

  • GWDG SAIA Göttingen: Access seems to be limited to universities in northwestern Germany. To use it, you must first set up an account at GWDG and acquire an API key. Then open QualCoder, go to "Project > Settings > AI Integration", click on "Advanced AI Options > New AI Profile", and give the profile a name. After that, enter your API key in the corresponding field, the URL https://chat-ai.academiccloud.de/v1 in the field "API base", and select a large and fast model from the list. You may also want to adjust the context window size depending on the model.
  • hessian.AI Darmstadt: Experimental access, only for eligible people from Hessian universities in Germany. Follow the instructions for GWDG above, but use https://llm-service.ai.tu-darmstadt.de as the API base URL.

Mid-size Models like Mistral, DeepSeek, and Others

The "AI profile" drop-down in the settings dialog also offers options for Mistral (France), DeepSeek (China), and OpenRouter, a platform through which many large language models on different servers can be accessed.

For all of these options, you will need an API key and most likely also a paid account for serious work. Check the data privacy conditions carefully before using any of these services.

Local AI Models on Your Own Machine

Local AI models offer the highest level of data protection, but they also require fairly powerful hardware to run at a reasonable speed and quality. In my testing, Gemma-4-31B-it worked quite well. It needs at least 24 GB of VRAM in 4-bit quantization with an acceptable context window size. For any serious agentic work in QualCoder, I would not go much smaller than that. AI-assisted coding, however, may still work with slightly smaller models.

  • Ollama is a popular choice for running language models locally and works well with QualCoder, using Ollama's OpenAI-compatible API.
  • Make sure Ollama and the AI model are set up and running. Then select the preconfigured Ollama local AI profile in the Settings dialog, which uses http://localhost:11434/v1/ as the API base.
  • The API key is not actually used by Ollama, but it must not be empty, or an error occurs.
  • Select a large and fast model from the list, most likely the same one for both, as you will usually have only one model loaded at a time. You may also want to adjust the context window size depending on your Ollama settings.

Other Models

If you have access to other large language models on cloud platforms, university servers, or your own machine, you can try integrating them into QualCoder as well. - The service you wish to use must provide an interface compatible with the OpenAI API. This is often the case, since this API has become a de facto standard in recent years. - Click on "Advanced AI Options > New AI Profile" in the settings dialog, enter the API network address under "API Base URL", and enter the model name in the fields for the large and fast model (these can be identical). You may also want to adjust the context window size depending on the model. - If you want more options, edit the config.ini file, located in the .qualcoder subfolder of the user's home directory. Do this only when QualCoder is not running. The AI model definitions are listed at the end of config.ini and have the following format (omit the "<>" marks): 

[ai_model_your_model_name]
desc = A description shown in the UI.
       Can have more than one line.
access_info_url = <URL pointing to a website with model info. Can be empty>
large_model = <The exact name of the model in the API>
large_model_context_window = <The maximum number of tokens in a single request>
fast_model = <Can be identical to large_model or name a smaller model, used for simple tasks>
fast_model_context_window = <The maximum number of tokens for the small model>
reasoning_effort = default
api_base = <The URL of the API base, e.g., http://localhost:11434/v1 for a local Ollama>
api_key = <The API key if needed, or "None" instead. Do not leave this field empty.>
Note that the section name must always start with the prefix 'ai_model_'.

If you get other services running in QualCoder, or if you tried and failed, we would like to hear about your experience.

Advanced AI Options

At the very bottom of the Settings dialog, you will find an "Advanced AI Options" button. Clicking it reveals a few more options.

  • One common use case is to switch to a newer or better AI model if your provider offers one. You can do that by selecting the model from the drop-down list in the "large model" and "fast model" fields, or by entering the exact name directly. To find the correct model name, search the web for YOUR MODEL api name. The large and fast models can be identical, but the fast model may also be much smaller because it is used only for housekeeping tasks, such as generating automatic titles for new AI agent chats.
  • Reasoning: This parameter determines how much internal "thinking" the AI does before responding. Not every model supports this parameter, so leave it on "default" if in doubt. Also note that QualCoder already has a lot of "thinking" loops built into the agent workflow itself, so a high reasoning setting may give you less improvement than expected. However, high reasoning will consume more energy, cost more, and also slow the AI down, so use this option with care.
  • When it comes to the other advanced options, it is probably best to leave them at their default values if you don't know what they mean. Note that the "temperature" and "top_p" parameters might be silently ignored by some models, especially in reasoning mode.

The Local AI Memory Setup

  • The AI agent in QualCoder uses a special local memory to search empirical documents quickly and find relevant passages. This greatly reduces the amount of data sent to the cloud, thereby enhancing privacy, saving resources, and increasing speed.
  • The memory is powered by a small local open-source AI model, approximately 2.5 GB in size, which is downloaded automatically the first time you activate the AI. Model storage locations:
  • Windows: C:\Users\YOUR_USERNAME\.cache\torch\sentence_transformers
  • Linux: /home/YOUR_USERNAME/.cache/torch/sentence_transformers
  • MacOS: /users/YOUR_USERNAME/.cache/torch/sentence_transformers
  • Once you open a QualCoder project, this AI model reads all text documents and incorporates them into its internal memory.
  • This process occurs only once. When you reopen the project later, the "AI memory" loads quickly from disk. If you add new documents to your project or edit existing ones, your local AI memory is updated accordingly.
  • The initial process of reading and memorizing your documents may take some time, so please be patient. It happens in the background, with the status bar showing "AI: reading". While this is happening, AI-related functions are unavailable, but you can use the rest of QualCoder as usual.

AI: reading message

Technical note: The QualCoder local AI memory is a hybrid system based on E5 sentence encoder embeddings stored in a FAISS vector store for semantic search, and a SQLite BM25 index for fast keyword retrieval. In addition, the AI agent can use regular expressions to search the project data.

Improve AI Usability in Your Project

The AI agent in QualCoder should be able to read and understand the structure of your project, your empirical documents, codes, and memos. It should also have a clear picture of the goals, research questions, and methods that drive your research. This allows it to provide much more targeted answers. Some suggestions:

  • Update your project memo (menu "Project > Project Memo") with a short description of your research topics, questions, objectives, and the empirical data collected. This information will accompany every request sent to the AI, resulting in much more useful answers.
  • Give your empirical documents readable names so the AI agent can infer the type of data, e.g., "Interview Alice.txt". You can rename documents directly in the "Manage files" tab without re-importing them.
  • When working with interview transcripts, it is advisable to mark the interviewer and respondent in every turn, e.g., with a prefix like "Interviewer:" and "Alice:". This allows the AI agent to grasp the different roles in the interview even when looking at only a small section of the transcript.
  • If you use memos to record personal notes and unfinished brainstorming ideas that you do not want to share with the AI agent, put these notes behind a "#####" mark. Any memo content below this mark will not be sent to the AI.

Some Notes on Privacy and Data Protection

  • We understand that using cloud-based services like those from OpenAI raises questions regarding data privacy and protection.

  • However, we believe that QualCoder's use of these services is aligned with the ethical principles that guide qualitative social research. Otherwise, we would not offer such features.

  • The final decision rests with you and depends heavily on your specific project, the type of data you handle, and the AI provider you decide to use. We aim to make it as transparent as possible what happens to your data so that you can make an informed decision.

QualCoder follows a "Privacy by Design" approach:

  • The app will send as little data as possible to the cloud, using local processing whenever feasible. Most features use the local AI memory described above to make a preselection of relevant data. Afterward, only a small number of selected text chunks, each about 500 characters long, are sent to the cloud for deeper analysis.

  • When you use the OpenAI API, your data is governed by the Enterprise privacy regulations. These regulations are much stricter in terms of data protection than those of free chatbots on the internet. OpenAI guarantees that the data sent via this interface will NOT be used to train AI models, will be kept confidential, and will be deleted within 30 days. Other AI service providers offer similar conditions.

  • QualCoder is not limited to commercial AI providers. For instance, we have partnered with "Blablador," a service running large language models on non-commercial academic hardware that offers excellent privacy (see above).

  • Additionally, it is possible to add your own models to QualCoder, including those running entirely locally on your machine without any network access. As of today, however, the trade-off in output quality is so significant that local AI models have only limited use cases, unless you have very powerful hardware. This situation will hopefully change in the future.

  • In general, we recommend that you anonymize your data very carefully before using any cloud-based AI service for analysis.