refactor: standardize imports and enhance logging

Major improvements across codebase:

Import Standardization:
- Convert relative imports to absolute (AGENTS.md compliance)
- src/batch/batch_orchestrator.py: from ..pipelines → from pipelines
- src/api/background_tasks.py: from .. → from api/storage
- src/worker/job_processor.py: relative → absolute imports
- Prepares for package namespace migration (v1.3.0)

Logging Enhancements (src/utils/logging_config.py):
- Add capture_warnings parameter (route warnings.warn to logging)
- Add capture_stdstreams parameter (capture print() calls)
- Attach handlers to third-party loggers (torch, ultralytics, etc.)
- Route py.warnings into log handlers for visibility
- StreamToLogger class for stdout/stderr redirection

Pipeline Import Resilience (batch_orchestrator.py):
- Individual try/catch per pipeline import
- Failure in one pipeline doesn't disable others
- Helpful error hints (e.g., missing libGL.so.1)
- Graceful degradation on import failures

Version Info Cleanup (src/version.py):
- Replace print() with logger.info() calls
- Consistent with structured logging approach
- No emoji/unicode (Windows compatibility)

Configuration Updates:
- .devcontainer/devcontainer.json: port/settings updates
- .github/workflows/ci-cd.yml: workflow adjustments
- Dockerfile.gpu: build improvements
- Dockerfile.oldgpu: legacy GPU support preserved

Documentation:
- docs/testing/testing_standards.md: updated guidelines
- docs/usage/pipeline_specs.md: spec updates
- tests/README.md: test documentation improvements

Debug Tools:
- scripts/debug_load_job.py: new job debugging utility
- scripts/test_logging.py: logging test improvements

Aligns with v1.3.0 roadmap goals:
- Package namespace preparation
- ASCII-safe console output
- Improved error diagnostics
- Graceful component failures

Author: InfantLab

.devcontainer/devcontainer.json

@@ -10,7 +10,7 @@
     "all"
   ],
   "features": {},
-  "postCreateCommand": "uv sync && uv sync --extra dev && uv pip install \"torch==2.8.0+cu130\" \"torchvision==0.21.0+cu130\" \"torchaudio==2.8.0+cu130\" --index-url https://download.pytorch.org/whl/cu130 && uv run pre-commit install",
+  "postCreateCommand": "uv sync && uv sync --extra dev && uv pip install \"torch==2.8.0+cu124\" \"torchvision==0.21.0+cu124\" \"torchaudio==2.8.0+cu124\" --index-url https://download.pytorch.org/whl/cu124 && uv run pre-commit install",
   "customizations": {
     "vscode": {
       "settings": {

.github/workflows/ci-cd.yml

@@ -34,7 +34,7 @@ jobs:
       if: matrix.os == 'ubuntu-latest'
       run: |
         sudo apt-get update
-        sudo apt-get install -y ffmpeg libsm6 libxext6 libxrender-dev libglib2.0-0
+  sudo apt-get install -y ffmpeg libsm6 libxext6 libxrender1 libglib2.0-0
         sudo apt-get install -y cmake build-essential
 
     - name: Install system dependencies (macOS)
@@ -101,7 +101,7 @@ jobs:
     - name: Install system dependencies
       run: |
         sudo apt-get update
-        sudo apt-get install -y ffmpeg libsm6 libxext6 libxrender-dev libglib2.0-0
+  sudo apt-get install -y ffmpeg libsm6 libxext6 libxrender1 libglib2.0-0
         sudo apt-get install -y cmake build-essential
 
     - name: Install dependencies
@@ -141,7 +141,7 @@ jobs:
     - name: Install system dependencies
       run: |
         sudo apt-get update
-        sudo apt-get install -y ffmpeg libsm6 libxext6 libxrender-dev libglib2.0-0
+  sudo apt-get install -y ffmpeg libsm6 libxext6 libxrender1 libglib2.0-0
         sudo apt-get install -y cmake build-essential
 
     - name: Install dependencies

Dockerfile.gpu

@@ -5,12 +5,12 @@
 #   docker build -f Dockerfile.gpu -t videoannotator:gpu .
 #   docker run --gpus all --rm -p 8000:8000 -v ${PWD}/data:/app/data videoannotator:gpu
 
-FROM nvidia/cuda:13.0.1-runtime-ubuntu24.04
+FROM nvidia/cuda:12.6.0-runtime-ubuntu24.04
 
 SHELL ["/bin/bash","-lc"]
 RUN apt-get update && apt-get install -y \
     curl python3 python3-venv python3-pip git \
-    libgl1-mesa-glx libglib2.0-0 libsm6 libxext6 libxrender-dev libgomp1 \
+    libgl1-mesa-dri libglib2.0-0 libsm6 libxext6 libxrender1 libgomp1 \
     && rm -rf /var/lib/apt/lists/*
 
 # Ensure locale is generated so LANG=en_US.UTF-8 works inside the container
@@ -46,14 +46,10 @@ COPY . .
 RUN if [ "${SKIP_IMAGE_UV_SYNC}" != "true" ]; then uv sync --frozen --no-editable; else echo "[BUILD] Skipping uv sync at image build (SKIP_IMAGE_UV_SYNC=true)"; fi
 
 # Install CUDA PyTorch for GPU acceleration (override CPU version)
-RUN if [ "${SKIP_TORCH_INSTALL}" != "true" ]; then uv pip install "torch==2.8.0+cu130" "torchvision==0.21.0+cu130" "torchaudio==2.8.0+cu130" --index-url https://download.pytorch.org/whl/cu130; else echo "[BUILD] Skipping torch install at image build (SKIP_TORCH_INSTALL=true)"; fi
+RUN if [ "${SKIP_TORCH_INSTALL}" != "true" ]; then uv pip install "torch==2.8.0+cu126" "torchvision==0.23.0+cu126" "torchaudio==2.8.0+cu126" --index-url https://download.pytorch.org/whl/cu126; else echo "[BUILD] Skipping torch install at image build (SKIP_TORCH_INSTALL=true)"; fi
 
 # Verify GPU access (no model downloading needed!)
-RUN uv run python3 -c "\
-import torch; \
-print(f'[GPU BUILD] CUDA available: {torch.cuda.is_available()}'); \
-print(f'[GPU BUILD] PyTorch version: {torch.__version__}'); \
-print('[GPU BUILD] Production image ready - models will download on first use');"
+RUN uv run python3 -c "import torch; print(f'[GPU BUILD] CUDA available: {torch.cuda.is_available()}'); print(f'[GPU BUILD] PyTorch version: {torch.__version__}'); print('[GPU BUILD] Production image ready - models will download on first use')"
 
 # Set environment for production
 ENV PYTHONUNBUFFERED=1

Dockerfile.oldgpu

@@ -0,0 +1,81 @@
+# VideoAnnotator Docker Image - Legacy GPU (GTX 10xx / CUDA 11.x)
+#
+# Purpose:
+# - Designed for older GPUs (eg. GTX 1060) that are best matched with CUDA 11.x
+# - Keeps heavy steps optional (SKIP_IMAGE_UV_SYNC / SKIP_TORCH_INSTALL) so builders can
+#   choose to perform network operations at container runtime instead of at build time.
+#
+# Usage (build):
+#   docker build -f Dockerfile.oldgpu -t videoannotator:oldgpu .
+#
+# Usage (run):
+#   docker run --gpus all --rm -p 18011:18011 -v ${PWD}/data:/app/data videoannotator:oldgpu
+
+# Choose a CUDA 11.x runtime image compatible with older GPUs/drivers
+FROM nvidia/cuda:11.3.1-runtime-ubuntu20.04
+
+SHELL ["/bin/bash","-lc"]
+
+# Install core system packages and graphics libs commonly required by some pipelines
+RUN apt-get update && apt-get install -y \
+    curl python3 python3-venv python3-pip git git-lfs \
+    libgl1-mesa-dri libglib2.0-0 libsm6 libxext6 libxrender1 libgomp1 \
+    && rm -rf /var/lib/apt/lists/*
+
+# Ensure locale is generated so LANG=en_US.UTF-8 works inside the container
+RUN apt-get update && apt-get install -y locales \
+    && locale-gen en_US.UTF-8 \
+    && update-locale LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8 \
+    && rm -rf /var/lib/apt/lists/*
+
+# Export UTF-8 locale for all processes
+ENV LANG=en_US.UTF-8
+ENV LC_ALL=en_US.UTF-8
+
+# Initialize Git LFS
+RUN git lfs install
+
+# uv package manager (project standard)
+RUN curl -LsSf https://astral.sh/uv/install.sh | sh
+ENV PATH="/root/.local/bin:${PATH}"
+
+WORKDIR /app
+
+# Build args to allow skipping heavy network steps during image build
+ARG SKIP_IMAGE_UV_SYNC=true
+ARG SKIP_TORCH_INSTALL=true
+
+# Copy project files (exclude large model artifacts via .dockerignore)
+COPY . .
+
+# Copy local models / weights if you want them baked into the image (optional)
+# COPY models/ /app/models/
+# COPY weights/ /app/weights/
+
+# Install Python dependencies via uv (can be skipped at build time)
+RUN if [ "${SKIP_IMAGE_UV_SYNC}" != "true" ]; then uv sync --frozen --no-editable; else echo "[BUILD] Skipping uv sync at image build (SKIP_IMAGE_UV_SYNC=true)"; fi
+
+# Torch installation: keep this optional because CUDA and appropriate wheel sets can vary
+# Provide build args to install a matching wheel at build time. Example values are
+# for CUDA 11.3: TORCH_WHEEL="torch==1.13.1+cu113 torchvision==0.14.1+cu113 torchaudio==0.13.1+cu113"
+ARG TORCH_WHEEL=""
+ARG TORCH_INDEX_URL="https://download.pytorch.org/whl/cu113"
+RUN if [ "${SKIP_TORCH_INSTALL}" != "true" ] && [ -n "${TORCH_WHEEL}" ]; then \
+            echo "[BUILD] Installing torch wheels: ${TORCH_WHEEL}"; \
+            uv pip install ${TORCH_WHEEL} --index-url ${TORCH_INDEX_URL}; \
+        else \
+            echo "[BUILD] Skipping torch install (SKIP_TORCH_INSTALL=${SKIP_TORCH_INSTALL}, TORCH_WHEEL set: ${TORCH_WHEEL:+yes})"; \
+        fi
+
+# Quick smoke-check (optional) - this will only run if uv and Python are available
+RUN uv run python3 -c "import sys; print('[OLDGPU BUILD] Python:', sys.version.splitlines()[0])"
+
+ENV PYTHONUNBUFFERED=1
+ENV CUDA_VISIBLE_DEVICES=0
+
+# Create directories for mounted volumes
+RUN mkdir -p /app/data /app/output /app/logs
+
+EXPOSE 18011
+
+CMD ["uv", "run", "python3", "api_server.py", "--log-level", "info", "--port", "18011"]

api_server.py

@@ -27,7 +27,9 @@
 
 def setup_logging(level: str = "INFO", logs_dir: str = "logs"):
     """Set up enhanced logging configuration."""
-    setup_videoannotator_logging(logs_dir=logs_dir, log_level=level)
+    # Capture Python warnings by default so compatibility warnings surface in logs.
+    setup_videoannotator_logging(logs_dir=logs_dir, log_level=level, capture_warnings=True,
+                                 capture_stdstreams=(level.upper()=="DEBUG"))
 
 def main():
     """Main entry point for the API server."""

docs/testing/testing_standards.md

@@ -73,15 +73,15 @@ The VideoAnnotator test suite uses a modular approach with dedicated test files
 #### Running Modular Tests
 ```bash
 # Run tests for a specific pipeline
-python -m pytest tests/test_face_pipeline.py -v
+uv run python -m pytest tests/test_face_pipeline.py -v
 
 # Run specific test categories across all pipelines  
-python -m pytest tests/ -m unit -v
-python -m pytest tests/ -m integration -v
-python -m pytest tests/ -m performance -v
+uv run python -m pytest tests/ -m unit -v
+uv run python -m pytest tests/ -m integration -v
+uv run python -m pytest tests/ -m performance -v
 
 # Run all pipeline tests through the test runner
-python -m pytest tests/test_all_pipelines.py -v
+uv run python -m pytest tests/test_all_pipelines.py -v
 ```
 
 ## Test File Standards

docs/usage/pipeline_specs.md

@@ -186,16 +186,16 @@ scene_detection:
 
 ```bash
 # Process single video with all pipelines
-python -m videoannotator process video.mp4
+uv run python -m videoannotator process video.mp4
 
 # Process specific pipeline
-python -m videoannotator process video.mp4 --pipeline person_tracking
+uv run python -m videoannotator process video.mp4 --pipeline person_tracking
 
 # Custom config
-python -m videoannotator process video.mp4 --config configs/high_performance.yaml
+uv run python -m videoannotator process video.mp4 --config configs/high_performance.yaml
 
 # Batch processing
-python -m videoannotator batch videos/ --output results/
+uv run python -m videoannotator batch videos/ --output results/
 ```
 
 ### Python API

scripts/debug_load_job.py

@@ -0,0 +1,24 @@
+"""
+Quick script to load a job from storage and print full traceback on failure.
+Run with: uv run python scripts/debug_load_job.py <job_id>
+"""
+import sys
+import traceback
+from pathlib import Path
+
+# Ensure package import works from repo root
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / 'src'))
+
+from api.database import get_storage_backend
+
+JOB_ID = sys.argv[1] if len(sys.argv) > 1 else '52325a4e-71e8-4a22-b934-0c4836fd746e'
+
+print(f"Attempting to load job: {JOB_ID}")
+storage = get_storage_backend()
+try:
+    job = storage.load_job_metadata(JOB_ID)
+    print('Loaded job OK:', getattr(job, 'job_id', None))
+except Exception as e:
+    print('Exception occurred while loading job:')
+    traceback.print_exc()
+    raise

scripts/test_logging.py

@@ -22,8 +22,8 @@ def test_logging_system():
     print("\n[TEST 1] Testing basic logging setup...")
 
     try:
-        from src.utils.logging_config import setup_videoannotator_logging, get_logger
-        loggers = setup_videoannotator_logging(logs_dir="logs", log_level="INFO")
+    from src.utils.logging_config import setup_videoannotator_logging, get_logger
+    loggers = setup_videoannotator_logging(logs_dir="logs", log_level="INFO", capture_warnings=True)
 
         api_logger = get_logger("api")
         request_logger = get_logger("requests") 

src/api/background_tasks.py

@@ -139,7 +139,8 @@ async def _process_cycle(self):
                         jobs_to_process.append(job)
                         self.processing_jobs.add(job_id)
                     except Exception as e:
-                        logger.error(f"Failed to load job {job_id}: {e}")
+                        # Log full exception traceback to identify offending imports
+                        logger.error(f"Failed to load job {job_id}: {e}", exc_info=True)
 
             # Start processing selected jobs
             for job in jobs_to_process: