fix(common): add exponential backoff to MinIO HTTP downloads

[unidel2035]

Summary

This PR fixes the 503 Service Unavailable errors when downloading files from MinIO, as reported in issue #712.

Problem

Users were experiencing 503 Server Error: Service Unavailable errors when uploading files to the knowledge base. The error occurred during file download from MinIO storage through the download_from_http function in kag/common/utils.py:300.

The root cause was that the retry mechanism (@retry(stop=stop_after_attempt(3))) was retrying immediately without any delay between attempts, giving MinIO no time to recover from temporary overload or unavailability.

Solution

Added exponential backoff to the retry logic:

• Import: Added wait_exponential from tenacity library
• Retry Strategy: Updated decorator to @retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, min=2, max=10))
  • First retry: waits ~2 seconds
  • Second retry: waits ~4 seconds
  • Maximum wait: 10 seconds
• Documentation: Enhanced function docstring to document retry behavior and optional dest parameter

Changes

• kag/common/utils.py: Added exponential backoff to download_from_http function
• tests/unit/common/test_utils.py: Added comprehensive unit tests covering:
  • Successful download scenarios
  • Retry behavior on 503 errors
  • Max retry exhaustion handling

Testing

• ✅ All code formatted with black
• ✅ Passes flake8 linting
• ✅ Added unit tests with mocked HTTP responses
• ✅ Tests verify retry count and exponential backoff behavior

Impact

This change significantly improves reliability when uploading files to knowledge bases by gracefully handling transient MinIO service unavailability, consistent with retry patterns used elsewhere in the codebase (e.g., LLM client, hybrid retrieval).

Fixes #712

---

🤖 Generated with Claude Code

[unidel2035]

🤖 Solution Draft Log

This log file contains the complete execution trace of the AI solution draft process.

📎 Log file uploaded as GitHub Gist (226KB) 🔗 View complete solution draft log

---

Now working session is ended, feel free to review and add any feedback on the solution draft.