Study Structure Example

This minimal example shows how to encode one hypothesis, one manipulated factor, replication control, one agent binding, one problem binding, and one output location.

YAML Example

study_id: prompt-framing-minimal
title: Prompt framing pilot
description: Minimal study structure example.

hypotheses:
  - hypothesis_id: h1
    statement: Structured framing prompts improve judged idea quality.
    direction: positive
    factor_bindings: [prompt_style]
    outcome_bindings: [quality_score]

factors:
  - name: prompt_style
    kind: manipulated
    levels:
      - name: baseline
        value: baseline
      - name: scaffolded
        value: scaffolded

outcomes:
  - name: quality_score
    kind: continuous
    description: Mean evaluator score per run.

run_budget:
  replicates: 2

agent_specs:
  - DirectLLMCall

problem_ids:
  - ideation_peanut_shelling_fu_cagan_kotovsky_2010

output_dir: artifacts/prompt-framing-minimal

Python Example

from design_research_experiments import Study, build_design, validate_study

study = Study.from_dict(
    {
        "study_id": "prompt-framing-minimal",
        "title": "Prompt framing pilot",
        "description": "Minimal study structure example.",
        "hypotheses": [
            {
                "hypothesis_id": "h1",
                "statement": "Structured framing prompts improve judged idea quality.",
                "direction": "positive",
                "factor_bindings": ["prompt_style"],
                "outcome_bindings": ["quality_score"],
            }
        ],
        "factors": [
            {
                "name": "prompt_style",
                "kind": "manipulated",
                "levels": [
                    {"name": "baseline", "value": "baseline"},
                    {"name": "scaffolded", "value": "scaffolded"},
                ],
            }
        ],
        "outcomes": [
            {
                "name": "quality_score",
                "kind": "continuous",
                "description": "Mean evaluator score per run.",
            }
        ],
        "run_budget": {"replicates": 2},
        "agent_specs": ["DirectLLMCall"],
        "problem_ids": ["ideation_peanut_shelling_fu_cagan_kotovsky_2010"],
        "output_dir": "artifacts/prompt-framing-minimal",
    }
)

errors = validate_study(study)
if errors:
    raise RuntimeError("\n".join(errors))

conditions = build_design(study)
print(study.study_id, len(conditions))

Why This Matters

The same study object controls admissibility, replication, and artifact output contracts. That is the core reason this package is the orchestration “hat” over agents, problems, and analysis.