# Install verification matrix

**Authority:** This document is the authoritative install-verification matrix for TranscriptX **0.9.4**. Do not advertise an install command that cannot pass its stated cell.

**Distribution reality:** versioned **git tags** + **Docker Compose** image. The package is **not published on PyPI**. Bare `pip install transcriptx` from PyPI will fail and must not be advertised as a primary install path.

**Repository:** https://github.com/glen-w/TranscriptX

## Supported interpreters

| Python | Status |
|--------|--------|
| 3.10 | Supported (CI matrix) |
| 3.11 | Supported (CI matrix) |
| 3.12 | Supported (CI matrix) |
| ≤3.9 or ≥3.13 | Unsupported (`requires-python = ">=3.10,<3.13"`) |

## Supported operating systems (claimed)

| OS | Status | Notes |
|----|--------|-------|
| macOS (Apple Silicon / Intel) | Supported-with-caveats | Prefer **Docker CPU** for predictable installs. Native Apple **MPS** is not universally validated for every optional model — see [installation.md](installation.md). If MPS init or model execution fails, use `TRANSCRIPTX_FORCE_CPU=1`. Host `.[bertopic]`/`[full]` may fail when `llvmlite` wheels are unavailable; Docker `image_pip_check` remains the fuller-stack image proof. |
| Linux (x86_64 / aarch64) | Supported | GPU via NVIDIA toolkit when available |
| Windows | Best-effort | Native Windows is not a primary CI target; WSL2 + Docker recommended. Native `inbox-watch` / `whispermlx-missing` on Windows is **not** a 1.0 cell (1.x theme **G3**). |

## Install paths

| Cell | Command / proof | Expected result |
|------|-----------------|-----------------|
| **Core (from git)** | `python -m venv .venv && source .venv/bin/activate && pip install -e .` | Import succeeds |
| **Core + dev** | `pip install -e ".[dev]"` | Dev tools + pytest stack; `make test-smoke` (charting needs matplotlib/geopy from the `dev` extra; spaCy-gated modules skip unless `.[nlp]` is also installed) |
| **Core + dev + web (CI PR tests)** | `pip install -e ".[dev,web]"` | Same as Core+dev plus Streamlit so contracts/fast can collect web modules (CI `tests` job) |
| **Core + dev + nlp** | `pip install -e ".[dev,nlp]"` then `python -m spacy download en_core_web_md` | Same as Core+dev plus spaCy-gated smoke (`make test-smoke-nlp`) |
| **Core + dev + nlp + web (CI NLP lane)** | `pip install -e ".[dev,nlp,web]"` then `python -m spacy download en_core_web_md` | CI `tests-nlp` job (smoke-nlp + contracts) |
| **docs** | `pip install -e ".[docs]"` | Docs build extras |
| **ner** | `pip install -e ".[ner]"` | NER optional deps |
| **emotion_lexical** | `pip install -e ".[emotion_lexical]"` | Lexical emotion deps |
| **emotion_transformers** | `pip install -e ".[emotion_transformers]"` | Transformer emotion deps |
| **emotion** | `pip install -e ".[emotion]"` | Combined emotion extras |
| **voice** | `pip install -e ".[voice]"` | Voice / audio analysis deps |
| **speaker_match** | `pip install -e ".[speaker_match]"` | Local ECAPA / SpeechBrain speaker-match deps (`import speechbrain`) |
| **nlp** | `pip install -e ".[nlp]"` then `python -m spacy download en_core_web_md` | NLP + spaCy model |
| **bertopic** | `pip install -e ".[bertopic]"` | Optional BERTopic stack (`bertopic`/`hdbscan`/`umap-learn`); also in `[full]` / Docker |
| **keyphrases** | `pip install -e ".[keyphrases]"` | Optional YAKE + KeyBERT for `keyphrases` module (noun-chunks path works without this extra) |
| **maps** | `pip install -e ".[maps]"` | Maps extras; Playwright for optional HTML→PNG (not required for Streamlit GUI) |
| **visualization** | `pip install -e ".[visualization]"` | Charts/PDF helpers + **ebooklib** for Overview export `index.epub` (with matplotlib/seaborn/wordcloud) |
| **plotly** | `pip install -e ".[plotly]"` | Plotly extras |
| **web** | `pip install -e ".[web]"` | Streamlit GUI only (not included in `[full]`) |
| **full** | `pip install -e ".[full]"` | All optional **analysis** extras; may fail on some hosts (e.g. llvmlite) — does **not** install Streamlit |
| **full + web (native GUI)** | `pip install -e ".[full,web]"` | Analysis extras + Streamlit; closest editable match to Docker GUI |
| **Docker production image** | `docker compose -f docker-compose.yml build` then `make docker-smoke` | **Production-image installation proof** (wheel + `requirements.txt` under `constraints.txt`). This is **not** `pip install -e '.[full]'` unless inventories are verified equal |
| **PyPI bare** | `pip install transcriptx` | **Not supported** — package is not on PyPI |

## Fresh-clone evidence (release bundle)

At tag time, record:

1. Clone of the exact release commit
2. Core editable install on one supported Python
3. Docker production-image build + smoke
4. Pointers to CI artefacts for the commit (test matrix + release-checks)

See `docs/dev/release_governance.md`.