feat: Add probabilistic transitions with weighted random selection

[bcorfman]

Add support for weighted transitions that allow non-deterministic state transitions based on configurable probabilities. This is useful for game AI, simulations, and randomized workflows.

Key features:

• Add optional 'weight' parameter to Transition class
• Add optional 'random_seed' parameter to StateMachine for deterministic testing
• Implement weighted selection in both sync and async engines
• Automatically display probability percentages in state diagrams
• Full backward compatibility (no weights = original first-match behavior)
• Zero/negative weights are ignored
• Conditions (guards/validators) work seamlessly with weighted transitions
• Complete pickling support

Changes:

• statemachine/transition.py: Add weight parameter and repr support
• statemachine/statemachine.py: Add random_seed and Random instance
• statemachine/engines/sync.py: Implement weighted selection logic
• statemachine/engines/async_.py: Implement weighted selection logic
• statemachine/contrib/diagram.py: Add probability labels to diagrams
• README.md: Add probabilistic transitions to features list
• docs/transitions.md: Add comprehensive documentation with examples
• tests/test_probabilistic_transitions.py: 20 comprehensive tests
• tests/examples/game_character_idle_machine.py: Working example

All 348 existing tests pass + 20 new tests = 368 total passing tests

[sonarqubecloud]

Quality Gate passed

Issues
2 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
5.0% Duplication on New Code

See analysis details on SonarQube Cloud

[fgmacedo]

Hi @bcorfman , how are you?

Thank you for your contribution.
I find your proposal quite interesting and I agree that this use case is relevant.

I am concerned about the changes to the internal mechanisms of the library. I would prefer to address this scenario in a way that does not interfere with the internal structure.

Could we explore alternative approaches that achieve the same result while maintaining the current internal design?

I was thinking about trying to create a wrapper around a transition list, like ProbTransitions((a.to(b), 70), (a.to(b), 20), (a.to(c), 10))... That inject special conditions that flip a random chance for each round. If works, it will be like a isolated contrib.

I will close the PR. Feel free to explore other options.