Context: Two related discoverability gaps encountered writing a first real Mellea script, plus a wrong comment in an existing example that compounds them.
1. Sampling strategy imports
The README feature list says "swap between rejection sampling, majority voting, and more with one parameter change." So I tried:
from mellea.stdlib.sampling import MajorityVotingStrategy # ImportError
There is no MajorityVotingStrategy. The class that does the job is MBRDRougeLStrategy in mellea/stdlib/sampling/majority_voting.py — named after its similarity metric (Minimum Bayes Risk Decoding + ROUGE-L), not the concept. It isn't re-exported from mellea.stdlib.sampling, so IDE completion doesn't surface it. To find it I had to grep source, read three class docstrings, and reverse-map "majority voting" → "MBRD" → "ROUGE-L". That's domain knowledge a developer who just wants "run it N times, take the consensus" shouldn't need.
The docs already acknowledge the surprise as a buried "Note" in inference-time-scaling.md — the workaround was documented instead of the gap fixed. BudgetForcingSamplingStrategy has the identical problem.
2. No correct minimal act(format=) example
There is one existing act(format=) example in act-and-aact.md, but its comment is wrong:
result = m.act(instruction, format=Planet)
print(result.value) # A Planet instance ← wrong: result.value is a JSON string
This actively misleads. Beyond that, there is no end-to-end getting-started example for session.act(Instruction(...), format=Model) — the natural path when building a prompt string yourself. To assemble the correct pattern I read session.py, functional.py, instruction.py, base.py, and two how-to docs. The missing correct example is also the one that would have shown the critical model_validate_json unwrapping step (see companion bug #1273).
Proposed fixes:
Sampling imports — re-export the currently hidden strategies from mellea/stdlib/sampling/__init__.py:
from .majority_voting import (
MBRDRougeLStrategy, # general-purpose text majority voting
MajorityVotingStrategyForMath, # specialised: numeric/math expression comparison
)
from .budget_forcing import BudgetForcingSamplingStrategy
Add one line to MBRDRougeLStrategy's docstring: "This is the general-purpose majority voting strategy for text outputs." Zero compatibility impact — purely additive.
Fix wrong comment and add correct minimal example — correct act-and-aact.md line 163 (# A Planet instance → # A JSON string — parse with Planet.model_validate_json(str(result))), and add docs/examples/structured_output_minimal.py:
from pydantic import BaseModel
from mellea import start_session
from mellea.stdlib.components import Instruction
class Classification(BaseModel):
label: str
confidence: float
with start_session("ollama") as m:
result = m.act(Instruction("Classify: 'ship it'"), format=Classification)
parsed = Classification.model_validate_json(str(result)) # the load-bearing line
print(parsed.label, parsed.confidence)
Related: PR #262 (stale since Jan 2026) adds runnable MBRD example files but not the __init__ re-exports this issue asks for — both are needed. Worth reviving alongside this fix.
Context: Two related discoverability gaps encountered writing a first real Mellea script, plus a wrong comment in an existing example that compounds them.
1. Sampling strategy imports
The README feature list says "swap between rejection sampling, majority voting, and more with one parameter change." So I tried:
There is no
MajorityVotingStrategy. The class that does the job isMBRDRougeLStrategyinmellea/stdlib/sampling/majority_voting.py— named after its similarity metric (Minimum Bayes Risk Decoding + ROUGE-L), not the concept. It isn't re-exported frommellea.stdlib.sampling, so IDE completion doesn't surface it. To find it I had to grep source, read three class docstrings, and reverse-map "majority voting" → "MBRD" → "ROUGE-L". That's domain knowledge a developer who just wants "run it N times, take the consensus" shouldn't need.The docs already acknowledge the surprise as a buried "Note" in
inference-time-scaling.md— the workaround was documented instead of the gap fixed.BudgetForcingSamplingStrategyhas the identical problem.2. No correct minimal
act(format=)exampleThere is one existing
act(format=)example inact-and-aact.md, but its comment is wrong:This actively misleads. Beyond that, there is no end-to-end getting-started example for
session.act(Instruction(...), format=Model)— the natural path when building a prompt string yourself. To assemble the correct pattern I readsession.py,functional.py,instruction.py,base.py, and two how-to docs. The missing correct example is also the one that would have shown the criticalmodel_validate_jsonunwrapping step (see companion bug #1273).Proposed fixes:
Sampling imports — re-export the currently hidden strategies from
mellea/stdlib/sampling/__init__.py:Add one line to
MBRDRougeLStrategy's docstring: "This is the general-purpose majority voting strategy for text outputs." Zero compatibility impact — purely additive.Fix wrong comment and add correct minimal example — correct
act-and-aact.mdline 163 (# A Planet instance→# A JSON string — parse with Planet.model_validate_json(str(result))), and adddocs/examples/structured_output_minimal.py:Related: PR #262 (stale since Jan 2026) adds runnable MBRD example files but not the
__init__re-exports this issue asks for — both are needed. Worth reviving alongside this fix.