Social Simulation

01 Orientation

Many experiments ask isolated people to answer the same question. Social simulation asks something different: what happens when agents act, react, reveal information, bargain, coordinate, or disagree inside a shared situation?

OneHeart is the study-definition and code-generation layer for that work. It stores the design as durable project state, validates it, and generates an inspectable pilot runner. Concordia supplies the simulation machinery; Expected Parrot EDSL supplies model access and post-run measurement.

02 The study model

A study becomes runnable when four pieces agree with one another.

03 Design before code

Begin with a causal contrast small enough to inspect. A good first pilot usually has two to four agents, one treatment, one primary outcome, and a short interaction.

A worked question

This tutorial uses a hiring interview: does an opening compliment increase the interviewer’s hiring rating? The candidate receives either a compliment or neutral-opening instruction; the interviewer and the rest of the setting remain fixed.

04 Create the project and interaction

oneheart init compliment_interview --title "Compliment Interview Pilot"
cd compliment_interview

oneheart study create compliment_effect \
  --title "Opening compliment effect" \
  --description "Candidate opens a job interview with or without a compliment."

oneheart study set-interaction compliment_effect \
  --premise "A final-round interview for a B2B marketing manager role." \
  --protocol ordered_dialogue \
  --max-turns 8 \
  --game-master dialogic

The premise describes common ground. It should contain what remains constant across conditions, not treatment-specific language. OneHeart supports ordered, random, and game-master-selected dialogue protocols.

05 Give agents goals and information

A name is not a social actor. Each focal agent needs a role, a goal, and enough context to behave distinctly. Keep public facts separate from information that only one agent should know.

oneheart agent add compliment_effect candidate \
  --name "Alex Rivera" --role candidate \
  --goal "Demonstrate fit and earn a strong hiring recommendation." \
  --prefab conversational \
  --public-bio "Five years of B2B SaaS marketing experience." \
  --private-context "Especially strong in demand generation and product marketing."

oneheart agent add compliment_effect interviewer \
  --name "Jordan Ellis" --role interviewer \
  --goal "Assess fundamentals, results, and communication fairly." \
  --prefab conversational

Use conversational for dialogue, basic when reflection and associative memory matter outside dialogue, and minimal for cheaper sweeps where richness is secondary.

oneheart agent attribute-set compliment_effect interviewer \
  evaluation_style=evidence-focused

06 Make treatments behavioral

Treatment level names are labels, not instructions. A model does not reliably infer the intended behavior from opening_compliment=compliment. Define the factor, then attach an explicit stage direction to every level.

oneheart treatment add compliment_effect opening_compliment \
  --scope agent --target candidate --type binary \
  --levels compliment,no_compliment --private

oneheart treatment level-set compliment_effect opening_compliment compliment \
  --instruction "Open with one sincere, specific compliment about the company or interviewer's work before answering. Do not compliment again."

oneheart treatment level-set compliment_effect opening_compliment no_compliment \
  --instruction "Open with a brief neutral professional greeting. Do not compliment the interviewer at any point."

Agent-scoped instructions enter the target agent’s resolved prompt. Study- or environment-scoped instructions enter the resolved premise. Visibility should reflect the design: a private instruction is not automatically shared with the other participants.

07 Define observable measurements

Measurements are extraction questions asked after the simulation. Make each prompt answerable from the transcript or simulation context, name the evaluator, and choose a response type that matches the construct.

oneheart measurement add compliment_effect hiring_rating \
  --kind outcome --response-type numeric --agent interviewer \
  --prompt "On a 1–7 scale, how strongly would you recommend hiring the candidate?"

oneheart measurement add compliment_effect would_hire \
  --kind outcome --response-type boolean --agent interviewer \
  --prompt "Would you hire the candidate? Answer yes or no."

oneheart measurement add compliment_effect noticed_compliment \
  --kind process --response-type boolean --agent interviewer \
  --prompt "Did the candidate compliment you during the interview? Answer yes or no."

08 Validate design and environment

Structural validation and runtime validation answer different questions. Run both before generation.

oneheart status
oneheart validate compliment_effect
oneheart doctor
oneheart validate compliment_effect --check-env

Generated runners expect the Expected Parrot Concordia fork with EDSL support. If Concordia exists only as a checkout, the runner accepts --concordia-src /path/to/concordia.

09 Generate, then inspect

oneheart codegen pilot compliment_effect

Read prompts.md before spending model calls. Confirm that the resolved premise is correct, every agent receives the intended context, every treatment has a level-specific instruction, and every measurement is unambiguous.

10 Execute the pilot explicitly

python oneheart_jobs/compliment_effect/run_pilot.py --confirm-prompts

For repeat runs of the same generation, create the acknowledgement file once and run without the flag:

touch oneheart_jobs/compliment_effect/prompts.acknowledged
python oneheart_jobs/compliment_effect/run_pilot.py

The runner performs a model preflight, builds Concordia entities and the game master, runs the simulation, writes logs and transcripts, and uses EDSL to extract the configured measurements.

11 Record provenance and export evidence

A generated directory is working code; a run record connects what was generated to what actually ran. Preserve the generation ID returned by codegen and record seed and model metadata.

oneheart run record compliment_effect \
  --type pilot \
  --generated <generation_id> \
  --outputs oneheart_jobs/compliment_effect/outputs/pilot_summary.json \
  --seed 42 \
  --model gpt-5.4

oneheart export outcomes --output .oneheart/exports/outcomes.csv

oneheart export chat-html \
  oneheart_jobs/compliment_effect/outputs/simulation_log.json \
  --output writeup/compliment-chat.html

Keep both forms of evidence: the transcript shows whether the social process was credible, while the outcome table supports comparisons across recorded runs.

12 From one pilot to a comparison

A treatment is a design object, but a generated pilot resolves one condition. Generate and run each arm deliberately, keeping the agents, setting, measurements, model policy, and analysis constant.

# For a two-level treatment, "first" selects the first declared level;
# "midpoint" selects the second. Separate output directories avoid overwrites.
oneheart codegen pilot compliment_effect --selector first \
  --output-dir oneheart_jobs/compliment_arm
oneheart codegen pilot compliment_effect --selector midpoint \
  --output-dir oneheart_jobs/no_compliment_arm

1. Generate the compliment condition and inspect its resolved prompt.
2. Generate the neutral condition and verify that only the intended instruction changes.
3. Run multiple seeds within each arm; one run per arm cannot estimate variation.
4. Record every run and export a single outcome table.
5. Inspect manipulation checks and transcript excerpts before estimating treatment differences.

13 Interpret without overclaiming

Simulation results characterize a configured model world. They do not automatically estimate how real people would behave. Interpretation should separate implementation validity, within-simulation evidence, and external validity.

14 Command reference and recovery

# The recovery loop for humans and coding agents:
oneheart status
oneheart docs show workflow
oneheart docs show study-design
oneheart docs show codegen

Prefer CLI mutations to hand-editing files under .oneheart/studies/. If a generated runner needs study-specific refinement, edit the working copy under oneheart_jobs/; leave the immutable provenance snapshot intact.