Add DeepForest-controlled HuggingFace authentication warning and docs

[Copilot]

Users loading models from HF Hub see an opaque unauthenticated-request warning from the HF library with no DeepForest-level guidance. This adds a clear, actionable one-time warning and supporting docs.

Changes

src/deepforest/main.py

• Imports huggingface_hub.get_token at module level (gracefully degrades if unavailable)
• Adds _warn_if_no_hf_token(): emits a UserWarning once per process (via _hf_token_warning_issued sentinel) when no token is found
• Calls _warn_if_no_hf_token() at the top of load_model()

# Warning emitted once when no token is configured
model = main.deepforest()
model.load_model("weecology/deepforest-tree")
# UserWarning: No Hugging Face token found. Downloads of models from the Hub will
# use unauthenticated requests, which have lower rate limits. Authentication is
# optional for public models but recommended. To authenticate, run
# `huggingface-cli login` or set the HF_TOKEN environment variable.
# See https://huggingface.co/docs/hub/security-tokens for details.

docs/user_guide/02_prebuilt.md

• Adds Hugging Face Authentication section: clarifies auth is optional, provides huggingface-cli login and HF_TOKEN instructions, links to official HF token docs.

tests/test_main.py

• test_hf_token_warning_emitted_when_no_token: warning fires with no token
• test_hf_token_warning_suppressed_when_token_present: no warning when token exists
• test_hf_token_warning_emitted_only_once: sentinel blocks duplicate warnings

AI-Assisted Development

• I used AI tools (e.g., GitHub Copilot, ChatGPT, etc.) in developing this PR
• I understand all the code I'm submitting
• I have reviewed and validated all AI-generated code

AI tools used (if applicable): GitHub Copilot

Original prompt

Create a code-side long-term fix for the HuggingFace Hub unauthenticated requests warning in weecology/DeepForest.

Context:
Users see a runtime warning similar to:
"Warning: You are sending unauthenticated requests to the HF Hub. Please set a HF_TOKEN to enable higher rate limits and faster downloads."
This occurs when DeepForest downloads models/configs from Hugging Face Hub without a token configured.

Goals:

1. Documentation fix (preferred long-term fix Check download speed of NEON data api #1):

   • Add clear documentation explaining that HuggingFace authentication is optional but recommended for faster downloads and higher rate limits.
   • Provide instructions for both:
     a) huggingface-cli login
     b) setting HF_TOKEN environment variable
   • Place the documentation in an appropriate existing docs page(s) related to model loading / prebuilt models / installation / troubleshooting.
   • Ensure docs are consistent with DeepForest’s current workflow of loading models from HF Hub (e.g., main.deepforest().load_model("weecology/deepforest-tree")).

2. Code fix (preferred long-term fix Upload 2015 orthos from T into Hypergator #2):

   • Add a DeepForest-level, user-friendly warning that triggers before/when Hugging Face Hub access is used and no token is found.
   • The warning should:
     • Not break existing behavior.
     • Be emitted once per process to avoid spam.
     • Provide actionable steps (login or set HF_TOKEN) and link to official HF authentication docs.
   • Implement this in the most appropriate location(s) in the code path for Hub access, such as:
     • deepforest.main.deepforest.load_model() (loads pretrained models from HF)
     • and/or deepforest.model.BaseModel/CropModel.from_pretrained where hf_hub_download is used.
   • Use huggingface_hub APIs to check token presence if available (e.g., HfFolder.get_token()), but handle import/version differences gracefully.
   • Add tests that validate the warning behavior:
     • When no token is present, the warning is emitted.
     • When a token is present (mocked), no warning.
     • Warning emitted only once.

Implementation notes:

• Keep messaging concise and non-alarming (authentication is optional for public models).
• Avoid printing tokens or sensitive data.
• Update any relevant docs references.

Acceptance criteria:

• New/updated documentation merged.
• Code warns users with a DeepForest-controlled message when unauthenticated.
• Tests cover the new behavior.
• CI passes.

This pull request was created from Copilot chat.

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.