From reaction records to a dataset

Build and validate with Python

The toolkit uses the same schema and validator as the platform. It provides constructors for materials, charges, segments and measurements, JSON/JSONL reading and writing, and upload CSV preparation. It runs independently without a database.

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

The example prepares complete records, an upload table and request file for local review. Then use the MCP client below to upload a draft and inspect the receipt; use complete CSV transfer for larger files.

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

A complete machine submission

This two-stage one-pot record illustrates the format, not a real experiment. Use a private draft for testing. For real contributions, replace the reaction, authors, source and license and verify the extracted facts.

1. Generate the reaction record

   One JSON object represents one experiment. Multiple experiments can be saved as JSONL, one object per line. Ordinary and multi-stage reactions use the same format.

   View the complete reaction 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. Validate and prepare the upload

   After connecting MCP, read the contract and validate with validate_reaction_records. Serialize each Reaction as a reaction_record string for upload. This is a file column, not a field inside the reaction.

   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)}]

   Supply dataset metadata once: title, description, authors, source and license. The download contains complete metadata and reaction rows, ready for the request argument of upload_records.

   View example metadata

   {
     "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."
   }

   Download complete upload request

3. Upload and inspect the draft

   This example uses the small-file tool with a 1 MiB row-data limit. The receipt returns the file ID and dataset link. Query the parse report with the returned file_id, wait for final counts, then inspect the reactions on the website.

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

   For larger data, use start_upload and complete CSV transfer, or batches within one upload session. Multiple files can be appended to the same draft version. Transfer methods and credentials

4. Review, then submit

   Upload creates a private draft. Once files, authors and license have been checked, submit it from the dataset page or authorize the MCP client to call submit_dataset_for_review. Publication follows approval.

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