docs: clarify sampling raises

[skyswordw]

Summary

• clarify the AssertionError entry for BaseSamplingStrategy.sample() so it matches the current select_from_failure and generation-log assertions
• document the concurrent subsample exception re-raise path when no subsample produces a result

Fixes #1213.

Checks

• uv run ruff format --check mellea/stdlib/sampling/base.py
• uv run ruff check mellea/stdlib/sampling/base.py
• uv run pytest test/stdlib/sampling/test_sampling_base_unit.py -q
• git diff --check

[skyswordw]

Marking this ready for review.

Local checks completed before opening the PR:

• uv run ruff format --check mellea/stdlib/sampling/base.py
• uv run ruff check mellea/stdlib/sampling/base.py
• uv run pytest test/stdlib/sampling/test_sampling_base_unit.py -q (16 passed)
• git diff --check

GitHub checks visible on the PR are currently green.

[planetf1]

A couple of small consistency notes inline — nothing that should hold this up.

[planetf1]

A couple of small consistency notes inline — nothing that should hold this up.

[planetf1]

Thanks for the PR — removing that stale assertion text is a good catch.

One small thing on the AssertionError description: "outside the generated samples" doesn't quite say what the assertion checks. The actual check is result_index < len(sample_generations), so "out-of-range index into sample_generations" is more direct. Same for the second part — "has no generation log to mark as final" is a roundabout way of saying "_generate_log is None".

The convention in this file is If \condition`with backtick code references — you can see it in theValueError` entry just below, and in the class docstring at line 131. Suggestion to bring it in line:

Suggested change

	AssertionError: If `select_from_failure` returns an index outside
	AssertionError: If `select_from_failure` returns an out-of-range index
	into `sample_generations`, or if the selected result's
	`_generate_log` is `None`.

[planetf1]

Same convention note here — all the other entries in this block start with If <condition>, but this one starts with "Re-raised from…".

The condition is also slightly imprecise: the exception only fires when no subsample produced a usable result. A subsample can raise and the call still succeeds if any other subsample came through — so "all subsamples fail" undersells the specificity of the trigger:

Suggested change

	Exception: Re-raised from a concurrent subsample if all subsamples
	Exception: If all subsamples raise without producing a result,
	the first non-cancellation exception is re-raised (e.g. a
	backend error).

[skyswordw]

Thanks, updated both docstring entries to match the suggested wording and the local If <condition> convention.

[planetf1]

Thanks for the improvement. LGTM