proxyml 0.1.2__tar.gz → 0.1.3__tar.gz

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

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

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

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

{proxyml-0.1.2 → 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.2 → proxyml-0.1.3}/src/proxyml/client.py

@@ -53,6 +53,14 @@ def get(endpoint: str, params: dict) -> requests.models.Response:
     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:
@@ -66,48 +74,61 @@ def put_schema(schema: dict):
     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"):                                                                                                                                         
+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"):                                                                                                                               
+    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                                                                                                                                                                     
-                                                            
-                                                                                                                                                                                        
+        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})                                                                                                         
+    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:                                                                                                                                                                     
+        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']):                                                                                                
+            for col, ftype in zip(payload['feature_names'], payload['feature_types']):
                 df[col] = _cast_column(df[col], ftype)
-            return df                                                                                                                                                                 
+            return df
         return payload
     logger.error(
         "Data synthesis failed with status %s: %s",
         r.status_code,
         r.text
     )
-    return None 
+    return None
 
 
 def train_surrogate(
-        samples: list, 
-        predictions: list, 
+        samples: list,
+        predictions: list,
         feature_names: list[str] | None,
-        task: str = 'auto', 
-        test_size: float = 0.2
+        task: str = 'auto',
+        test_size: float = 0.2,
+        name: str | None = None,
+        comments: str | None = None,
     ):
-    r = post(endpoint='/surrogate/train', payload={'samples': samples, 'predictions': predictions, 'feature_names': feature_names, 'task': task, 'test_size': test_size})
+    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(
@@ -115,13 +136,13 @@ def train_surrogate(
         r.status_code,
         r.text
     )
-    return None 
+    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 
+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()
@@ -130,21 +151,21 @@ def predict(samples: list, version: int | None):  # Defaults to latest version i
         r.status_code,
         r.text
     )
-    return None 
+    return None
 
 
-def find_counterfactual(sample, target, n_neighbors: int = 10000, perturbation_scale: float = 0.1, version: int | None = None, as_df: bool = True):
+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,  # handle numpy scalars
+        'target_label': target.item() if hasattr(target, 'item') else target,
         'n_neighbors': n_neighbors,
         'perturbation_scale': perturbation_scale,
-    }    
-    if version:  # Also rejects version 0 (versions start at 1)
-        payload['version'] = version 
+    }
+    if version is not None:
+        payload['version'] = version
     r = post(endpoint='/explain/counterfactual', payload=payload)
     if r.status_code == 200:
-        payload = r.json()                                                                                                                                                            
+        payload = r.json()
         if as_df:
             if payload['counterfactual'] is None:
                 print(f"No counterfactual found: {payload.get('warning')}")
@@ -159,7 +180,7 @@ def find_counterfactual(sample, target, n_neighbors: int = 10000, perturbation_s
         r.status_code,
         r.text
     )
-    return None 
+    return None
 
 
 def interpret_counterfactual(
@@ -176,15 +197,15 @@ def interpret_counterfactual(
         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. "
@@ -199,8 +220,91 @@ def interpret_counterfactual(
         )
 
 
-def get_feature_importances(version: int | None = None, ):
-    params = {'version': version} if version else {}
+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()
@@ -209,4 +313,33 @@ def get_feature_importances(version: int | None = None, ):
         r.status_code,
         r.text,
     )
-    return None 
+    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.2 → proxyml-0.1.3}/src/proxyml.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: proxyml
-Version: 0.1.2
+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.2/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