导出与使用数据集¶
ChemWorld 的数据集不是一堆运行日志，而是一组可以追溯、回放和验证的交互记录。每条记录把 Action、 公开观测、任务合同、Agent 行为摘要和 replay metadata 绑定在一起，可用于离线分析、world-model 训练、教学回放与论文 artifact。
怎么选格式
人工检查和回放优先使用 JSONL；批量统计、表格分析或离线训练优先使用 Parquet。
数据集中有哪些对象¶
| 对象 | 用途 |
|---|---|
| trajectory JSONL | 每一步 action、三层 outcome、termination、contract hash 和 replay metadata |
| agent view | 每一步公开给 agent 的 rl_vector、tool_json 和 lab_report 视图 |
| agent trace | agent 的 prompt 摘要、selected action、validator result、observation summary、memory note 和 hypothesis note |
| dataset export | 把 trajectory 转成 JSONL copy 或 Parquet/表格友好的 flattened records |
| dataset card | 记录 task、seeds、world law version、env version、hash、privacy status 和 replay verification |
三层结果字段¶
Trajectory v0.2 不再把物理结果、Agent 反馈和正式评价混称为 outcome：
| 字段 | 含义 |
|---|---|
environment_outcome |
世界/运行时实际产生的 observation、事务、状态摘要、仪器和资源后果 |
agent_visible_observation |
当前反馈条件真正释放给 Agent 的 observation、标准视图与 observed reward |
evaluation_outcome |
真实 online reward、final score、reward source 与 scoring contract 绑定 |
反馈延迟、删除或置换实验只能修改 agent_visible_observation；另外两层必须保持与同一 world seed、动作和
真实执行配对。observation、reward、agent_view、leaderboard_score 和 benchmark_task_id 暂时作为
v0.1 兼容别名保留。
v0.2 中 task_id 是稳定 Task Contract 标识，run_id 是带执行上下文的运行标识；campaign_id 对应
一个 Agent 在一个 Task × Scenario × Seed 上的研究运行。读取历史 v0.1 数据时，稳定任务名仍从
benchmark_task_id 获取。
导出一份数据集¶
chemworld datasets export \
--submission runs/example_submission/trajectories/tool_stub.jsonl \
--format jsonl \
--output runs/example_dataset.jsonl
chemworld datasets export \
--submission runs/example_submission/trajectories/tool_stub.jsonl \
--format parquet \
--output runs/example_dataset.parquet
chemworld datasets card --dataset runs/example_dataset.jsonl
Parquet 导出需要本地安装 pyarrow 或 fastparquet。如果只需要审阅和回放，JSONL 足够；如果要做批量统计、offline model 训练或表格分析，优先使用 Parquet。
Agent Trace 记录了什么¶
trajectory 原始记录保留完整 agent_trace 列表。flattened dataset 额外提供这些列，便于表格分析：
| 字段 | 含义 |
|---|---|
agent_trace_step_count |
当前记录中累计的 agent trace 条数 |
agent_trace_prompt_summary |
最新一步 prompt/public context 摘要 |
agent_trace_selected_action |
最新一步 agent 选择的 action |
agent_trace_validation_result |
validator、constraint flag、precondition 和错误信息摘要 |
agent_trace_observation_summary |
最新一步 public observation/reward/leaderboard 摘要 |
agent_trace_reasoning_summary |
agent 自述的简短策略理由，不保存完整 chain-of-thought |
agent_trace_hypothesis_note |
agent 当前机制假设或下一轮解释线索 |
agent_trace_memory_note |
agent 从历史 public observation 形成的短记忆 |
这些字段只来自 public observation、task prompt、validator result 和 agent 自己的公开行为摘要，不允许读取 hidden ledgers、rate constants、private scenario 参数或 debug truth。
示例¶
运行：
python examples/demo_dataset_agent_trace_export.py
该示例会：
- 使用
ToolUsingLLMStubAgent跑通reaction-to-assay； - 写出 trajectory JSONL；
- 导出 dataset JSONL；
- 如果本地有 Parquet backend，则导出 Parquet；
- 打印最终 lab report 和 agent trace 摘要字段。
用 Dataset Card 说明来源¶
dataset_card() 会扫描数据集并输出：
- task ids、seeds、env version、world law version；
- task/runtime/mechanism/scoring/observation contract hash；
- replay verification summary；
- agent manifest summary；
- privacy/anonymization status；
- known limitations。
公开发布数据集前，应检查 dataset card 中的 privacy 字段，尤其是 human pilot trajectory、explanation 文本和 agent metadata。
发布前检查¶
- 每条 trajectory 必须通过 schema validation。
- 新生成数据应使用
chemworld-trajectory-0.3；旧 trajectory 只按兼容策略读取，不应写成当前格式。 - 每个公开 dataset 应能追溯到 task id、scenario id、mechanism hash、seed、commit hash 和生成命令。
agent_view与agent_trace必须是 public-facing；不能泄露 hidden species id、hidden amounts、rate constants 或 private-eval 参数。- replay verification 不通过的数据集不能作为 benchmark artifact 发布。