1. Overview: Primitives → EML → Rendered Experiment
CogGym separates experiment construction into three stages. Researchers describe the design with compact primitives, a Python compiler materializes those inputs as EML, and the CogGym renderer executes that EML as a participant-facing experiment.
1.1. The Complete Pipeline
Primitives are authoring inputs. EML is the static execution contract. The rendered experiment is the participant-facing result.
| Stage | Purpose | Primary artifacts |
|---|---|---|
| Primitives | Express experiment-design intent concisely. | Assets and their metadata, query definitions, primitive model cards, trial-generation rules, conditions, blocks, and sequencing intent. |
| EML | Provide a concrete, portable execution contract. | config.json, trial.jsonl, instruction.jsonl, and referenced assets. Every trial and sequence is explicit. |
| Rendered experiment | Execute the materialized experiment and collect responses. | Instruction screens, stimulus/query trials, optional trial feedback, and response records. |
1.2. Documentation Structure
The rest of the documentation follows the two arrows in the pipeline. Runtime behavior and authoring behavior are documented separately.
| Continue with | Use it to understand | Does not cover |
|---|---|---|
| 2. EML → Rendering | The original EML package, how the renderer resolves it, and the field-level config, trial, and instruction schemas. | Primitive definitions, model cards, compiler inputs, or generation logic. |
| 3. Generating EML from Primitives | Asset and query inputs, primitive model cards, trial expansion, experimental design, sequencing, and Python compilation. | Renderer implementation or participant-screen behavior beyond the EML contract. |
The boundary is deliberate: the compiler may use Python to express rich design logic, but it must resolve that logic into ordinary, static EML before rendering begins.