Fix installation error with improved backend fallback and error messages

[Copilot]

The installation error "CUDA flash_dmattn_func is not available. Please check the installation." was occurring when users had a partially installed CUDA extension. This happened when the flash_dmattn_cuda module could be imported but the interface functions failed to load, creating a confusing state where CUDA_AVAILABLE=True but flash_dmattn_func=None.

Problem

Users following the installation instructions would encounter:

from flash_dmattn import flash_dmattn_func_auto
func = flash_dmattn_func_auto()  # RuntimeError: CUDA flash_dmattn_func is not available...

The error occurred because:

1. The CUDA extension module imported successfully (CUDA_AVAILABLE=True)
2. But interface functions failed to import (flash_dmattn_func=None)
3. Auto-selection logic incorrectly chose CUDA backend
4. Error message provided no actionable guidance

Solution

Backend Detection: Added _is_cuda_fully_available() helper that checks both module import AND function availability, ensuring backends are only reported as available when fully functional.

Graceful Fallback: Modified auto-selection logic to properly fall back to working backends (Triton/Flex) when CUDA appears available but functions are missing.

Better Error Messages: Improved error messages to distinguish between "CUDA not built" vs "CUDA partially installed" scenarios, providing specific installation commands.

Documentation Updates: Updated README examples to use recommended auto-selection pattern and added comprehensive troubleshooting section for CUDA extension issues.

Key Changes

• Robust backend detection that prevents false positives
• Automatic fallback to working backends instead of cryptic failures
• Actionable error messages with specific pip install commands
• Updated documentation showing best practices and troubleshooting

Now users with partial installations get working functionality with clear guidance on how to complete the installation if desired.

Fixes #150.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.