chemetrian

Official Python SDK for the Chemetrian API. Drive Bayesian Optimization (and future services) with pandas DataFrames and one API key.

Install

pip install chemetrian

Quickstart

from chemetrian import Chemetrian

client = Chemetrian(api_key="sk_live_…")                 # or set CHEMETRIAN_API_KEY
# QA: Chemetrian(api_key="sk_live_…", base_url="https://qa.chemetrian.com")

features = [
    {"feature_name": "temp",     "feature_type": "CONTINUOUS_NUMERICAL",
     "lower_bound": 20, "upper_bound": 120, "step_size": 10},
    {"feature_name": "catalyst", "feature_type": "CATEGORICAL",
     "feature_values": ["Pd", "Ni", "Cu"]},
]
targets = [{"target_name": "yield", "goal": "maximize", "threshold": 0}]

# 1. Start a campaign → DataFrame of suggested experiments (priority == 1)
df = client.bayesian_optimization.initialize(
    project="amide-coupling", workflow_name="run-1",
    features=features, targets=targets, batch_size=4,
)

# 2. Run the suggested rows, fill in the measured target, submit → next batch
df.loc[df["priority"] == 1, "yield"] = [72.4, 55.1, 38.9, 80.2]
df = client.bayesian_optimization.run_round("amide-coupling", "run-1", df, batch_size=4)

# 3. (Optional) start from existing data instead of step 1
df = client.bayesian_optimization.initialize_with_experiments(
    project="amide-coupling", workflow_name="run-2",
    experiments=historical_df, targets=targets, batch_size=4,   # features auto-detected
)

Each call submits a job and blocks until it finishes (polling under the hood), then returns a DataFrame. priority: 1 = suggested (run it), -1 = completed.

Projects & workflows

client.list_projects()
client.create_project("amide-coupling", description="Q3 scouting")
client.bayesian_optimization.list_workflows("amide-coupling")

Errors

All raise subclasses of chemetrian.ChemetrianError: ValidationError (client-side), AuthError (401), InsufficientCreditsError (402), NotFoundError (404), RateLimitError (429, auto-retried), JobFailedError, JobTimeoutError.

Configuration