proxyml 0.1.6__tar.gz → 0.1.8__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: proxyml
-Version: 0.1.6
+Version: 0.1.8
 Summary: Python SDK for calling the ProxyML API
 Author-email: ProxyML <contact@proxyml.ai>
 License:                                  Apache License
@@ -223,6 +223,8 @@ 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?
 
 Most explainability tools require sending your data to a third-party server. 

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

@@ -5,6 +5,8 @@ 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?
 
 Most explainability tools require sending your data to a third-party server. 

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

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

{proxyml-0.1.6 → proxyml-0.1.8}/src/proxyml/client.py

@@ -1,5 +1,6 @@
 import logging
 logger = logging.getLogger(__name__)
+from typing import Any
 
 import requests
 import os
@@ -14,6 +15,9 @@ _BOOL_STRINGS = {"true", "false"}
 
 
 def _headers() -> dict:
+    """
+    Constructs the request headers required for making calls to the ProxyML API.
+    """
     api_key = os.getenv("PROXYML_API_KEY", "")
     if not api_key:
         raise EnvironmentError(
@@ -27,6 +31,16 @@ def _headers() -> dict:
 
 
 def post(endpoint: str, payload: dict) -> requests.models.Response:
+    """
+    POSTs 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.
+
+    Returns:
+        requests Response object.
+    """
     r = requests.post(
         url=f'{PROXYML_BASE_URL}{endpoint}',
         json=payload,
@@ -36,6 +50,16 @@ def post(endpoint: str, payload: dict) -> requests.models.Response:
 
 
 def put(endpoint: str, payload: dict) -> requests.models.Response:
+    """
+    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.
+
+    Returns:
+        requests Response object.
+    """    
     r = requests.put(
         url=f'{PROXYML_BASE_URL}{endpoint}',
         json=payload,
@@ -45,6 +69,16 @@ def put(endpoint: str, payload: dict) -> requests.models.Response:
 
 
 def get(endpoint: str, params: dict) -> requests.models.Response:
+    """
+    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.
+
+    Returns:
+        requests Response object.
+    """
     r = requests.get(
         url=f'{PROXYML_BASE_URL}{endpoint}',
         headers=_headers(),
@@ -54,6 +88,15 @@ def get(endpoint: str, params: dict) -> requests.models.Response:
 
 
 def delete(endpoint: str) -> requests.models.Response:
+    """
+    DELETE 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'.
+
+    Returns:
+        requests Response object.
+    """
     r = requests.delete(
         url=f'{PROXYML_BASE_URL}{endpoint}',
         headers=_headers()
@@ -61,7 +104,16 @@ def delete(endpoint: str) -> requests.models.Response:
     return r
 
 
-def put_schema(schema: dict, name: str = "default"):
+def put_schema(schema: dict, name: str = "default") -> Any:
+    """
+    Uploads a data schema.
+
+    Args:
+        schema (dict): data schema object
+        name (str): optional name for the schema, defaults to "default".
+    Returns:
+        API response JSON object, or None if the return code was not 200.
+    """
     r = put(endpoint=f'/schema/{name}', payload=schema)
     if r.status_code == 200:
         logger.info("Schema '%s' uploaded successfully", name)
@@ -117,6 +169,15 @@ def delete_schema(name: str) -> bool:
 
 
 def _cast_column(series: pd.Series, ftype: str) -> pd.Series:
+    """
+    Casts a pandas Series to a Python type based on a specified ftype.
+
+    Args:
+        series (pd.Series): data to cast
+        ftype (str): type of conversion, one of "continuous", "count", "numeric_ordinal", "categorical", or "categorical_ordinal".
+    Returns:
+        pd.Series cast to specific ftype.
+    """
     if ftype in ("continuous",):
         return series.astype(float)
     if ftype in ("count", "numeric_ordinal"):
@@ -129,7 +190,18 @@ 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"):
+def synthesize_data(num_points: int = 100, sample: list | None = None, as_df: bool = True, schema_name: str = "default") -> Any:
+    """
+    Synthesizes data based on a data schema.
+
+    Args:
+        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."
+    Returns:
+        JSON object representing the synthesized data if as_df=False, a pandas DataFrame if as_df=True, or None if an error occurred.
+    """
     if sample is None:
         r = post(endpoint='/synthesize/neighbors', payload={'n': num_points, 'schema_name': schema_name})
     else:
@@ -159,7 +231,22 @@ def train_surrogate(
         schema_name: str = "default",
         name: str | None = None,
         comments: str | None = None,
-    ):
+    ) -> Any:
+    """
+    Trains a surrogate model to predict a "black box" model's predictions.
+
+    Args:
+        samples (list): list of samples that were provided to the black box for inference, e.g. the output from synthesize_data().
+        predictions (list): the inferences on the samples, made by the black box model.
+        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."
+        name (str): an optional name for the surrogate.
+        comments (str): an optional comment string for the surrogate.
+    Returns:
+        JSON object denoting surrogate training result, or None if an error occurred.
+    """
     payload = {
         'samples': samples,
         'predictions': predictions,
@@ -183,7 +270,36 @@ def train_surrogate(
     return None
 
 
-def predict(sample: list, version: str | None = 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.
+    
+    Args:
+        sample (list): a single sample
+        version (str): name of the surrogate model to use.
+    Returns:
+        JSON object denoting result of the surrogate prediction, or None if an error occurred.
+    """
     payload = {'inputs': sample}
     if version is not None:
         payload['version'] = version
@@ -198,7 +314,21 @@ def predict(sample: list, version: str | None = None):
     return None
 
 
-def find_counterfactual(sample, target, n_neighbors: int = 10000, perturbation_scale: float = 0.1, version: str | 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) -> Any:
+    """
+    Attempts to find a counterfactual sample: a sample that is near to a given sample in featurespace, but with a specified prediction. Counterfactuals are
+    not guaranteed i.e., it's possible to not be able to find a nearby sample with the desired label / target value.
+
+    Args:
+        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.
+        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:
+        JSON counterfactual if as_df=False, pandas DataFrame if as_df=True, None if an error occurred.
+    """
     payload = {
         'instance': sample,
         'target_label': target.item() if hasattr(target, 'item') else target,
@@ -233,6 +363,17 @@ def interpret_counterfactual(
     prediction_changed: bool,
     exclude_from_diff: list[str] | None
 ) -> str:
+    """
+    Simple string interpretation of a counterfactual result. No API calls are required.
+
+    Args:
+        sample (dict): the original prediction i.e. the sample from which counterfactuals were drawn.
+        counterfactual (dict): the counterfactual returned by ProxyML.
+        prediction_changed (bool): True if the prediction changed, False if it did not (or didn't change as much as desired).
+        exclude_from_diff (list): list of keys that should not be considered in interpreting the counterfactual.
+    Returns:
+        String summarizing the differences (if any) observed between sample and counterfactual.
+    """
     if not exclude_from_diff:
         exclude_from_diff = list()
     diffs = {
@@ -264,7 +405,16 @@ def interpret_counterfactual(
         )
 
 
-def predict_batch(samples: list[list], version: str | None = None):
+def predict_batch(samples: list[list], version: str | None = None) -> Any:
+    """
+    Calls a surrogate model to make batch predictions.
+    
+    Args:
+        sample (list): a list of samples
+        version (str): name of the surrogate model to use.
+    Returns:
+        JSON object denoting result of the surrogate prediction, or None if an error occurred.
+    """
     payload = {'inputs': samples}
     if version is not None:
         payload['version'] = version
@@ -286,7 +436,21 @@ def find_counterfactuals(
     perturbation_scale: float = 0.1,
     version: str | None = None,
     as_dfs: bool = True,
-):
+) -> Any:
+    """
+    Attempts to find counterfactual samples: samples that are near a given sample in featurespace, but with a specified prediction. Counterfactuals are
+    not guaranteed i.e., it's possible to not be able to find a nearby sample with the desired label / target value.
+
+    Args:
+        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.
+        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:
+        JSON counterfactuals if as_df=False, pandas DataFrame if as_df=True, None if an error occurred.
+    """    
     payload = {
         'instances': samples,
         'target_label': target.item() if hasattr(target, 'item') else target,
@@ -322,7 +486,15 @@ def find_counterfactuals(
     return None
 
 
-def get_model_summary(version: str | None = None):
+def get_model_summary(version: str | None = None) -> Any:
+    """
+    Retrieves a summary of a given surrogate.
+
+    Args:
+        version (str): name of the surrogate model to retrieve.
+    Returns:
+        JSON object summarizing the surrogate, or None if an error occurred.
+    """
     params = {'version': version} if version is not None else {}
     r = get(endpoint='/explain/summary', params=params)
     if r.status_code == 200:
@@ -335,7 +507,37 @@ def get_model_summary(version: str | None = None):
     return None
 
 
-def diff_models(version_a: str, version_b: str):
+def get_model_schema(version: str) -> Any:
+    """
+    Retrieves the schema associated with a particular surrogate.
+    
+    Args:
+        version (str): name of the surrogate model.
+    Returns:
+        JSON object representation of the model's schema, or None if an error occurred.
+    """
+    r = get(endpoint=f'/surrogate/models/{version}/schema', params=dict())
+    if r.status_code == 200:
+        return r.json()
+    logger.error(
+        "Schema retrieval failed with status %s: %s",
+        r.status_code,
+        r.text,
+    )
+    return None
+
+
+def diff_models(version_a: str, version_b: str) -> Any:
+    """
+    Returns a summary of the differences between two surrogates.  The surrogates must have the same model task (i.e. a classification model can't be compared with a regression model), and they must
+    have at least one feature in common.
+
+    Args:
+        version_a (str): name of one surrogate
+        version_b (str): name of the other surrogate
+    Returns:
+        JSON object summarizing the difference between version_a and version_b, or None if an error occurred.
+    """
     r = get(endpoint='/explain/diff', params={'version_a': version_a, 'version_b': version_b})
     if r.status_code == 200:
         return r.json()
@@ -347,7 +549,15 @@ def diff_models(version_a: str, version_b: str):
     return None
 
 
-def get_feature_importances(version: str | None = None):
+def get_feature_importances(version: str | None = None) -> Any:
+    """
+    Convenience function to directly retrieve feature importances from a surrogate model.
+
+    Args:
+        version (str): ID of the surrogate
+    Returns:
+        JSON object of feature importances, or None if an error occurred.
+    """
     params = {'version': version} if version is not None else {}
     r = get(endpoint='/explain/importance', params=params)
     if r.status_code == 200:

{proxyml-0.1.6 → proxyml-0.1.8}/src/proxyml/schema.py

@@ -8,6 +8,15 @@ from pandas.api.types import is_float_dtype, is_integer_dtype
 
 
 def gen_continuous_schema(s: pd.Series, name: str | None = None) -> dict:
+    """
+    Generates a schema entry for continuous data.
+
+    Args:
+        s (pandas Series): data to characterize
+        name (str): optional name for the entry, defaults to s.name.
+    Returns:
+        schema dict
+    """
     return {
         'type': 'continuous',
         'name': name or s.name,
@@ -19,6 +28,15 @@ def gen_continuous_schema(s: pd.Series, name: str | None = None) -> dict:
 
 
 def gen_categorical_schema(s: pd.Series, name: str | None = None) -> dict:
+    """
+    Generates a schema entry for categorical data.
+
+    Args:
+        s (pandas Series): data to characterize
+        name (str): optional name for the entry, defaults to s.name.
+    Returns:
+        schema dict
+    """
     counts = s.value_counts(normalize=True)                                                                                                                                         
     return {                                        
         'type': 'categorical',
@@ -28,6 +46,15 @@ def gen_categorical_schema(s: pd.Series, name: str | None = None) -> dict:
 
 
 def gen_discrete_schema(s: pd.Series, name: str | None = None) -> dict:
+    """
+    Generates a schema entry for discrete data.
+
+    Args:
+        s (pandas Series): data to characterize
+        name (str): optional name for the entry, defaults to s.name.
+    Returns:
+        schema dict
+    """
     return {                                        
         'type': 'count',
         'name': name or s.name,    
@@ -37,6 +64,15 @@ def gen_discrete_schema(s: pd.Series, name: str | None = None) -> dict:
 
 
 def get_schema(df: pd.DataFrame, immutable_cols: list[str] | None) -> dict:
+    """
+    Generates a data schema for a pandas DataFrame, based on the data types of the columns.
+
+    Args:
+        df (pandas DataFrame): data to characterize
+        immutable_cols (list): list of columns to consider immutable. These columns will have schema entries, but the surrogate will _not_ use them for inference.
+    Returns:
+        data schema as dict. Review and adjust as needed.
+    """
     schema = {
         'features': list(),
         '_note': (

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: proxyml
-Version: 0.1.6
+Version: 0.1.8
 Summary: Python SDK for calling the ProxyML API
 Author-email: ProxyML <contact@proxyml.ai>
 License:                                  Apache License
@@ -223,6 +223,8 @@ 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?
 
 Most explainability tools require sending your data to a third-party server. 

{proxyml-0.1.6 → proxyml-0.1.8}/tests/test_client.py

@@ -10,6 +10,7 @@ from proxyml.client import (
     delete_model,
     delete_schema,
     diff_models,
+    export_surrogate,
     fetch_schema,
     find_counterfactuals,
     get_model_summary,
@@ -552,3 +553,37 @@ 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