Glossary

Every term the Reef documentation depends on, defined once. The five concepts a user of the endpoint needs come first, in the order the design page explains them. The rest is the vocabulary the reference pages build on.

Scenario#

One isolated learning lane. A scenario groups the records, the training state, and the version chain for one workload, so two workloads can never share data or updates. The first request creates it, binds its recipe (and optionally a starting artifact version), and those bindings never change. Named by the x-reef-scenario header on every request.

Receipt#

The user-facing handle for a stored record: the x-reef-agent-record-id header on every inference response. It points at the stored record (AgentRecord in the scenario's RecordStore) of that exact exchange, including which artifact version was serving when the answer was produced. The same identifier is exposed as agent_record_id in JSON payloads. Feedback quotes receipts, so every report lands on precisely the answers it judged.

Report#

A message to POST /reef/report carrying feedback about one or more exchanges, named by the receipts in its references. Reef pins the feedback to those exact exchanges and consumes each report only once, even if it arrives late or is retried.

Feedback#

What a report carries: an optional numeric score, and a feedback field that Reef's core does not interpret. That field holds a plain string or a structured object, such as a rubric breakdown, judge output, or whatever the recipe reading it cares about. A numeric score is the common case, though feedback can be something else entirely.

Recipe#

The scenario's learning configuration: how records and their feedback become a new version (of the weights or the harness). Concretely, a recipe binds the processor that pairs records into batches, the algorithm that trains on a batch, the runtime that executes model work, the surface that delivers the result, and the checkpoint cadence. The base recipe kind records the complete data flow and never changes anything.

Recipe kind#

A registered recipe name, resolvable from the x-reef-recipe header or a YAML config. The kind table in reef.recipes.registry decides what resolves: built-ins register with register_kind(), and a kind may also be a dotted reference package.module:ClassName to a recipe class Reef does not bundle. One placeholder kind, currently ace, is registered and can be found by name, but you cannot build it yet. See recipes.

Loss family#

The backend objective a training recipe declares (loss_family) for backend boot configuration. It is a separate thing from the recipe's step_preparer name, so different data-side signals can reuse the same tensor loss. The openclawrl recipe, for example, prepares its own reward-as-advantage signal on the shared pg family. The bundled families are sft, pg, sao, opd, tttd, and openclawrl-topk. An unbundled family registers its spec with register_loss_family or is named as a dotted package.module:SPEC reference.

Preparer#

The step-preparation function that turns a reserved batch into a StepSignal, meaning the loss family, the advantages, and the next algorithm state. The computation is the same no matter which backend executes it. A training recipe selects its preparer through the step_preparer class variable: either a registered name ("sao") or a dotted "module:callable" path. Preparers are registered by name, and a backend that needs its own dependencies for one preparer registers it from its own package (Slime's torch-backed tttd advantage math, for example). Writing a custom recipe means writing a recipe class plus one preparer, and a pairing spec too when no shipped processor fits. The define a recipe guide walks the complete path.

Version chain#

The per-scenario history of every accepted update. Each update is a version with a parent, durable versions are Git-backed checkpoints, any version can be pinned (x-reef-artifact-version) or rolled back to, and every receipt records the version that served its answer.

Artifact#

The versioned thing itself: a weights checkpoint or a tree of text files (skills, harness trees). An ArtifactRef names one exact version. A live weight artifact serves from engine memory between checkpoints, while a durable one has Git-backed bytes. See artifacts.

Surface#

An evolution surface (EvolutionSurface): how a published artifact version reaches its consumer. The same surface object runs on the request path (transform the request, verify the response against the frozen version) and on the commit/rollback path (validate before staging, restore a rollback target). WeightSurface syncs weights into the serving engine; HarnessSurface serves a harness tree by client pull. See surfaces.

Harness#

Two meanings, and the docs use both:

1. Your harness is the agent program around the model: prompts, conversations, tools, environments, and grading. It lives outside Reef, and Reef never owns it.
2. The harness tree is Reef's deliverable, a versioned artifact of text layers (skills/, config/, tools/, context/) that HarnessSurface serves over GET /reef/harness for the client to pull and apply. When Reef "trains the harness", this artifact is what a new version changes.

Runtime#

Two meanings:

1. The request-plane contract, InferenceRuntime and TrainingRuntime (reef/runtime), is the external service that executes model work. Inference is always required. GPU training is needed only for recipes that update weights. See runtimes.
2. Training backend integrations are the concrete stacks that implement the training side: Reef's Slime training runtime, or frameworks such as veRL and AReaL shipping the same bridge.

Skill#

A text instruction file (SKILL.md) the LLM reads, forming the skills/ layer of a harness tree. A skill can be injected server-side into each request or client-pulled with the rest of the tree, and skill evolution (propose → pairwise gate → publish → rollback) updates it with no GPU at all.

OpenClaw-RL#

One of the bundled recipes (arXiv:2603.10165), recipe kind openclawrl: an unmodified agent learns from live conversation traffic with a next-state binary reward. Everything it needs sits inside the recipe. Its processor rebuilds sessions from recorded traffic by trace matching and judges each turn on a private PRM worker, with no external grader and no session headers.

SAO#

Single-Rollout Asynchronous Optimization (arXiv:2607.07508), recipe kind sao: one graded rollout drives one training step, with no comparison group or slowest-sample barrier.

TTT-Discover#

Test-time-training discover, abbreviated TTTD (arXiv:2601.16175), recipe kind tttd: a model specializes to one hard problem during the search itself. The search loop stays in your harness, and the recipe handles the grouped training step.

ACE#

Agentic Context Engineering (arXiv:2510.04618), recipe kind ace, registered but not yet functional (#176): a Reflector/Curator proposer distills failed traces into incremental SKILL.md edits, published only when they win the pairwise gate.

ReasoningBank#

Memory evolve (arXiv:2509.25140), in progress (#177). It distills reasoning strategies from both successful and failed trajectories into retrievable memory items, and each write is a proposal on the version chain.

OPD#

On-policy distillation, the subject of the continual OPD RFC. Reef does not bundle it as a recipe. A student policy trains against a frozen teacher's logits. The backend's built-in opd loss family remains backend plumbing, and the cookbook recipe that demonstrated it was removed from the tree (examples/opd in git history).