n best beam search

[Niduank]

Summary

• Add n_best parameter to Beam dataclass to return multiple hypotheses from beam search decoding
• Add NBestHypothesis dataclass with text, score, and confidence fields
• Add hypotheses attribute to AlignedResult to store N-best results
• Update documentation with N-best usage examples

Test plan

• Verify greedy decoding still works (returns hypotheses=None)
• Verify beam search with n_best=1 returns single hypothesis
• Verify beam search with n_best=3 returns 3 hypotheses sorted by score
• Verify streaming transcription works with new decode signature
• Verify chunked transcription works
• Test with v3 model (mlx-community/parakeet-tdt-0.6b-v3)

Usage

  from parakeet_mlx import from_pretrained, DecodingConfig, Beam                                                        
                                                                                                                        
  model = from_pretrained("mlx-community/parakeet-tdt-0.6b-v3")                                                         
  config = DecodingConfig(decoding=Beam(beam_size=5, n_best=3))                                                         
  result = model.transcribe("audio.wav", decoding_config=config)                                                        
                                                                                                                        
  for hyp in result.hypotheses:                                                                                         
      print(f"Text: {hyp.text}, Score: {hyp.score:.2f}, Confidence: {hyp.confidence:.2f}")

[senstella]

Thank you for taking the time to put this PR! I really appreciate the contribution. I had a few thoughts on the interface design that might help make things easier to maintain in future. Please let me know if you have other ideas!

[senstella]

I think implementing this as other dataclass is a bit redundant. Perhaps we can have list[AlignedSentence] instead?

[senstella]

I wonder if we could have an interface other than result, results_nbest, results_hidden. Perhaps we need to make something like DecodingOutput / DecodingResult so that we can extend that if there's any other modifications or improvements would happen.