proxyml 0.1.1__tar.gz → 0.1.3__tar.gz

{proxyml-0.1.1 → proxyml-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: proxyml
-Version: 0.1.1
+Version: 0.1.3
 Summary: Python SDK for calling the ProxyML API
 Author-email: ProxyML <contact@proxyml.ai>
 License:                                  Apache License

{proxyml-0.1.1 → proxyml-0.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "proxyml"
-version = "0.1.1"
+version = "0.1.3"
 description = "Python SDK for calling the ProxyML API"
 readme = "README.md"
 license = {file = "LICENSE"}

{proxyml-0.1.1 → proxyml-0.1.3}/src/proxyml/__init__.py

@@ -3,9 +3,15 @@ from proxyml.client import (
     synthesize_data,
     train_surrogate,
     predict,
+    predict_batch,
     find_counterfactual,
+    find_counterfactuals,
     interpret_counterfactual,
     get_feature_importances,
+    get_model_summary,
+    diff_models,
+    list_models,
+    delete_model,
 )
 from proxyml.schema import (
     get_schema,
@@ -19,8 +25,15 @@ __all__ = [
     "synthesize_data",
     "train_surrogate",
     "predict",
+    "predict_batch",
     "find_counterfactual",
+    "find_counterfactuals",
     "interpret_counterfactual",
+    "get_feature_importances",
+    "get_model_summary",
+    "diff_models",
+    "list_models",
+    "delete_model",
     "get_schema",
     "gen_continuous_schema",
     "gen_categorical_schema",

proxyml-0.1.3/src/proxyml/client.py

@@ -0,0 +1,345 @@
+import logging
+logger = logging.getLogger(__name__)
+
+import requests
+import os
+import numpy as np
+import pandas as pd
+from pandas.api.types import is_float_dtype, is_integer_dtype
+
+
+PROXYML_BASE_URL = os.getenv("PROXYML_BASE_URL", "https://api.proxyml.ai/api/v1")
+
+_BOOL_STRINGS = {"true", "false"}
+
+
+def _headers() -> dict:
+    api_key = os.getenv("PROXYML_API_KEY", "")
+    if not api_key:
+        raise EnvironmentError(
+            "PROXYML_API_KEY is not set. "
+            "Set the environment variable before using the SDK."
+        )
+    return {
+        'Content-Type': 'application/json',
+        'X-API-KEY': api_key,
+    }
+
+
+def post(endpoint: str, payload: dict) -> requests.models.Response:
+    r = requests.post(
+        url=f'{PROXYML_BASE_URL}{endpoint}',
+        json=payload,
+        headers=_headers()
+    )
+    return r
+
+
+def put(endpoint: str, payload: dict) -> requests.models.Response:
+    r = requests.put(
+        url=f'{PROXYML_BASE_URL}{endpoint}',
+        json=payload,
+        headers=_headers()
+    )
+    return r
+
+
+def get(endpoint: str, params: dict) -> requests.models.Response:
+    r = requests.get(
+        url=f'{PROXYML_BASE_URL}{endpoint}',
+        headers=_headers(),
+        params=params
+    )
+    return r
+
+
+def delete(endpoint: str) -> requests.models.Response:
+    r = requests.delete(
+        url=f'{PROXYML_BASE_URL}{endpoint}',
+        headers=_headers()
+    )
+    return r
+
+
+def put_schema(schema: dict):
+    r = put(endpoint='/schema', payload=schema)
+    if r.status_code == 200:
+        logger.info("Schema uploaded successfully")
+        return r.json()
+    logger.error(
+        "Schema upload failed with status %s: %s",
+        r.status_code,
+        r.text
+    )
+    return None
+
+
+def _cast_column(series: pd.Series, ftype: str) -> pd.Series:
+    if ftype in ("continuous",):
+        return series.astype(float)
+    if ftype in ("count", "numeric_ordinal"):
+        return series.astype(int)
+    if ftype in ("categorical", "categorical_ordinal"):
+        # convert "true"/"false" strings back to booleans when appropriate
+        unique = {str(v).lower() for v in series.dropna().unique()}
+        if unique <= _BOOL_STRINGS:
+            return series.map({"true": True, "false": False, True: True, False: False})
+    return series
+
+
+def synthesize_data(num_points: int = 100, sample: list | None = None, as_df: bool = True):
+    if sample is None:
+        r = post(endpoint='/synthesize/neighbors', payload={'n': num_points})
+    else:
+        r = post(endpoint='/synthesize/blended', payload={'n': num_points, 'instance': [col.item() for col in sample]})
+    if r.status_code == 200:
+        payload = r.json()
+        if as_df:
+            df = pd.DataFrame(payload['samples'], columns=payload['feature_names'])
+            for col, ftype in zip(payload['feature_names'], payload['feature_types']):
+                df[col] = _cast_column(df[col], ftype)
+            return df
+        return payload
+    logger.error(
+        "Data synthesis failed with status %s: %s",
+        r.status_code,
+        r.text
+    )
+    return None
+
+
+def train_surrogate(
+        samples: list,
+        predictions: list,
+        feature_names: list[str] | None,
+        task: str = 'auto',
+        test_size: float = 0.2,
+        name: str | None = None,
+        comments: str | None = None,
+    ):
+    payload = {
+        'samples': samples,
+        'predictions': predictions,
+        'feature_names': feature_names,
+        'task': task,
+        'test_size': test_size,
+    }
+    if name is not None:
+        payload['name'] = name
+    if comments is not None:
+        payload['comments'] = comments
+    r = post(endpoint='/surrogate/train', payload=payload)
+    if r.status_code == 200:
+        return r.json()
+    logger.error(
+        "Surrogate training failed with status %s: %s",
+        r.status_code,
+        r.text
+    )
+    return None
+
+
+def predict(sample: list, version: str | None = None):
+    payload = {'inputs': sample}
+    if version is not None:
+        payload['version'] = version
+    r = post(endpoint='/surrogate/predict', payload=payload)
+    if r.status_code == 200:
+        return r.json()
+    logger.error(
+        "Surrogate prediction failed with status %s: %s",
+        r.status_code,
+        r.text
+    )
+    return None
+
+
+def find_counterfactual(sample, target, n_neighbors: int = 10000, perturbation_scale: float = 0.1, version: str | None = None, as_df: bool = True):
+    payload = {
+        'instance': sample,
+        'target_label': target.item() if hasattr(target, 'item') else target,
+        'n_neighbors': n_neighbors,
+        'perturbation_scale': perturbation_scale,
+    }
+    if version is not None:
+        payload['version'] = version
+    r = post(endpoint='/explain/counterfactual', payload=payload)
+    if r.status_code == 200:
+        payload = r.json()
+        if as_df:
+            if payload['counterfactual'] is None:
+                print(f"No counterfactual found: {payload.get('warning')}")
+                return None
+            df = pd.DataFrame([payload['counterfactual']], columns=payload['feature_names'])
+            for col, ftype in zip(payload['feature_names'], payload['feature_types']):
+                df[col] = _cast_column(df[col], ftype)
+            return df
+        return payload
+    logger.error(
+        "Counterfactual failed with status %s: %s",
+        r.status_code,
+        r.text
+    )
+    return None
+
+
+def interpret_counterfactual(
+    sample: dict,
+    counterfactual: dict,
+    prediction_changed: bool,
+    exclude_from_diff: list[str] | None
+) -> str:
+    if not exclude_from_diff:
+        exclude_from_diff = list()
+    diffs = {
+        k: (sample[k], counterfactual[k])
+        for k in sample
+        if sample[k] != counterfactual[k]
+        and k not in exclude_from_diff
+    }
+
+    if not diffs:
+        return "No meaningful differences found between sample and counterfactual."
+
+    changes = ", ".join(
+        f"{feature} from {original} to {cf_value}"
+        for feature, (original, cf_value) in diffs.items()
+    )
+
+    if prediction_changed:
+        return (
+            f"Changing {changes} may result in a different prediction. "
+            f"Note: this is based on a surrogate model and should be treated as approximate."
+        )
+    else:
+        return (
+            f"A counterfactual was found suggesting {changes}, however "
+            f"the original model's prediction did not change. "
+            f"This may indicate the surrogate model does not fully capture "
+            f"the original model's decision boundary in this region."
+        )
+
+
+def predict_batch(samples: list[list], version: str | None = None):
+    payload = {'inputs': samples}
+    if version is not None:
+        payload['version'] = version
+    r = post(endpoint='/surrogate/predict/batch', payload=payload)
+    if r.status_code == 200:
+        return r.json()
+    logger.error(
+        "Batch prediction failed with status %s: %s",
+        r.status_code,
+        r.text,
+    )
+    return None
+
+
+def find_counterfactuals(
+    samples: list[list],
+    target,
+    n_neighbors: int = 10000,
+    perturbation_scale: float = 0.1,
+    version: str | None = None,
+    as_dfs: bool = True,
+):
+    payload = {
+        'instances': samples,
+        'target_label': target.item() if hasattr(target, 'item') else target,
+        'n_neighbors': n_neighbors,
+        'perturbation_scale': perturbation_scale,
+    }
+    if version is not None:
+        payload['version'] = version
+    r = post(endpoint='/explain/counterfactual/batch', payload=payload)
+    if r.status_code == 200:
+        data = r.json()
+        if as_dfs:
+            feature_names = data['feature_names']
+            feature_types = data['feature_types']
+            results = []
+            for item in data['results']:
+                if item['counterfactual'] is None:
+                    if item.get('warning'):
+                        print(f"No counterfactual found: {item['warning']}")
+                    results.append(None)
+                else:
+                    df = pd.DataFrame([item['counterfactual']], columns=feature_names)
+                    for col, ftype in zip(feature_names, feature_types):
+                        df[col] = _cast_column(df[col], ftype)
+                    results.append(df)
+            return results
+        return data
+    logger.error(
+        "Batch counterfactual failed with status %s: %s",
+        r.status_code,
+        r.text,
+    )
+    return None
+
+
+def get_model_summary(version: str | None = None):
+    params = {'version': version} if version is not None else {}
+    r = get(endpoint='/explain/summary', params=params)
+    if r.status_code == 200:
+        return r.json()
+    logger.error(
+        "Model summary failed with status %s: %s",
+        r.status_code,
+        r.text,
+    )
+    return None
+
+
+def diff_models(version_a: str, version_b: str):
+    r = get(endpoint='/explain/diff', params={'version_a': version_a, 'version_b': version_b})
+    if r.status_code == 200:
+        return r.json()
+    logger.error(
+        "Model diff failed with status %s: %s",
+        r.status_code,
+        r.text,
+    )
+    return None
+
+
+def get_feature_importances(version: str | None = None):
+    params = {'version': version} if version is not None else {}
+    r = get(endpoint='/explain/importance', params=params)
+    if r.status_code == 200:
+        return r.json()
+    logger.error(
+        "Feature importances failed with status %s: %s",
+        r.status_code,
+        r.text,
+    )
+    return None
+
+
+def list_models() -> list[dict] | None:
+    """Return metadata for all trained surrogate models, newest first."""
+    r = get(endpoint='/surrogate/models', params={})
+    if r.status_code == 200:
+        return r.json()['models']
+    logger.error(
+        "List models failed with status %s: %s",
+        r.status_code,
+        r.text,
+    )
+    return None
+
+
+def delete_model(model_id: str) -> bool:
+    """Delete a surrogate model by its UUID. Returns True on success, False if not found."""
+    r = delete(endpoint=f'/surrogate/models/{model_id}')
+    if r.status_code == 204:
+        return True
+    if r.status_code == 404:
+        logger.warning("Surrogate model %s not found", model_id)
+        return False
+    logger.error(
+        "Delete model failed with status %s: %s",
+        r.status_code,
+        r.text,
+    )
+    return False

{proxyml-0.1.1 → proxyml-0.1.3}/src/proxyml.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: proxyml
-Version: 0.1.1
+Version: 0.1.3
 Summary: Python SDK for calling the ProxyML API
 Author-email: ProxyML <contact@proxyml.ai>
 License:                                  Apache License

proxyml-0.1.3/tests/test_client.py

@@ -0,0 +1,422 @@
+import os
+from unittest.mock import MagicMock, patch
+
+import pandas as pd
+import pytest
+
+from proxyml.client import (
+    _cast_column,
+    _headers,
+    delete_model,
+    diff_models,
+    find_counterfactuals,
+    get_model_summary,
+    interpret_counterfactual,
+    list_models,
+    predict,
+    predict_batch,
+    put_schema,
+    synthesize_data,
+    train_surrogate,
+)
+
+
+# ---------------------------------------------------------------------------
+# _headers
+# ---------------------------------------------------------------------------
+
+def test_headers_raises_without_api_key(monkeypatch):
+    monkeypatch.delenv("PROXYML_API_KEY", raising=False)
+    with pytest.raises(EnvironmentError, match="PROXYML_API_KEY"):
+        _headers()
+
+
+def test_headers_returns_correct_dict(monkeypatch):
+    monkeypatch.setenv("PROXYML_API_KEY", "test-key")
+    h = _headers()
+    assert h["X-API-KEY"] == "test-key"
+    assert h["Content-Type"] == "application/json"
+
+
+# ---------------------------------------------------------------------------
+# _cast_column
+# ---------------------------------------------------------------------------
+
+def test_cast_column_continuous():
+    s = pd.Series(["1.5", "2.5", "3.5"])
+    result = _cast_column(s, "continuous")
+    assert result.dtype == float
+
+
+def test_cast_column_count():
+    s = pd.Series([1.0, 2.0, 3.0])
+    result = _cast_column(s, "count")
+    assert result.dtype == int
+
+
+def test_cast_column_numeric_ordinal():
+    s = pd.Series([1.0, 2.0, 3.0])
+    result = _cast_column(s, "numeric_ordinal")
+    assert result.dtype == int
+
+
+def test_cast_column_categorical_bool_strings():
+    s = pd.Series(["true", "false", "true"])
+    result = _cast_column(s, "categorical")
+    assert result.tolist() == [True, False, True]
+
+
+def test_cast_column_categorical_passthrough():
+    s = pd.Series(["a", "b", "c"])
+    result = _cast_column(s, "categorical")
+    assert result.tolist() == ["a", "b", "c"]
+
+
+def test_cast_column_unknown_type_passthrough():
+    s = pd.Series([1, 2, 3])
+    result = _cast_column(s, "unknown_type")
+    assert result.tolist() == [1, 2, 3]
+
+
+# ---------------------------------------------------------------------------
+# interpret_counterfactual
+# ---------------------------------------------------------------------------
+
+def test_interpret_counterfactual_prediction_changed():
+    result = interpret_counterfactual(
+        sample={"age": 30, "income": 50000},
+        counterfactual={"age": 30, "income": 75000},
+        prediction_changed=True,
+        exclude_from_diff=None,
+    )
+    assert "income from 50000 to 75000" in result
+    assert "different prediction" in result
+    assert "surrogate model" in result
+
+
+def test_interpret_counterfactual_prediction_unchanged():
+    result = interpret_counterfactual(
+        sample={"age": 30, "income": 50000},
+        counterfactual={"age": 30, "income": 75000},
+        prediction_changed=False,
+        exclude_from_diff=None,
+    )
+    assert "income from 50000 to 75000" in result
+    assert "did not change" in result
+
+
+def test_interpret_counterfactual_no_diffs():
+    result = interpret_counterfactual(
+        sample={"age": 30},
+        counterfactual={"age": 30},
+        prediction_changed=True,
+        exclude_from_diff=None,
+    )
+    assert result == "No meaningful differences found between sample and counterfactual."
+
+
+def test_interpret_counterfactual_exclude_from_diff():
+    result = interpret_counterfactual(
+        sample={"age": 30, "id": 999},
+        counterfactual={"age": 35, "id": 888},
+        prediction_changed=True,
+        exclude_from_diff=["id"],
+    )
+    assert "id" not in result
+    assert "age from 30 to 35" in result
+
+
+# ---------------------------------------------------------------------------
+# API functions (mocked HTTP)
+# ---------------------------------------------------------------------------
+
+def _mock_response(status_code, json_body):
+    r = MagicMock()
+    r.status_code = status_code
+    r.json.return_value = json_body
+    r.text = str(json_body)
+    return r
+
+
+@patch("proxyml.client.put")
+def test_put_schema_success(mock_put):
+    mock_put.return_value = _mock_response(200, {"status": "ok"})
+    result = put_schema({"features": []})
+    assert result == {"status": "ok"}
+    mock_put.assert_called_once_with(endpoint="/schema", payload={"features": []})
+
+
+@patch("proxyml.client.put")
+def test_put_schema_failure(mock_put):
+    mock_put.return_value = _mock_response(422, {"detail": "invalid"})
+    result = put_schema({"features": []})
+    assert result is None
+
+
+@patch("proxyml.client.post")
+def test_predict_success(mock_post):
+    mock_post.return_value = _mock_response(200, {"prediction": 1, "probability": 0.9})
+    result = predict(sample=[1.0, 2.0, 3.0], version=None)
+    assert result == {"prediction": 1, "probability": 0.9}
+    payload = mock_post.call_args.kwargs["payload"]
+    assert payload["inputs"] == [1.0, 2.0, 3.0]
+    assert "version" not in payload
+
+
+@patch("proxyml.client.post")
+def test_predict_with_version(mock_post):
+    mock_post.return_value = _mock_response(200, {"prediction": 0})
+    uid = "550e8400-e29b-41d4-a716-446655440000"
+    predict(sample=[1.0, 2.0], version=uid)
+    payload = mock_post.call_args.kwargs["payload"]
+    assert payload["version"] == uid
+
+
+@patch("proxyml.client.post")
+def test_predict_failure_returns_none(mock_post):
+    mock_post.return_value = _mock_response(422, {"detail": "bad input"})
+    result = predict(sample=[1.0, 2.0], version=None)
+    assert result is None
+
+
+@patch("proxyml.client.post")
+def test_synthesize_data_no_sample(mock_post):
+    mock_post.return_value = _mock_response(200, {
+        "samples": [[1.0, "true"], [2.5, "false"]],
+        "feature_names": ["f_cont", "f_cat"],
+        "feature_types": ["continuous", "categorical"],
+    })
+    df = synthesize_data(num_points=2, sample=None)
+    assert isinstance(df, pd.DataFrame)
+    assert list(df.columns) == ["f_cont", "f_cat"]
+    mock_post.assert_called_once_with(
+        endpoint="/synthesize/neighbors", payload={"n": 2}
+    )
+
+
+@patch("proxyml.client.post")
+def test_synthesize_data_failure_returns_none(mock_post):
+    mock_post.return_value = _mock_response(500, {})
+    result = synthesize_data(num_points=10, sample=None)
+    assert result is None
+
+
+@patch("proxyml.client.post")
+def test_train_surrogate_with_metadata(mock_post):
+    mock_post.return_value = _mock_response(200, {
+        "version": "abc-123", "trained_at": "2026-04-19T12:00:00",
+        "task": "regression", "name": "v1", "comments": "test run",
+        "feature_names": None, "metrics": {"r2": 0.95}, "warning": None,
+    })
+    result = train_surrogate(
+        samples=[[1.0, 2.0]], predictions=[3.0],
+        feature_names=None, name="v1", comments="test run",
+    )
+    payload = mock_post.call_args.kwargs["payload"]
+    assert payload["name"] == "v1"
+    assert payload["comments"] == "test run"
+    assert result["version"] == "abc-123"
+    assert result["trained_at"] == "2026-04-19T12:00:00"
+
+
+@patch("proxyml.client.post")
+def test_train_surrogate_omits_none_metadata(mock_post):
+    mock_post.return_value = _mock_response(200, {"version": "abc-123"})
+    train_surrogate(samples=[[1.0]], predictions=[1.0], feature_names=None)
+    payload = mock_post.call_args.kwargs["payload"]
+    assert "name" not in payload
+    assert "comments" not in payload
+
+
+@patch("proxyml.client.get")
+def test_list_models_success(mock_get):
+    models = [{"version": "abc-123", "task": "regression", "name": "v1",
+               "comments": None, "feature_names": None, "metrics": {"r2": 0.9},
+               "trained_at": "2026-04-19T12:00:00"}]
+    mock_get.return_value = _mock_response(200, {"models": models})
+    result = list_models()
+    assert result == models
+    mock_get.assert_called_once_with(endpoint="/surrogate/models", params={})
+
+
+@patch("proxyml.client.get")
+def test_list_models_failure_returns_none(mock_get):
+    mock_get.return_value = _mock_response(401, {"detail": "unauthorized"})
+    assert list_models() is None
+
+
+@patch("proxyml.client.delete")
+def test_delete_model_success(mock_delete):
+    mock_delete.return_value = _mock_response(204, None)
+    assert delete_model("abc-123") is True
+    mock_delete.assert_called_once_with(endpoint="/surrogate/models/abc-123")
+
+
+@patch("proxyml.client.delete")
+def test_delete_model_not_found(mock_delete):
+    mock_delete.return_value = _mock_response(404, {"detail": "not found"})
+    assert delete_model("no-such-id") is False
+
+
+# ---------------------------------------------------------------------------
+# predict_batch
+# ---------------------------------------------------------------------------
+
+@patch("proxyml.client.post")
+def test_predict_batch_success(mock_post):
+    mock_post.return_value = _mock_response(200, {
+        "predictions": [0.74, 0.31],
+        "model_version": "surrogate-abc-regression",
+    })
+    result = predict_batch(samples=[[1.0, 2.0], [3.0, 4.0]])
+    assert result["predictions"] == [0.74, 0.31]
+    payload = mock_post.call_args.kwargs["payload"]
+    assert payload["inputs"] == [[1.0, 2.0], [3.0, 4.0]]
+    assert "version" not in payload
+
+
+@patch("proxyml.client.post")
+def test_predict_batch_with_version(mock_post):
+    mock_post.return_value = _mock_response(200, {"predictions": [1], "model_version": "surrogate-abc-classification"})
+    uid = "550e8400-e29b-41d4-a716-446655440000"
+    predict_batch(samples=[[1.0]], version=uid)
+    payload = mock_post.call_args.kwargs["payload"]
+    assert payload["version"] == uid
+
+
+@patch("proxyml.client.post")
+def test_predict_batch_failure_returns_none(mock_post):
+    mock_post.return_value = _mock_response(422, {"detail": "bad input"})
+    assert predict_batch(samples=[[1.0, 2.0]]) is None
+
+
+# ---------------------------------------------------------------------------
+# find_counterfactuals
+# ---------------------------------------------------------------------------
+
+_BATCH_CF_RESPONSE = {
+    "results": [
+        {"counterfactual": [1.5, "yes"], "outlier_score": 0.1, "warning": None},
+        {"counterfactual": None, "outlier_score": 0.9, "warning": "no CF found"},
+    ],
+    "feature_names": ["f_cont", "f_cat"],
+    "feature_types": ["continuous", "categorical"],
+    "task": "classification",
+    "target_label": "high",
+    "model_version": "surrogate-abc-classification",
+}
+
+
+@patch("proxyml.client.post")
+def test_find_counterfactuals_as_df(mock_post):
+    mock_post.return_value = _mock_response(200, _BATCH_CF_RESPONSE)
+    results = find_counterfactuals(samples=[[1.0, "no"], [2.0, "no"]], target="high")
+    assert len(results) == 2
+    assert isinstance(results[0], pd.DataFrame)
+    assert results[0]["f_cont"].iloc[0] == 1.5
+    assert results[1] is None  # no counterfactual for second instance
+
+
+@patch("proxyml.client.post")
+def test_find_counterfactuals_raw(mock_post):
+    mock_post.return_value = _mock_response(200, _BATCH_CF_RESPONSE)
+    result = find_counterfactuals(samples=[[1.0, "no"]], target="high", as_dfs=False)
+    assert result == _BATCH_CF_RESPONSE
+
+
+@patch("proxyml.client.post")
+def test_find_counterfactuals_payload(mock_post):
+    mock_post.return_value = _mock_response(200, _BATCH_CF_RESPONSE)
+    uid = "550e8400-e29b-41d4-a716-446655440000"
+    find_counterfactuals(
+        samples=[[1.0, "no"]], target="high",
+        n_neighbors=500, perturbation_scale=0.2, version=uid, as_dfs=False,
+    )
+    payload = mock_post.call_args.kwargs["payload"]
+    assert payload["instances"] == [[1.0, "no"]]
+    assert payload["target_label"] == "high"
+    assert payload["n_neighbors"] == 500
+    assert payload["perturbation_scale"] == 0.2
+    assert payload["version"] == uid
+
+
+@patch("proxyml.client.post")
+def test_find_counterfactuals_failure_returns_none(mock_post):
+    mock_post.return_value = _mock_response(404, {"detail": "no surrogate"})
+    assert find_counterfactuals(samples=[[1.0]], target="high") is None
+
+
+# ---------------------------------------------------------------------------
+# get_model_summary
+# ---------------------------------------------------------------------------
+
+_SUMMARY_RESPONSE = {
+    "model_version": "abc-123",
+    "task": "regression",
+    "trained_at": "2026-04-20T10:00:00",
+    "name": "v2",
+    "comments": None,
+    "feature_names": ["MedInc", "Latitude"],
+    "metrics": {"r2": 0.92},
+    "feature_importances": [
+        {"feature": "MedInc", "coefficient": 0.82, "abs_coefficient": 0.82},
+        {"feature": "Latitude", "coefficient": -0.61, "abs_coefficient": 0.61},
+    ],
+    "per_class_importances": None,
+    "note": "Coefficients are in the scaled feature space.",
+}
+
+
+@patch("proxyml.client.get")
+def test_get_model_summary_success(mock_get):
+    mock_get.return_value = _mock_response(200, _SUMMARY_RESPONSE)
+    result = get_model_summary()
+    assert result == _SUMMARY_RESPONSE
+    mock_get.assert_called_once_with(endpoint="/explain/summary", params={})
+
+
+@patch("proxyml.client.get")
+def test_get_model_summary_with_version(mock_get):
+    mock_get.return_value = _mock_response(200, _SUMMARY_RESPONSE)
+    get_model_summary(version="abc-123")
+    mock_get.assert_called_once_with(endpoint="/explain/summary", params={"version": "abc-123"})
+
+
+@patch("proxyml.client.get")
+def test_get_model_summary_failure_returns_none(mock_get):
+    mock_get.return_value = _mock_response(404, {"detail": "not found"})
+    assert get_model_summary() is None
+
+
+# ---------------------------------------------------------------------------
+# diff_models
+# ---------------------------------------------------------------------------
+
+_DIFF_RESPONSE = {
+    "version_a": "aaa-111",
+    "version_b": "bbb-222",
+    "task": "regression",
+    "metric_diff": {"r2": {"a": 0.87, "b": 0.92, "delta": 0.05}},
+    "coefficient_diff": [
+        {"feature": "MedInc", "a": 0.82, "b": 0.76, "delta": -0.06},
+    ],
+    "features_added": [],
+    "features_removed": ["Population"],
+}
+
+
+@patch("proxyml.client.get")
+def test_diff_models_success(mock_get):
+    mock_get.return_value = _mock_response(200, _DIFF_RESPONSE)
+    result = diff_models(version_a="aaa-111", version_b="bbb-222")
+    assert result == _DIFF_RESPONSE
+    mock_get.assert_called_once_with(
+        endpoint="/explain/diff",
+        params={"version_a": "aaa-111", "version_b": "bbb-222"},
+    )
+
+
+@patch("proxyml.client.get")
+def test_diff_models_failure_returns_none(mock_get):
+    mock_get.return_value = _mock_response(422, {"detail": "different tasks"})
+    assert diff_models(version_a="aaa-111", version_b="bbb-222") is None

proxyml-0.1.1/src/proxyml/client.py

@@ -1,212 +0,0 @@
-import logging
-logger = logging.getLogger(__name__)
-
-import requests
-import os
-import numpy as np
-import pandas as pd
-from pandas.api.types import is_float_dtype, is_integer_dtype
-
-
-PROXYML_BASE_URL = os.getenv("PROXYML_BASE_URL", "https://api.proxyml.ai/api/v1")
-
-_BOOL_STRINGS = {"true", "false"}
-
-
-def _headers() -> dict:
-    api_key = os.getenv("PROXYML_API_KEY", "")
-    if not api_key:
-        raise EnvironmentError(
-            "PROXYML_API_KEY is not set. "
-            "Set the environment variable before using the SDK."
-        )
-    return {
-        'Content-Type': 'application/json',
-        'X-API-KEY': api_key,
-    }
-
-
-def post(endpoint: str, payload: dict) -> requests.models.Response:
-    r = requests.post(
-        url=f'{PROXYML_BASE_URL}{endpoint}',
-        json=payload,
-        headers=_headers()
-    )
-    return r
-
-
-def put(endpoint: str, payload: dict) -> requests.models.Response:
-    r = requests.put(
-        url=f'{PROXYML_BASE_URL}{endpoint}',
-        json=payload,
-        headers=_headers()
-    )
-    return r
-
-
-def get(endpoint: str, params: dict) -> requests.models.Response:
-    r = requests.get(
-        url=f'{PROXYML_BASE_URL}{endpoint}',
-        headers=_headers(),
-        params=params
-    )
-    return r
-
-
-def put_schema(schema: dict):
-    r = put(endpoint='/schema', payload=schema)
-    if r.status_code == 200:
-        logger.info("Schema uploaded successfully")
-        return r.json()
-    logger.error(
-        "Schema upload failed with status %s: %s",
-        r.status_code,
-        r.text
-    )
-    return None
-
-
-def _cast_column(series: pd.Series, ftype: str) -> pd.Series:                                                                                                                         
-    if ftype in ("continuous",):                                                                                                                                                      
-        return series.astype(float)                                                                                                                                                   
-    if ftype in ("count", "numeric_ordinal"):                                                                                                                                         
-        return series.astype(int)
-    if ftype in ("categorical", "categorical_ordinal"):                                                                                                                               
-        # convert "true"/"false" strings back to booleans when appropriate
-        unique = {str(v).lower() for v in series.dropna().unique()}                                                                                                                   
-        if unique <= _BOOL_STRINGS:                                                                                                                                                   
-            return series.map({"true": True, "false": False, True: True, False: False})                                                                                               
-    return series                                                                                                                                                                     
-                                                            
-                                                                                                                                                                                        
-def synthesize_data(num_points: int = 100, sample: list | None = None, as_df: bool = True):
-    if sample is None:                                                                                                                                                                
-        r = post(endpoint='/synthesize/neighbors', payload={'n': num_points})                                                                                                         
-    else:
-        r = post(endpoint='/synthesize/blended', payload={'n': num_points, 'instance': [col.item() for col in sample]})                                                               
-    if r.status_code == 200:                                                                                                                                                          
-        payload = r.json()                                                                                                                                                            
-        if as_df:                                                                                                                                                                     
-            df = pd.DataFrame(payload['samples'], columns=payload['feature_names'])
-            for col, ftype in zip(payload['feature_names'], payload['feature_types']):                                                                                                
-                df[col] = _cast_column(df[col], ftype)
-            return df                                                                                                                                                                 
-        return payload
-    logger.error(
-        "Data synthesis failed with status %s: %s",
-        r.status_code,
-        r.text
-    )
-    return None 
-
-
-def train_surrogate(
-        samples: list, 
-        predictions: list, 
-        feature_names: list[str] | None,
-        task: str = 'auto', 
-        test_size: float = 0.2
-    ):
-    r = post(endpoint='/surrogate/train', payload={'samples': samples, 'predictions': predictions, 'feature_names': feature_names, 'task': task, 'test_size': test_size})
-    if r.status_code == 200:
-        return r.json()
-    logger.error(
-        "Surrogate training failed with status %s: %s",
-        r.status_code,
-        r.text
-    )
-    return None 
-
-
-def predict(samples: list, version: int | None):  # Defaults to latest version if not specified
-    payload = {'inputs': samples}
-    if version:  # Also rejects version 0 (versions start at 1)
-        payload['version'] = version 
-    r = post(endpoint='/surrogate/predict', payload=payload)
-    if r.status_code == 200:
-        return r.json()
-    logger.error(
-        "Surrogate prediction failed with status %s: %s",
-        r.status_code,
-        r.text
-    )
-    return None 
-
-
-def find_counterfactual(sample, target, n_neighbors: int = 10000, perturbation_scale: float = 0.1, version: int | None = None, as_df: bool = True):
-    payload = {
-        'instance': sample,
-        'target_label': target,
-        'n_neighbors': n_neighbors,
-        'perturbation_scale': perturbation_scale,
-    }
-    if version:  # Also rejects version 0 (versions start at 1)
-        payload['version'] = version 
-    r = post(endpoint='/explain/counterfactual', payload=payload)
-    if r.status_code == 200:
-        payload = r.json()                                                                                                                                                            
-        if as_df:
-            if payload['counterfactual'] is None:
-                print(f"No counterfactual found: {payload.get('warning')}")
-                return None
-            df = pd.DataFrame([payload['counterfactual']], columns=payload['feature_names'])
-            for col, ftype in zip(payload['feature_names'], payload['feature_types']):
-                df[col] = _cast_column(df[col], ftype)
-            return df
-        return payload
-    logger.error(
-        "Counterfactual failed with status %s: %s",
-        r.status_code,
-        r.text
-    )
-    return None 
-
-
-def interpret_counterfactual(
-    sample: dict,
-    counterfactual: dict,
-    prediction_changed: bool,
-    exclude_from_diff: list[str] | None
-) -> str:
-    if not exclude_from_diff:
-        exclude_from_diff = list()
-    diffs = {
-        k: (sample[k], counterfactual[k])
-        for k in sample
-        if sample[k] != counterfactual[k]
-        and k not in exclude_from_diff
-    }
-    
-    if not diffs:
-        return "No meaningful differences found between sample and counterfactual."
-    
-    changes = ", ".join(
-        f"{feature} from {original} to {cf_value}"
-        for feature, (original, cf_value) in diffs.items()
-    )
-    
-    if prediction_changed:
-        return (
-            f"Changing {changes} may result in a different prediction. "
-            f"Note: this is based on a surrogate model and should be treated as approximate."
-        )
-    else:
-        return (
-            f"A counterfactual was found suggesting {changes}, however "
-            f"the original model's prediction did not change. "
-            f"This may indicate the surrogate model does not fully capture "
-            f"the original model's decision boundary in this region."
-        )
-
-
-def get_feature_importances(version: int | None = None, ):
-    params = {'version': version} if version else {}
-    r = get(endpoint='/explain/importance', params=params)
-    if r.status_code == 200:
-        return r.json()
-    logger.error(
-        "Feature importances failed with status %s: %s",
-        r.status_code,
-        r.text,
-    )
-    return None 

proxyml-0.1.1/tests/test_client.py

@@ -1,193 +0,0 @@
-import os
-from unittest.mock import MagicMock, patch
-
-import pandas as pd
-import pytest
-
-from proxyml.client import (
-    _cast_column,
-    _headers,
-    interpret_counterfactual,
-    predict,
-    put_schema,
-    synthesize_data,
-)
-
-
-# ---------------------------------------------------------------------------
-# _headers
-# ---------------------------------------------------------------------------
-
-def test_headers_raises_without_api_key(monkeypatch):
-    monkeypatch.delenv("PROXYML_API_KEY", raising=False)
-    with pytest.raises(EnvironmentError, match="PROXYML_API_KEY"):
-        _headers()
-
-
-def test_headers_returns_correct_dict(monkeypatch):
-    monkeypatch.setenv("PROXYML_API_KEY", "test-key")
-    h = _headers()
-    assert h["X-API-KEY"] == "test-key"
-    assert h["Content-Type"] == "application/json"
-
-
-# ---------------------------------------------------------------------------
-# _cast_column
-# ---------------------------------------------------------------------------
-
-def test_cast_column_continuous():
-    s = pd.Series(["1.5", "2.5", "3.5"])
-    result = _cast_column(s, "continuous")
-    assert result.dtype == float
-
-
-def test_cast_column_count():
-    s = pd.Series([1.0, 2.0, 3.0])
-    result = _cast_column(s, "count")
-    assert result.dtype == int
-
-
-def test_cast_column_numeric_ordinal():
-    s = pd.Series([1.0, 2.0, 3.0])
-    result = _cast_column(s, "numeric_ordinal")
-    assert result.dtype == int
-
-
-def test_cast_column_categorical_bool_strings():
-    s = pd.Series(["true", "false", "true"])
-    result = _cast_column(s, "categorical")
-    assert result.tolist() == [True, False, True]
-
-
-def test_cast_column_categorical_passthrough():
-    s = pd.Series(["a", "b", "c"])
-    result = _cast_column(s, "categorical")
-    assert result.tolist() == ["a", "b", "c"]
-
-
-def test_cast_column_unknown_type_passthrough():
-    s = pd.Series([1, 2, 3])
-    result = _cast_column(s, "unknown_type")
-    assert result.tolist() == [1, 2, 3]
-
-
-# ---------------------------------------------------------------------------
-# interpret_counterfactual
-# ---------------------------------------------------------------------------
-
-def test_interpret_counterfactual_prediction_changed():
-    result = interpret_counterfactual(
-        sample={"age": 30, "income": 50000},
-        counterfactual={"age": 30, "income": 75000},
-        prediction_changed=True,
-        exclude_from_diff=None,
-    )
-    assert "income from 50000 to 75000" in result
-    assert "different prediction" in result
-    assert "surrogate model" in result
-
-
-def test_interpret_counterfactual_prediction_unchanged():
-    result = interpret_counterfactual(
-        sample={"age": 30, "income": 50000},
-        counterfactual={"age": 30, "income": 75000},
-        prediction_changed=False,
-        exclude_from_diff=None,
-    )
-    assert "income from 50000 to 75000" in result
-    assert "did not change" in result
-
-
-def test_interpret_counterfactual_no_diffs():
-    result = interpret_counterfactual(
-        sample={"age": 30},
-        counterfactual={"age": 30},
-        prediction_changed=True,
-        exclude_from_diff=None,
-    )
-    assert result == "No meaningful differences found between sample and counterfactual."
-
-
-def test_interpret_counterfactual_exclude_from_diff():
-    result = interpret_counterfactual(
-        sample={"age": 30, "id": 999},
-        counterfactual={"age": 35, "id": 888},
-        prediction_changed=True,
-        exclude_from_diff=["id"],
-    )
-    assert "id" not in result
-    assert "age from 30 to 35" in result
-
-
-# ---------------------------------------------------------------------------
-# API functions (mocked HTTP)
-# ---------------------------------------------------------------------------
-
-def _mock_response(status_code, json_body):
-    r = MagicMock()
-    r.status_code = status_code
-    r.json.return_value = json_body
-    r.text = str(json_body)
-    return r
-
-
-@patch("proxyml.client.put")
-def test_put_schema_success(mock_put):
-    mock_put.return_value = _mock_response(200, {"status": "ok"})
-    result = put_schema({"features": []})
-    assert result == {"status": "ok"}
-    mock_put.assert_called_once_with(endpoint="/schema", payload={"features": []})
-
-
-@patch("proxyml.client.put")
-def test_put_schema_failure(mock_put):
-    mock_put.return_value = _mock_response(422, {"detail": "invalid"})
-    result = put_schema({"features": []})
-    assert result is None
-
-
-@patch("proxyml.client.post")
-def test_predict_success(mock_post):
-    mock_post.return_value = _mock_response(200, {"prediction": 1, "probability": 0.9})
-    result = predict(samples=[1.0, 2.0, 3.0], version=None)
-    assert result == {"prediction": 1, "probability": 0.9}
-    payload = mock_post.call_args.kwargs["payload"]
-    assert payload["inputs"] == [1.0, 2.0, 3.0]
-    assert "version" not in payload
-
-
-@patch("proxyml.client.post")
-def test_predict_with_version(mock_post):
-    mock_post.return_value = _mock_response(200, {"prediction": 0})
-    predict(samples=[1.0, 2.0], version=3)
-    payload = mock_post.call_args.kwargs["payload"]
-    assert payload["version"] == 3
-
-
-@patch("proxyml.client.post")
-def test_predict_failure_returns_none(mock_post):
-    mock_post.return_value = _mock_response(422, {"detail": "bad input"})
-    result = predict(samples=[1.0, 2.0], version=None)
-    assert result is None
-
-
-@patch("proxyml.client.post")
-def test_synthesize_data_no_sample(mock_post):
-    mock_post.return_value = _mock_response(200, {
-        "samples": [[1.0, "true"], [2.5, "false"]],
-        "feature_names": ["f_cont", "f_cat"],
-        "feature_types": ["continuous", "categorical"],
-    })
-    df = synthesize_data(num_points=2, sample=None)
-    assert isinstance(df, pd.DataFrame)
-    assert list(df.columns) == ["f_cont", "f_cat"]
-    mock_post.assert_called_once_with(
-        endpoint="/synthesize/neighbors", payload={"n": 2}
-    )
-
-
-@patch("proxyml.client.post")
-def test_synthesize_data_failure_returns_none(mock_post):
-    mock_post.return_value = _mock_response(500, {})
-    result = synthesize_data(num_points=10, sample=None)
-    assert result is None