AICoE: The AI Co-Ethnographer

AICoE is an end-to-end pipeline for qualitative research, using large language models (in this repository, Anthropic's Claude is used). Introduced in our paper The AI Co-Ethnographer: How Far Can Automation Take Qualitative Research? (NLP4DH 2025), it goes beyond automating code assignments and covers the analysis process from inductive code development to pattern discovery, in five stages:

1. Open coding. Each interview is processed separately and the model proposes up to N candidate codes, balancing descriptive and interpretive coding. Isolating the analysis per interview keeps it close to the primary data and within context limits.
2. Code consolidation. The per-interview codes are synthesized into a unified codebook of at most M codes by analyzing overlap and merging similar concepts, a computational counterpart to axial coding.
3. Code application. Each consolidated code is applied to each interview. The model sees the entire transcript, so the full conversational context informs which passages are selected. Every extracted quote is mapped back to its transcript utterances and classified as verbatim, fuzzy (paraphrase) or unmatched (possible hallucination); the counts are reported per run.
4. Pattern finding. For each code, the coded segments from all interviews are analyzed for recurring ideas, contradictions and relationships, yielding findings per code.
5. Findings synthesis. All findings are scored on grounding, relevance and insight, then deduplicated, merged and ranked into a final report.

Setup

Installation

python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt -r requirements-web.txt

API Key

You will have to provide an Anthropic API key in the UI, or by setting ANTHROPIC_API_KEY in your environment or a .env file (see .env.example).

Usage

Web UI

python -m aicoe.web        # web UI at http://127.0.0.1:8000

The dashboard manages settings, runs and stage execution with live progress. Each stage has its own view: preprocessing, open coding, codebook, coded transcripts, findings, synthesis. The codebook is editable (rename, describe, add, delete) until code application has run; after that, forking the run reopens it for editing. Coded transcripts are shown color-coded per utterance with quote verification markers. The app is local and single-user.

_{The coded transcripts view: each utterance carries its assigned codes, the legend filters by code while the minimap shows code coverage across the whole interview and allows quick navigation.}

CLI

The pipeline can also be run from the terminal:

python cli.py              # interactive
python cli.py --model sonnet --input ./transcripts --stages 1 2 3 4 5 --yes

All options are available as flags, see python cli.py --help.

Input

AICoE reads a folder of transcripts that share one format. .vtt, .txt, .srt and .pdf are parsed natively; for any other format, a parser is generated on first use and reused afterwards. Transcripts are normalized into utterance units before coding. An optional research context describes your goals and is injected into the coding prompts. It is set per run on the dashboard (or as RESEARCH_CONTEXT.md in the input folder, which seeds new runs).

Runs

Every analysis is stored as a run under runs/ inside the input folder. A run holds its per-stage outputs, a manifest (per-stage models, configuration, input file hashes) and a frozen copy of the chunked transcripts. Runs can be forked up to a chosen stage, for example to revise the codebook and reapply codes, or to rerun only the synthesis on a stronger model. The CLI selects runs with --run, --new-run and --list-runs; the web UI has a run switcher and fork controls.

A run's codebook and coded transcripts can be exported as a REFI-QDA project (.qdpx) for use in NVivo, ATLAS.ti, MAXQDA and other QDA tools: the "Export QDPX" link on the dashboard, or python cli.py --input ./transcripts --run <id> --export-qdpx out.qdpx.

Citation

If you use this project, please cite our work:

@inproceedings{retkowski-etal-2025-ai,
    title = "The {AI} Co-Ethnographer: How Far Can Automation Take Qualitative Research?",
    author = "Retkowski, Fabian  and
      Sudmann, Andreas  and
      Waibel, Alexander",
    editor = {H{\"a}m{\"a}l{\"a}inen, Mika  and
      {\"O}hman, Emily  and
      Bizzoni, Yuri  and
      Miyagawa, So  and
      Alnajjar, Khalid},
    booktitle = "Proceedings of the 5th International Conference on Natural Language Processing for Digital Humanities",
    month = may,
    year = "2025",
    address = "Albuquerque, USA",
    publisher = "Association for Computational Linguistics",
    url = "https://aclanthology.org/2025.nlp4dh-1.8/",
    doi = "10.18653/v1/2025.nlp4dh-1.8",
    pages = "73--90",
    ISBN = "979-8-89176-234-3",
    abstract = "Qualitative research often involves labor-intensive processes that are difficult to scale while preserving analytical depth. This paper introduces The AI Co-Ethnographer (AICoE), a novel end-to-end pipeline developed for qualitative research and designed to move beyond the limitations of simply automating code assignments, offering a more integrated approach. AICoE organizes the entire process, encompassing open coding, code consolidation, code application, and even pattern discovery, leading to a comprehensive analysis of qualitative data."
}

License

This project is licensed under the GNU Affero General Public License v3.0. See LICENSE.