aqda 0.3.1__tar.gz

aqda-0.3.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Timo Seidl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aqda-0.3.1/PKG-INFO

@@ -0,0 +1,308 @@
+Metadata-Version: 2.4
+Name: aqda
+Version: 0.3.1
+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.
+- **Image & audio support** — Import 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, 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, Text Analysis | `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 git+https://github.com/tseidl/aqda.git
+```
+
+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 install --force git+https://github.com/tseidl/aqda.git
+```
+
+### 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
+- **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.

aqda-0.3.1/README.md

@@ -0,0 +1,275 @@
+# 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.
+- **Image & audio support** — Import 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, 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, Text Analysis | `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 git+https://github.com/tseidl/aqda.git
+```
+
+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 install --force git+https://github.com/tseidl/aqda.git
+```
+
+### 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
+- **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.

aqda-0.3.1/aqda/__init__.py

@@ -0,0 +1,3 @@
+"""AQDA - Open-source qualitative data analysis tool."""
+
+__version__ = "0.3.1"

aqda-0.3.1/aqda/__main__.py

@@ -0,0 +1,59 @@
+"""Entry point for running AQDA as a module or via the console script."""
+
+import argparse
+import threading
+import webbrowser
+
+import uvicorn
+
+from aqda import __version__
+
+DEFAULT_HOST = "127.0.0.1"
+DEFAULT_PORT = 8765
+
+
+# Build the argument parser for the `aqda` console script.
+def build_parser():
+    parser = argparse.ArgumentParser(
+        prog="aqda",
+        description="AQDA — Augmented Qualitative Data Analysis. "
+        "Starts the local web app and opens it in your browser.",
+    )
+    parser.add_argument("--version", action="version", version=f"aqda {__version__}")
+    parser.add_argument(
+        "--host", default=DEFAULT_HOST, help=f"Interface to bind (default: {DEFAULT_HOST})"
+    )
+    parser.add_argument(
+        "--port", type=int, default=DEFAULT_PORT, help=f"Port to bind (default: {DEFAULT_PORT})"
+    )
+    parser.add_argument(
+        "--no-browser", action="store_true", help="Do not open a browser window on startup"
+    )
+    return parser
+
+
+def main():
+    args = build_parser().parse_args()
+
+    # Open browser after a short delay to let the server start
+    def open_browser():
+        import time
+
+        time.sleep(1.5)
+        webbrowser.open(f"http://{args.host}:{args.port}")
+
+    if not args.no_browser:
+        threading.Thread(target=open_browser, daemon=True).start()
+
+    print(f"\n  AQDA is running at http://{args.host}:{args.port}\n")
+    from aqda.app import app
+
+    config = uvicorn.Config(app, host=args.host, port=args.port, log_level="warning")
+    server = uvicorn.Server(config)
+    app.state.uvicorn_server = server
+    # uvicorn exits with status 3 itself if the port is already in use.
+    server.run()
+
+
+if __name__ == "__main__":
+    main()