Metadata-Version: 2.4
Name: aqda
Version: 0.4.0
Summary: AQDA — Augmented Qualitative Data Analysis. Local-first QDA with AI.
Author: Timo Seidl
License-Expression: MIT
Project-URL: Homepage, https://github.com/tseidl/aqda
Project-URL: Repository, https://github.com/tseidl/aqda
Project-URL: Issues, https://github.com/tseidl/aqda/issues
Keywords: qualitative-research,qda,coding,social-science,refi-qda
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn[standard]>=0.27
Requires-Dist: python-multipart>=0.0.9
Requires-Dist: aiosqlite>=0.20
Requires-Dist: pdfplumber>=0.11
Requires-Dist: httpx>=0.27
Provides-Extra: audio
Requires-Dist: faster-whisper>=1.0; extra == "audio"
Provides-Extra: dev
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Dynamic: license-file

# AQDA — Augmented Qualitative Data Analysis

**A free, open-source tool for qualitative researchers. AI-powered, local-first, privacy-respecting.**

AQDA gives you a modern coding interface with local AI assistance — without cloud subscriptions, without your data ever leaving your machine. It runs as a local web app in your browser.

![Python](https://img.shields.io/badge/python-3.10+-blue)
![License](https://img.shields.io/badge/license-MIT-green)

---

## What Can AQDA Do?

### Core Qualitative Coding

- **Text coding** — Select text, apply codes, build your codebook. Click on any coded passage to see applied codes or remove them.
- **Hierarchical codes** — Organize codes in parent-child trees with colors and descriptions. Drag and drop in the sidebar to re-parent or reorder.
- **Text, Word, PDF, image & audio files** — Import `.txt`, `.docx` (formatting is dropped), and `.pdf` documents, images (JPG, PNG, GIF, WebP), and audio files (MP3, WAV, M4A) with optional local transcription via Whisper.
- **Memos** — Write analytical notes at the project, document, or code level. Anchor a memo to a specific passage and jump back to it, and reference codes or other memos inline by typing `@` — click a reference to jump straight to it.
- **Document variables & tags** — Add metadata (author, date, source) to documents, auto-extracted from filenames on import. Give a document a short tag (e.g. `INT`) shown next to it in the sidebar.
- **Coder identity** — Set your name in Settings; each coding records who made it, so collaborators show up as distinct coders in REFI-QDA exports.
- **Segments browser** — Browse all coded segments across documents. Click to jump to the passage in context, or delete directly from the list.
- **Export** — REFI-QDA (.qdpx) for MAXQDA/ATLAS.ti/NVivo, including document variables and memos linked to their codes and passages; codebook (.qdc), CSV, JSON.

### AI-Powered Augmentation

AQDA uses [Ollama](https://ollama.com) to run AI models locally on your computer. No internet connection required, no data shared with anyone.

| Feature | What it does |
|---------|-------------|
| **Topic Search** | Find passages across your documents that match a topic or theme you describe |
| **Code Suggest** | Given a code, find uncoded passages that might belong to it (from its definition and coded examples); review each and **Apply** or **Dismiss** it |
| **Consistency Check** | Flag coded segments that seem like outliers within a code — like inter-rater reliability with yourself over time |
| **Hierarchy Suggest** | After inductive coding, get suggestions for grouping your codes into parent categories |
| **Code Definition Generator** | Applied a code many times but haven't written a definition yet? Generate one from the actual coded passages |

When you click on an AI result, AQDA jumps to the passage in the document and highlights it, so you can immediately see the context and decide whether to code it.

Topic Search and Code Suggest cover text, PDF, and transcribed audio. Mark any document as **Reference** from its header (e.g. pre-coded examples or training material) to keep it out of AI results.

These tools are designed as a **methodological interlocutor** — they interrogate your coding rather than generate it. The researcher always has the final word.

### Two Types of AI Models

AQDA uses two types of models for different purposes:

| Model type | What it does | Used by | Recommended model |
|-----------|-------------|---------|-------------------|
| **Embedding model** | Converts text into numerical representations so similar passages can be found | Topic Search, Code Suggest, Consistency Check | `nomic-embed-text` (fast, 274 MB) |
| **LLM (language model)** | Reads text and generates structured output (definitions, groupings) | Hierarchy Suggest, Define Code, Summarize Theme | `qwen3.5:9b` (6 GB) |

You need one of each. They are configured in **Settings**.

---

## Getting Started

### What You Need

- **Python 3.10 or newer**
- **pipx** (installs Python apps in isolated environments)
- **Chrome, Firefox, or Brave** — Safari has known issues with large file imports and downloads
- **Ollama** (optional, for AI features) — [ollama.com/download](https://ollama.com/download)

### Install

Open a terminal and run:

```bash
pipx install aqda
```

Already installed? Refresh AQDA to the current version with:

```bash
pipx reinstall aqda
```

Then start AQDA:

```bash
aqda
```

This opens your browser at `http://127.0.0.1:8765`. To stop, click **Close AQDA** in the
app. Pressing `Ctrl+C` once in the terminal is the equivalent safe shutdown.


<details>
<summary><strong>Don't have Python or pipx?</strong></summary>

**Mac:**
```bash
# Install Homebrew (skip if you already have it)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```
After Homebrew installs, it prints commands to add it to your PATH — copy and run those lines, then:
```bash
brew install python pipx
pipx ensurepath
```
Close and reopen Terminal, then install AQDA.

**Windows:**

Download Python from [python.org](https://www.python.org/downloads/) — **check "Add python.exe to PATH"** during installation. Then:
```bash
pip install pipx
pipx ensurepath
```
Close and reopen Command Prompt, then install AQDA.
</details>

<details>
<summary><strong>Getting "command not found" after install?</strong></summary>

Run `pipx ensurepath`, then **close and reopen your terminal**. This adds pipx's install directory to your PATH.
</details>

### Setting Up AI Features (Optional)

1. [Download and install Ollama](https://ollama.com/download)
2. Open a terminal and pull the models:
   ```bash
   ollama pull nomic-embed-text   # for similarity search
   ollama pull qwen3.5:9b         # for analysis and definitions
   ```
3. In AQDA, go to **Settings** and select your models under "Embedding Model" and "LLM Model"
4. Open the **AI panel** (sparkle icon in the left sidebar)

All AI processing happens on your machine. Nothing is sent to any server.

### Audio Transcription (Optional)

To transcribe audio files locally using Whisper:

```bash
pipx inject aqda "aqda[audio]"
```

Then import an audio file (MP3, WAV, M4A) and click the transcribe button.

### Auto-Extract Metadata from Filenames (Optional)

If your files follow a naming convention, AQDA can automatically extract variables on import. In **Settings → Filename Variable Parsing**, set a regex pattern with named groups.

For example, files like `2025-03-10_guardian_from-border-crackdown.txt`:

```
(?P<date>\d{4}-\d{2}-\d{2})_(?P<source>[^_]+)_(?P<title>.+)
```

This extracts `date`, `source`, and `title` as document variables automatically when you import.

### Updating

```bash
pipx upgrade aqda
```

### Uninstalling

```bash
pipx uninstall aqda
```

This removes the app but keeps your data in `~/.aqda/`. To remove everything, also delete that folder.

---

## Your Data

AQDA saves every change immediately. There is no Save button. Its private working database
lives at `~/.aqda/aqda.db`; normal users never need to open or move this file.

- **Automatic backups** — AQDA keeps seven verified daily backups in `~/.aqda/backups/`
  and creates an extra backup before migrations or replacing a project from a collaborator
  (the ten newest collaboration backups are kept; adjustable in Settings)
- **Move or archive a project** with an `.aqda` snapshot from the Export menu
- **Deleted projects** go to a trash bin and can be restored

Do not put the live `aqda.db` in Google Drive, Dropbox, OneDrive, or a network folder.
AQDA's collaboration feature below provides the same convenient shared-folder experience
without exposing a live SQLite database to cloud-sync races.

To restore a full backup, close AQDA, keep the current `aqda.db` as an extra copy, and copy
the chosen backup into its place as `aqda.db`.

### Collaboration — Google Drive, Dropbox, or a Shared Folder

Collaboration is designed to feel like opening the same document from a shared folder.
AQDA quietly uses a safe local working copy and syncs complete, closed snapshots in the
background. The local working copy lives with all your other projects inside the hidden
`~/.aqda/aqda.db` database; it is not another file you have to open or manage. You never
need to save manually.

**Set up a project:**

1. Make a folder for that project or team inside Google Drive, Dropbox, OneDrive, your
   university cloud, or another synced location.
2. Open the project in AQDA and click **Collaborate**.
3. Choose a previously saved location, or click **Choose another shared folder…** and select
   the folder from step 1.
4. On the other researcher's computer, add that same folder under
   **Settings → Collaboration**.
5. The project appears under **Shared projects available**; click **Open project** once.

AQDA remembers multiple collaboration locations. A project with one co-author can use a
Google Drive folder, another can use a university-cloud folder, and a third can use Dropbox;
clicking **Collaborate** lets you choose the appropriate location for each project. Each
project connects to one location at a time.

After that, both researchers open the project normally from AQDA's project list. Changes
save locally immediately and complete snapshots are published to the shared folder after a
short delay. Incoming changes appear automatically. Before replacing local project data,
AQDA creates and verifies a full safety backup.

If two people happen to work at the same time—or one computer was offline—AQDA detects the
two histories and keeps neither person's work from overwriting the other. The original shared
project remains your branch. AQDA creates exactly one clearly named **Collaborator reference**
project for each other branch and updates that same reference as new work arrives; it does not
make another copy or shared folder on every sync.

Treat the collaborator reference as a comparison copy, not a new place to code. To resolve it:

1. Compare the two projects and agree which branch everyone will continue from.
2. On a computer where the current shared project is the chosen branch, open the collaborator
   reference and click **Keep my current shared version**. The reference moves to Trash.
3. On a computer where the collaborator reference is the chosen branch, open it and click
   **Use this version for collaboration**. AQDA creates a full backup, switches the shared
   project, and keeps the previous local branch as a clearly named local archive.

This is an explicit choice rather than an automatic merge: qualitative coding decisions from
two branches cannot safely be guessed together.

Under the hood, the collaboration folder contains one `.aqda-project` folder with a complete
snapshot file for each participating computer. These are managed by AQDA; collaborators should
not rename or edit them manually. **Stop sharing** removes this computer's snapshot while keeping
its local project intact; starting collaboration again reuses the same managed project folder.

**Stopping AQDA:** use the **Close AQDA** button, or press Ctrl+C once in the terminal. Both
perform a graceful final sync. Closing only the browser tab leaves the local AQDA server
running, which is harmless; reopen `http://127.0.0.1:8765` to return. If the computer stops
unexpectedly, the hidden local copy is retained and syncs on the next launch.

> **Not supported:** automatically merging two independently edited versions into one.

For one-person local work, nothing changes: create a project, work normally, and close AQDA.
Everything autosaves; no files or caches need to be managed.

---

## Export Formats

| Format | Use case |
|--------|----------|
| `.aqda` | Save a standalone copy to send or archive — full AQDA round-trip import/export |
| `.qdpx` | REFI-QDA text exchange — import into MAXQDA, ATLAS.ti, NVivo |
| `.qdc` | Codebook XML — share code hierarchies between projects |
| `.csv` | Coded segments as a table — for further analysis in R, Excel, etc. |
| `.json` | Analysis data and document variables — for R, Python, or custom processing |

QDPX currently exports text and audio transcripts as text sources. Original audio and image
media are not embedded in the QDPX package; use `.aqda` when an exact AQDA round-trip is needed.

---

## License

MIT

## Acknowledgments

Built with substantial assistance from [Claude Code](https://claude.ai/code) (Claude Opus 4.6 by [Anthropic](https://anthropic.com)). Architecture, backend, frontend, and AI integration were developed collaboratively through human-AI pair programming.

Inspired by [QualCoder](https://github.com/ccbogel/QualCoder) and the qualitative research community's need for modern, accessible, AI-augmented analysis tools.
