oneheart — Concordia-backed multi-agent social simulation CLI

oneheart designs, validates, generates, records, and exports Concordia-backed multi-agent social simulations. The agent uses it to help the user define a study, agents, treatments, measurements, generated pilot code, run records, outcome exports, and chat/report artifacts for experiments where agent interactions are themselves the object of analysis.

Documentation: Read the rendered social-simulation tutorial or browse the self-contained HTML source.

Copy and paste into Codex or Claude Code

Install OneHeart from GitHub with
`pip install "git+https://github.com/expectedparrot/oneheart.git"`.
Run `oneheart agent-start`, follow its state-aware checklist, and rerun it after
material changes. Keep `.oneheart/` as the canonical study record. Inspect all
generated prompts and code before execution, and stop for my approval before
any paid remote inference. Never display or commit credentials.

For local development:

python -m pip install -e ".[dev]"
pytest -q

When to use this

• The user wants to simulate social interaction among multiple agents, not just collect independent survey answers.
• The study needs explicit agents, roles, goals, private/public context, treatments, and measurements.
• Concordia-style generated pilot code or simulation logs are expected outputs.
• The user needs validation and recording around generated runs, not just ad hoc scripts.

When this is a stretch (and how to adapt)

• The task is a simple survey or vignette experiment. Use sinclair for survey-building and pilot discipline unless multi-agent interaction is central.
• The user needs personas from interviews. Use saldana first, then add selected personas as oneheart agents.
• The user needs aggregate population calibration. Use manning to calibrate an AgentList, then use relevant agents in oneheart if interactions matter.
• The output is open-ended transcripts. Run oneheart for simulation, then analyze transcripts with bewley or validate with messick.
• The simulation premise is under-specified. Create a small pilot study with clear roles and measurements before generating complex treatments.

Decision rule for the calling agent

Before dispatching to oneheart, confirm:

1. The study requires interaction among two or more agents or between agents and a simulated environment.
2. Agents need roles, goals, context, or traits beyond a single prompt.
3. Treatments or measurements should be tracked as study objects.
4. Generated Concordia code, run recording, or transcript export is part of the workflow.

If yes to the first three, oneheart is the right method.

Inputs and elicitation

Study premise and protocol

What it is: the simulation question, premise, interaction protocol, number of turns, and game-master setup.

How the agent elicits this:

• Ask what social situation is being simulated and what decision or behavior is being observed.
• Ask who interacts with whom, in what setting, and for how many turns.
• Ask whether the protocol is interview, negotiation, collaboration, conflict, deliberation, service encounter, or another interaction type.
• Ask what should stay constant across treatments.

Default to suggest: a short pilot with 2-4 agents, one clear setting, and a small number of turns.

Fallback: if the user cannot specify a protocol, draft a minimal interaction premise and validate it before adding treatments.

Agents

What it is: simulated participants with names/IDs, roles, goals, public bios, private context, attributes, and optional model settings.

How the agent elicits this:

• Ask what roles need to be represented and whether personas come from interviews, theory, or hand-authored scenarios.
• Ask what each agent knows publicly versus privately.
• Ask what goal each agent pursues during the interaction.
• Ask whether agent attributes should vary systematically across treatments.

Default to suggest: start with the minimum agents required for the interaction and give each a concise role, goal, and private context.

Fallback: use saldana for interview-grounded personas or a simple hand-authored prefab for exploratory pilots.

Treatments and measurements

What it is: experimental variations and outcome measures for simulation runs.

How the agent elicits this:

• Ask what changes between conditions: script, context, instruction, environment, agent attribute, or intervention.
• Ask what outcomes should be measured: choice, sentiment, compliance, conflict, agreement, recall, or transcript-coded behavior.
• Ask whether measurement should be automatic, human-coded, or downstream-labeled.

Default to suggest: one treatment contrast and one primary outcome for the first pilot.

Fallback: if outcomes are qualitative, export transcripts and analyze them with bewley or labeling.

Outputs

oneheart produces:

• .oneheart/ project state with studies, agents, attributes, treatments, measurements, generated jobs, runs, and exports.
• Generated Concordia pilot code under an output directory chosen by oneheart codegen pilot.
• Run records with generated path, outputs, model/seed metadata, and run IDs.
• Outcome exports such as CSVs.
• Chat HTML exports from Concordia logs and embedded report artifacts.
• Validation/status output for study readiness.

Workflow

Canonical sequence:

1. oneheart init <path> — initialize a project.
2. oneheart study create ... — define the study and description.
3. oneheart study set-interaction ... — set premise, protocol, turns, and game master.
4. oneheart agent add ... — define participating agents.
5. oneheart agent attribute-set ... — add systematic traits where needed.
6. oneheart treatment add ... — define conditions or interventions.
7. oneheart measurement add ... — define outcomes.
8. oneheart validate — check study readiness and environment if requested.
9. oneheart codegen pilot ... — generate Concordia run code.
10. Run generated code externally as appropriate.
11. oneheart run record ... — record completed runs and outputs.
12. oneheart export outcomes or oneheart export chat-html — create analysis/report artifacts.

Use oneheart status and oneheart doctor to recover project state and environment readiness.

Worked examples

Designing a negotiation pilot

User: "I want to simulate a buyer-seller negotiation with and without a compliment at the start."

Agent: "Oneheart fits because the interaction is the object of study. I’ll create a study with buyer and seller agents, define the negotiation premise, add a compliment treatment, and measure agreement quality or final price. For the pilot, I’d keep it to one treatment contrast and a short turn limit."

User: "Measure whether they reach agreement and tone of the exchange."

Agent: "Agreement can be a direct measurement. Tone may need transcript labeling after export, so I’ll include the measurement and plan a downstream labeling pass if needed."

oneheart init negotiation_study --title "Compliment negotiation pilot"
oneheart study create compliment_effect --title "Compliment effect" --description "Buyer-seller negotiation with opening compliment treatment"
oneheart study set-interaction compliment_effect --premise "A buyer and seller negotiate a service contract" --protocol ordered_dialogue --max-turns 12 --game-master dialogic
oneheart agent add compliment_effect buyer --name "Buyer" --role "buyer" --goal "Reach a fair agreement"
oneheart agent add compliment_effect seller --name "Seller" --role "seller" --goal "Protect margin while maintaining relationship"
oneheart treatment add compliment_effect opening_compliment --scope study --type prompt --levels control,compliment
oneheart measurement add compliment_effect agreement --kind outcome --response-type boolean --agent buyer --prompt "Did the negotiation reach agreement?"
oneheart validate compliment_effect --check-env
oneheart codegen pilot compliment_effect --output-dir oneheart_jobs/compliment_effect

Output: validated study state and generated Concordia pilot code.

Recording and exporting a run

oneheart run record --type pilot --generated oneheart_jobs/compliment_effect --outputs oneheart_jobs/compliment_effect/outputs/results.json --seed 42
oneheart export outcomes --output .oneheart/exports/outcomes.csv
oneheart export chat-html oneheart_jobs/compliment_effect/outputs/log.json --output writeup/negotiation_chat.html

Output: run metadata, outcome CSV, and an HTML chat artifact for review or reporting.

Quick command reference

For full options, run oneheart <subcommand> --help.

Command	Purpose
oneheart init	Initialize a simulation project.
oneheart doctor / status	Check environment and project state.
oneheart validate	Validate study readiness.
oneheart docs ...	Read built-in guidance.
oneheart study ...	Create, configure, show, list, and set default studies.
oneheart agent ...	Add agents and attributes.
oneheart treatment ...	Define treatment variations.
oneheart measurement ...	Define outcomes or observations.
oneheart codegen pilot	Generate Concordia pilot code.
oneheart run record	Record completed generated runs.
oneheart export outcomes	Export outcome data.
oneheart export chat-html	Convert simulation logs to chat HTML.

Common pitfalls

• Complex multi-treatment simulations are hard to debug; pilot one contrast first.
• Agents need goals and private context, not just names, or interactions become generic.
• Generated code is not the durable study record; record runs back into oneheart.
• Transcript-based outcomes need a separate coding/labeling plan.
• Environment validation matters before codegen/run handoff; use doctor and validate --check-env.

Cross-references

• Upstream: saldana creates interview-grounded agents; manning calibrates mixtures for population representation.
• Downstream: bewley and labeling analyze transcripts; messick validates simulation results; gutenberg compiles reports.
• Adjacent methods: sinclair for non-interactive survey studies; voting for preference aggregation from simulated agents.

State contract

.oneheart/ stores project metadata, study specs, agents, treatments, measurements, generated job records, run records, and exports. Generated Concordia directories are inspectable working code; oneheart project state is the durable record that should be updated after runs complete.

JSON output and error codes

oneheart uses structured output unless --human is requested. Common recoverable failures include missing project state, invalid study IDs, incomplete study configuration, missing agents/treatments/measurements, environment check failures, and run-record paths that do not exist.

License

OneHeart is released under the MIT License.