MAINT GCG: extract candidate proposal phase (#2665)

[Vardhman Gupta (Kaap10)]

Description

This PR addresses Item 1 (Extract candidate proposal) of umbrella issue #2665, completing the first phase of the GCG optimization phase extraction following #2416 and merged PR #2467.

Tagging Roman Lutz (@romanlutz) as requested on #2665.

Key Changes:

• GCGCandidateProposer: Extracted worker gradient dispatch, cross-device tensor migration to main_device, $L_2$ gradient normalization, incompatible gradient shape grouping, token candidate sampling, and candidate filtering into a dedicated, modular component.
• CandidateProposalBatch: Introduced an immutable typed @dataclass(frozen=True, slots=True) encapsulating control_candidates_by_group and group_worker_indices.
• GCGMultiPromptAttack.step(): Replaced ~50 lines of entangled inline gradient collection and sampling loop with clean delegation to GCGCandidateProposer.
• Backward Compatibility: Retained _sample_control_candidates() and _filter_control_candidates() delegation shims on GCGMultiPromptAttack to guarantee zero regressions for existing tests and subclass overrides.

Non-breaking change: Public API signatures and return values remain 100% backward-compatible.

Tests and Documentation

Tests Added & Executed:

• Added dedicated deterministic unit test suite in tests/unit/executor/promptgen/gcg/test_gcg_proposal.py:
  • test_num_groups_property: Validates CandidateProposalBatch attributes.
  • test_empty_workers_raises_value_error: Validates ValueError on empty workers.
  • test_worker_and_prompt_count_mismatch_raises_value_error: Validates worker/prompt count parity.
  • test_single_worker_gradient_dispatch_and_normalization: Verifies $L_2$ normalization and protocol delegation.
  • test_same_shape_multiple_workers_accumulate_into_single_group: Verifies gradient summation on matching shapes.
  • test_mismatched_shapes_creates_multiple_candidate_groups: Verifies shape-mismatch grouping behavior.

Verification Results:

• pytest tests/unit/executor/promptgen/gcg/test_gcg_proposal.py: 6/6 passed (100%)
• pytest tests/unit/executor/promptgen/gcg/: 249/249 passed (100% GCG suite pass)
• pytest tests/integration/executor/promptgen/gcg/test_gcg_attack_wiring_integration.py: 4/4 passed
• ty check: All checks passed (0 errors)
• ruff check & ruff format: Clean (0 errors)
• pre-commit run --all-files: All hooks passed (All Green)

[Vardhman Gupta (Kaap10)]

@microsoft-github-policy-service agree