chemetrian 0.1.0__tar.gz

chemetrian-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chemetrian
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

chemetrian-0.1.0/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.1
+Name: chemetrian
+Version: 0.1.0
+Summary: Official Python SDK for the Chemetrian API (Bayesian Optimization, and more).
+Home-page: https://www.chemetrian.com
+License: MIT
+Keywords: chemetrian,bayesian-optimization,chemistry,api-client
+Author: Chemetrian
+Author-email: dev@chemetrian.com
+Requires-Python: >=3.9,<4.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Requires-Dist: pandas (>=1.5)
+Requires-Dist: requests (>=2.28,<3.0)
+Project-URL: Repository, https://gitlab.com/patel.simd/chemetrian-python-sdk
+Description-Content-Type: text/markdown
+
+# chemetrian
+
+Official Python SDK for the Chemetrian API. Drive Bayesian Optimization (and future
+services) with pandas DataFrames and one API key.
+
+## Install
+
+```bash
+pip install chemetrian
+```
+
+## Quickstart
+
+```python
+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
+
+```python
+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 |
+

chemetrian-0.1.0/README.md

@@ -0,0 +1,68 @@
+# chemetrian
+
+Official Python SDK for the Chemetrian API. Drive Bayesian Optimization (and future
+services) with pandas DataFrames and one API key.
+
+## Install
+
+```bash
+pip install chemetrian
+```
+
+## Quickstart
+
+```python
+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
+
+```python
+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 |

chemetrian-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[tool.poetry]
+name = "chemetrian"
+version = "0.1.0"
+description = "Official Python SDK for the Chemetrian API (Bayesian Optimization, and more)."
+readme = "README.md"
+license = "MIT"
+authors = ["Chemetrian <dev@chemetrian.com>"]
+homepage = "https://www.chemetrian.com"
+repository = "https://gitlab.com/patel.simd/chemetrian-python-sdk"
+keywords = ["chemetrian", "bayesian-optimization", "chemistry", "api-client"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Chemistry",
+]
+packages = [{ include = "chemetrian", from = "src" }]
+
+[tool.poetry.dependencies]
+python = "^3.9"
+requests = "^2.28"
+pandas = ">=1.5"
+
+# Dev-only — NOT installed for partners (kept out of the published package). `jupyter` is a
+# meta-package that pulls in the whole notebook stack; it belongs here, not in runtime deps.
+[tool.poetry.group.dev.dependencies]
+pytest = "^7"
+responses = "^0.23"
+jupyter = "^1.1.1"
+
+[build-system]
+requires = ["poetry-core>=1.8.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.pytest.ini_options]
+# Default run (`poetry run pytest` from the SDK root) is the MOCKED suite only. e2e/ is a
+# LIVE suite with its own e2e/pytest.ini (its own rootdir) and must never be collected here.
+testpaths = ["tests"]
+markers = [
+    "e2e: LIVE end-to-end test against a real backend (defined for the e2e/ suite).",
+    "slow: submits REAL compute and polls for minutes (e2e/ suite).",
+]

chemetrian-0.1.0/src/chemetrian/__init__.py

@@ -0,0 +1,31 @@
+"""Official Python SDK for the Chemetrian API."""
+
+from .client import Chemetrian
+from .exceptions import (
+    ChemetrianError,
+    ValidationError,
+    APIError,
+    AuthError,
+    InsufficientCreditsError,
+    NotFoundError,
+    ConflictError,
+    RateLimitError,
+    JobFailedError,
+    JobTimeoutError,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Chemetrian",
+    "ChemetrianError",
+    "ValidationError",
+    "APIError",
+    "AuthError",
+    "InsufficientCreditsError",
+    "NotFoundError",
+    "ConflictError",
+    "RateLimitError",
+    "JobFailedError",
+    "JobTimeoutError",
+]

chemetrian-0.1.0/src/chemetrian/_http.py

@@ -0,0 +1,112 @@
+"""Internal HTTP transport for the SDK.
+
+Not part of the public API — it just knows the base URL, attaches the Bearer key, maps
+error responses to typed exceptions, retries on 429 (honoring Retry-After), and polls jobs.
+"""
+
+import os
+import time
+
+import requests
+
+from .exceptions import (
+    APIError,
+    AuthError,
+    InsufficientCreditsError,
+    NotFoundError,
+    ConflictError,
+    RateLimitError,
+    JobFailedError,
+    JobTimeoutError,
+)
+
+DEFAULT_BASE_URL = "https://www.chemetrian.com"  # prod; QA is https://qa.chemetrian.com
+_API_PREFIX = "/api/v1"
+
+
+class HttpClient:
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str | None = None,
+        timeout: float = 30.0,
+        max_retries: int = 5,
+    ):
+        self.api_key = api_key
+        self.base_url = (
+            base_url or os.environ.get("CHEMETRIAN_API_URL") or DEFAULT_BASE_URL
+        ).rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.session = requests.Session()
+        self.session.headers.update(
+            {"Authorization": f"Bearer {api_key}", "Accept": "application/json"}
+        )
+
+    def request(self, method: str, path: str, json=None, params=None) -> dict:
+        url = f"{self.base_url}{_API_PREFIX}{path}"
+        attempt = 0
+        while True:
+            resp = self.session.request(
+                method, url, json=json, params=params, timeout=self.timeout
+            )
+            # Auto-backoff on rate limiting so honest callers don't have to.
+            if resp.status_code == 429 and attempt < self.max_retries:
+                time.sleep(self._retry_after(resp, default=1.0))
+                attempt += 1
+                continue
+            return self._handle(resp)
+
+    def poll_job(
+        self, job_id: str, interval: float = 2.0, timeout: float = 1800.0
+    ) -> dict:
+        """Poll GET /jobs/{id} until it finishes; return the result dict."""
+        start = time.monotonic()
+        while True:
+            result = self.request("GET", f"/jobs/{job_id}")
+            status = result.get("status")
+            if status == "finished":
+                return result
+            if status == "failed":
+                raise JobFailedError(f"Job {job_id} finished in a failed state.")
+            if time.monotonic() - start > timeout:
+                raise JobTimeoutError(
+                    f"Job {job_id} did not finish within {timeout:.0f}s."
+                )
+            time.sleep(interval)
+
+    # ── internals ────────────────────────────────────────────────────────────
+    def _handle(self, resp) -> dict:
+        if 200 <= resp.status_code < 300:
+            return resp.json() if resp.content else {}
+        detail = self._detail(resp)
+        code = resp.status_code
+        if code == 401:
+            raise AuthError(detail, 401)
+        if code == 402:
+            raise InsufficientCreditsError(detail, 402)
+        if code == 404:
+            raise NotFoundError(detail, 404)
+        if code == 409:
+            raise ConflictError(detail, 409)
+        if code == 429:
+            raise RateLimitError(detail, retry_after=self._retry_after(resp))
+        raise APIError(detail, code)
+
+    @staticmethod
+    def _retry_after(resp, default: float = 0.0) -> float:
+        try:
+            return float(resp.headers.get("Retry-After", default) or default)
+        except (TypeError, ValueError):
+            return default
+
+    @staticmethod
+    def _detail(resp) -> str:
+        try:
+            data = resp.json()
+            d = data.get("detail")
+            if isinstance(d, str):
+                return d
+            return str(d) if d else (resp.text or f"HTTP {resp.status_code}")
+        except ValueError:
+            return resp.text or f"HTTP {resp.status_code}"

chemetrian-0.1.0/src/chemetrian/_validation.py

@@ -0,0 +1,60 @@
+"""Client-side validation — fail fast on obvious mistakes before hitting the network.
+
+This is a convenience/UX layer (better errors, less wasted traffic for honest callers).
+It is NOT a security boundary — the server validates everything independently.
+"""
+
+from .exceptions import ValidationError
+
+VALID_FEATURE_TYPES = {"DISCRETE_NUMERICAL", "CONTINUOUS_NUMERICAL", "CATEGORICAL"}
+VALID_GOALS = {"maximize", "minimize"}
+
+
+def validate_features(features: list) -> None:
+    if not features:
+        raise ValidationError("At least one feature is required.")
+    for f in features:
+        name = f.get("feature_name")
+        if not name:
+            raise ValidationError("Every feature needs a 'feature_name'.")
+        ftype = f.get("feature_type")
+        if ftype not in VALID_FEATURE_TYPES:
+            raise ValidationError(
+                f"Feature '{name}': feature_type must be one of "
+                f"{sorted(VALID_FEATURE_TYPES)}."
+            )
+        if ftype == "CONTINUOUS_NUMERICAL":
+            for k in ("lower_bound", "upper_bound", "step_size"):
+                if f.get(k) is None:
+                    raise ValidationError(
+                        f"Feature '{name}' (CONTINUOUS_NUMERICAL) needs '{k}'."
+                    )
+            if f["lower_bound"] >= f["upper_bound"]:
+                raise ValidationError(
+                    f"Feature '{name}': lower_bound must be < upper_bound."
+                )
+            if f["step_size"] <= 0:
+                raise ValidationError(f"Feature '{name}': step_size must be > 0.")
+        else:  # DISCRETE_NUMERICAL / CATEGORICAL
+            if not f.get("feature_values"):
+                raise ValidationError(
+                    f"Feature '{name}' ({ftype}) needs non-empty 'feature_values'."
+                )
+
+
+def validate_targets(targets: list) -> None:
+    if not targets:
+        raise ValidationError("At least one target is required.")
+    for t in targets:
+        if not t.get("target_name"):
+            raise ValidationError("Every target needs a 'target_name'.")
+        if (t.get("goal") or "").lower() not in VALID_GOALS:
+            raise ValidationError(
+                f"Target '{t.get('target_name')}': goal must be "
+                "'maximize' or 'minimize'."
+            )
+
+
+def validate_batch_size(batch_size) -> None:
+    if not isinstance(batch_size, int) or batch_size <= 0:
+        raise ValidationError("batch_size must be a positive integer.")

chemetrian-0.1.0/src/chemetrian/bayesian_optimization.py

@@ -0,0 +1,213 @@
+"""Bayesian Optimization service — the `client.bayesian_optimization` namespace.
+
+Each optimization call submits a job and blocks (polling) until it finishes, then returns
+a pandas DataFrame of experiments. The async job/poll is hidden from the caller.
+"""
+
+import time
+
+import pandas as pd
+
+from . import _validation
+from .exceptions import JobFailedError, JobTimeoutError
+
+
+def _staged_poll_delay(elapsed: float) -> float:
+    """Backoff cadence for long-running jobs (mirrors the web app's polling): fast early,
+    gentle later. elapsed is seconds since the poll started."""
+    if elapsed <= 10:
+        return 1.0
+    if elapsed <= 30:
+        return 2.0
+    if elapsed <= 210:
+        return 5.0
+    if elapsed <= 1800:
+        return 30.0
+    return 180.0
+
+
+def _to_records(experiments) -> list:
+    """Accept a DataFrame or a list of row-dicts; return a list of row-dicts."""
+    if isinstance(experiments, pd.DataFrame):
+        return experiments.to_dict(orient="records")
+    if isinstance(experiments, list):
+        return experiments
+    raise _validation.ValidationError(
+        "experiments must be a pandas DataFrame or a list of row dicts."
+    )
+
+
+class BayesianOptimizationService:
+    def __init__(
+        self, http, poll_interval: float | None = None, poll_timeout: float = 1800.0
+    ):
+        self._http = http
+        # None -> staged backoff (fast early, gentle later). A number -> fixed interval.
+        self._poll_interval = poll_interval
+        self._poll_timeout = poll_timeout
+
+    def initialize(
+        self,
+        project: str,
+        workflow_name: str,
+        features: list,
+        targets: list,
+        batch_size: int,
+        exploit_explore_strategy: str = "balanced",
+        wait: bool = True,
+    ):
+        """Start a campaign. With wait=True (default) block until the first batch is ready
+        and return it as a DataFrame; with wait=False return the submit handle."""
+        _validation.validate_features(features)
+        _validation.validate_targets(targets)
+        _validation.validate_batch_size(batch_size)
+        body = {
+            "workflow_name": workflow_name,
+            "features": features,
+            "targets": targets,
+            "batch_size": batch_size,
+            "exploit_explore_strategy": exploit_explore_strategy,
+        }
+        submit = self._http.request(
+            "POST", f"/projects/{project}/bo/initialize", json=body
+        )
+        return self._finish(project, workflow_name, submit, wait)
+
+    def initialize_with_experiments(
+        self,
+        project: str,
+        workflow_name: str,
+        experiments,
+        targets: list,
+        batch_size: int,
+        features: list | None = None,
+        exploit_explore_strategy: str = "balanced",
+        wait: bool = True,
+    ):
+        """Seed a campaign from existing measured experiments. Omit `features` to
+        auto-detect the parameter space from the data. See `wait`."""
+        _validation.validate_targets(targets)
+        _validation.validate_batch_size(batch_size)
+        if features is not None:
+            _validation.validate_features(features)
+        body = {
+            "workflow_name": workflow_name,
+            "targets": targets,
+            "batch_size": batch_size,
+            "experiments": _to_records(experiments),
+            "features": features,
+            "exploit_explore_strategy": exploit_explore_strategy,
+        }
+        submit = self._http.request(
+            "POST",
+            f"/projects/{project}/bo/initialize-with-experiments",
+            json=body,
+        )
+        return self._finish(project, workflow_name, submit, wait)
+
+    def run_round(
+        self,
+        project: str,
+        workflow_name: str,
+        experiments,
+        batch_size: int,
+        wait: bool = True,
+    ):
+        """Submit the returned frame with measured target values filled in; get the next
+        suggested batch back. See `wait`."""
+        _validation.validate_batch_size(batch_size)
+        body = {"experiments": _to_records(experiments), "batch_size": batch_size}
+        submit = self._http.request(
+            "POST",
+            f"/projects/{project}/workflows/{workflow_name}/rounds",
+            json=body,
+        )
+        return self._finish(project, workflow_name, submit, wait)
+
+    def list_workflows(self, project: str, job_type: str | None = None) -> list:
+        """List campaigns in a project, grouped by job type."""
+        params = {"job_type": job_type} if job_type else None
+        resp = self._http.request(
+            "GET", f"/projects/{project}/workflows", params=params
+        )
+        return resp.get("workflows", [])
+
+    def get_global_shap(self, project: str, workflow_name: str) -> pd.DataFrame:
+        """Global feature importance for the latest completed round, as signed
+        contributions in [-1, 1] (sign = direction, magnitude = strength). Returns a
+        DataFrame indexed by feature, one column per target. Empty for a round with no
+        model yet (a pure initialize)."""
+        resp = self._http.request(
+            "GET", f"/projects/{project}/workflows/{workflow_name}/global-shap"
+        )
+        return pd.DataFrame(resp.get("globalShap") or {})
+
+    def get_workflow_results(
+        self,
+        project: str,
+        workflow_name: str,
+        include_all: bool = False,
+        include_shap: bool = False,
+    ):
+        """The single poller + recovery call. Returns the latest round's DataFrame if it
+        has finished, else a status dict `{"status": ..., "round": ...}`.
+
+        include_all=True returns EVERY candidate (priority 0/-1/1) with predictions, so you
+        can pick or update an experiment outside the suggested batch. Off by default because
+        it can be large for big design spaces.
+        include_shap=True keeps the per-row SHAP columns (per-experiment feature
+        attributions), dropped by default. For aggregate importance use get_global_shap."""
+        raw = self._fetch_workflow_result(
+            project, workflow_name, include_all, include_shap
+        )
+        if raw.get("status") == "finished":
+            return pd.DataFrame(raw.get("experiments") or [])
+        return {"status": raw.get("status"), "round": raw.get("round")}
+
+    # ── internals ────────────────────────────────────────────────────────────
+    def _fetch_workflow_result(
+        self,
+        project: str,
+        workflow_name: str,
+        include_all: bool = False,
+        include_shap: bool = False,
+    ) -> dict:
+        params = {}
+        if include_all:
+            params["include_all"] = "true"
+        if include_shap:
+            params["include_shap"] = "true"
+        return self._http.request(
+            "GET",
+            f"/projects/{project}/workflows/{workflow_name}/results",
+            params=params or None,
+        )
+
+    def _finish(self, project: str, workflow_name: str, submit: dict, wait: bool):
+        if not wait:
+            return submit
+        return self._poll_workflow(project, workflow_name)
+
+    def _poll_workflow(self, project: str, workflow_name: str) -> pd.DataFrame:
+        start = time.monotonic()
+        while True:
+            raw = self._fetch_workflow_result(project, workflow_name)
+            status = raw.get("status")
+            if status == "finished":
+                return pd.DataFrame(raw.get("experiments") or [])
+            if status == "failed":
+                raise JobFailedError(
+                    f"The latest round of '{workflow_name}' finished in a failed state."
+                )
+            elapsed = time.monotonic() - start
+            if elapsed > self._poll_timeout:
+                raise JobTimeoutError(
+                    f"'{workflow_name}' did not finish within "
+                    f"{self._poll_timeout:.0f}s."
+                )
+            delay = (
+                self._poll_interval
+                if self._poll_interval is not None
+                else _staged_poll_delay(elapsed)
+            )
+            time.sleep(delay)

chemetrian-0.1.0/src/chemetrian/client.py

@@ -0,0 +1,59 @@
+"""The top-level Chemetrian client.
+
+Multi-service by design: each service hangs off the client (`client.bayesian_optimization`),
+so new services slot in later without changing existing code. Cross-service resources
+(projects) live directly on the client.
+"""
+
+import os
+
+from ._http import HttpClient
+from .bayesian_optimization import BayesianOptimizationService
+from .exceptions import ValidationError
+
+
+class Chemetrian:
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float = 30.0,
+        poll_interval: float | None = None,
+        poll_timeout: float = 1800.0,
+    ):
+        """
+        Args:
+            api_key: your `sk_live_…` key. Falls back to the CHEMETRIAN_API_KEY env var.
+            base_url: API host. Defaults to production; pass a QA host or set
+                CHEMETRIAN_API_URL to point elsewhere.
+            timeout: per-request timeout (seconds).
+            poll_interval: seconds between polls while waiting for a job. Default (None)
+                uses a staged backoff (1s early → up to 3min for long jobs); pass a number
+                for a fixed interval.
+            poll_timeout: give up waiting after this many seconds.
+        """
+        api_key = api_key or os.environ.get("CHEMETRIAN_API_KEY")
+        if not api_key:
+            raise ValidationError(
+                "An API key is required — pass api_key=… or set CHEMETRIAN_API_KEY."
+            )
+        if not api_key.startswith("sk_"):
+            raise ValidationError(
+                "API key looks malformed (expected it to start with 'sk_')."
+            )
+
+        self._http = HttpClient(api_key, base_url=base_url, timeout=timeout)
+
+        # Services
+        self.bayesian_optimization = BayesianOptimizationService(
+            self._http, poll_interval=poll_interval, poll_timeout=poll_timeout
+        )
+
+    # ── projects (cross-service) ─────────────────────────────────────────────
+    def list_projects(self) -> list:
+        return self._http.request("GET", "/projects").get("projects", [])
+
+    def create_project(self, name: str, description: str = "") -> dict:
+        return self._http.request(
+            "POST", "/projects", json={"name": name, "description": description}
+        )

chemetrian-0.1.0/src/chemetrian/exceptions.py

@@ -0,0 +1,52 @@
+"""Exception hierarchy for the Chemetrian SDK.
+
+All SDK errors derive from ChemetrianError, so callers can catch broadly or narrowly.
+"""
+
+
+class ChemetrianError(Exception):
+    """Base class for all SDK errors."""
+
+
+class ValidationError(ChemetrianError):
+    """A request failed client-side validation before it was ever sent."""
+
+
+class APIError(ChemetrianError):
+    """The API returned an error response."""
+
+    def __init__(self, message: str, status_code: int | None = None):
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class AuthError(APIError):
+    """401 — missing / invalid / expired / revoked API key."""
+
+
+class InsufficientCreditsError(APIError):
+    """402 — the owner account is out of credits."""
+
+
+class NotFoundError(APIError):
+    """404 — project / workflow / job not found in this workspace."""
+
+
+class ConflictError(APIError):
+    """409 — already exists (e.g. a campaign name is taken)."""
+
+
+class RateLimitError(APIError):
+    """429 — rate limit or concurrency cap exceeded."""
+
+    def __init__(self, message: str, retry_after: float | None = None):
+        super().__init__(message, status_code=429)
+        self.retry_after = retry_after
+
+
+class JobFailedError(ChemetrianError):
+    """A submitted optimization job finished in a failed state."""
+
+
+class JobTimeoutError(ChemetrianError):
+    """A job did not finish within the client's poll timeout."""