https://github.com/mihaiconstantin/boterview
Effortlessly conduct chatbot-based interviews with customizable protocols and randomized condition assignments, tailored for social science research.
https://github.com/mihaiconstantin/boterview
chatbot interview llm qualitative-research research social-science survey-research
Last synced: 8 months ago
JSON representation
Effortlessly conduct chatbot-based interviews with customizable protocols and randomized condition assignments, tailored for social science research.
- Host: GitHub
- URL: https://github.com/mihaiconstantin/boterview
- Owner: mihaiconstantin
- License: mit
- Created: 2025-02-06T13:39:58.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-04-02T11:26:39.000Z (about 1 year ago)
- Last Synced: 2025-10-13T09:06:32.936Z (8 months ago)
- Topics: chatbot, interview, llm, qualitative-research, research, social-science, survey-research
- Language: Python
- Homepage: https://boterview.dev
- Size: 1.6 MB
- Stars: 4
- Watchers: 2
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
AI-based interview studies...
...as smooth as butter
`boterview` is a `Python` package that enables social science researchers to
easily deploy chatbot-based interviews with customizable protocols and
randomized condition assignment.
## Installation
You can install the package from the `PyPI` repository using `pip` as follows:
```bash
# Install using `pip`.
pip install boterview
```
Depending on your setup, you may consider using a `Python` virtual environment
before running the command above. For instance, you can create a new virtual
environment called `.venv` and activate it as follows:
```bash
# Create a new directory for your study.
mkdir my-study
# Move into the directory.
cd my-study
# Create a new `Python` virtual environment called `.venv`.
python -m venv .venv
# Activate the virtual environment.
source .venv/bin/activate
```
### Development Version
You may also install the development version of the package directly from the
`GitHub` repository using `pip` as follows:
```bash
# Install using `pip`.
pip install boterview@git+https://github.com/mihaiconstantin/boterview
```
## Usage
To use `boterview`, you need to specify a `TOML` configuration file for your
study, and provide several text files containing the interview-related content,
as well as the user interface content (e.g., the study instruction, consent
information and more). While all these things can be done manually, `boterview`
provides a command line interface (CLI) to help you with the process.
### Commands
To get started, you can run the command below to see all the available command
available in the `boterview` CLI.
```bash
# Show all available commands.
boterview --help
```
Boterview provides four main command groups: `generate`, `parse`, `preview`, and
`run`. For each command, please check the help message (i.e., via `--help`) to
see the available options and arguments.
### Content Generation
The `boterview generate` command can be used to generate various things related
to your study. It contains three main subcommands:
- `codes`: Used to generate participation codes for your study.
- `secret`: Used to generate a random secret required to run the study.
- `study`: Used to scaffold an example study setup.
## Data Parsing
The `boterview parse` command can be used to parse the study database. It is
used to extract the study data from the `sqlite` database and save it as a
`markdown` file.
### Condition Previewing
The `boterview preview` command can be used to preview a study condition given a
configuration file. This command prints to the console the content that
constitutes the system prompt for the bot for a given study condition.
## Running the Study
The `boterview run` command can be used to start a study based on a
configuration file. This command starts a web server that serves the study
interface and handles the chatbot interactions.
### Example
Below you can find a minimal example to get you started with `boterview`. The
commands below assume you have already installed the package.
```bash
# Scaffold a study in the current working directory with 100 participation codes, and include a secret.
boterview generate study --path . --quantity 100 --config study.toml --secret
# Preview the default condition setup.
boterview preview --config study.toml --condition "Condition 1"
# Run the study and save the data in the `boterview.db` database file.
boterview run --config study.toml --database boterview.db
```
At this point, you can access the study at
[http://localhost:8080](http://localhost:8080).
Suppose several participants have went through the study and you want to
download the data. You can do so by navigating to the `/download` endpoint. The
secret required to download the data is stored in the `study.toml` file (i.e.,
it was automatically included by the `--secret` flag used when scaffolding the
study).
Alternatively, use the `boterview parse` command against the database file,
which will extract the data and save it as a `markdown` file in the current
working directory. For example:
```bash
# Parse the study data.
boterview parse --config study.toml --database boterview.db
```
**_Note._** We are working on expanding the documentation and adding more
examples. For the time being, the instructions above should suffice to get you
started with `boterview`. We also recommend reading the comments in the study
configuration file, as well as the application interface default content. See
the _Contributing_ section below for more information on how you can help.
## Contributing
- Any contributions are welcome and greatly appreciated. Please open a [pull
request](https://github.com/mihaiconstantin/boterview/pulls) on `GitHub`.
- To report bugs, or request new features, please open an
[issue](https://github.com/mihaiconstantin/boterview/issues) on `GitHub`.
## License
- The package source code in this repository is licensed under the [MIT
license](https://opensource.org/license/mit).
-
The documentation and other website materials by Mihai Constantin are licensed under CC BY 4.0.