# ADR-006: PyTorch as Optional Dependency

## Status

Accepted

## Context

PyTorch is the inference backend for the detector model. However, PyTorch is
large:

- `torch` (CPU): ~200MB download, ~700MB installed
- `torch` (CUDA): ~2.5GB download, ~5GB+ installed

Making PyTorch a required dependency would force a 200MB-2.5GB download on
every user, even those who already have PyTorch installed. This is the
standard problem for ML libraries, and the HuggingFace ecosystem has
converged on a solution.

## Decision

Make PyTorch an optional dependency via extras (`pip install
alknet-firewall[torch]`). The base install includes all non-ML dependencies
(sklearn, huggingface-hub, safetensors, tokenizers, numpy). ML inference
backends are installed separately.

Use lazy imports with clear error messages when PyTorch is not installed:

```python
try:
    import torch
except ImportError:
    raise ImportError(
        "PyTorch is required for alknet-firewall inference. "
        "Install with: pip install 'alknet-firewall[torch]' "
        "or pip install torch --index-url https://download.pytorch.org/whl/cpu"
    )
```

## Consequences

**Positive**:
- Base install is ~30MB download, ~100MB installed — very lightweight
- Users with existing PyTorch installations don't re-download
- Follows HuggingFace ecosystem conventions (transformers, safetensors, HF
  hub all use this pattern)
- uv supports CPU/GPU torch variant selection via `[tool.uv.sources]` and
  `[[tool.uv.index]]`

**Negative**:
- More complex dependency specification in pyproject.toml
- Users must read installation docs to choose the right extra
- Runtime import errors if users forget to install a backend
- CPU-only torch requires two-step install or uv configuration (can't be
  expressed in pip extras alone)
- PyTorch is the only supported inference backend; future alternatives
  (burn/cublas via safetensors) would require separate integration work

## References

- [modern-python-project-setup.md](../research/modern-python-project-setup.md) —
  Section 2: PyTorch handling
- [python-ml-packaging.md](../research/python-ml-packaging.md) — Section 1:
  PyTorch as dependency