feat(fusion): complete learned RRF weights with FitResult, N-retriever grid, bayesian fitting, and save/load (#49)

[shivamm-gupta]

Description

Completes the Learned Fusion Weights feature by addressing gaps in the original implementation (PR #204). Adds a structured FitResult return type, generalises grid search to N retrievers, introduces bayesian optimisation as a fitting strategy, and provides save/load serialisation for production workflows.

Related issue

Closes #49

Changes

FitResult dataclass

• New structured return type for fit() with weights, score, method, and n_evaluations fields
• to_dict() for dict conversion, save() / load() for JSON persistence
• Exported from the dynavec package

Fixed _fit_grid() for N retrievers

• Previously hardcoded for exactly 2 retrievers ([w1, 1-w1])
• Now generalises to N-dimensional simplex via stars-and-bars partitioning
• Retains the fast 1-D sweep path for the 2-retriever case

New _fit_bayesian() method

• Uses scipy.optimize.minimize (Nelder-Mead) on a softmax-parameterised weight simplex
• Gracefully falls back to random search with a warning if scipy is not installed
• No new required dependency — scipy is optional

Updated notebook

• Added method comparison table (grid vs random vs bayesian)
• Added save/load workflow demo
• Added FitResult inspection examples
• Added 3-retriever grid search demo

Test coverage: 5 → 14 tests

• FitResult dataclass fields and return type
• Grid search for 2 and 3 retrievers
• Random and bayesian fitting
• Save/load JSON roundtrip
• Error handling edge cases

Testing

• Tests pass locally (uv run --no-sync pytest -q — all pass)
• Ruff checks pass
• Documentation updated (notebook)

Checklist

• My changes are focused and relevant to this pull request.
• I have added or updated tests where appropriate.
• I have reviewed my changes for unrelated modifications.
• I have updated documentation where necessary.

[codeforstartups]

Rounds out the learned-fusion work from #204 nicely (#49): a FitResult dataclass with JSON save()/load(), N-retriever grid search, and an optional Bayesian (Nelder-Mead on a softmax simplex) method that gracefully falls back to random with a warning when scipy is not installed — good defensive design. Verified locally: ruff clean, 14 fusion tests pass, CI green. Merging — thanks @shivamm-gupta! 🙌