fix: Update MultiTurnStrategy to include validation failure reasons in repair messages

[vabarbosa]

Description

This PR fixes MultiTurnStrategy to include detailed validation failure reasons from ValidationResult.reason in repair messages. The strategy now provides the model with actionable feedback about what went wrong (similar to RepairTemplateStrategy), significantly improving convergence rates. In addition, documentation updates were made and an example added.

Changes

1. Core Fix (mellea/stdlib/sampling/base.py):

   • Added module-level docstring explaining all sampling strategies and their use cases
   • Updated MultiTurnStrategy.repair() to include ValidationResult.reason in user messages

2. Documentation (docs/examples/instruct_validate_repair/README.md):

   • Added comprehensive "Sampling Strategies" section explaining when to use each strategy
   • Included code examples for all existing three strategies

3. Example (docs/examples/instruct_validate_repair/multiturn_strategy_example.py):

   • New working example demonstrating MultiTurnStrategy with validation functions

Impact

• ✅ MultiTurnStrategy now converges effectively with validation functions
• ✅ Users get clear guidance on using the sampling strategy
• ✅ Validation feedback is more actionable (and not ignored)

Testing

The new example can be run as a test:

uv run pytest docs/examples/instruct_validate_repair/multiturn_strategy_example.py

Related Issues

Fixes #631

---

Checklist

• Code changes implement the fix
• Module docstring added
• Documentation updated
• Working example provided
• Backward compatible
• Tests pass (uv run pytest -m "not qualitative")
• Code formatted (uv run ruff format .)
• Linting passes (uv run ruff check .)
• Type checking passes (uv run mypy .)

[mergify]

Merge Protections

Your pull request matches the following merge protections and will not be merged until they are valid.

🟢 Enforce conventional commit

Wonderful, this rule succeeded.

Make sure that we follow https://www.conventionalcommits.org/en/v1.0.0/

• title ~= ^(fix|feat|docs|style|refactor|perf|test|build|ci|chore|revert|release)(?:\(.+\))?:

[jakelorocco]

@vabarbosa, thank you for the PR. I pushed one change to correct the docstring for the sampling file since the rejection strat doesn't rely on validation_result.reason. Everything else looks good so I'll approve and it'll merge after the workflows pass.

Thank you!