proxyml 0.1.7__tar.gz → 0.1.9__tar.gz

{proxyml-0.1.7 → proxyml-0.1.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: proxyml
-Version: 0.1.7
+Version: 0.1.9
 Summary: Python SDK for calling the ProxyML API
 Author-email: ProxyML <contact@proxyml.ai>
 License:                                  Apache License
@@ -208,6 +208,7 @@ License-File: LICENSE
 Requires-Dist: requests>=2.28
 Requires-Dist: numpy>=1.23
 Requires-Dist: pandas>=1.5
+Requires-Dist: orjson>=3.9
 Provides-Extra: dev
 Requires-Dist: build; extra == "dev"
 Requires-Dist: twine; extra == "dev"

{proxyml-0.1.7 → proxyml-0.1.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "proxyml"
-version = "0.1.7"
+version = "0.1.9"
 description = "Python SDK for calling the ProxyML API"
 readme = "README.md"
 license = {file = "LICENSE"}
@@ -29,6 +29,7 @@ dependencies = [
     "requests>=2.28",
     "numpy>=1.23",
     "pandas>=1.5",
+    "orjson>=3.9",
 ]
 
 [project.optional-dependencies]

{proxyml-0.1.7 → proxyml-0.1.9}/src/proxyml/__init__.py

@@ -12,9 +12,11 @@ from proxyml.client import (
     interpret_counterfactual,
     get_feature_importances,
     get_model_summary,
+    get_model_schema,
     diff_models,
     list_models,
     delete_model,
+    export_surrogate,
     get_usage,
     rotate_key,
     explain_local,
@@ -40,9 +42,11 @@ __all__ = [
     "interpret_counterfactual",
     "get_feature_importances",
     "get_model_summary",
+    "get_model_schema",
     "diff_models",
     "list_models",
     "delete_model",
+    "export_surrogate",
     "get_usage",
     "rotate_key",
     "explain_local",

{proxyml-0.1.7 → proxyml-0.1.9}/src/proxyml/client.py

@@ -2,6 +2,7 @@ import logging
 logger = logging.getLogger(__name__)
 from typing import Any
 
+import orjson
 import requests
 import os
 import numpy as np
@@ -9,11 +10,13 @@ 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 _base_url() -> str:
+    return os.getenv("PROXYML_BASE_URL", "https://api.proxyml.ai/api/v1")
+
+
 def _headers() -> dict:
     """
     Constructs the request headers required for making calls to the ProxyML API.
@@ -42,8 +45,8 @@ def post(endpoint: str, payload: dict) -> requests.models.Response:
         requests Response object.
     """
     r = requests.post(
-        url=f'{PROXYML_BASE_URL}{endpoint}',
-        json=payload,
+        url=f'{_base_url()}{endpoint}',
+        data=orjson.dumps(payload, option=orjson.OPT_SERIALIZE_NUMPY),
         headers=_headers()
     )
     return r
@@ -61,8 +64,8 @@ def put(endpoint: str, payload: dict) -> requests.models.Response:
         requests Response object.
     """    
     r = requests.put(
-        url=f'{PROXYML_BASE_URL}{endpoint}',
-        json=payload,
+        url=f'{_base_url()}{endpoint}',
+        data=orjson.dumps(payload, option=orjson.OPT_SERIALIZE_NUMPY),
         headers=_headers()
     )
     return r
@@ -80,7 +83,7 @@ def get(endpoint: str, params: dict) -> requests.models.Response:
         requests Response object.
     """
     r = requests.get(
-        url=f'{PROXYML_BASE_URL}{endpoint}',
+        url=f'{_base_url()}{endpoint}',
         headers=_headers(),
         params=params
     )
@@ -98,7 +101,7 @@ def delete(endpoint: str) -> requests.models.Response:
         requests Response object.
     """
     r = requests.delete(
-        url=f'{PROXYML_BASE_URL}{endpoint}',
+        url=f'{_base_url()}{endpoint}',
         headers=_headers()
     )
     return r
@@ -186,7 +189,7 @@ def _cast_column(series: pd.Series, ftype: str) -> pd.Series:
         # 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.map(lambda v: {"true": True, "false": False}.get(str(v).lower(), v))
     return series
 
 
@@ -205,7 +208,7 @@ def synthesize_data(num_points: int = 100, sample: list | None = None, as_df: bo
     if sample is None:
         r = post(endpoint='/synthesize/neighbors', payload={'n': num_points, 'schema_name': schema_name})
     else:
-        r = post(endpoint='/synthesize/blended', payload={'n': num_points, 'instance': [col.item() for col in sample], 'schema_name': schema_name})
+        r = post(endpoint='/synthesize/blended', payload={'n': num_points, 'instance': list(sample), 'schema_name': schema_name})
     if r.status_code == 200:
         payload = r.json()
         if as_df:
@@ -270,6 +273,26 @@ def train_surrogate(
     return None
 
 
+def export_surrogate(version: str) -> Any:
+    """
+    Exports a surrogate model to JSON e.g., classes, intercept, per_class_intercepts, features, scalers, etc.; everything required
+    to reconstruct the surrogate.
+    
+    Args:
+        version (str): name of the surrogate to export
+    Returns:
+        JSON object representing the surrogate, or None if an error occurred. 
+    """
+    r = get(endpoint=f'/surrogate/models/{version}/export', params=dict())
+    if r.status_code == 200:
+        return r.json()
+    logger.error(                                                                                                                                                            
+        "Surrogate export failed (version=%s, status=%s): %s",                                                                                                             
+        version, r.status_code, r.text,                                                                                                                                      
+    )
+    return None
+
+
 def predict(sample: list, version: str | None = None) -> Any:
     """
     Calls a surrogate model to make a single prediction.
@@ -311,7 +334,7 @@ def find_counterfactual(sample, target, n_neighbors: int = 10000, perturbation_s
     """
     payload = {
         'instance': sample,
-        'target_label': target.item() if hasattr(target, 'item') else target,
+        'target_label': target,
         'n_neighbors': n_neighbors,
         'perturbation_scale': perturbation_scale,
     }
@@ -319,16 +342,16 @@ def find_counterfactual(sample, target, n_neighbors: int = 10000, perturbation_s
         payload['version'] = version
     r = post(endpoint='/explain/counterfactual', payload=payload)
     if r.status_code == 200:
-        payload = r.json()
+        response = r.json()
         if as_df:
-            if payload['counterfactual'] is None:
-                print(f"No counterfactual found: {payload.get('warning')}")
+            if response['counterfactual'] is None:
+                logger.warning("No counterfactual found: %s", response.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 = pd.DataFrame([response['counterfactual']], columns=response['feature_names'])
+            for col, ftype in zip(response['feature_names'], response['feature_types']):
                 df[col] = _cast_column(df[col], ftype)
             return df
-        return payload
+        return response
     logger.error(
         "Counterfactual failed with status %s: %s",
         r.status_code,
@@ -341,7 +364,7 @@ def interpret_counterfactual(
     sample: dict,
     counterfactual: dict,
     prediction_changed: bool,
-    exclude_from_diff: list[str] | None
+    exclude_from_diff: list[str] | None = None
 ) -> str:
     """
     Simple string interpretation of a counterfactual result. No API calls are required.
@@ -433,7 +456,7 @@ def find_counterfactuals(
     """    
     payload = {
         'instances': samples,
-        'target_label': target.item() if hasattr(target, 'item') else target,
+        'target_label': target,
         'n_neighbors': n_neighbors,
         'perturbation_scale': perturbation_scale,
     }
@@ -449,7 +472,7 @@ def find_counterfactuals(
             for item in data['results']:
                 if item['counterfactual'] is None:
                     if item.get('warning'):
-                        print(f"No counterfactual found: {item['warning']}")
+                        logger.warning("No counterfactual found: %s", item['warning'])
                     results.append(None)
                 else:
                     df = pd.DataFrame([item['counterfactual']], columns=feature_names)

{proxyml-0.1.7 → proxyml-0.1.9}/src/proxyml.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: proxyml
-Version: 0.1.7
+Version: 0.1.9
 Summary: Python SDK for calling the ProxyML API
 Author-email: ProxyML <contact@proxyml.ai>
 License:                                  Apache License
@@ -208,6 +208,7 @@ License-File: LICENSE
 Requires-Dist: requests>=2.28
 Requires-Dist: numpy>=1.23
 Requires-Dist: pandas>=1.5
+Requires-Dist: orjson>=3.9
 Provides-Extra: dev
 Requires-Dist: build; extra == "dev"
 Requires-Dist: twine; extra == "dev"

{proxyml-0.1.7 → proxyml-0.1.9}/src/proxyml.egg-info/requires.txt

@@ -1,6 +1,7 @@
 requests>=2.28
 numpy>=1.23
 pandas>=1.5
+orjson>=3.9
 
 [dev]
 build

{proxyml-0.1.7 → proxyml-0.1.9}/tests/test_client.py

@@ -6,12 +6,18 @@ import pytest
 
 from proxyml.client import (
     _cast_column,
+    _base_url,
     _headers,
     delete_model,
     delete_schema,
     diff_models,
+    explain_local,
+    export_surrogate,
     fetch_schema,
+    find_counterfactual,
     find_counterfactuals,
+    get_feature_importances,
+    get_model_schema,
     get_model_summary,
     get_usage,
     interpret_counterfactual,
@@ -30,6 +36,16 @@ from proxyml.client import (
 # _headers
 # ---------------------------------------------------------------------------
 
+def test_base_url_default(monkeypatch):
+    monkeypatch.delenv("PROXYML_BASE_URL", raising=False)
+    assert _base_url() == "https://api.proxyml.ai/api/v1"
+
+
+def test_base_url_reads_env_at_call_time(monkeypatch):
+    monkeypatch.setenv("PROXYML_BASE_URL", "https://custom.example.com/api/v1")
+    assert _base_url() == "https://custom.example.com/api/v1"
+
+
 def test_headers_raises_without_api_key(monkeypatch):
     monkeypatch.delenv("PROXYML_API_KEY", raising=False)
     with pytest.raises(EnvironmentError, match="PROXYML_API_KEY"):
@@ -71,6 +87,18 @@ def test_cast_column_categorical_bool_strings():
     assert result.tolist() == [True, False, True]
 
 
+def test_cast_column_categorical_bool_strings_capitalized():
+    s = pd.Series(["True", "False", "True"])
+    result = _cast_column(s, "categorical")
+    assert result.tolist() == [True, False, True]
+
+
+def test_cast_column_categorical_python_bools():
+    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")
@@ -552,3 +580,221 @@ def test_rotate_key_success(mock_post):
 def test_rotate_key_failure_returns_none(mock_post):
     mock_post.return_value = _mock_response(403, {"detail": "Key rotation is not available for test accounts"})
     assert rotate_key() is None
+
+
+# ---------------------------------------------------------------------------
+# export_surrogate
+# ---------------------------------------------------------------------------
+
+_EXPORT_RESPONSE = {
+    "version": "abc-123",
+    "classes": [0, 1],
+    "intercept": [0.5],
+    "per_class_intercepts": None,
+    "features": [{"name": "age", "type": "continuous"}],
+    "scalers": {"age": {"mean": 35.0, "scale": 10.0}},
+}
+
+
+@patch("proxyml.client.get")
+def test_export_surrogate_success(mock_get):
+    mock_get.return_value = _mock_response(200, _EXPORT_RESPONSE)
+    result = export_surrogate(version="abc-123")
+    assert result == _EXPORT_RESPONSE
+
+
+@patch("proxyml.client.get")
+def test_export_surrogate_calls_correct_endpoint(mock_get):
+    mock_get.return_value = _mock_response(200, _EXPORT_RESPONSE)
+    export_surrogate(version="abc-123")
+    mock_get.assert_called_once_with(endpoint="/surrogate/models/abc-123/export", params={})
+
+
+@patch("proxyml.client.get")
+def test_export_surrogate_failure_returns_none(mock_get):
+    mock_get.return_value = _mock_response(404, {"detail": "model not found"})
+    assert export_surrogate(version="no-such-version") is None
+
+
+# ---------------------------------------------------------------------------
+# find_counterfactual
+# ---------------------------------------------------------------------------
+
+_CF_RESPONSE = {
+    "counterfactual": [1.5, "yes"],
+    "feature_names": ["f_cont", "f_cat"],
+    "feature_types": ["continuous", "categorical"],
+    "outlier_score": 0.1,
+    "warning": None,
+    "task": "classification",
+    "target_label": "high",
+    "model_version": "surrogate-abc-classification",
+}
+
+_CF_RESPONSE_NONE = {
+    "counterfactual": None,
+    "feature_names": ["f_cont", "f_cat"],
+    "feature_types": ["continuous", "categorical"],
+    "outlier_score": 0.9,
+    "warning": "no counterfactual found",
+    "task": "classification",
+    "target_label": "high",
+    "model_version": "surrogate-abc-classification",
+}
+
+
+@patch("proxyml.client.post")
+def test_find_counterfactual_as_df(mock_post):
+    mock_post.return_value = _mock_response(200, _CF_RESPONSE)
+    result = find_counterfactual(sample=[1.0, "no"], target="high")
+    assert isinstance(result, pd.DataFrame)
+    assert list(result.columns) == ["f_cont", "f_cat"]
+    assert result["f_cont"].iloc[0] == 1.5
+
+
+@patch("proxyml.client.post")
+def test_find_counterfactual_raw(mock_post):
+    mock_post.return_value = _mock_response(200, _CF_RESPONSE)
+    result = find_counterfactual(sample=[1.0, "no"], target="high", as_df=False)
+    assert result == _CF_RESPONSE
+
+
+@patch("proxyml.client.post")
+def test_find_counterfactual_none_returns_none(mock_post):
+    mock_post.return_value = _mock_response(200, _CF_RESPONSE_NONE)
+    result = find_counterfactual(sample=[1.0, "no"], target="high")
+    assert result is None
+
+
+@patch("proxyml.client.post")
+def test_find_counterfactual_payload(mock_post):
+    mock_post.return_value = _mock_response(200, _CF_RESPONSE)
+    uid = "550e8400-e29b-41d4-a716-446655440000"
+    find_counterfactual(
+        sample=[1.0, "no"], target="high",
+        n_neighbors=500, perturbation_scale=0.2, version=uid,
+    )
+    payload = mock_post.call_args.kwargs["payload"]
+    assert payload["instance"] == [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_counterfactual_no_version_in_payload(mock_post):
+    mock_post.return_value = _mock_response(200, _CF_RESPONSE)
+    find_counterfactual(sample=[1.0, "no"], target="high")
+    payload = mock_post.call_args.kwargs["payload"]
+    assert "version" not in payload
+
+
+@patch("proxyml.client.post")
+def test_find_counterfactual_failure_returns_none(mock_post):
+    mock_post.return_value = _mock_response(404, {"detail": "no surrogate"})
+    assert find_counterfactual(sample=[1.0, "no"], target="high") is None
+
+
+# ---------------------------------------------------------------------------
+# get_feature_importances
+# ---------------------------------------------------------------------------
+
+_IMPORTANCES_RESPONSE = {
+    "feature_importances": [
+        {"feature": "MedInc", "coefficient": 0.82, "abs_coefficient": 0.82},
+        {"feature": "Latitude", "coefficient": -0.61, "abs_coefficient": 0.61},
+    ],
+    "per_class_importances": None,
+    "model_version": "abc-123",
+    "task": "regression",
+    "note": "Coefficients are in the scaled feature space.",
+}
+
+
+@patch("proxyml.client.get")
+def test_get_feature_importances_success(mock_get):
+    mock_get.return_value = _mock_response(200, _IMPORTANCES_RESPONSE)
+    result = get_feature_importances()
+    assert result == _IMPORTANCES_RESPONSE
+    mock_get.assert_called_once_with(endpoint="/explain/importance", params={})
+
+
+@patch("proxyml.client.get")
+def test_get_feature_importances_with_version(mock_get):
+    mock_get.return_value = _mock_response(200, _IMPORTANCES_RESPONSE)
+    get_feature_importances(version="abc-123")
+    mock_get.assert_called_once_with(endpoint="/explain/importance", params={"version": "abc-123"})
+
+
+@patch("proxyml.client.get")
+def test_get_feature_importances_failure_returns_none(mock_get):
+    mock_get.return_value = _mock_response(404, {"detail": "not found"})
+    assert get_feature_importances() is None
+
+
+# ---------------------------------------------------------------------------
+# get_model_schema
+# ---------------------------------------------------------------------------
+
+_MODEL_SCHEMA_RESPONSE = {
+    "features": [
+        {"type": "continuous", "name": "age", "mean": 35.0, "std": 10.0, "min": 18.0, "max": 90.0},
+        {"type": "categorical", "name": "gender", "valid_categories": {"M": 0.5, "F": 0.5}},
+    ]
+}
+
+
+@patch("proxyml.client.get")
+def test_get_model_schema_success(mock_get):
+    mock_get.return_value = _mock_response(200, _MODEL_SCHEMA_RESPONSE)
+    result = get_model_schema(version="abc-123")
+    assert result == _MODEL_SCHEMA_RESPONSE
+    mock_get.assert_called_once_with(endpoint="/surrogate/models/abc-123/schema", params={})
+
+
+@patch("proxyml.client.get")
+def test_get_model_schema_failure_returns_none(mock_get):
+    mock_get.return_value = _mock_response(404, {"detail": "not found"})
+    assert get_model_schema(version="no-such-version") is None
+
+
+# ---------------------------------------------------------------------------
+# explain_local
+# ---------------------------------------------------------------------------
+
+_EXPLAIN_LOCAL_RESPONSE = {
+    "prediction": 1,
+    "feature_contributions": [
+        {"feature": "MedInc", "contribution": 0.5, "abs_contribution": 0.5},
+        {"feature": "Latitude", "contribution": -0.2, "abs_contribution": 0.2},
+    ],
+    "intercept": 0.1,
+    "probabilities": [0.2, 0.8],
+    "per_class_contributions": None,
+}
+
+
+@patch("proxyml.client.post")
+def test_explain_local_success(mock_post):
+    mock_post.return_value = _mock_response(200, _EXPLAIN_LOCAL_RESPONSE)
+    result = explain_local(instance=[1.0, 2.0])
+    assert result == _EXPLAIN_LOCAL_RESPONSE
+    payload = mock_post.call_args.kwargs["payload"]
+    assert payload["instance"] == [1.0, 2.0]
+    assert "version" not in payload
+
+
+@patch("proxyml.client.post")
+def test_explain_local_with_version(mock_post):
+    mock_post.return_value = _mock_response(200, _EXPLAIN_LOCAL_RESPONSE)
+    uid = "550e8400-e29b-41d4-a716-446655440000"
+    explain_local(instance=[1.0, 2.0], version=uid)
+    payload = mock_post.call_args.kwargs["payload"]
+    assert payload["version"] == uid
+
+
+@patch("proxyml.client.post")
+def test_explain_local_failure_returns_none(mock_post):
+    mock_post.return_value = _mock_response(422, {"detail": "bad input"})
+    assert explain_local(instance=[1.0, 2.0]) is None