Fix service GPU device ordering, expand docs, add banner (v0.2.1) (#6)

* Pin CUDA device order in service startup

Set CUDA_DEVICE_ORDER=PCI_BUS_ID in the service package __init__ (before
any submodule imports torch), matching the CLI. Without it, CUDA's
default FASTEST_FIRST ordering made REFINERY_DEVICE=cuda:N select a
different physical GPU than nvidia-smi index N on multi-GPU hosts, so
the service could load models onto the wrong card.

* Fix and expand service-mode operations docs

Correct the tmpfs example to --mount type=tmpfs,dst=/scratch,
tmpfs-mode=1777 in service.md and deployment.md; a bare --tmpfs
/scratch mounts root-owned and fails every job with PermissionError.
Add a GPU-selection section, an end-to-end local-directory batch
runbook, and troubleshooting entries (tmpfs perms, wrong-GPU, batch
cap) to service.md.

* Add project banner to README

Add the Audio Refinery banner (118 KB JPG) centered at the top of the
README. The image lives in docs/images/ because the repo-root assets/
tree is gitignored.

* Prepare release v0.2.1

Patch release: service GPU-ordering fix plus service-mode doc
corrections and the README banner. Bump version and add the CHANGELOG
entry.

* Reference side-effect import in service init test

Assert on src.service.__name__ so the deliberate side-effect import
(which triggers the CUDA_DEVICE_ORDER default) is no longer flagged as
unused by CodeQL, and drop the now-unnecessary noqa.

* Log alignment fallback and note default model

Log the WhisperX forced-alignment failure at debug level (with the
detected language and device) before falling back to transcription-only
segments, instead of swallowing the exception silently. Document the
default large-v3 model in the module docstring.

* Normalize HuggingFace to Hugging Face

Use the official two-word company name consistently across docs, source
docstrings/help text, error messages, and tests. Error-string changes
in diarizer.py and their test assertions move together.

* Bump vulnerable transitive and dev dependencies

Upgrade aiohttp 3.13.3 -> 3.13.5, requests 2.32.5 -> 2.34.2, Pygments
2.19.2 -> 2.20.0, and pytest 9.0.2 -> 9.0.3 to their patched versions,
closing 13 Dependabot alerts. torch and transformers stay pinned
(WhisperX); those alerts wait for v0.3.0.

* Clarify CUDA_DEVICE_ORDER defaults and harden its test

Reword "pins" to "defaults ... (respecting an explicit override)" in the
service __init__ comment, service.md, and the CHANGELOG to match the
os.environ.setdefault behavior. Rewrite the test with monkeypatch +
importlib.reload so it deterministically covers both the default-when-
unset and respect-explicit-override branches.

Author: chris-colinsky

CHANGELOG.md

@@ -5,6 +5,23 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.1] - 2026-05-21
+
+### Fixed
+
+- Service mode now defaults `CUDA_DEVICE_ORDER` to `PCI_BUS_ID` at startup (matching the CLI, respecting an explicit override), so `REFINERY_DEVICE=cuda:N` selects the GPU at `nvidia-smi` index N rather than CUDA's default FASTEST_FIRST ordering. Previously a multi-GPU host could load models onto the wrong card.
+- WhisperX forced-alignment failures are now logged at debug level (with the detected language and device) before falling back to transcription-only segments, instead of being swallowed silently.
+
+### Documentation
+
+- Corrected the service-mode tmpfs example to `--mount type=tmpfs,dst=/scratch,tmpfs-mode=1777`. A bare `--tmpfs /scratch` mounts root-owned, so the non-root `refinery` user could not write scratch and every job failed with `PermissionError`. Applied the same fix in `docs/deployment.md`.
+- Added service-mode GPU-selection guidance, an end-to-end local-directory batch runbook, and troubleshooting entries (tmpfs permissions, wrong-GPU selection, batch-size cap) to `docs/service.md`.
+- Added the project banner to the README.
+
+### Security
+
+- Upgraded vulnerable transitive and dev dependencies to patched versions: `aiohttp` 3.13.3 → 3.13.5, `requests` 2.32.5 → 2.34.2, `Pygments` 2.19.2 → 2.20.0, and `pytest` 9.0.2 → 9.0.3. Closes 13 Dependabot alerts (10 `aiohttp` plus `requests`, `Pygments`, `pytest`). The `torch` and `transformers` alerts remain deferred to v0.3.0, when WhisperX removal lifts the `torch==2.1.2` / `transformers<4.40` pins.
+
 ## [0.2.0] - 2026-05-20
 
 ### Added
@@ -54,7 +71,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Centralized Demucs scratch directory resolution in CLI — RAM disk detection and fallback confirmation now happen in one place
 - Worker status reporting and failure aggregation in `pipeline-parallel` refactored for improved accuracy
 - `python-dotenv` import in Slack notifier is now conditional — avoids import-time failure when the package is absent
-- DEPLOYMENT.md expanded: HuggingFace token setup, NVIDIA driver requirements, cloud instance guidelines, and Docker usage
+- DEPLOYMENT.md expanded: Hugging Face token setup, NVIDIA driver requirements, cloud instance guidelines, and Docker usage
 - Combined report fields documented in README under the Parallel Pipeline section
 
 ### Fixed

CLAUDE.md

@@ -26,7 +26,7 @@ audio-refinery/
 │   ├── separator.py           # Demucs vocal separation wrapper
 │   ├── diarizer.py            # Pyannote speaker diarization wrapper
 │   ├── transcriber.py         # WhisperX transcription wrapper
-│   ├── sentiment_analyzer.py  # HuggingFace sentiment analysis
+│   ├── sentiment_analyzer.py  # Hugging Face sentiment analysis
 │   ├── pipeline.py            # Batch pipeline orchestration (947 lines)
 │   ├── gpu_utils.py           # GPU queries via nvidia-smi
 │   ├── notifier.py            # Slack webhook notifications

README.md

@@ -1,3 +1,7 @@
+<p align="center">
+  <img src="docs/images/audio-refinery-banner.jpg" alt="Audio Refinery — whimsical audio processing for AI" width="820">
+</p>
+
 # Audio Refinery
 
 GPU-accelerated audio processing pipeline: vocal separation (Demucs), speaker diarization (Pyannote), transcription (WhisperX), and text sentiment analysis. Its primary use case is building AI-ready audio databases — transforming raw recordings into structured, speaker-attributed JSON with word-level timestamps that feed directly into RAG pipelines, vector stores, and fine-tuning datasets. The pipeline uses a Ghost Track strategy: AI models run against a clean, music-free vocal stem to maximize accuracy, then the resulting metadata is applied back to the original audio, preserving its acoustic character. Designed to run on 24 GB consumer GPUs with all models resident in VRAM simultaneously, it processes large corpora in batch with no model reload overhead between files.
@@ -48,7 +52,7 @@ source .venv/bin/activate
 # Install all deps (uv sync, whisperx, CUDA torch wheels, pre-commit hooks)
 make dev-setup
 
-# Copy the env template and add your HuggingFace token
+# Copy the env template and add your Hugging Face token
 cp .env.example .env
 # Edit .env and set HF_TOKEN=hf_your_token_here
 
@@ -65,11 +69,11 @@ audio-refinery --help
 
 ## Prerequisites
 
-### HuggingFace access token (required for diarization)
+### Hugging Face access token (required for diarization)
 
-Pyannote speaker diarization models are gated on HuggingFace. This applies to **both** CLI and service mode. Complete these steps once:
+Pyannote speaker diarization models are gated on Hugging Face. This applies to **both** CLI and service mode. Complete these steps once:
 
-1. Create a HuggingFace account at [huggingface.co](https://huggingface.co) if you don't have one.
+1. Create a Hugging Face account at [huggingface.co](https://huggingface.co) if you don't have one.
 2. Accept the license for each gated model (must be logged in):
    - [pyannote/speaker-diarization-3.1](https://huggingface.co/pyannote/speaker-diarization-3.1)
    - [pyannote/segmentation-3.0](https://huggingface.co/pyannote/segmentation-3.0)
@@ -109,16 +113,16 @@ selection rationale, and data model.
 
 ## Documentation
 
-| Document                               | Description                                                        |
-|----------------------------------------|--------------------------------------------------------------------|
-| [Index](docs/index.md)                 | Navigation hub for all documentation                               |
-| [CLI Reference](docs/cli.md)           | Every command, flag, and example for workstation use               |
-| [Service Guide](docs/service.md)       | HTTP API, container deployment, env vars, ops, troubleshooting     |
-| [Architecture](docs/architecture.md)   | Ghost Track pipeline design, model selection rationale, data model |
-| [Use Cases](docs/use-cases.md)         | Who uses this and for what                                         |
-| [Performance](docs/performance.md)     | Throughput benchmarks, scaling options, optimization guide         |
-| [Deployment](docs/deployment.md)       | Production patterns, async workers, Docker, monitoring             |
-| [Development](docs/development.md)      | Dev setup, testing, contributing, release process                  |
+| Document                             | Description                                                        |
+|--------------------------------------|--------------------------------------------------------------------|
+| [Index](docs/index.md)               | Navigation hub for all documentation                               |
+| [CLI Reference](docs/cli.md)         | Every command, flag, and example for workstation use               |
+| [Service Guide](docs/service.md)     | HTTP API, container deployment, env vars, ops, troubleshooting     |
+| [Architecture](docs/architecture.md) | Ghost Track pipeline design, model selection rationale, data model |
+| [Use Cases](docs/use-cases.md)       | Who uses this and for what                                         |
+| [Performance](docs/performance.md)   | Throughput benchmarks, scaling options, optimization guide         |
+| [Deployment](docs/deployment.md)     | Production patterns, async workers, Docker, monitoring             |
+| [Development](docs/development.md)   | Dev setup, testing, contributing, release process                  |
 
 ---
 
@@ -150,4 +154,4 @@ See [docs/development.md](docs/development.md) for the full developer guide, inc
 
 **audio-refinery** is released under the [MIT License](LICENSE).
 
-**Dependency note:** The Pyannote model weights (`pyannote/speaker-diarization-3.1` and `pyannote/segmentation-3.0`) are gated on HuggingFace under separate terms. If you run this tool in a commercial data product, verify that your HuggingFace account's accepted terms cover your use case. The MIT license on this software does not extend to the model weights — those are governed by their respective HuggingFace model cards.
+**Dependency note:** The Pyannote model weights (`pyannote/speaker-diarization-3.1` and `pyannote/segmentation-3.0`) are gated on Hugging Face under separate terms. If you run this tool in a commercial data product, verify that your Hugging Face account's accepted terms cover your use case. The MIT license on this software does not extend to the model weights — those are governed by their respective Hugging Face model cards.

SECURITY.md

@@ -24,5 +24,5 @@ Security issues relevant to this project include:
 
 ## Out of Scope
 
-- Issues in third-party models (Demucs, Pyannote, WhisperX, HuggingFace) — report those upstream
+- Issues in third-party models (Demucs, Pyannote, WhisperX, Hugging Face) — report those upstream
 - Issues requiring physical access to the machine running the pipeline

docs/architecture.md

@@ -124,7 +124,7 @@ WhisperX augments Whisper with a forced alignment stage:
 The combination of these three outputs — text, word-level timestamps, and speaker labels — is
 what makes the `TranscriptionResult` JSON useful for downstream search, editing, and analysis.
 
-### Stage 4: Sentiment Analysis (HuggingFace Transformers)
+### Stage 4: Sentiment Analysis (Hugging Face Transformers)
 
 **Model:** `cardiffnlp/twitter-roberta-base-sentiment-latest` (default; configurable)
 

docs/cli.md

@@ -8,7 +8,7 @@ batch runs over a local directory of WAV files. For the long-lived HTTP service
 
 This page assumes you have already installed the package — see
 [Installation](../README.md#installation) in the README and the
-[HuggingFace token setup](../README.md#prerequisites), which diarization
+[Hugging Face token setup](../README.md#prerequisites), which diarization
 requires in either mode.
 
 ## Contents
@@ -61,7 +61,7 @@ RAM-tight machines a fast SSD is a fine target.
 ## Demucs model weights
 
 The first run auto-downloads the `htdemucs` weights (~80 MB) to
-`~/.cache/torch/hub/checkpoints/`. No HuggingFace token or manual download is
+`~/.cache/torch/hub/checkpoints/`. No Hugging Face token or manual download is
 required for separation.
 
 ---
@@ -151,7 +151,7 @@ Options:
                           (e.g. 'cuda:0').  [default: cuda]
   --min-speakers INTEGER  Minimum number of speakers (optional hint for Pyannote).
   --max-speakers INTEGER  Maximum number of speakers (optional hint for Pyannote).
-  --hf-token TEXT         HuggingFace token (overrides HF_TOKEN env var).
+  --hf-token TEXT         Hugging Face token (overrides HF_TOKEN env var).
   -o, --output-file FILE  Write DiarizationResult JSON to this file.
   --help                  Show this message and exit.
 ```
@@ -168,8 +168,8 @@ audio-refinery diarize /path/to/vocals.wav -d cuda:0 -o /tmp/diarization.json
 
 ### Troubleshooting
 
-- **`HuggingFace token not found`** — Follow the HF setup steps in the README.
-- **`Failed to load Pyannote pipeline`** — Check that you accepted both model licenses on HuggingFace.
+- **`Hugging Face token not found`** — Follow the HF setup steps in the README.
+- **`Failed to load Pyannote pipeline`** — Check that you accepted both model licenses on Hugging Face.
 
 ---
 
@@ -278,7 +278,7 @@ Arguments:
   TRANSCRIPTION_FILE     TranscriptionResult JSON written by step 3  [required]
 
 Options:
-  --model TEXT           HuggingFace text-classification model name.
+  --model TEXT           Hugging Face text-classification model name.
                          [default: cardiffnlp/twitter-roberta-base-sentiment-latest]
   -d, --device TEXT      Compute device: 'cpu', 'cuda', or 'cuda:N'.  [default: cpu]
   -o, --output-file FILE Write SentimentResult JSON to this file.
@@ -368,7 +368,7 @@ Options:
                                      WhisperX CTranslate2 compute type  [default: float16]
   --batch-size INTEGER               WhisperX batch size  [default: 16]
   --language TEXT                    Language code (e.g. 'en') or 'auto'  [default: en]
-  --hf-token TEXT                    HuggingFace token for Pyannote (overrides HF_TOKEN env var)
+  --hf-token TEXT                    Hugging Face token for Pyannote (overrides HF_TOKEN env var)
   --no-resume                        Re-process all files, ignoring existing outputs
   --keep-scratch                     Keep Demucs stems on the scratch disk after the run
   --whisper-model TEXT               WhisperX model name  [default: large-v3]
@@ -633,7 +633,7 @@ Options:
                                      WhisperX CTranslate2 compute type  [default: float16]
   --batch-size INTEGER               WhisperX batch size  [default: 16]
   --language TEXT                    Language code (e.g. 'en') or 'auto'  [default: en]
-  --hf-token TEXT                    HuggingFace token for Pyannote (overrides HF_TOKEN env var)
+  --hf-token TEXT                    Hugging Face token for Pyannote (overrides HF_TOKEN env var)
   --no-resume                        Re-process all files, ignoring existing outputs
   --keep-scratch                     Keep Demucs stems on the scratch disk after the run
   --whisper-model TEXT               WhisperX model name  [default: large-v3]

docs/deployment.md

@@ -106,9 +106,9 @@ the full endpoint reference, output schemas, and environment-variable table.
 
 ### Container prerequisites
 
-#### HuggingFace token
+#### Hugging Face token
 
-Pyannote speaker diarization uses gated models that require HuggingFace
+Pyannote speaker diarization uses gated models that require Hugging Face
 authentication:
 
 1. Create a free account at [huggingface.co](https://huggingface.co)
@@ -182,7 +182,7 @@ Hub as `lunarcommand/audio-refinery:<version>`.
 docker run --gpus all -p 8000:8000 \
   -e REFINERY_API_KEYS=your-secret-key \
   -e HF_TOKEN="${HF_TOKEN}" \
-  --tmpfs /scratch -e REFINERY_SCRATCH_DIR=/scratch \
+  --mount type=tmpfs,dst=/scratch,tmpfs-mode=1777 -e REFINERY_SCRATCH_DIR=/scratch \
   lunarcommand/audio-refinery:latest
 ```
 
@@ -229,7 +229,7 @@ the command — useful for containerized batch jobs over a bind-mounted director
 ```bash
 docker run --rm --gpus '"device=0"' \
   -v /data/audio:/data \
-  --tmpfs /scratch -e REFINERY_SCRATCH_DIR=/scratch \
+  --mount type=tmpfs,dst=/scratch,tmpfs-mode=1777 -e REFINERY_SCRATCH_DIR=/scratch \
   -e HF_TOKEN="${HF_TOKEN}" \
   -e SLACK_WEBHOOK_URL="${SLACK_WEBHOOK_URL}" \
   lunarcommand/audio-refinery:latest \

docs/development.md

@@ -96,7 +96,7 @@ audio-refinery/
 │   ├── separator.py           # Demucs vocal separation wrapper
 │   ├── diarizer.py            # Pyannote speaker diarization wrapper
 │   ├── transcriber.py         # WhisperX transcription wrapper
-│   ├── sentiment_analyzer.py  # HuggingFace sentiment analysis
+│   ├── sentiment_analyzer.py  # Hugging Face sentiment analysis
 │   ├── pipeline.py            # Batch pipeline orchestration
 │   ├── gpu_utils.py           # GPU queries via nvidia-smi
 │   ├── notifier.py            # Slack webhook notifications
@@ -270,7 +270,7 @@ Hooks run:
 - **ffmpeg-python**: FFmpeg subprocess wrapper
 - **click** (>=8.1): CLI framework
 - **rich** (>=13.0): Terminal formatting, tables, and progress spinners
-- **transformers** (>=4.30.0): HuggingFace models for sentiment analysis
+- **transformers** (>=4.30.0): Hugging Face models for sentiment analysis
 
 ### Conflicting Dependencies (Install Separately)
 
@@ -480,7 +480,7 @@ uv run mypy src/ --ignore-missing-imports --show-error-codes
 - [Demucs](https://github.com/facebookresearch/demucs) — Vocal separation model
 - [Pyannote.audio](https://github.com/pyannote/pyannote-audio) — Speaker diarization
 - [WhisperX](https://github.com/m-bain/whisperX) — Transcription with alignment
-- [HuggingFace Transformers](https://huggingface.co/docs/transformers) — Sentiment model
+- [Hugging Face Transformers](https://huggingface.co/docs/transformers) — Sentiment model
 - [Click](https://click.palletsprojects.com/) — CLI framework
 - [Rich](https://rich.readthedocs.io/) — Terminal UI library
 - [Pydantic](https://docs.pydantic.dev/) — Data validation

docs/dockerhub-overview.md

@@ -23,7 +23,7 @@ Wait for `GET /health` to return `200` (model warmup, ~10–30 s), then
 
 - NVIDIA GPU — **24 GB VRAM recommended** (holds all models resident)
 - NVIDIA driver ≥ 525.85.12 and the NVIDIA Container Toolkit on the host
-- A HuggingFace token for the gated Pyannote models (`HF_TOKEN`)
+- A Hugging Face token for the gated Pyannote models (`HF_TOKEN`)
 
 ## Tags
 
@@ -35,7 +35,7 @@ Wait for `GET /health` to return `200` (model warmup, ~10–30 s), then
 | Variable | Purpose |
 |----------|---------|
 | `REFINERY_API_KEYS` | **required** — bearer-token allowlist |
-| `HF_TOKEN` | **required** — HuggingFace token for diarization |
+| `HF_TOKEN` | **required** — Hugging Face token for diarization |
 | `REFINERY_WHISPER_MODEL` | Whisper variant (default `large-v3`) |
 | `REFINERY_SCRATCH_DIR` | per-job scratch; mount a tmpfs for throughput |
 
@@ -44,5 +44,5 @@ Full environment reference, CLI usage, and architecture:
 
 ## License
 
-MIT. Pyannote model weights are gated under separate HuggingFace terms — verify
+MIT. Pyannote model weights are gated under separate Hugging Face terms — verify
 your account's accepted terms cover your use case.