[gerardo-navarro]

Summary

Behind a proxy that re-signs HTTPS traffic (#318), a model download fails with a long requests/urllib3 traceback that ends in CERTIFICATE_VERIFY_FAILED. Users cannot tell what to do from it.

download_model now detects a certificate failure anywhere in the exception chain and raises ModelDownloadError:

Could not download model 'large-v3-turbo': the server certificate could not be verified. A proxy in your network most likely inspects HTTPS traffic with its own certificate. Ask your IT department, or install the model manually: https://github.com/aTrainTranscription/aTrain/blob/develop/docs/offline-model-install.md

• The original exception stays chained (raise ... from error), so the traceback in the dialog still shows the details.
• Detection walks __cause__, __context__, reason and args. urllib3 keeps the ssl.SSLCertVerificationError in args rather than chaining it. Walking the chain also covers httpx once huggingface_hub 1.x lands (Upgrade to Transformers 5.17 and Hugging Face Hub 1.33 #286).
• All other errors pass through unchanged.

Stacked on #320: the message links to docs/offline-model-install.md, which #320 adds. Base is feature_offline_model_docs; retarget to develop once #320 is merged.

References

Refs #318, depends on #320, related to #319

Screenshots / Examples

Real chain from requests behind a TLS-inspecting proxy:

requests.exceptions.SSLError
  urllib3.exceptions.MaxRetryError
    urllib3.exceptions.SSLError
      (args) ssl.SSLCertVerificationError

_is_certificate_error returns True for it, False for e.g. OSError("connection lost").

Verification Steps

• uv run --no-sync pytest tests/unit/test_load_resources.py: 2 new tests fail without the change, all 5 pass with it.
• Detection checked against a real requests call through a TLS-inspecting proxy (not just the constructed chain in the test).
• ruff check, ruff format --check, bandit clean.
• Windows 11 VM with mitmproxy, without its CA in the trust store: Models page → Download tiny shows the new message.