proxyml 0.1.9__tar.gz → 0.2.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: proxyml
-Version: 0.1.9
+Version: 0.2.0
 Summary: Python SDK for calling the ProxyML API
 Author-email: ProxyML <contact@proxyml.ai>
 License:                                  Apache License
@@ -221,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?
@@ -316,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.9 → 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.9 → proxyml-0.2.0}/pyproject.toml

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

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

@@ -20,6 +20,8 @@ from proxyml.client import (
     get_usage,
     rotate_key,
     explain_local,
+    explain_local_batch,
+    update_model,
 )
 from proxyml.schema import (
     get_schema,
@@ -50,6 +52,8 @@ __all__ = [
     "get_usage",
     "rotate_key",
     "explain_local",
+    "explain_local_batch",
+    "update_model",
     "get_schema",
     "gen_continuous_schema",
     "gen_categorical_schema",

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

@@ -90,6 +90,25 @@ def get(endpoint: str, params: dict) -> requests.models.Response:
     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.
@@ -599,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,
@@ -612,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.
 
@@ -633,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.9 → proxyml-0.2.0}/src/proxyml.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: proxyml
-Version: 0.1.9
+Version: 0.2.0
 Summary: Python SDK for calling the ProxyML API
 Author-email: ProxyML <contact@proxyml.ai>
 License:                                  Apache License
@@ -221,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?
@@ -316,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.9 → proxyml-0.2.0}/tests/test_client.py

@@ -12,6 +12,7 @@ from proxyml.client import (
     delete_schema,
     diff_models,
     explain_local,
+    explain_local_batch,
     export_surrogate,
     fetch_schema,
     find_counterfactual,
@@ -29,6 +30,7 @@ from proxyml.client import (
     rotate_key,
     synthesize_data,
     train_surrogate,
+    update_model,
 )
 
 
@@ -345,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")
@@ -798,3 +813,92 @@ def test_explain_local_with_version(mock_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