Skip to content

feat: re-export MBRDRougeLStrategy from mellea.stdlib.sampling and add minimal structured-output-via-act() example #1275

Description

@planetf1

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.

Metadata

Metadata

Assignees

Labels

area/samplingSamplingStrategy, SamplingResult, ModelOption, generation optionsarea/stdlibCore abstractions: Context, MOT, SamplingStrategy, formatters, serializationenhancementNew feature or requestp2Medium/low: minor bugs, niche features, polish, docs, tests, cleanup. Scoped, lower urgency.

Type

No type
No fields configured for issues without a type.

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions