从反应记录到数据集

Python 构建与校验

工具包使用平台同一套规范与校验代码，提供物料、投料、阶段、测量的构建函数，以及 JSON／JSONL 读写和上传 CSV 准备。可独立运行，无需连接数据库。

unzip isynth-python-toolkit.zip -d isynth-toolkit
cd isynth-toolkit
python -m pip install .
cd examples
python build_reaction.py
isynth-validate reactions.jsonl

示例生成完整反应、上传表格和请求文件，供本地核对。随后可使用下方 MCP 客户端上传草稿并查看处理回执；大型文件使用完整 CSV 上传。

material / product / charge / quantity / segment / measurement / reaction
read_reactions / write_reactions / write_upload_csv / prepare_upload

一个完整的机器提交示例

下面的一锅两阶段记录用于说明格式，不代表真实实验。测试使用私有草稿；贡献真实数据时，替换反应内容、作者、来源和许可，并核对提取结果。

1. 生成反应记录

   一个 JSON 对象对应一次实验；多次实验可保存为 JSONL，每行一个对象。普通反应与一锅多步使用相同格式。

   查看完整反应 JSON

   {
     "schema_version": "1.9.0",
     "reaction_identifier": "EXP-0002",
     "materials": [
       {
         "id": "reactant_1",
         "identifiers": [
           {
             "type": "SMILES",
             "value": "C[C@H](O)c1ccccc1"
           }
         ],
         "role": "reactant"
       },
       {
         "id": "reagent_1",
         "identifiers": [
           {
             "type": "SMILES",
             "value": "CC(=O)OC(C)=O"
           }
         ],
         "role": "reagent"
       },
       {
         "id": "solvent_1",
         "identifiers": [
           {
             "type": "SMILES",
             "value": "CC#N"
           }
         ],
         "role": "solvent"
       }
     ],
     "initial_state": {
       "inputs": [
         {
           "material": "reactant_1",
           "amount": {
             "value": 1,
             "unit": "mmol",
             "raw": "1 mmol"
           }
         },
         {
           "material": "solvent_1",
           "amount": {
             "value": 2,
             "unit": "mL",
             "raw": "2 mL"
           }
         }
       ],
       "conditions": {
         "temperature": {
           "value": 0,
           "unit": "°C"
         }
       }
     },
     "segments": [
       {
         "added_materials": [
           {
             "material": "reagent_1",
             "amount": {
               "value": 1,
               "unit": "mmol"
             }
           }
         ],
         "duration": {
           "value": 1,
           "unit": "h"
         },
         "text": "The reagent was added dropwise at 0 °C, and the solution turned yellow. After 1 h, an aliquot was taken for HPLC.",
         "measurements": [
           {
             "subject": "reactant_1",
             "type": "conversion",
             "value": {
               "value": 95,
               "scale": "percent",
               "raw": "95 %"
             },
             "text": "Method: HPLC."
           }
         ]
       },
       {
         "added_materials": [
           {
             "material": "reagent_1",
             "amount": {
               "value": 1,
               "unit": "mmol"
             }
           }
         ],
         "conditions": {
           "temperature": {
             "value": 80,
             "unit": "°C"
           }
         },
         "duration": {
           "value": 3,
           "unit": "h"
         },
         "text": "The same mixture was heated to 80 °C for 3 h."
       }
     ],
     "products": [
       {
         "id": "product_1",
         "identifiers": [
           {
             "type": "SMILES",
             "value": "CC(=O)O[C@H](C)c1ccccc1"
           }
         ]
       }
     ],
     "measurements": [
       {
         "subject": "product_1",
         "type": "yield",
         "value": {
           "value": 80,
           "scale": "percent",
           "raw": "80 %"
         },
         "text": "Method: isolated."
       },
       {
         "subject": "product_1",
         "type": "ee",
         "value": {
           "value": 94,
           "scale": "percent",
           "raw": "94 %"
         },
         "text": "Method: chiral HPLC."
       }
     ],
     "workup": "The reaction mixture was worked up and purified as reported.",
     "provenance": {
       "reference": "Fictional documentation fixture. All quantities and observations illustrate format only; no experiment or source paper is claimed."
     },
     "text": "FORMAT EXAMPLE ONLY. Not a laboratory instruction or a reported experimental result."
   }

2. 校验并准备上传

   连接 MCP 后读取规范，用 validate_reaction_records 校验反应。上传时将每条 Reaction 序列化为一个 reaction_record 字符串；它是文件中的一列，不是反应内部的字段。

   get_identity()
   get_schema()
   get_reaction_contract(view="object")
   validate_reaction_records(records=[reaction])
   
   # Python: preserve the complete nested record in one cell
   rows = [{"reaction_record": json.dumps(reaction, ensure_ascii=False)}]

   数据集信息另行填写一次：标题、说明、作者、来源与许可。下载文件包含完整元信息和反应行，可直接作为 upload_records 的 request。

   查看示例元信息

   {
     "source_system": "isynth-documentation",
     "source_record_id": "structured-format-example:revision-1",
     "source_kind": "manual",
     "source_reference": "https://isynth.ichemdata.com/schemas/reaction-workflow.example.json",
     "acquired_at": "2026-10-08T00:00:00Z",
     "filename": "reaction-example.csv",
     "dataset": {
       "title": "Fictional one-pot reaction — format example",
       "description": "A fictional reaction demonstrating structured submission; not experimental evidence.",
       "license": "CC-BY-4.0",
       "source_type": "lab"
     },
     "column_mapping": {},
     "source_units": {},
     "authors": [
       {
         "author_name": "iSynth documentation example"
       }
     ],
     "attribution_source": "Fictional documentation fixture; replace authors, provenance and license with verified information for real data."
   }

   下载完整上传请求

3. 上传并查看草稿

   此示例使用小文件上传工具，行数据上限为 1 MiB。上传回执返回文件编号和数据集链接；用回执的 file_id 查询解析结果。计数确认完成后，再核对网页中的反应。

   receipt = upload_records(request=complete_request)
   get_parse_report(file_id=receipt["file_id"])
   get_dataset_status(dataset_id=receipt["dataset_id"])

   大型数据使用 start_upload 和完整 CSV 传输，或在同一上传会话内分批传输。多个文件可以追加到同一个草稿版本。 上传方式与凭证配置

4. 核对后提交审核

   上传生成私有草稿。确认所有文件、作者和许可后，在数据集页面提交审核；经授权的 MCP 客户端也可调用 submit_dataset_for_review。通过审核后才发布。

python -m pip install mcp==1.30.0
python isynth_mcp_client.py validate structured-upload.json
python isynth_mcp_client.py upload structured-upload.json
# Replace FILE_ID with the file_id from the receipt
python isynth_mcp_client.py parse-report FILE_ID