PhysicalToM

基于确定性信念追踪的物理心智理论（Physical ToM）故事生成库。

PhysicalToM 是一个用于生成心智理论评测故事的 Python 库，聚焦于物理世界场景（物体移动、房间转移、容器操作）。所有标准答案均通过状态机信念追踪器确定性计算，无需任何人工标注或 LLM 判断。

特性

• 确定性 GT：所有答案来自纯状态机 FullBeliefTracker，而非 LLM 判断
• 12 种问题类型：记忆、现实、一阶信念、二阶信念、行为预测、回溯信念、可答性等
• 5 种故事类型：room_transfer、container、distracted、peek、multi_agent
• 5 种扩展：高阶信念（三/四阶）、信念变体（内容/序列/身份）、道德伦理、对话 ToM、假装游戏
• 思维链（CoT）：从追踪器历史自动生成推理链，无需人工标注
• 输出适配器：支持转换为 BigToM、FANToM、HiToM、SimpleToM、ToMBench 格式

安装

pip install -r requirements.txt
pip install -e .

快速开始

from physical_tom.pipeline.pipeline import generate_story

result = generate_story(
    story_type="room_transfer",
    num_people=2,
    difficulty="easy",
    seed=42,
)

print(result["story_text"])
for q in result["questions"]:
    print(q["question"], "→", q["GT"])

或直接运行示例：

python examples/quickstart.py

包结构

physical_tom/
├── core/
│   ├── belief_tracker.py       # FullBeliefTracker — 7 个原子动作，一/二阶信念追踪
│   ├── question_generator.py   # 12 种问题类型生成器
│   ├── cot_generator.py        # 从追踪器历史自动生成 CoT 推理链
│   └── distractor_generator.py # 高质量 MCQ 干扰项生成
├── extensions/
│   ├── high_order.py           # 三/四阶信念追踪扩展
│   ├── belief_variants.py      # 内容 / 序列 / 身份 false belief 扩展
│   ├── moral_ethics.py         # 道德伦理场景扩展
│   ├── dialogue_tom.py         # 对话格式信息不对称扩展
│   └── pretend_play.py         # 假装游戏场景扩展
└── pipeline/
    ├── pipeline.py             # generate_story() — 统一生成入口
    ├── story_context.py        # 上下文池（人物 / 房间 / 物体）
    ├── story_infiller.py       # 结构化脚本 → 自然语言故事
    └── output_adapter.py       # 多数据集格式适配器

API 参考

generate_story()

from physical_tom.pipeline.pipeline import generate_story

result = generate_story(
    story_type="room_transfer",   # room_transfer | container | distracted | peek | multi_agent
    extensions=None,              # ["high_order", "belief_variants", "moral_ethics", "dialogue_tom", "pretend_play"]
    num_people=2,
    max_order=2,                  # 2 / 3 / 4（需搭配 "high_order" 扩展）
    difficulty="medium",          # easy | medium | hard
    context=None,                 # 自定义上下文字典（覆盖 StoryContextGenerator）
    llm_client=None,              # 可选 LLM 客户端（用于 NL 实例化）
    seed=None,
)

返回值：

{
    "story_text": str,
    "questions": [{"question_type": str, "question": str, "GT": ..., "distractors": [...], "CoT": str}],
    "GT_answers": {"question_type": answer, ...},
    "CoT": {"question_type": cot_text, ...},
    "metadata": {"story_type": str, "people": [...], "rooms": [...], "objects": [...], ...},
}

FullBeliefTracker

from physical_tom.core.belief_tracker import FullBeliefTracker

tracker = FullBeliefTracker(
    people=["Alice", "Bob"],
    rooms=["kitchen", "bedroom"],
    objects=["ball"],
    initial_locations={"ball": "table"},
)

tracker.enter_room("Alice", "kitchen")
tracker.enter_room("Bob", "kitchen")
tracker.move_object("Alice", "ball", "table", "shelf")
tracker.leave_room("Bob", "kitchen")
tracker.move_object("Alice", "ball", "shelf", "drawer")

print(tracker.get_first_order_belief("Bob", "ball"))   # → "shelf"（错误信念）
print(tracker.world_state.object_locations["ball"])    # → "drawer"（真实位置）