proxyml 0.2.2__tar.gz → 0.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: proxyml
-Version: 0.2.2
+Version: 0.3.0
 Summary: Python SDK for calling the ProxyML API
 Author-email: ProxyML <contact@proxyml.ai>
 License:                                  Apache License
@@ -209,6 +209,9 @@ Requires-Dist: requests>=2.28
 Requires-Dist: numpy>=1.23
 Requires-Dist: pandas>=1.5
 Requires-Dist: orjson>=3.9
+Requires-Dist: proxyml-core>=0.1
+Provides-Extra: local
+Requires-Dist: proxyml-core[modeling]>=0.1; extra == "local"
 Provides-Extra: dev
 Requires-Dist: build; extra == "dev"
 Requires-Dist: twine; extra == "dev"
@@ -236,6 +239,12 @@ statistics are uploaded — your data stays yours.
 pip install proxyml
 ```
 
+Want to train a challenger model locally, with no round-trip to the API? Install the `local` extra (adds scikit-learn and scipy):
+
+```bash
+pip install 'proxyml[local]'
+```
+
 ## Setup
 
 ProxyML requires an API key. Set it as an environment variable before importing the package:
@@ -261,11 +270,12 @@ from proxyml import get_schema
 df = pd.read_csv("data.csv")
 schema = get_schema(df, immutable_cols=["age", "gender"])
 
-# 2. Upload the schema
-proxyml.put_schema(schema)
+# 2. Upload the schema under a name — synthesis and training reference it by name
+SCHEMA_NAME = "my_schema"
+proxyml.put_schema(schema, name=SCHEMA_NAME)
 
 # 3. Generate synthetic training data
-synth_df = proxyml.synthesize_data(num_points=500)
+synth_df = proxyml.synthesize_data(num_points=500, schema_name=SCHEMA_NAME)
 
 # 4. Score synthetic data with your black-box model
 predictions = my_model.predict(synth_df.values.tolist())
@@ -275,6 +285,7 @@ proxyml.train_surrogate(
     samples=synth_df.values.tolist(),
     predictions=predictions,
     feature_names=list(synth_df.columns),
+    schema_name=SCHEMA_NAME,
 )
 
 # 6. Find a counterfactual explanation
@@ -301,6 +312,8 @@ See [`docs/quickstart.md`](docs/quickstart.md) for a full walkthrough and [`docs
 
 **Surrogate model** — A fast, interpretable model trained to approximate your black-box model's behavior on synthetic data. Once trained, it can be queried directly via the ProxyML API.
 
+**Challenger model** — Trained the same way as a surrogate, but locally (`proxyml.local`, no round-trip to the API) and against either real ground-truth labels (a genuine challenger to compare against a champion model) or a black box's predictions (a surrogate/explainer). Its export is structurally identical to a server-trained surrogate's, so the two can be compared and scored with the exact same arithmetic.
+
 **Counterfactual explanation** — Given a prediction, a counterfactual is the minimal change to input features that would produce a different prediction. It answers: *"What would have to be different for the outcome to change?"*
 
 **Schema** — Describes the statistical properties of each feature (type, range, distribution). Used to generate realistic synthetic data and constrain counterfactual search.
@@ -309,13 +322,17 @@ See [`docs/quickstart.md`](docs/quickstart.md) for a full walkthrough and [`docs
 
 | Function | Description |
 |---|---|
-| `get_schema(df, immutable_cols)` | Generate a schema dict from a DataFrame |
-| `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 |
+| `get_schema(df, immutable_cols)` | Infer a `FeatureSchema` from a DataFrame |
+| `put_schema(schema, name)` | Upload a schema to the API under a name |
+| `synthesize_data(num_points, sample, as_df, schema_name)` | Generate synthetic data points |
+| `train_surrogate(samples, predictions, feature_names, task, test_size, schema_name)` | Train a surrogate model |
+| `train_auto_surrogate(data, target_col, ...)` | Load data + train a surrogate in one call, skipping synthesis |
+| `export_surrogate(version)` | Export a surrogate for offline scoring via `predict_from_export` |
 | `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.local.train_challenger(df, target, schema, ...)` | Train a challenger model locally — no API round-trip (`pip install 'proxyml[local]'`) |
+| `proxyml.local.train_auto_challenger(data, target_col, ...)` | Load data + train a local challenger in one call |
 
 Full documentation: [`docs/api.md`](docs/api.md)
 
@@ -323,6 +340,10 @@ Full documentation: [`docs/api.md`](docs/api.md)
 
 - [`examples/basic_usage.py`](examples/basic_usage.py) — Schema upload, data synthesis, surrogate training
 - [`examples/counterfactual_example.py`](examples/counterfactual_example.py) — Counterfactual search and interpretation
+- [`examples/regression_example.py`](examples/regression_example.py) — Regression with immutable features
+- [`examples/multiclass_example.py`](examples/multiclass_example.py) — Multi-class classification with per-class feature importances
+- [`examples/testing_example.py`](examples/testing_example.py) — Using a surrogate as a reference model in CI
+- [`examples/surrogate_export_example.py`](examples/surrogate_export_example.py) — Exporting a surrogate and reproducing its predictions locally
 
 ## License
 

{proxyml-0.2.2 → proxyml-0.3.0}/README.md

@@ -17,6 +17,12 @@ statistics are uploaded — your data stays yours.
 pip install proxyml
 ```
 
+Want to train a challenger model locally, with no round-trip to the API? Install the `local` extra (adds scikit-learn and scipy):
+
+```bash
+pip install 'proxyml[local]'
+```
+
 ## Setup
 
 ProxyML requires an API key. Set it as an environment variable before importing the package:
@@ -42,11 +48,12 @@ from proxyml import get_schema
 df = pd.read_csv("data.csv")
 schema = get_schema(df, immutable_cols=["age", "gender"])
 
-# 2. Upload the schema
-proxyml.put_schema(schema)
+# 2. Upload the schema under a name — synthesis and training reference it by name
+SCHEMA_NAME = "my_schema"
+proxyml.put_schema(schema, name=SCHEMA_NAME)
 
 # 3. Generate synthetic training data
-synth_df = proxyml.synthesize_data(num_points=500)
+synth_df = proxyml.synthesize_data(num_points=500, schema_name=SCHEMA_NAME)
 
 # 4. Score synthetic data with your black-box model
 predictions = my_model.predict(synth_df.values.tolist())
@@ -56,6 +63,7 @@ proxyml.train_surrogate(
     samples=synth_df.values.tolist(),
     predictions=predictions,
     feature_names=list(synth_df.columns),
+    schema_name=SCHEMA_NAME,
 )
 
 # 6. Find a counterfactual explanation
@@ -82,6 +90,8 @@ See [`docs/quickstart.md`](docs/quickstart.md) for a full walkthrough and [`docs
 
 **Surrogate model** — A fast, interpretable model trained to approximate your black-box model's behavior on synthetic data. Once trained, it can be queried directly via the ProxyML API.
 
+**Challenger model** — Trained the same way as a surrogate, but locally (`proxyml.local`, no round-trip to the API) and against either real ground-truth labels (a genuine challenger to compare against a champion model) or a black box's predictions (a surrogate/explainer). Its export is structurally identical to a server-trained surrogate's, so the two can be compared and scored with the exact same arithmetic.
+
 **Counterfactual explanation** — Given a prediction, a counterfactual is the minimal change to input features that would produce a different prediction. It answers: *"What would have to be different for the outcome to change?"*
 
 **Schema** — Describes the statistical properties of each feature (type, range, distribution). Used to generate realistic synthetic data and constrain counterfactual search.
@@ -90,13 +100,17 @@ See [`docs/quickstart.md`](docs/quickstart.md) for a full walkthrough and [`docs
 
 | Function | Description |
 |---|---|
-| `get_schema(df, immutable_cols)` | Generate a schema dict from a DataFrame |
-| `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 |
+| `get_schema(df, immutable_cols)` | Infer a `FeatureSchema` from a DataFrame |
+| `put_schema(schema, name)` | Upload a schema to the API under a name |
+| `synthesize_data(num_points, sample, as_df, schema_name)` | Generate synthetic data points |
+| `train_surrogate(samples, predictions, feature_names, task, test_size, schema_name)` | Train a surrogate model |
+| `train_auto_surrogate(data, target_col, ...)` | Load data + train a surrogate in one call, skipping synthesis |
+| `export_surrogate(version)` | Export a surrogate for offline scoring via `predict_from_export` |
 | `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.local.train_challenger(df, target, schema, ...)` | Train a challenger model locally — no API round-trip (`pip install 'proxyml[local]'`) |
+| `proxyml.local.train_auto_challenger(data, target_col, ...)` | Load data + train a local challenger in one call |
 
 Full documentation: [`docs/api.md`](docs/api.md)
 
@@ -104,6 +118,10 @@ Full documentation: [`docs/api.md`](docs/api.md)
 
 - [`examples/basic_usage.py`](examples/basic_usage.py) — Schema upload, data synthesis, surrogate training
 - [`examples/counterfactual_example.py`](examples/counterfactual_example.py) — Counterfactual search and interpretation
+- [`examples/regression_example.py`](examples/regression_example.py) — Regression with immutable features
+- [`examples/multiclass_example.py`](examples/multiclass_example.py) — Multi-class classification with per-class feature importances
+- [`examples/testing_example.py`](examples/testing_example.py) — Using a surrogate as a reference model in CI
+- [`examples/surrogate_export_example.py`](examples/surrogate_export_example.py) — Exporting a surrogate and reproducing its predictions locally
 
 ## License
 

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "proxyml"
-version = "0.2.2"
+version = "0.3.0"
 description = "Python SDK for calling the ProxyML API"
 readme = "README.md"
 license = {file = "LICENSE"}
@@ -30,15 +30,19 @@ dependencies = [
     "numpy>=1.23",
     "pandas>=1.5",
     "orjson>=3.9",
+    "proxyml-core>=0.1",
 ]
 
 [project.optional-dependencies]
+local = [
+    "proxyml-core[modeling]>=0.1",
+]
 dev = [
     "build",
     "twine",
     "pytest",
-    "black",    
-    "ruff",     
+    "black",
+    "ruff",
 ]
 
 [project.urls]

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

@@ -6,6 +6,7 @@ from proxyml.client import (
     delete_schema,
     synthesize_data,
     train_surrogate,
+    train_auto_surrogate,
     predict,
     predict_batch,
     find_counterfactual,
@@ -24,12 +25,7 @@ from proxyml.client import (
     explain_local_batch,
     update_model,
 )
-from proxyml.schema import (
-    get_schema,
-    gen_continuous_schema,
-    gen_categorical_schema,
-    gen_discrete_schema,
-)
+from proxyml.schema_builder import get_schema
 
 __all__ = [
     "health_check",
@@ -39,6 +35,7 @@ __all__ = [
     "delete_schema",
     "synthesize_data",
     "train_surrogate",
+    "train_auto_surrogate",
     "predict",
     "predict_batch",
     "find_counterfactual",
@@ -57,7 +54,4 @@ __all__ = [
     "explain_local_batch",
     "update_model",
     "get_schema",
-    "gen_continuous_schema",
-    "gen_categorical_schema",
-    "gen_discrete_schema",
 ]

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

@@ -1,5 +1,6 @@
 import logging
 import os
+from pathlib import Path
 from typing import Any
 
 import orjson
@@ -8,6 +9,10 @@ import pandas as pd
 import requests
 from pandas.api.types import is_float_dtype, is_integer_dtype
 
+from proxyml.schema_builder import get_schema
+from proxyml_core.export import SurrogateExport
+from proxyml_core.schema import FeatureSchema
+
 logger = logging.getLogger(__name__)
 
 _BOOL_STRINGS = {"true", "false"}
@@ -156,20 +161,20 @@ def delete(endpoint: str) -> requests.models.Response | _ErrorResponse:
         return _ErrorResponse()
 
 
-def put_schema(schema: dict, name: str) -> Any:
+def put_schema(schema: FeatureSchema, name: str) -> FeatureSchema | None:
     """
     Uploads a data schema.
 
     Args:
-        schema (dict): data schema object
+        schema (FeatureSchema): data schema object, e.g. from get_schema()
         name (str): name for the schema.
     Returns:
-        API response JSON object, or None if the return code was not 200.
+        The stored FeatureSchema, or None if the return code was not 200.
     """
-    r = put(endpoint=f'/schema/{name}', payload=schema)
+    r = put(endpoint=f'/schema/{name}', payload=schema.to_dict())
     if r.status_code == 200:
         logger.info("Schema '%s' uploaded successfully", name)
-        return r.json()
+        return FeatureSchema.from_dict(r.json())
     logger.error(
         "Schema upload failed with status %s: %s",
         r.status_code,
@@ -178,11 +183,14 @@ def put_schema(schema: dict, name: str) -> Any:
     return None
 
 
-def fetch_schema(name: str) -> dict | None:
+def fetch_schema(name: str) -> FeatureSchema | None:
     """Retrieve a stored feature schema by name."""
     r = get(endpoint=f'/schema/{name}', params={})
     if r.status_code == 200:
-        return r.json()
+        payload = r.json()
+        if payload.get('schema_warning'):
+            logger.warning(payload['schema_warning'])
+        return FeatureSchema.from_dict(payload)
     logger.error(
         "Fetch schema failed with status %s: %s",
         r.status_code,
@@ -323,22 +331,84 @@ def train_surrogate(
     return None
 
 
-def export_surrogate(version: str) -> Any:
+def train_auto_surrogate(
+        data: str | Path | pd.DataFrame,
+        target_col: str,
+        feature_names: list[str] | None = None,
+        task: str = 'auto',
+        test_size: float = 0.2,
+        *,
+        schema_name: str,
+        immutable_cols: list[str] | None = None,
+        name: str | None = None,
+        comments: str | None = None,
+    ) -> Any:
     """
-    Exports a surrogate model to JSON e.g., classes, intercept, per_class_intercepts, features, scalers, etc.; everything required
-    to reconstruct the surrogate.
-    
+    Loads data that already contains samples and a target/prediction column,
+    infers and uploads a feature schema, and trains a server-side surrogate
+    against target_col — all in one call.
+
+    Assumes `data` already contains the samples you want to train on and the
+    value to predict for each one (real ground truth or a black box's
+    predictions), so it skips synthesize_data() entirely. If you need the
+    server to generate synthetic samples for you to score first, use
+    synthesize_data() and train_surrogate() directly instead (see
+    examples/basic_usage.py).
+
+    Args:
+        data (str | Path | DataFrame): a CSV path, or an already-loaded DataFrame,
+            containing both the feature columns and target_col.
+        target_col (str): name of the column to train against.
+        feature_names (list): subset of feature columns to train on; omit for all.
+            (The full sample width is always uploaded — feature_names only tells
+            the surrogate which columns to actually fit on.)
+        task (str): specifies the modeling task, one of "classification," "regression," or "auto".
+        test_size (float): fraction of the data to set aside for test data, defaults to 0.2.
+        schema_name (str): name to store the inferred schema under.
+        immutable_cols (list): passed through to get_schema().
+        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 schema upload
+        or training failed.
+    """
+    df = data if isinstance(data, pd.DataFrame) else pd.read_csv(data)
+    target = df[target_col]
+    features_df = df.drop(columns=[target_col])
+
+    schema = get_schema(features_df, immutable_cols=immutable_cols)
+    if put_schema(schema, name=schema_name) is None:
+        return None
+
+    return train_surrogate(
+        samples=features_df.values.tolist(),
+        predictions=target.tolist(),
+        feature_names=feature_names,
+        task=task,
+        test_size=test_size,
+        schema_name=schema_name,
+        name=name,
+        comments=comments,
+    )
+
+
+def export_surrogate(version: str) -> SurrogateExport | None:
+    """
+    Exports a surrogate model — classes, intercept, per_class_intercepts, features,
+    scalers, etc.; everything required to reconstruct the surrogate. Score it locally,
+    with zero sklearn, via proxyml_core.export.predict_from_export(export, sample).
+
     Args:
         version (str): name of the surrogate to export
     Returns:
-        JSON object representing the surrogate, or None if an error occurred. 
+        SurrogateExport, 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 SurrogateExport.from_dict(r.json())
+    logger.error(
+        "Surrogate export failed (version=%s, status=%s): %s",
+        version, r.status_code, r.text,
     )
     return None
 
@@ -560,18 +630,21 @@ def get_model_summary(version: str | None = None) -> Any:
     return None
 
 
-def get_model_schema(version: str) -> Any:
+def get_model_schema(version: str) -> FeatureSchema | None:
     """
     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.
+        The model's FeatureSchema, or None if an error occurred.
     """
     r = get(endpoint=f'/surrogate/models/{version}/schema', params=dict())
     if r.status_code == 200:
-        return r.json()
+        payload = r.json()
+        if payload.get('schema_warning'):
+            logger.warning(payload['schema_warning'])
+        return FeatureSchema.from_dict(payload)
     logger.error(
         "Schema retrieval failed with status %s: %s",
         r.status_code,

proxyml-0.3.0/src/proxyml/local/__init__.py

@@ -0,0 +1,24 @@
+try:
+    import proxyml_core.modeling  # noqa: F401
+except ImportError as exc:
+    raise ImportError(
+        "Local challenger training requires the 'local' extra: pip install 'proxyml[local]'"
+    ) from exc
+
+from proxyml.local.challenger import (
+    LADDERS,
+    Complexity,
+    Rung,
+    TrainedChallenger,
+    train_auto_challenger,
+    train_challenger,
+)
+
+__all__ = [
+    "train_challenger",
+    "train_auto_challenger",
+    "Complexity",
+    "Rung",
+    "TrainedChallenger",
+    "LADDERS",
+]