fix(wan/shared): validate DIFFSYNTH_ATTENTION_IMPLEMENTATION

[wayrise]

Closes #12. Thanks @rakhimovv for the write-up — I reproduced all three modes before fixing, including the NameError.

Semantics

You asked whether an unrecognized value should raise or warn-and-fall-back. Raise, matching components.py, which is already the answer for the sibling variable:

	unknown name	known name, library missing
WAM_ATTENTION_IMPL	ValueError	warn, fall back
DIFFSYNTH_ATTENTION_IMPLEMENTATION (before)	accepted	accepted, then crashes
DIFFSYNTH_ATTENTION_IMPLEMENTATION (after)	ValueError	warn, fall back

Two env vars in one codebase behaving differently is its own trap, and the compatibility argument is thin: only five values were ever meaningful, so anyone spelling one correctly is unaffected. Anyone who is not is currently training on SDPA without knowing it, which is the outcome worth breaking loudly.

One consequence worth calling out: ATTENTION_IMPLEMENTATION is resolved at module scope, so a rejected name now raises at import rather than at first dispatch. That is deliberate — a typo should stop the run rather than quietly downgrade it, and the message names the valid choices. _log_attention_backends already wraps the import per subsystem, so diagnostics still degrade to Wan shared core : ERROR (...) instead of taking the process down.

The three modes, before and after

Verified on Python 3.10, torch 2.7.1+cu128, H200, with and without the official flash_attn 2.8.3 wheel. FA3 and sage are not installed, which is the ordinary case.

1. Uninstalled backend — was a crash at dispatch

$ DIFFSYNTH_ATTENTION_IMPLEMENTATION=flash_attention_3
# before
attention_forward: NameError: name 'flash_attn_interface' is not defined
# after
[WARNING] DIFFSYNTH_ATTENTION_IMPLEMENTATION='flash_attention_3' requested but not available, falling back to auto-detect
ATTENTION_IMPLEMENTATION = 'torch'   → attention_forward runs

2. Typo — was accepted silently

$ DIFFSYNTH_ATTENTION_IMPLEMENTATION=bogus
# before: ATTENTION_IMPLEMENTATION = 'bogus', ran as plain SDPA
# after
ValueError: Unknown DIFFSYNTH_ATTENTION_IMPLEMENTATION='bogus'.
  Choose from: ['flash_attention_3', 'flash_attention_2', 'sage_attention', 'xformers', 'torch']

3. Empty string — was reachable via the is not None guard

$ DIFFSYNTH_ATTENTION_IMPLEMENTATION=
# before: ATTENTION_IMPLEMENTATION = ''
# after : ATTENTION_IMPLEMENTATION = 'torch'

That also settles the cosmetic you and I went back and forth on in #11 — the deploy report now reads Wan shared core : torch for a blank override, with nothing added to the logger. Your call to fix the cause instead was the right one.

What changed

initialize_attention_priority() now strips and lowercases the override, rejects a name outside KNOWN_ATTENTION_IMPLEMENTATIONS, and checks the corresponding *_AVAILABLE flag before honouring it. Auto-detection is unchanged — same priority order, now driven by that tuple rather than an if/elif chain, and pinned by a test so this refactor can't have reshuffled it silently.

A valid, installed override still wins over auto-detection (flash_attention_2 requested and present → flash_attention_2; torch requested with flash-attn installed → torch, i.e. opting out still works).

Tests

Six cases in tests/test_attention_backend_dispatch.py, all CPU-only. Against origin/main's attention.py they fail 4/6 — the other two pin behaviour that was already correct (a valid available override is honoured; the auto-detection order).

full suite, no flash-attn   : 1979 passed, 20 skipped
full suite, with flash-attn : 1979 passed, 20 skipped
ruff check / ruff format --check / compileall : clean

🤖 Generated with Claude Code

[wayrise]

Closing in favour of #14, which does the same job and got here first.

My mistake: I picked up #12 and wrote this without checking whether a PR was already open. @rakhimovv had pushed #14 forty minutes earlier — and had said in the issue he was ready to send one, so the fault is entirely on me for not looking.

For the record, since it's mildly reassuring rather than embarrassing: the two arrived at the same semantics independently. Both mirror components.py — unknown name raises, known-but-uninstalled warns and falls back — and both landed on treating a blank value as "no override" rather than an error.

Where they differ, #14 is the better change. It leaves the auto-detection if-chain alone; this branch restructured it into a table-driven loop and then had to add a test pinning the priority order to prove the refactor was inert. Less churn for the same fix. Its test file is also slightly broader — test_torch_is_always_selectable covers a case I missed.

I verified #14 on an H200 before saying any of this, and reviewed it there.

Nothing here is worth salvaging except possibly one invariant — a loop asserting every known backend degrades to torch when nothing is installed — which I've left as a non-blocking note on #14. Branch deleted.