proxyml 0.2.0__tar.gz → 0.2.2__tar.gz

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

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

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

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

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

@@ -1,4 +1,5 @@
 from proxyml.client import (
+    health_check,
     put_schema,
     fetch_schema,
     list_schemas,
@@ -31,6 +32,7 @@ from proxyml.schema import (
 )
 
 __all__ = [
+    "health_check",
     "put_schema",
     "fetch_schema",
     "list_schemas",

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

@@ -1,16 +1,26 @@
 import logging
-logger = logging.getLogger(__name__)
+import os
 from typing import Any
 
 import orjson
-import requests
-import os
 import numpy as np
 import pandas as pd
+import requests
 from pandas.api.types import is_float_dtype, is_integer_dtype
 
+logger = logging.getLogger(__name__)
 
 _BOOL_STRINGS = {"true", "false"}
+_TIMEOUT = 120
+
+
+class _ErrorResponse:
+    """Returned by HTTP helpers when a network-level error occurs."""
+    status_code = 0
+    text = ""
+
+    def json(self) -> dict:
+        return {}
 
 
 def _base_url() -> str:
@@ -33,7 +43,7 @@ def _headers() -> dict:
     }
 
 
-def post(endpoint: str, payload: dict) -> requests.models.Response:
+def post(endpoint: str, payload: dict) -> requests.models.Response | _ErrorResponse:
     """
     POSTs a request to a ProxyML API endpoint.
 
@@ -44,53 +54,65 @@ def post(endpoint: str, payload: dict) -> requests.models.Response:
     Returns:
         requests Response object.
     """
-    r = requests.post(
-        url=f'{_base_url()}{endpoint}',
-        data=orjson.dumps(payload, option=orjson.OPT_SERIALIZE_NUMPY),
-        headers=_headers()
-    )
-    return r
+    try:
+        return requests.post(
+            url=f'{_base_url()}{endpoint}',
+            data=orjson.dumps(payload, option=orjson.OPT_SERIALIZE_NUMPY),
+            headers=_headers(),
+            timeout=_TIMEOUT,
+        )
+    except requests.exceptions.RequestException as exc:
+        logger.error("Network error POSTing to %s: %s", endpoint, exc)
+        return _ErrorResponse()
 
 
-def put(endpoint: str, payload: dict) -> requests.models.Response:
+def put(endpoint: str, payload: dict) -> requests.models.Response | _ErrorResponse:
     """
     PUTs a request to a ProxyML API endpoint.
 
     Args:
         endpoint (str): ProxyML API endpoint.  PROXYML_BASE_URL is prepended e.g. use endpoint='/schemas' not 'https://api.proxyml.ai/api/v1/schemas'.
-        payload (dict): JSON payload to POST.
+        payload (dict): JSON payload to PUT.
 
     Returns:
         requests Response object.
-    """    
-    r = requests.put(
-        url=f'{_base_url()}{endpoint}',
-        data=orjson.dumps(payload, option=orjson.OPT_SERIALIZE_NUMPY),
-        headers=_headers()
-    )
-    return r
+    """
+    try:
+        return requests.put(
+            url=f'{_base_url()}{endpoint}',
+            data=orjson.dumps(payload, option=orjson.OPT_SERIALIZE_NUMPY),
+            headers=_headers(),
+            timeout=_TIMEOUT,
+        )
+    except requests.exceptions.RequestException as exc:
+        logger.error("Network error PUTting to %s: %s", endpoint, exc)
+        return _ErrorResponse()
 
 
-def get(endpoint: str, params: dict) -> requests.models.Response:
+def get(endpoint: str, params: dict | None = None) -> requests.models.Response | _ErrorResponse:
     """
     GETs a request to a ProxyML API endpoint.
 
     Args:
         endpoint (str): ProxyML API endpoint.  PROXYML_BASE_URL is prepended e.g. use endpoint='/schemas' not 'https://api.proxyml.ai/api/v1/schemas'.
-        params (dict): JSON payload to POST.
+        params (dict): query parameters.
 
     Returns:
         requests Response object.
     """
-    r = requests.get(
-        url=f'{_base_url()}{endpoint}',
-        headers=_headers(),
-        params=params
-    )
-    return r
+    try:
+        return requests.get(
+            url=f'{_base_url()}{endpoint}',
+            headers=_headers(),
+            params=params,
+            timeout=_TIMEOUT,
+        )
+    except requests.exceptions.RequestException as exc:
+        logger.error("Network error GETting %s: %s", endpoint, exc)
+        return _ErrorResponse()
 
 
-def patch(endpoint: str, payload: dict) -> requests.models.Response:
+def patch(endpoint: str, payload: dict) -> requests.models.Response | _ErrorResponse:
     """
     PATCHes a request to a ProxyML API endpoint.
 
@@ -101,15 +123,19 @@ def patch(endpoint: str, payload: dict) -> requests.models.Response:
     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
+    try:
+        return requests.patch(
+            url=f'{_base_url()}{endpoint}',
+            data=orjson.dumps(payload, option=orjson.OPT_SERIALIZE_NUMPY),
+            headers=_headers(),
+            timeout=_TIMEOUT,
+        )
+    except requests.exceptions.RequestException as exc:
+        logger.error("Network error PATCHing %s: %s", endpoint, exc)
+        return _ErrorResponse()
 
 
-def delete(endpoint: str) -> requests.models.Response:
+def delete(endpoint: str) -> requests.models.Response | _ErrorResponse:
     """
     DELETE request to a ProxyML API endpoint.
 
@@ -119,20 +145,24 @@ def delete(endpoint: str) -> requests.models.Response:
     Returns:
         requests Response object.
     """
-    r = requests.delete(
-        url=f'{_base_url()}{endpoint}',
-        headers=_headers()
-    )
-    return r
+    try:
+        return requests.delete(
+            url=f'{_base_url()}{endpoint}',
+            headers=_headers(),
+            timeout=_TIMEOUT,
+        )
+    except requests.exceptions.RequestException as exc:
+        logger.error("Network error DELETEing %s: %s", endpoint, exc)
+        return _ErrorResponse()
 
 
-def put_schema(schema: dict, name: str = "default") -> Any:
+def put_schema(schema: dict, name: str) -> Any:
     """
     Uploads a data schema.
 
     Args:
         schema (dict): data schema object
-        name (str): optional name for the schema, defaults to "default".
+        name (str): name for the schema.
     Returns:
         API response JSON object, or None if the return code was not 200.
     """
@@ -148,7 +178,7 @@ def put_schema(schema: dict, name: str = "default") -> Any:
     return None
 
 
-def fetch_schema(name: str = "default") -> dict | None:
+def fetch_schema(name: str) -> dict | None:
     """Retrieve a stored feature schema by name."""
     r = get(endpoint=f'/schema/{name}', params={})
     if r.status_code == 200:
@@ -212,7 +242,7 @@ def _cast_column(series: pd.Series, ftype: str) -> pd.Series:
     return series
 
 
-def synthesize_data(num_points: int = 100, sample: list | None = None, as_df: bool = True, schema_name: str = "default") -> Any:
+def synthesize_data(num_points: int = 100, sample: list | None = None, as_df: bool = True, *, schema_name: str) -> Any:
     """
     Synthesizes data based on a data schema.
 
@@ -220,7 +250,7 @@ def synthesize_data(num_points: int = 100, sample: list | None = None, as_df: bo
         num_points (int): number of samples to synthesize, defaults to 100.
         sample (list): if specified, synthesized data will be a blend of samples generated from the schema and a number of perturbations around this sample. If not specified (default), all synthesized data is generated by sampling from the data schema.
         as_df (bool): if True (default), data are returned as a pandas DataFrame.
-        schema_name (str): name of the data schema to use to generate the data, defaults to "default."
+        schema_name (str): name of the data schema to use to generate the data.
     Returns:
         JSON object representing the synthesized data if as_df=False, a pandas DataFrame if as_df=True, or None if an error occurred.
     """
@@ -250,7 +280,8 @@ def train_surrogate(
         feature_names: list[str] | None,
         task: str = 'auto',
         test_size: float = 0.2,
-        schema_name: str = "default",
+        *,
+        schema_name: str,
         name: str | None = None,
         comments: str | None = None,
     ) -> Any:
@@ -263,7 +294,7 @@ def train_surrogate(
         feature_names (list): names of the features (columns) in the data.
         task (str): specifies the modeling task, one of "classification," "regression," or "auto" in which case ProxyML will attempt to automatically determine the modeling task.
         test_size (float): fraction of the data to set aside for test data, defaults to 0.2.
-        schema_name (str): name of the data schema to use, defaults to "default."
+        schema_name (str): name of the data schema to use.
         name (str): an optional name for the surrogate.
         comments (str): an optional comment string for the surrogate.
     Returns:
@@ -345,7 +376,7 @@ def find_counterfactual(sample, target, n_neighbors: int = 10000, perturbation_s
         sample (list): point around which neighbors will be found.
         target (Any): the desired prediction outcome, can be a string or number for classification or a target predicted value for regression.
         n_neighbors (int): the number of neighbors to search, defaults to 10000.
-        pertubation_scale (float): controls the "wiggle" in the features around the provided sample. Defaults to 0.1.
+        perturbation_scale (float): controls the "wiggle" in the features around the provided sample. Defaults to 0.1.
         version (str): name of the surrogate model to run, defaults to "default."
         as_df (bool): if True, return the counterfactual as a dataframe. If False, returns JSON object.
     Returns:
@@ -467,7 +498,7 @@ def find_counterfactuals(
         samples (list): list of points around which neighbors will be found.
         target (Any): the desired prediction outcome, can be a string or number for classification or a target predicted value for regression.
         n_neighbors (int): the number of neighbors to search, defaults to 10000.
-        pertubation_scale (float): controls the "wiggle" in the features around the provided sample. Defaults to 0.1.
+        perturbation_scale (float): controls the "wiggle" in the features around the provided sample. Defaults to 0.1.
         version (str): name of the surrogate model to run, defaults to "default."
         as_df (bool): if True, return the counterfactual as a dataframe. If False, returns JSON object.
     Returns:
@@ -592,6 +623,23 @@ def get_feature_importances(version: str | None = None) -> Any:
     return None
 
 
+def health_check() -> dict | None:
+    """Check API connectivity and version. Does not require authentication and does not count against usage quota.
+
+    Returns:
+        Dict with ``status``, ``model_loaded``, and ``version``, or None on failure.
+    """
+    try:
+        r = requests.get(url=f'{_base_url()}/health', timeout=_TIMEOUT)
+    except requests.exceptions.RequestException as exc:
+        logger.error("Network error calling /health: %s", exc)
+        return None
+    if r.status_code == 200:
+        return r.json()
+    logger.error("Health check failed with status %s: %s", r.status_code, r.text)
+    return None
+
+
 def get_usage() -> dict | None:
     """Return current tier, usage counts, and quota for the authenticated user."""
     r = get(endpoint='/account/usage', params={})

{proxyml-0.2.0 → proxyml-0.2.2}/src/proxyml/schema.py

@@ -1,11 +1,11 @@
 import logging
-logger = logging.getLogger(__name__)
 
-import os
 import numpy as np
 import pandas as pd
 from pandas.api.types import is_float_dtype, is_integer_dtype
 
+logger = logging.getLogger(__name__)
+
 
 def gen_continuous_schema(s: pd.Series, name: str | None = None) -> dict:
     """
@@ -73,6 +73,11 @@ def get_schema(df: pd.DataFrame, immutable_cols: list[str] | None) -> dict:
     Returns:
         data schema as dict. Review and adjust as needed.
     """
+    if immutable_cols:
+        unknown = set(immutable_cols) - set(df.columns)
+        if unknown:
+            logger.warning("immutable_cols not found in DataFrame and will be ignored: %s", sorted(unknown))
+
     schema = {
         'features': list(),
         '_note': (

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

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

{proxyml-0.2.0 → proxyml-0.2.2}/tests/test_client.py

@@ -3,11 +3,13 @@ from unittest.mock import MagicMock, patch
 
 import pandas as pd
 import pytest
+import requests
 
 from proxyml.client import (
     _cast_column,
     _base_url,
     _headers,
+    health_check,
     delete_model,
     delete_schema,
     diff_models,
@@ -34,6 +36,31 @@ from proxyml.client import (
 )
 
 
+# ---------------------------------------------------------------------------
+# health_check
+# ---------------------------------------------------------------------------
+
+@patch("proxyml.client.requests.get")
+def test_health_check_success(mock_get):
+    mock_get.return_value = _mock_response(200, {"status": "ok", "model_loaded": True, "version": "0.1.0"})
+    result = health_check()
+    assert result == {"status": "ok", "model_loaded": True, "version": "0.1.0"}
+    mock_get.assert_called_once()
+    assert mock_get.call_args.kwargs["url"].endswith("/health")
+    assert "headers" not in mock_get.call_args.kwargs  # no auth header
+
+
+@patch("proxyml.client.requests.get")
+def test_health_check_failure_returns_none(mock_get):
+    mock_get.return_value = _mock_response(503, {"detail": "unavailable"})
+    assert health_check() is None
+
+
+@patch("proxyml.client.requests.get", side_effect=requests.exceptions.ConnectionError("connection refused"))
+def test_health_check_network_error_returns_none(mock_get):
+    assert health_check() is None
+
+
 # ---------------------------------------------------------------------------
 # _headers
 # ---------------------------------------------------------------------------
@@ -174,11 +201,11 @@ def _mock_response(status_code, json_body):
 
 
 @patch("proxyml.client.put")
-def test_put_schema_default(mock_put):
+def test_put_schema_success(mock_put):
     mock_put.return_value = _mock_response(200, {"features": []})
-    result = put_schema({"features": []})
+    result = put_schema({"features": []}, name="myschema")
     assert result == {"features": []}
-    mock_put.assert_called_once_with(endpoint="/schema/default", payload={"features": []})
+    mock_put.assert_called_once_with(endpoint="/schema/myschema", payload={"features": []})
 
 
 @patch("proxyml.client.put")
@@ -191,7 +218,7 @@ def test_put_schema_named(mock_put):
 @patch("proxyml.client.put")
 def test_put_schema_failure(mock_put):
     mock_put.return_value = _mock_response(422, {"detail": "invalid"})
-    result = put_schema({"features": []})
+    result = put_schema({"features": []}, name="myschema")
     assert result is None
 
 
@@ -200,11 +227,11 @@ def test_put_schema_failure(mock_put):
 # ---------------------------------------------------------------------------
 
 @patch("proxyml.client.get")
-def test_fetch_schema_default(mock_get):
+def test_fetch_schema_success(mock_get):
     mock_get.return_value = _mock_response(200, {"features": [{"type": "continuous", "name": "age"}]})
-    result = fetch_schema()
+    result = fetch_schema(name="myschema")
     assert result["features"][0]["name"] == "age"
-    mock_get.assert_called_once_with(endpoint="/schema/default", params={})
+    mock_get.assert_called_once_with(endpoint="/schema/myschema", params={})
 
 
 @patch("proxyml.client.get")
@@ -282,12 +309,12 @@ def test_synthesize_data_no_sample(mock_post):
         "feature_names": ["f_cont", "f_cat"],
         "feature_types": ["continuous", "categorical"],
     })
-    df = synthesize_data(num_points=2, sample=None)
+    df = synthesize_data(num_points=2, sample=None, schema_name="myschema")
     assert isinstance(df, pd.DataFrame)
     assert list(df.columns) == ["f_cont", "f_cat"]
     payload = mock_post.call_args.kwargs["payload"]
     assert payload["n"] == 2
-    assert payload["schema_name"] == "default"
+    assert payload["schema_name"] == "myschema"
 
 
 @patch("proxyml.client.post")
@@ -303,7 +330,7 @@ def test_synthesize_data_named_schema(mock_post):
 @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)
+    result = synthesize_data(num_points=10, sample=None, schema_name="myschema")
     assert result is None
 
 
@@ -312,16 +339,16 @@ 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,
+        "feature_names": None, "metrics": {"r2": 0.95}, "warnings": [],
     })
     result = train_surrogate(
         samples=[[1.0, 2.0]], predictions=[3.0],
-        feature_names=None, name="v1", comments="test run",
+        feature_names=None, schema_name="myschema", name="v1", comments="test run",
     )
     payload = mock_post.call_args.kwargs["payload"]
     assert payload["name"] == "v1"
     assert payload["comments"] == "test run"
-    assert payload["schema_name"] == "default"
+    assert payload["schema_name"] == "myschema"
     assert result["version"] == "abc-123"
     assert result["trained_at"] == "2026-04-19T12:00:00"
 
@@ -337,7 +364,7 @@ def test_train_surrogate_named_schema(mock_post):
 @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)
+    train_surrogate(samples=[[1.0]], predictions=[1.0], feature_names=None, schema_name="myschema")
     payload = mock_post.call_args.kwargs["payload"]
     assert "name" not in payload
     assert "comments" not in payload