tsinghua-fib-lab Hypothesis Management
Manage research hypotheses for AgentSociety experiments. Each hypothesis defines experiment groups (control/treatment) and specifies required agent classes and environment modules.
When to Use
- User says "hypothesis", "research question", "experiment groups", or "control vs treatment"
- Literature search is done and user wants to formulate testable claims
- User needs to define what to compare in a simulation experiment
Do NOT use when:
- No literature search has been done yet (use literature-search first)
- User wants to run an existing experiment (use experiment-config)
Quick Reference
Use the Python interpreter from .env. See CLAUDE.md for setup.
Run commands from the workspace root through .agentsociety/bin/ags.py.
| Action | Command |
|---|---|
| List hypotheses | $PYTHON_PATH .agentsociety/bin/ags.py hypothesis list [--workspace PATH] [--json] |
| Add hypothesis | $PYTHON_PATH .agentsociety/bin/ags.py hypothesis add --description TEXT --rationale TEXT --groups JSON... --agent-classes TYPE... --env-modules TYPE... [--skip-module-validation] [--json] |
| Get hypothesis | $PYTHON_PATH .agentsociety/bin/ags.py hypothesis get --hypothesis-id ID [--json] |
| Delete hypothesis | $PYTHON_PATH .agentsociety/bin/ags.py hypothesis delete --hypothesis-id ID |
| Discover modules if needed | $PYTHON_PATH .agentsociety/bin/ags.py scan-modules list --short |
| Inspect one module | $PYTHON_PATH .agentsociety/bin/ags.py scan-modules info --type agent --name PersonAgent |
Workflow
digraph hypothesis_flow {
rankdir=LR;
node [shape=box, style=filled, fillcolor="#E8F4FD"];
topic [label="read TOPIC.md\nand literature index"];
clarify [label="clarify question\nand comparison goal"];
names [label="agent/env names known?"];
scan [label="scan-modules\noptional helper"];
groups [label="define control\nand treatment groups"];
write [label="write HYPOTHESIS.md\nand SIM_SETTINGS.json"];
sync [label="sync TOPIC.md"];
topic -> clarify -> names;
names -> groups [label="yes"];
names -> scan [label="no"];
scan -> groups;
groups -> write -> sync;
}
Module Selection
Every hypothesis must specify at least one agent class and one environment module. If the exact names are uncertain, use scan-modules to discover or validate them before writing SIM_SETTINGS.json.
Group JSON Format:
{
"name": "treatment",
"group_type": "treatment",
"description": "Agents with high social capital scores",
"agent_selection_criteria": "agents whose social_connections > median"
}
Common Module Combinations:
| Domain | Agent Classes | Environment Modules |
|---|---|---|
| Social simulation | PersonAgent |
SimpleSocialSpace GlobalInformationEnv |
| Economic behavior | LLMDonorAgent |
EconomySpace |
| Game theory | PrisonersDilemmaAgent |
PrisonersDilemmaEnv |
Output Structure
hypothesis_{id}/
HYPOTHESIS.md # Hypothesis description and groups
SIM_SETTINGS.json # Agent and environment module configuration
experiment_1/
EXPERIMENT.md
experiment_2/
EXPERIMENT.md
After adding/modifying/deleting a hypothesis, update TOPIC.md with the hypothesis overview and link.
Common Mistakes
| Mistake | Fix |
|---|---|
Writing SIM_SETTINGS.json with uncertain module names |
Run scan-modules to confirm valid class and module names |
| Omitting agent classes or env modules | Both are required -- hypothesis creation will fail |
| Using invalid module names | Copy exact names from ags.py scan-modules list --short output |
| Forgetting to update TOPIC.md after changes | Always sync TOPIC.md with hypothesis overview |
| Defining only one group | Define at least a control and a treatment group for comparison |
| Not providing rationale | --rationale grounds the hypothesis in literature; do not skip it |
Pipeline Position
Predecessors: literature-search Optional inputs: web-research (supplementary non-academic context) Optional helpers: scan-modules (when module names are unknown or need validation) Successors: experiment-config
Progress Tracking
After adding a hypothesis successfully:
$PYTHON .agentsociety/bin/ags.py research-pipeline update-stage hypothesis completed --metadata '{"hypotheses_count": N}'