proxyml 0.1.8__tar.gz → 0.2.0__tar.gz

{proxyml-0.1.8 → proxyml-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: proxyml
-Version: 0.1.8
+Version: 0.2.0
 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"
@@ -220,9 +221,6 @@ Dynamic: license-file
 
 Python SDK for the [ProxyML API](https://proxyml.ai).
 
-> **Status:** Early access — server endpoints coming soon.  
-> [Request early access](mailto:contact@proxyml.ai) or star this repo to follow progress.
-
 <img width="577" height="115" alt="creditg_car_counterfactual" src="https://github.com/user-attachments/assets/8f913c95-1190-4b3c-ba7d-6690e9ebb3e0" />
 
 ## Why ProxyML?
@@ -315,7 +313,7 @@ See [`docs/quickstart.md`](docs/quickstart.md) for a full walkthrough and [`docs
 | `put_schema(schema)` | Upload a schema to the API |
 | `synthesize_data(num_points, sample, as_df)` | Generate synthetic data points |
 | `train_surrogate(samples, predictions, feature_names, task, test_size)` | Train a surrogate model |
-| `predict(samples, version)` | Score samples with the surrogate model |
+| `predict(sample, version)` | Score a single sample with the surrogate model |
 | `find_counterfactual(sample, target, ...)` | Find a counterfactual for a given sample |
 | `interpret_counterfactual(sample, counterfactual, ...)` | Generate a human-readable explanation |
 

{proxyml-0.1.8 → proxyml-0.2.0}/README.md

@@ -2,9 +2,6 @@
 
 Python SDK for the [ProxyML API](https://proxyml.ai).
 
-> **Status:** Early access — server endpoints coming soon.  
-> [Request early access](mailto:contact@proxyml.ai) or star this repo to follow progress.
-
 <img width="577" height="115" alt="creditg_car_counterfactual" src="https://github.com/user-attachments/assets/8f913c95-1190-4b3c-ba7d-6690e9ebb3e0" />
 
 ## Why ProxyML?
@@ -97,7 +94,7 @@ See [`docs/quickstart.md`](docs/quickstart.md) for a full walkthrough and [`docs
 | `put_schema(schema)` | Upload a schema to the API |
 | `synthesize_data(num_points, sample, as_df)` | Generate synthetic data points |
 | `train_surrogate(samples, predictions, feature_names, task, test_size)` | Train a surrogate model |
-| `predict(samples, version)` | Score samples with the surrogate model |
+| `predict(sample, version)` | Score a single sample with the surrogate model |
 | `find_counterfactual(sample, target, ...)` | Find a counterfactual for a given sample |
 | `interpret_counterfactual(sample, counterfactual, ...)` | Generate a human-readable explanation |
 

{proxyml-0.1.8 → proxyml-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "proxyml"
-version = "0.1.8"
+version = "0.2.0"
 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.8 → proxyml-0.2.0}/src/proxyml/__init__.py

@@ -12,12 +12,16 @@ 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,
+    explain_local_batch,
+    update_model,
 )
 from proxyml.schema import (
     get_schema,
@@ -40,12 +44,16 @@ __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",
+    "explain_local_batch",
+    "update_model",
     "get_schema",
     "gen_continuous_schema",
     "gen_categorical_schema",

{proxyml-0.1.8 → proxyml-0.2.0}/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,13 +83,32 @@ 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
     )
     return r
 
 
+def patch(endpoint: str, payload: dict) -> requests.models.Response:
+    """
+    PATCHes a request to a ProxyML API endpoint.
+
+    Args:
+        endpoint (str): ProxyML API endpoint.
+        payload (dict): JSON payload to PATCH.
+
+    Returns:
+        requests Response object.
+    """
+    r = requests.patch(
+        url=f'{_base_url()}{endpoint}',
+        data=orjson.dumps(payload, option=orjson.OPT_SERIALIZE_NUMPY),
+        headers=_headers()
+    )
+    return r
+
+
 def delete(endpoint: str) -> requests.models.Response:
     """
     DELETE request to a ProxyML API endpoint.
@@ -98,7 +120,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 +208,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 +227,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:
@@ -331,7 +353,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,
     }
@@ -339,16 +361,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,
@@ -361,7 +383,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.
@@ -453,7 +475,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,
     }
@@ -469,7 +491,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)
@@ -596,11 +618,19 @@ def rotate_key() -> str | None:
     return None
 
 
-def list_models() -> list[dict] | None:
-    """Return metadata for all trained surrogate models, newest first."""
-    r = get(endpoint='/surrogate/models', params={})
+def list_models(limit: int = 50, offset: int = 0) -> dict | None:
+    """Return a page of trained surrogate models, newest first.
+
+    Args:
+        limit (int): maximum number of models to return (1–200, default 50).
+        offset (int): number of models to skip for pagination (default 0).
+    Returns:
+        Dict with ``models`` (list of metadata dicts) and ``total`` (int,
+        total number of surrogates regardless of pagination), or None on failure.
+    """
+    r = get(endpoint='/surrogate/models', params={'limit': limit, 'offset': offset})
     if r.status_code == 200:
-        return r.json()['models']
+        return r.json()
     logger.error(
         "List models failed with status %s: %s",
         r.status_code,
@@ -609,6 +639,30 @@ def list_models() -> list[dict] | None:
     return None
 
 
+def explain_local_batch(instances: list[list], version: str | None = None) -> dict | None:
+    """Per-feature contribution breakdown for multiple instances in one call.
+
+    Args:
+        instances (list[list]): list of feature vectors, each in schema order.
+        version (str): surrogate version UUID. None uses the latest version.
+    Returns:
+        Dict with ``results`` (one contribution entry per instance), ``model_version``,
+        ``task``, and ``schema_warning``, or None on failure.
+    """
+    payload: dict = {"instances": instances}
+    if version is not None:
+        payload["version"] = version
+    r = post(endpoint="/explain/local/batch", payload=payload)
+    if r.status_code == 200:
+        return r.json()
+    logger.error(
+        "Batch local explanation failed with status %s: %s",
+        r.status_code,
+        r.text,
+    )
+    return None
+
+
 def explain_local(instance: list, version: str | None = None) -> dict | None:
     """Per-feature contribution breakdown for a single instance.
 
@@ -630,6 +684,37 @@ def explain_local(instance: list, version: str | None = None) -> dict | None:
     return None
 
 
+def update_model(version: str, name: str | None = ..., comments: str | None = ...) -> dict | None:
+    """Update the name and/or comments of a surrogate without retraining.
+
+    Pass a string to set the field, or ``None`` to clear it. Omit a parameter
+    entirely to leave that field unchanged.
+
+    Args:
+        version (str): UUID of the surrogate to update.
+        name (str | None): new name, None to clear, or omit to leave unchanged.
+        comments (str | None): new comments, None to clear, or omit to leave unchanged.
+    Returns:
+        Updated model metadata dict, or None on failure.
+    """
+    payload: dict = {}
+    if name is not ...:
+        payload["name"] = name
+    if comments is not ...:
+        payload["comments"] = comments
+    if not payload:
+        raise ValueError("Provide at least one of: name, comments")
+    r = patch(endpoint=f'/surrogate/models/{version}', payload=payload)
+    if r.status_code == 200:
+        return r.json()
+    logger.error(
+        "Update model 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}')

{proxyml-0.1.8 → proxyml-0.2.0}/src/proxyml.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: proxyml
-Version: 0.1.8
+Version: 0.2.0
 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"
@@ -220,9 +221,6 @@ Dynamic: license-file
 
 Python SDK for the [ProxyML API](https://proxyml.ai).
 
-> **Status:** Early access — server endpoints coming soon.  
-> [Request early access](mailto:contact@proxyml.ai) or star this repo to follow progress.
-
 <img width="577" height="115" alt="creditg_car_counterfactual" src="https://github.com/user-attachments/assets/8f913c95-1190-4b3c-ba7d-6690e9ebb3e0" />
 
 ## Why ProxyML?
@@ -315,7 +313,7 @@ See [`docs/quickstart.md`](docs/quickstart.md) for a full walkthrough and [`docs
 | `put_schema(schema)` | Upload a schema to the API |
 | `synthesize_data(num_points, sample, as_df)` | Generate synthetic data points |
 | `train_surrogate(samples, predictions, feature_names, task, test_size)` | Train a surrogate model |
-| `predict(samples, version)` | Score samples with the surrogate model |
+| `predict(sample, version)` | Score a single sample with the surrogate model |
 | `find_counterfactual(sample, target, ...)` | Find a counterfactual for a given sample |
 | `interpret_counterfactual(sample, counterfactual, ...)` | Generate a human-readable explanation |
 

{proxyml-0.1.8 → proxyml-0.2.0}/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.8 → proxyml-0.2.0}/tests/test_client.py

@@ -6,13 +6,19 @@ import pytest
 
 from proxyml.client import (
     _cast_column,
+    _base_url,
     _headers,
     delete_model,
     delete_schema,
     diff_models,
+    explain_local,
+    explain_local_batch,
     export_surrogate,
     fetch_schema,
+    find_counterfactual,
     find_counterfactuals,
+    get_feature_importances,
+    get_model_schema,
     get_model_summary,
     get_usage,
     interpret_counterfactual,
@@ -24,6 +30,7 @@ from proxyml.client import (
     rotate_key,
     synthesize_data,
     train_surrogate,
+    update_model,
 )
 
 
@@ -31,6 +38,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"):
@@ -72,6 +89,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")
@@ -318,11 +347,24 @@ def test_train_surrogate_omits_none_metadata(mock_post):
 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})
+               "trained_at": "2026-04-19T12:00:00", "mlflow_run_id": None}]
+    mock_get.return_value = _mock_response(200, {"models": models, "total": 1})
     result = list_models()
-    assert result == models
-    mock_get.assert_called_once_with(endpoint="/surrogate/models", params={})
+    assert result == {"models": models, "total": 1}
+    mock_get.assert_called_once_with(endpoint="/surrogate/models", params={"limit": 50, "offset": 0})
+
+
+@patch("proxyml.client.get")
+def test_list_models_pagination(mock_get):
+    models = [{"version": f"v{i}", "task": "regression", "name": None,
+               "comments": None, "feature_names": None, "metrics": None,
+               "trained_at": "2026-05-01T00:00:00", "mlflow_run_id": None}
+              for i in range(10)]
+    mock_get.return_value = _mock_response(200, {"models": models, "total": 42})
+    result = list_models(limit=10, offset=20)
+    assert result["total"] == 42
+    assert len(result["models"]) == 10
+    mock_get.assert_called_once_with(endpoint="/surrogate/models", params={"limit": 10, "offset": 20})
 
 
 @patch("proxyml.client.get")
@@ -587,3 +629,276 @@ def test_export_surrogate_calls_correct_endpoint(mock_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
+
+
+# ---------------------------------------------------------------------------
+# explain_local_batch
+# ---------------------------------------------------------------------------
+
+_EXPLAIN_LOCAL_BATCH_RESPONSE = {
+    "results": [_EXPLAIN_LOCAL_RESPONSE, _EXPLAIN_LOCAL_RESPONSE],
+    "model_version": "surrogate-abc-regression",
+    "task": "regression",
+    "schema_warning": None,
+}
+
+
+@patch("proxyml.client.post")
+def test_explain_local_batch_success(mock_post):
+    mock_post.return_value = _mock_response(200, _EXPLAIN_LOCAL_BATCH_RESPONSE)
+    instances = [[1.0, 2.0], [3.0, 4.0]]
+    result = explain_local_batch(instances=instances)
+    assert result == _EXPLAIN_LOCAL_BATCH_RESPONSE
+    payload = mock_post.call_args.kwargs["payload"]
+    assert payload["instances"] == instances
+    assert "version" not in payload
+
+
+@patch("proxyml.client.post")
+def test_explain_local_batch_with_version(mock_post):
+    mock_post.return_value = _mock_response(200, _EXPLAIN_LOCAL_BATCH_RESPONSE)
+    uid = "550e8400-e29b-41d4-a716-446655440000"
+    explain_local_batch(instances=[[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_batch_failure_returns_none(mock_post):
+    mock_post.return_value = _mock_response(422, {"detail": "bad input"})
+    assert explain_local_batch(instances=[[1.0, 2.0]]) is None
+
+
+# ---------------------------------------------------------------------------
+# update_model
+# ---------------------------------------------------------------------------
+
+@patch("proxyml.client.patch")
+def test_update_model_name(mock_patch):
+    meta = {"version": "abc-123", "task": "regression", "name": "new name",
+            "comments": None, "feature_names": None, "metrics": None,
+            "trained_at": "2026-05-07T00:00:00", "mlflow_run_id": None}
+    mock_patch.return_value = _mock_response(200, meta)
+    result = update_model("abc-123", name="new name")
+    assert result == meta
+    payload = mock_patch.call_args.kwargs["payload"]
+    assert payload == {"name": "new name"}
+
+
+@patch("proxyml.client.patch")
+def test_update_model_comments(mock_patch):
+    mock_patch.return_value = _mock_response(200, {})
+    update_model("abc-123", comments="some notes")
+    payload = mock_patch.call_args.kwargs["payload"]
+    assert payload == {"comments": "some notes"}
+
+
+@patch("proxyml.client.patch")
+def test_update_model_both_fields(mock_patch):
+    mock_patch.return_value = _mock_response(200, {})
+    update_model("abc-123", name="prod", comments="v2 data")
+    payload = mock_patch.call_args.kwargs["payload"]
+    assert payload == {"name": "prod", "comments": "v2 data"}
+
+
+@patch("proxyml.client.patch")
+def test_update_model_clear_field(mock_patch):
+    mock_patch.return_value = _mock_response(200, {})
+    update_model("abc-123", comments=None)
+    payload = mock_patch.call_args.kwargs["payload"]
+    assert payload == {"comments": None}
+
+
+def test_update_model_no_fields_raises():
+    with pytest.raises(ValueError):
+        update_model("abc-123")
+
+
+@patch("proxyml.client.patch")
+def test_update_model_failure_returns_none(mock_patch):
+    mock_patch.return_value = _mock_response(404, {"detail": "not found"})
+    assert update_model("abc-123", name="x") is None