[feature]: @rllm.rollout and @rllm.evaluator decorators + cookbook examples

[jeffreysijuntan]

@rllm.rollout and @rllm.evaluator decorators + cookbook examples

Summary

• New @rllm.rollout decorator — turns any plain function into an AgentFlow-compatible object. Supports sync and async functions, and automatically coerces return values (str, dict, list[Trajectory], or Episode) into a proper Episode.
• New @rllm.evaluator decorator — turns a scoring function into an Evaluator-compatible object. Accepts float, bool, (float, bool) tuples, or EvalOutput returns.
• Top-level exports — both decorators are accessible as rllm.rollout and rllm.evaluator via lazy imports in rllm/__init__.py.
• Comprehensive tests — 406-line test suite covering bare/parameterized decorator syntax, return-value coercion, async support, protocol conformance, and edge cases.
• Two new cookbooks:
  • cookbooks/geo3k/ — geometry QA agent with VLM support, showing eval + train end-to-end.
  • cookbooks/solver_judge_flow/ — multi-agent solver-judge pattern with separate reasoning and judging trajectories.
• README rewrite — streamlined with a focus on the new decorator-based API, quickstart code snippets, and simplified installation instructions.

Motivation

The existing AgentFlow / Evaluator protocol requires users to define classes with specific method signatures. The new decorators reduce boilerplate to a single @rllm.rollout or @rllm.evaluator annotation on a plain function, making it significantly easier to get started with rLLM for both eval and training.

Files changed

File	Change
rllm/__init__.py	Add lazy imports for rollout and evaluator
rllm/experimental/eval/rollout_decorator.py	New — AgentFlowFn, EvaluatorFn, coercion helpers, @rollout and @evaluator decorators
tests/eval/test_rollout_decorator.py	New — full test coverage for both decorators
cookbooks/geo3k/	New — geometry VLM agent cookbook (flow, evaluator, train script, README)
cookbooks/solver_judge_flow/	New — multi-agent solver-judge cookbook (flow, evaluator, train script, README)
README.md	Rewritten with decorator-first quickstart and updated links

Test plan

• pytest tests/eval/test_rollout_decorator.py passes
• rllm eval gsm8k still works (no regression from __init__.py changes)
• Cookbook examples run with python test.py in each cookbook directory