chemetrian 0.1.0

Official Python SDK for the Chemetrian API (Bayesian Optimization, and more).

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

arg / env	purpose
api_key / CHEMETRIAN_API_KEY	your key
base_url / CHEMETRIAN_API_URL	API host (QA vs prod)
poll_interval, poll_timeout	how long the SDK waits for a job