Inference runs a trained property-prediction model on your molecules. There are four model families: MPNN (message-passing neural networks, Chemprop-style; model_type: "mpnn"), QSAR (classical models on fingerprints and descriptors, chosen by cross-validation from a panel; model_type: "qsar"), physics-hybrid (a Joback or Hansen group-contribution estimate plus a correction learned from your measurements; model_type: "thermo_hybrid") and mixture (a property of a solute in a solvent, or of one molecule, across temperatures and other conditions; model_type: "thermo_mixture"). QSAR, physics-hybrid and mixture predictions, and those of recently trained MPNN models, also return a 90% interval and whether each input is like the training data. MPNN and QSAR models can also return a signed value per atom showing which atoms raise or lower the prediction (return_contributions). A mixture request takes solutes, solvents and condition values (for example a temperature grid) and predicts every combination. Reaction models (model_type: "reaction_mpnn") predict a property of atom-mapped reactions, such as a yield, from the reaction and its conditions; send input_format: "reaction_smiles" and the model's condition components. You can use:
- Public models that CogniChem provides: list them with List public models (filter with
model_type=mpnn). - Your own models, trained on your data with the MPNN Models (
train-mpnn), QSAR Models (train-qsar), Reaction Models (train-reaction-mpnn) or Thermo Property Models (train-thermo-hybrid,train-thermo-mixture) training jobs: list them with List your saved models. Each plan allows a set number of custom models; see Plans and limits. The guide Train an MPNN model walks through both steps.
Like utilities, inference is not charged to your wallet. Each molecule counts toward your plan's monthly inference allowance, and at the limit submits return 403.
Run a prediction
Submit an inference request with model_type, model_name, and a payload (set is_public_model to true for a public model; leave it false for one you trained), then poll Get inference status and read Get an inference result. Submit a batch of inference requests sends several requests at once.
from cognichem_client import CogniChem
client = CogniChem.from_env()
print(client.inference.models.mpnn.public()) # pick a model_name
result = client.inference.run(
"mpnn",
"MODEL_NAME",
{"input_data": ["CCO", "c1ccccc1O"], "input_format": "smiles", "is_public_model": True},
)
print(result.data)Payload
mpnn Property prediction with a trained MPNN (Chemprop-style) model: a public model or one you trained with the train-mpnn job. predictions has one value per molecule: the value (regression; the first target of a multi-target model, with every target in predictions_by_target), P(class 1) for binary models (labels at 0.5), or the predicted class's probability for multiclass (labels, and probabilities in output_spec.classes order). output_spec.task says which. Where the model has them (#908 Phase 3): uncertainty (an ensemble's member spread), intervals (90% conformal prediction interval of a regression model; intervals_by_target for several targets), ad_similarity (max Tanimoto similarity to the training set) and in_domain (inside the model's calibrated applicability domain). With return_contributions (#908 Phase 4): atom_contributions, one signed value per atom in input atom order (positive atoms raise the prediction, negative atoms lower it; Integrated Gradients through the whole model, ensembles averaged), attribution_base (a molecule's values add up to its prediction minus this baseline), attribution_method, and atom_contributions_by_target / attribution_base_by_target for several targets.
| Field | Type | Description |
|---|---|---|
input_data[]required | string[] | Limits: |
input_formatrequired | string | One of: |
is_public_model | boolean | True for a public model name from list_inference_models; false for your own trained model. Default: |
return_contributions | boolean | Return signed per-atom contributions to each prediction (larger, slower result). At most 100 molecules per request. Default: |
return_coordinates | boolean | Return atom coordinates (larger result). Default: |
generate_3d | boolean | Embed 3D coordinates during preprocessing. Defaults to the model's training-time setting. |
add_hydrogens | boolean | Add explicit hydrogens. Defaults to the model's training-time setting; a different value is rejected. |
remove_hydrogens | boolean | Remove explicit hydrogens. Defaults to the model's training-time setting; a different value is rejected. |
batch_size | integer | Default: |
qsar Property prediction with a classical QSAR model you trained with the train-qsar job: the value (regression) or the probability of class 1 (binary), a 90% conformal interval or standard deviation where the model has one, the nearest-neighbour Tanimoto similarity to the training set, and optional signed per-atom attributions.
| Field | Type | Description |
|---|---|---|
input_data[]required | string[] | Limits: |
input_formatrequired | string | Format of every input_data entry. One of: |
is_public_model | boolean | Predict with a public model of this name instead of one you trained. Default: |
return_contributions | boolean | Return signed per-atom attributions (models with linear, random forest or LightGBM winners and Morgan features); atom order follows the input structure. Default: |
reaction_mpnn Reaction property prediction (yield, selectivity, barrier or rate constant) with a reaction model you trained with the train-reaction-mpnn job. input_data holds atom-mapped reaction SMILES (map them with reaction-map); a model trained with condition components (ligand, base, solvent, ...) also needs components with one SMILES per reaction under the same names. predictions has one value per reaction: the value (regression, clipped to the model's target_bounds; the first target of a multi-target model, with every target in predictions_by_target), P(class 1) for binary models (labels at 0.5), or the predicted class's probability for multiclass (labels, and probabilities in output_spec.classes order). Where the model has them: uncertainty (an ensemble's member spread), intervals (90% conformal prediction interval of a regression model), ad_similarity (max Tanimoto similarity of the reaction-plus-components fingerprint to the training set) and in_domain (inside the model's calibrated applicability domain).
| Field | Type | Description |
|---|---|---|
input_data[]required | string[] | Atom-mapped reaction SMILES (reactants>reagents>products), one per prediction. Limits: |
input_formatrequired | string | Format of every input_data entry. One of: |
components | map<string, string[]> | Condition molecules: component name to one SMILES per reaction ('' where the reaction has none). Required when the model was trained with components; the names must match the model's. |
is_public_model | boolean | True for a public model name from list_inference_models; false for your own trained model. Default: |
batch_size | integer | Default: |
thermo_hybrid Property prediction with a physics-hybrid model you trained with the train-thermo-hybrid job: for each corrected property, the group-contribution estimate (Joback or Stefanis-Panayiotou), the learned correction, their sum in the model's unit with a 90% conformal interval, and whether the molecule is in the applicability domain. Outside the domain the estimate is returned and flagged unless fallback is none.
| Field | Type | Description |
|---|---|---|
input_data[]required | string[] | Limits: |
input_formatrequired | string | Format of every structure entry. One of: |
is_public_model | boolean | Predict with a public model of this name instead of one you trained. Default: |
fallback | string | Override the model's fallback: baseline returns the physics estimate outside the applicability domain (flagged); none returns the hybrid prediction everywhere. One of: |
thermo_mixture Solution and mixture property prediction with a model you trained with the train-thermo-mixture job: every solute (input_data) with every solvent (or row by row), at every combination of the condition values (e.g. a temperature grid), so one request gives a solvent screen or a property-versus-temperature curve. Each prediction carries its unit, a 90% conformal interval, and whether the solute is similar to training, the solvent was seen in training and the conditions lie in the training range.
| Field | Type | Description |
|---|---|---|
input_data[]required | string[] | Solutes (the first component). Limits: |
input_formatrequired | string | Format of every structure entry. One of: |
solvents[] | string[] | Solvents (the second component), in input_format; required for two-component models. Limits: |
pairing | string | grid: every solute with every solvent; rows: the i-th solute with the i-th solvent (equal lengths). Default: |
conditions | object | Values for each condition the model was trained with, keyed by quantity, each in any unit of that quantity; predictions cover every combination. |
conditions.temperature | object | |
conditions.temperature.values[]required | number[] | Limits: |
conditions.temperature.unitrequired | string | One of: |
conditions.pressure | object | |
conditions.pressure.values[]required | number[] | Limits: |
conditions.pressure.unitrequired | string | One of: |
conditions.mole_fraction | object | |
conditions.mole_fraction.values[]required | number[] | Limits: |
conditions.mole_fraction.unitrequired | string | One of: |
is_public_model | boolean | Predict with a public model of this name instead of one you trained. Default: |