ci+docs: prep v1.4.1 and fix GitHub Actions

Author: InfantLab

.github/workflows/ci-cd.yml

@@ -2,25 +2,20 @@ name: CI/CD Pipeline
 
 on:
   push:
-    branches: [main, develop]
+    branches: [master, main, develop]
   pull_request:
-    branches: [main, develop]
+    branches: [master, main, develop]
   release:
     types: [published]
+  workflow_dispatch:
 
 jobs:
   test:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
         os: [ubuntu-latest, windows-latest, macos-latest]
-        python-version: [3.8, 3.9, "3.10", "3.11"]
-        exclude:
-          # Exclude some combinations to reduce job count
-          - os: macos-latest
-            python-version: 3.8
-          - os: windows-latest
-            python-version: 3.8
+        python-version: ["3.12"]
 
     steps:
       - uses: actions/checkout@v4
@@ -30,6 +25,11 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
 
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
       - name: Install system dependencies (Ubuntu)
         if: matrix.os == 'ubuntu-latest'
         run: |
@@ -47,35 +47,22 @@ jobs:
         run: |
           choco install ffmpeg cmake
 
-      - name: Cache pip dependencies
-        uses: actions/cache@v3
-        with:
-          path: ~/.cache/pip
-          key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
-          restore-keys: |
-            ${{ runner.os }}-pip-
-
       - name: Install dependencies
         run: |
-          python -m pip install --upgrade pip
-          pip install -e .[dev]
+          uv sync --dev
 
-      - name: Lint with flake8
+      - name: Lint (ruff - minimal)
         run: |
-          flake8 src tests --count --select=E9,F63,F7,F82 --show-source --statistics
-          flake8 src tests --count --exit-zero --max-complexity=10 --max-line-length=88 --statistics
-
-      - name: Format check with black
-        run: |
-          black --check src tests
+          uv run ruff check src/videoannotator tests --select=E9,F63,F7,F82
 
       - name: Type check with mypy
+        if: github.event_name == 'workflow_dispatch'
         run: |
-          mypy src
+          uv run mypy src/videoannotator
 
       - name: Test with pytest
         run: |
-          pytest tests/ -v --cov=src --cov-report=xml --cov-report=term-missing
+          uv run pytest -q --cov=src/videoannotator --cov-report=xml --cov-report=term-missing
 
       - name: Upload coverage to Codecov
         uses: codecov/codecov-action@v3
@@ -88,15 +75,20 @@ jobs:
   integration-test:
     runs-on: ubuntu-latest
     needs: test
-    if: github.event_name == 'push' || github.event_name == 'pull_request'
+    if: github.event_name == 'workflow_dispatch'
 
     steps:
       - uses: actions/checkout@v4
 
-      - name: Set up Python 3.9
+      - name: Set up Python 3.12
         uses: actions/setup-python@v4
         with:
-          python-version: 3.9
+          python-version: "3.12"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
 
       - name: Install system dependencies
         run: |
@@ -106,37 +98,34 @@ jobs:
 
       - name: Install dependencies
         run: |
-          python -m pip install --upgrade pip
-          pip install -e .[all]
-
-      - name: Download test data
-        run: |
-          # Create test data directory
-          mkdir -p tests/data
-          # Download sample video (replace with actual test data)
-          curl -o tests/data/sample_video.mp4 "https://sample-videos.com/zip/10/mp4/SampleVideo_360x240_1mb.mp4"
+          uv sync --dev
 
       - name: Run integration tests
         run: |
-          pytest tests/ -v -m integration --cov=src --cov-report=xml
+          uv run pytest -q -m integration
 
       - name: Test CLI interface
         run: |
-          uv run python -m src.cli --help
-          uv run python -m src.cli server --help
+          uv run videoannotator --help
+          uv run videoannotator server --help
 
   performance-test:
     runs-on: ubuntu-latest
     needs: test
-    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    if: github.event_name == 'workflow_dispatch'
 
     steps:
       - uses: actions/checkout@v4
 
-      - name: Set up Python 3.9
+      - name: Set up Python 3.12
         uses: actions/setup-python@v4
         with:
-          python-version: 3.9
+          python-version: "3.12"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
 
       - name: Install system dependencies
         run: |
@@ -146,17 +135,11 @@ jobs:
 
       - name: Install dependencies
         run: |
-          python -m pip install --upgrade pip
-          pip install -e .[all]
-
-      - name: Download test data
-        run: |
-          mkdir -p tests/data
-          curl -o tests/data/sample_video.mp4 "https://sample-videos.com/zip/10/mp4/SampleVideo_360x240_1mb.mp4"
+          uv sync --dev
 
       - name: Run performance tests
         run: |
-          pytest tests/ -v -m performance --benchmark-only --benchmark-json=benchmark.json
+          uv run pytest -q -m performance --benchmark-only --benchmark-json=benchmark.json
 
       - name: Store benchmark result
         uses: benchmark-action/github-action-benchmark@v1
@@ -195,10 +178,10 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - name: Set up Python 3.9
+      - name: Set up Python 3.12
         uses: actions/setup-python@v4
         with:
-          python-version: 3.9
+          python-version: "3.12"
 
       - name: Install build dependencies
         run: |
@@ -222,7 +205,7 @@ jobs:
   docker-build:
     runs-on: ubuntu-latest
     needs: [test, integration-test]
-    if: github.event_name == 'push' && (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/develop')
+    if: github.event_name == 'push' && (github.ref == 'refs/heads/master' || github.ref == 'refs/heads/main' || github.ref == 'refs/heads/develop') && secrets.DOCKER_USERNAME != '' && secrets.DOCKER_PASSWORD != ''
 
     steps:
       - uses: actions/checkout@v4

CHANGELOG.md

@@ -15,16 +15,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Benchmark results and performance validation
 - Additional contributor documentation improvements
 
-## [1.4.1] - 2025-12-18
+## [1.4.1] - 2025-12-26
 
-### Documentation & UX Polish
+### Release Quality, Docs, and Developer Experience
+
+#### Added
+- **Container/Devcontainer**: Baked `hadolint` into Docker images and devcontainer so pre-commit hooks work reliably.
+- **Dockerfiles**: Added `git-lfs` to CPU/GPU Dockerfiles for smoother model/asset workflows.
 
 #### Changed
-- **Documentation**: Archived historical/versioned docs under `docs/archive/` and updated inbound links.
-- **Documentation**: Standardized examples on the canonical API port `18011` and Docker Compose-first workflows.
-- **CLI/Logging**: Removed stale v1.2.0 references and ensured first-run messaging reflects the current package version.
+- **Documentation**: Consolidated the JOSS manuscript into `paper/paper.md` and replaced `docs/joss.md` with a pointer to avoid divergence.
+- **Repository Hygiene**: Moved top-level helper scripts into organized subfolders under `scripts/` and updated imports to the `videoannotator.*` package namespace.
+- **Entrypoints**: Updated `api_server.py` to act as a compatibility wrapper; documentation now recommends using the `videoannotator` CLI.
+- **README**: Rationalized repeated setup/install instructions, fixed broken/non-links, and replaced hard-coded test/coverage claims with CI status.
 
 #### Fixed
+- **Docs**: Standardized examples on the canonical API port `18011` and corrected Docker run port mappings.
 - **Docs**: Replaced placeholder `docs/usage/accessing_results.md` with a real results retrieval guide.
 
 ## [1.4.0] - 2025-12-15

README.md

@@ -5,7 +5,7 @@
 [![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
 [![uv](https://img.shields.io/badge/uv-package%20manager-FF4B4B?logo=uv&logoColor=white)](https://github.com/astral-sh/uv)
 [![Docker](https://img.shields.io/badge/Docker-GPU%20Ready-2496ED?logo=docker&logoColor=white)](https://docs.docker.com/)
-[![Tests](https://img.shields.io/badge/tests-720%20passing%20(94.4%25)-success.svg)](tests/)
+[![CI](https://github.com/InfantLab/VideoAnnotator/actions/workflows/ci-cd.yml/badge.svg)](https://github.com/InfantLab/VideoAnnotator/actions/workflows/ci-cd.yml)
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/InfantLab/VideoAnnotator)
 
 **Automated video analysis toolkit for human interaction research** - Extract comprehensive behavioral annotations from videos using AI pipelines, with an intuitive web interface for visualization and analysis.
@@ -34,7 +34,7 @@ VideoAnnotator provides both **automated processing** and **interactive visualiz
 - Supports batch processing and custom configurations
 - Outputs standardized JSON data
 
-### 🌐 **[Video Annotation Viewer](https://github.com/InfantLab/video-annotation-viewer)**
+### 🌐 **[Video Annotation Viewer](https://github.com/InfantLab/video-annotation-viewer)** (paired repository)
 
 **Interactive web-based visualization tool**
 
@@ -87,27 +87,27 @@ git clone https://github.com/InfantLab/video-annotation-viewer.git
 cd video-annotation-viewer
 npm install
 npm run dev
+```
 
-Note: Ensure Node and NPM are installed. On macOS with Homebrew:
-brew install node
+Note: Ensure Node and NPM are installed. On macOS with Homebrew: `brew install node`
 
-# Open http://localhost:3000 and load your VideoAnnotator results
-```
+Open http://localhost:3000 and load your VideoAnnotator results.
 
 **🎉 That's it!** You now have both automated video processing and interactive visualization.
 
 ## 🧠 AI Pipelines & Capabilities
 
 Authoritative pipeline metadata (names, tasks, modalities, capabilities) is generated from the registry:
 
-- Pipeline specification table: `docs/pipelines_spec.md` (auto-generated; do not edit by hand)
-- Emotion output format spec: `docs/specs/emotion_output_format.md`
+- Pipeline specification table: [docs/pipelines_spec.md](docs/pipelines_spec.md) (auto-generated; do not edit by hand)
+- Pipeline API endpoint: http://localhost:18011/api/v1/pipelines
+- Emotion output format spec: [docs/development/emotion_output_format.md](docs/development/emotion_output_format.md)
 
 Additional Specs:
 
-- Output Naming Conventions: `docs/specs/output_naming_conventions.md` (stable patterns for downstream tooling)
-- Emotion Validator Utility: `src/validation/emotion_validator.py` (programmatic validation of `.emotion.json` files)
-- CLI Validation: `videoannotator validate-emotion path/to/file.emotion.json` returns non-zero exit on failure
+- Output Naming Conventions: [docs/development/output_naming_conventions.md](docs/development/output_naming_conventions.md) (stable patterns for downstream tooling)
+- Emotion Validator Utility: [src/videoannotator/validation/emotion_validator.py](src/videoannotator/validation/emotion_validator.py) (programmatic validation of `.emotion.json` files)
+- CLI Validation: `uv run videoannotator validate-emotion path/to/file.emotion.json` returns non-zero exit on failure
   Client tools (e.g. the Video Annotation Viewer) should rely on those sources or the `/api/v1/pipelines` endpoint rather than hard-coding pipeline assumptions.
 
 ### **Person Tracking Pipeline**
@@ -118,7 +118,7 @@ Additional Specs:
 
 ### **Face Analysis Pipeline**
 
-- **Technology**: OpenFace 3.0, LAION Face, OpenCV backends
+- **Technology**: [OpenFace 3.0](https://github.com/CMU-MultiComp-Lab/OpenFace-3.0), LAION Face ([LAION](https://laion.ai/)), OpenCV backends
 - **Outputs**: 68-point landmarks, emotions, action units, gaze direction, head pose
 - **Use cases**: Emotional analysis, attention tracking, facial expression studies
 
@@ -212,70 +212,32 @@ VideoAnnotator generates rich, structured data like this:
 
 ## 🔗 Integration & Export
 
-### **Direct Integration**
-
-- **Python**: Import JSON data into pandas, matplotlib, seaborn
-- **R**: Load data with jsonlite, analyze with tidyverse
-- **MATLAB**: Process JSON with built-in functions
-
-### **Annotation Tools**
-
-- **CVAT**: Computer Vision Annotation Tool integration
-- **LabelStudio**: Machine learning annotation platform
-- **ELAN**: Linguistic annotation software compatibility
+VideoAnnotator produces machine-readable outputs (primarily JSON files and API responses) intended to be easy to consume from common data tools.
 
-### **Analysis Platforms**
+- **Python**: Load JSON into pandas / numpy for analysis (see [examples/](examples/))
+- **R / MATLAB**: Not currently supported with official helper packages, but the JSON outputs can be consumed using standard JSON readers
+- **Visualization**: Use the companion [Video Annotation Viewer](https://github.com/InfantLab/video-annotation-viewer) for interactive playback + overlays
 
-- **Video Annotation Viewer**: Interactive web-based analysis (recommended)
-- **Custom dashboards**: Build with our REST API
-- **Jupyter notebooks**: Examples included in repository
-
-## 🛠️ Installation & Usage
-
-### **Method 1: Direct Installation (Recommended)**
-
-```bash
-# Modern Python environment
-curl -LsSf https://astral.sh/uv/install.sh | sh
-git clone https://github.com/InfantLab/VideoAnnotator.git
-cd VideoAnnotator
-uv sync
+## 🛠️ Installation Options
 
-# Start processing
-uv run videoannotator server --host 0.0.0.0 --port 18011
-```
+The quickstart above covers the recommended local install via `uv`. For more detail, see the [installation guide](docs/installation/INSTALLATION.md).
 
-### **Method 2: Docker (Production)**
+### **Docker (CPU/GPU)**
 
 ```bash
 # CPU version (lightweight)
 docker build -f Dockerfile.cpu -t videoannotator:cpu .
-docker run -p 18011:8000 videoannotator:cpu
+docker run -p 18011:18011 videoannotator:cpu
 
 # GPU version (faster processing)
 docker build -f Dockerfile.gpu -t videoannotator:gpu .
-docker run -p 18011:8000 --gpus all videoannotator:gpu
+docker run -p 18011:18011 --gpus all videoannotator:gpu
 
 # Development version (pre-cached models)
 docker build -f Dockerfile.dev -t videoannotator:dev .
 docker run -p 18011:18011 --gpus all videoannotator:dev
 ```
 
-### **Method 3: Research Platform Integration**
-
-```python
-# Python API for custom workflows
-from videoannotator import VideoAnnotator
-
-annotator = VideoAnnotator()
-results = annotator.process("video.mp4", pipelines=["person", "face"])
-
-# Analyze results
-import pandas as pd
-df = pd.DataFrame(results['person_tracking'])
-print(f"Detected {df['person_id'].nunique()} unique people")
-```
-
 ## 📚 Documentation & Resources
 
 | Resource                                                                 | Description                            |
@@ -284,7 +246,7 @@ print(f"Detected {df['person_id'].nunique()} unique people")
 | **[🎮 Live API Testing](http://localhost:18011/docs)**                   | Interactive API when server is running |
 | **[🚀 Getting Started Guide](docs/usage/GETTING_STARTED.md)**            | Step-by-step setup and first video     |
 | **[🔧 Installation Guide](docs/installation/INSTALLATION.md)**           | Detailed installation instructions     |
-| **[⚙️ Pipeline Specifications](docs/usage/pipeline_specs.md)**           | Technical pipeline documentation       |
+| **[⚙️ Pipeline Specifications](docs/pipelines_spec.md)**                 | Auto-generated pipeline spec table     |
 | **[🎯 Demo Commands](docs/usage/demo_commands.md)**                      | Example commands and workflows         |
 
 ## 👥 Research Applications
@@ -342,7 +304,7 @@ print(f"Detected {df['person_id'].nunique()} unique people")
 
 ### **Development**
 
-- **Code quality**: 83% test coverage, modern Python practices
+- **Code quality**: Automated linting, typing checks, and tests (see the CI badge above)
 - **Documentation**: Comprehensive guides and API documentation
 - **CI/CD**: Automated testing and deployment pipelines
 - **Standards**: Following research software engineering best practices
@@ -355,7 +317,7 @@ If you use VideoAnnotator in your research, please cite:
 
 ```
 Addyman, C. (2025). VideoAnnotator: Automated video analysis toolkit for human interaction research.
-Zenodo. https://Zenodo. doi.org/10.5281/zenodo.16961751
+Zenodo. https://doi.org/10.5281/zenodo.16961751
 ```
 
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.16961751.svg)](https://doi.org/10.5281/zenodo.16961751)