{"id":25283026,"url":"https://github.com/mihaiconstantin/boterview","last_synced_at":"2025-10-13T09:06:33.284Z","repository":{"id":277162275,"uuid":"928345849","full_name":"mihaiconstantin/boterview","owner":"mihaiconstantin","description":"Effortlessly conduct chatbot-based interviews with customizable protocols and randomized condition assignments, tailored for social science research.","archived":false,"fork":false,"pushed_at":"2025-04-02T11:26:39.000Z","size":1674,"stargazers_count":4,"open_issues_count":2,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-10-13T09:06:32.936Z","etag":null,"topics":["chatbot","interview","llm","qualitative-research","research","social-science","survey-research"],"latest_commit_sha":null,"homepage":"https://boterview.dev","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mihaiconstantin.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-02-06T13:39:58.000Z","updated_at":"2025-08-27T08:40:15.000Z","dependencies_parsed_at":"2025-02-12T13:56:27.452Z","dependency_job_id":"30f5fe7b-022a-43aa-bff1-96085a460eee","html_url":"https://github.com/mihaiconstantin/boterview","commit_stats":null,"previous_names":["mihaiconstantin/boterview"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/mihaiconstantin/boterview","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mihaiconstantin%2Fboterview","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mihaiconstantin%2Fboterview/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mihaiconstantin%2Fboterview/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mihaiconstantin%2Fboterview/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mihaiconstantin","download_url":"https://codeload.github.com/mihaiconstantin/boterview/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mihaiconstantin%2Fboterview/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279014481,"owners_count":26085535,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-13T02:00:06.723Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chatbot","interview","llm","qualitative-research","research","social-science","survey-research"],"created_at":"2025-02-12T19:58:17.637Z","updated_at":"2025-10-13T09:06:33.267Z","avatar_url":"https://github.com/mihaiconstantin.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://boterview.dev\"\u003e\n        \u003cimg width=\"180px\" src=\"https://raw.githubusercontent.com/mihaiconstantin/boterview/refs/heads/main/frontend/app/src/assets/images/boterview-logo.png\" alt=\"boterview logo\"/\u003e\n    \u003c/a\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003e\n    \u003csub\u003eAI-based interview studies...\u003cbr\u003e...as smooth as butter\u003c/sub\u003e\n\u003c/h1\u003e\n\n\u003c!-- badges: start --\u003e\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://www.repostatus.org/#active\"\u003e\u003cimg src=\"https://www.repostatus.org/badges/latest/active.svg\" alt=\"Repository status\"/\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/mihaiconstantin/boterview/releases\"\u003e\u003cimg src=\"https://img.shields.io/github/v/release/mihaiconstantin/boterview?display_name=tag\u0026sort=semver\" alt=\"GitHub version\"/\u003e\u003c/a\u003e\n    \u003ca href=\"https://pypi.org/project/boterview/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/v/boterview\" alt=\"PyPI version\"/\u003e\u003c/a\u003e\n    \u003ca href=\"https://pypi.org/project/boterview/\"\u003e\u003cimg src=\"https://img.shields.io/pepy/dt/boterview\" alt=\"PyPI monthly downloads\"/\u003e\u003c/a\u003e\n\u003c/p\u003e\n\u003c!-- badges: end --\u003e\n\n`boterview` is a `Python` package that enables social science researchers to\neasily deploy chatbot-based interviews with customizable protocols and\nrandomized condition assignment.\n\n## Installation\n\nYou can install the package from the `PyPI` repository using `pip` as follows:\n\n```bash\n# Install using `pip`.\npip install boterview\n```\n\nDepending on your setup, you may consider using a `Python` virtual environment\nbefore running the command above. For instance, you can create a new virtual\nenvironment called `.venv` and activate it as follows:\n\n```bash\n# Create a new directory for your study.\nmkdir my-study\n\n# Move into the directory.\ncd my-study\n\n# Create a new `Python` virtual environment called `.venv`.\npython -m venv .venv\n\n# Activate the virtual environment.\nsource .venv/bin/activate\n```\n\n### Development Version\n\nYou may also install the development version of the package directly from the\n`GitHub` repository using `pip` as follows:\n\n```bash\n# Install using `pip`.\npip install boterview@git+https://github.com/mihaiconstantin/boterview\n```\n\n## Usage\n\nTo use `boterview`, you need to specify a `TOML` configuration file for your\nstudy, and provide several text files containing the interview-related content,\nas well as the user interface content (e.g., the study instruction, consent\ninformation and more). While all these things can be done manually, `boterview`\nprovides a command line interface (CLI) to help you with the process.\n\n### Commands\n\nTo get started, you can run the command below to see all the available command\navailable in the `boterview` CLI.\n\n```bash\n# Show all available commands.\nboterview --help\n```\n\nBoterview provides four main command groups: `generate`, `parse`, `preview`, and\n`run`. For each command, please check the help message (i.e., via `--help`) to\nsee the available options and arguments.\n\n### Content Generation\n\nThe `boterview generate` command can be used to generate various things related\nto your study. It contains three main subcommands:\n\n- `codes`: Used to generate participation codes for your study.\n- `secret`: Used to generate a random secret required to run the study.\n- `study`: Used to scaffold an example study setup.\n\n## Data Parsing\n\nThe `boterview parse` command can be used to parse the study database. It is\nused to extract the study data from the `sqlite` database and save it as a\n`markdown` file.\n\n### Condition Previewing\n\nThe `boterview preview` command can be used to preview a study condition given a\nconfiguration file. This command prints to the console the content that\nconstitutes the system prompt for the bot for a given study condition.\n\n## Running the Study\n\nThe `boterview run` command can be used to start a study based on a\nconfiguration file. This command starts a web server that serves the study\ninterface and handles the chatbot interactions.\n\n### Example\n\nBelow you can find a minimal example to get you started with `boterview`. The\ncommands below assume you have already installed the package.\n\n```bash\n# Scaffold a study in the current working directory with 100 participation codes, and include a secret.\nboterview generate study --path . --quantity 100 --config study.toml --secret\n\n# Preview the default condition setup.\nboterview preview --config study.toml --condition \"Condition 1\"\n\n# Run the study and save the data in the `boterview.db` database file.\nboterview run --config study.toml --database boterview.db\n```\n\nAt this point, you can access the study at\n[http://localhost:8080](http://localhost:8080).\n\nSuppose several participants have went through the study and you want to\ndownload the data. You can do so by navigating to the `/download` endpoint. The\nsecret required to download the data is stored in the `study.toml` file (i.e.,\nit was automatically included by the `--secret` flag used when scaffolding the\nstudy).\n\nAlternatively, use the `boterview parse` command against the database file,\nwhich will extract the data and save it as a `markdown` file in the current\nworking directory. For example:\n\n```bash\n# Parse the study data.\nboterview parse --config study.toml --database boterview.db\n```\n\n**_Note._** We are working on expanding the documentation and adding more\nexamples. For the time being, the instructions above should suffice to get you\nstarted with `boterview`. We also recommend reading the comments in the study\nconfiguration file, as well as the application interface default content. See\nthe _Contributing_ section below for more information on how you can help.\n\n## Contributing\n\n- Any contributions are welcome and greatly appreciated. Please open a [pull\n  request](https://github.com/mihaiconstantin/boterview/pulls) on `GitHub`.\n- To report bugs, or request new features, please open an\n  [issue](https://github.com/mihaiconstantin/boterview/issues) on `GitHub`.\n\n## License\n\n- The package source code in this repository is licensed under the [MIT\n  license](https://opensource.org/license/mit).\n- \u003cp class=\"license-cc\" xmlns:cc=\"https://creativecommons.org/ns\" xmlns:dct=\"https://purl.org/dc/terms/\"\u003e\u003ca property=\"dct:title\" rel=\"cc:attributionURL\" href=\"https://boterview.dev\"\u003eThe documentation and other website materials\u003c/a\u003e by \u003ca rel=\"cc:attributionURL dct:creator\" property=\"cc:attributionName\" href=\"https://mihaiconstantin.com\"\u003eMihai Constantin\u003c/a\u003e are licensed under \u003ca href=\"https://creativecommons.org/licenses/by/4.0/\" target=\"_blank\" rel=\"license noopener noreferrer\" style=\"display:inline-block;\"\u003eCC BY 4.0\u003c/a\u003e.\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmihaiconstantin%2Fboterview","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmihaiconstantin%2Fboterview","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmihaiconstantin%2Fboterview/lists"}