LUCID Toolkit Setup Guide (v1.6)

IMPORTANT: This is a detailed guide with step-by-step instructions and screenshots, if you instead want a Quick Start guide, click here, and scroll down after following the link.

Table of Contents

  1. Introduction
  2. Prerequisites
  3. Setup Guide
  1. Configuration Reference
  1. Data Output Explanation
  2. Troubleshooting Guide
  3. Appendix A: Supplementary Information for AI Assistants

Academic Citation for the LUCID Framework and Accompanying Toolkit:

Garvey, Aaron M. and Simon J. Blanchard (2025), “Generative AI as a Research Confederate: The “LUCID” Methodological Framework and Toolkit for Controlled Human-AI Interactions Research in Marketing,” Working Manuscript.

1. Introduction

Welcome to the LUCID (LLM Unified Confederate for Interactive Dialogue) Toolkit! This document serves as your guide to setting up, configuring, and managing the toolkit.

IMPORTANT: This document is designed to be uploaded directly to the Generative AI platform of your choice. Once uploaded, your GenAI assistant can use the comprehensive information herein to answer questions about setup steps, configuration questions, customization, and troubleshooting. We recommend using ChatGPT o3, Gemini Advanced 2.5, Claude Sonnet 3.7, or their most recent successors. Please leverage your GenAI assistant before contacting the creators directly with troubleshooting questions. Of course, please do report to us any suspected bugs you discover!

Usage License: The LUCID toolkit code is available for non-commercial use under Creative Commons BY-NC-SA (https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode.en).

Purpose: The LUCID toolkit provides a configurable tool enabling researchers to conduct human-AI interaction studies within the Qualtrics survey platform. It was designed to illustrate and support the LUCID methodological framework for research into human-genAI interactions (Garvey and Blanchard 2025). Participants interact with a generative AI model (like OpenAI's GPT series) via a chat interface embedded directly in a survey question. This toolkit provides an unprecedented combination of experimental control and ecological validity in administering research into human-GenAI interactions.

Components:

This guide explains how to deploy the backend, set up the Qualtrics survey, configure the tool, understand the collected data, and troubleshoot common issues. It assumes basic familiarity with navigating the Qualtrics platform but limited technical experience beyond that.

2. Prerequisites

Before you begin, you will need accounts for the following services:

3. Setup Guide

Setting up LUCID involves two main parts: deploying the backend service and configuring your Qualtrics survey. If you need help during setup, remember you can upload this document to your GenAI assistant.

3.1. Backend Deployment (Vercel)

To proceed with this setup, you will first need to sign up for a free GitHub account (https://github.com/signup) and a free Vercel “Hobby” account (https://vercel.com/signup).

Your LUCID backend will run on Vercel, a cloud platform. We use a simple "Deploy Button" method linked to a GitHub code repository. This process copies the backend code to your own GitHub account and deploys it to your Vercel account. This might sound complex, but the process is very straightforward, and the end result is a single link that you will paste into your Qualtrics survey.

  1. Navigate to the Code Repository: Open your web browser and go to the official LUCID backend repository on GitHub: https://github.com/amgarv/LUCID_TOOL_BACKEND
  2. Find the README: The main page of the repository automatically displays the contents of the README.md file. Scroll down this page if necessary to view the instructions. (see screenshot below)

 

 

  1. Click the "Deploy with Vercel" Button: Within the displayed README content, locate and click the “Deploy” button that looks like this:

 

 

  1. Connect Git Provider: Vercel will open and prompt you to sign in, choose “Continue with Github,” like this:

  1. Create your Project:

  1. Input Your OpenAI API Key: **This is crucial.** Vercel will prompt you for:

 

 

  1. Deploy: Click the "Deploy" button in Vercel.
  2. Wait: Vercel will build and deploy your backend. This usually takes 1-2 minutes. Wait for the "Congratulations!" status (you might see confetti!). A screenshot of a computer AI-generated content may be incorrect.
  3. Get Your Backend URL:
  1. OPTIONAL FOR ADVANCED USERS: Security through ALLOWED_ORIGINS

o        The LUCID backend is set up to support CORS security. The backend will default to allowing requests from any origin (*). This makes setup easy, but less secure as technically anyone with your deployment URL could run studies with your backend and incur OpenAI API costs to you. If you keep this approach and do not set up CORS security, strongly consider disabling the OpenAI secret key via the OpenAI platform when not actively collecting data to make sure no one else can use your backend.

To limit use of your tool to only specific Qualtrics domains, advanced users you can set the ALLOWED_ORGINS within Vercel.

 

3.2. Qualtrics Setup

Integrate your new Vercel backend with your Qualtrics survey using the provided template.

  1. Download Template: Download the LUCID_Qualtrics_Template_1_One_Group_Design.qsf (or similar) file from the GitHub toolkit repository at https://github.com/amgarv/LUCID_TOOL_BACKEND
  2. Import into Qualtrics: Create a new project "From a File" and upload the .qsf.
  3. Configure Survey Flow:

A screenshot of a computer AI-generated content may be incorrect.

  1. Review Survey Content:

Preview your survey thoroughly to ensure the chat interface loads and communicates with your backend.

4. Configuration Reference

Configure LUCID via Embedded Data fields in the Qualtrics Survey Flow. (see screenshot below)

4.1. Backend URL

4.2. Logging Variables

4.3. Prompts

4.4. Introduction Message

4.5. User Interface Settings

4.6. Interaction Limits

4.7. Model Settings

4.8. Experimental Conditions

The “Randomizer” element can be used to create and administer multiple conditions that each reflect a different configuration of the LUCID tool. For example, a two-group between subjects design could be created such that one condition contains an initialization prompt that instructs the LLM to respond in a casual tone, whereas the other condition contains a different initialization prompt that instructs the LLM to respond in a formal tone.

5. Data Output Explanation

IMPORTANT: When exporting your LUCID survey dataset to SPSS format, select “more options” and set the string width option to extra long (32,000) to ensure that conversation history and logs are not cut short.

Key Embedded Data fields saved with each Qualtrics response:

6. Troubleshooting Guide

If you encounter problems, upload this entire document to your preferred GenAI assistant and describe the issue. Provide the AI with:

Common Issues & Checks (for reference or discussion with AI assistant):

Appendix A: Supplementary Information for AI Assistants

(This appendix provides technical context for a GenAI assistant analyzing this document.)

1. LUCID System Overview:

2. Key Configuration Points:

3. Common Error Signatures & Checks (for AI Reference):

4. Key Logs/Info User Should Provide: