proxyml 0.6.0__tar.gz → 0.8.0__tar.gz

{proxyml-0.6.0 → proxyml-0.8.0}/PKG-INFO

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

{proxyml-0.6.0 → proxyml-0.8.0}/pyproject.toml

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

{proxyml-0.6.0 → proxyml-0.8.0}/src/proxyml/local/__init__.py

@@ -10,6 +10,7 @@ from proxyml.local.challenger import (
     Complexity,
     Rung,
     TrainedChallenger,
+    fingerprint_labels,
     score_champion,
     to_challenger_upload,
     train_auto_challenger,
@@ -21,6 +22,7 @@ __all__ = [
     "train_auto_challenger",
     "score_champion",
     "to_challenger_upload",
+    "fingerprint_labels",
     "Complexity",
     "Rung",
     "TrainedChallenger",

{proxyml-0.6.0 → proxyml-0.8.0}/src/proxyml/local/challenger.py

@@ -10,6 +10,8 @@ training target was real ground truth or a black box's predictions.
 
 from __future__ import annotations
 
+import hashlib
+import json
 from dataclasses import dataclass, replace
 from enum import Enum
 from importlib.metadata import version as _pkg_version
@@ -121,9 +123,30 @@ class TrainedChallenger:
     n_samples_total: int
     n_samples_dropped_unlabeled: int
     population_note: str
+    target_fingerprint: str
     champion_metrics: dict[str, float] | None = None
 
 
+def fingerprint_labels(values: np.ndarray | list) -> str:
+    """Hash an array of labels, deterministically, without the data ever leaving this process.
+
+    ``.tolist()`` converts numpy scalars to native Python types before
+    serializing, so the hash doesn't drift across numpy versions with
+    different scalar repr behavior. Order is preserved (not sorted) since
+    it encodes row alignment — that's exactly what a "same data?" check
+    needs to be sensitive to.
+
+    Public so callers that score a champion decoupled from
+    ``train_challenger()`` — e.g. two separate tool calls in an MCP
+    server, with no shared Python state between them — can compute
+    ``champion_data_fingerprint`` themselves and carry it into a payload
+    assembled by hand, the same way ``to_challenger_upload(champion_labels=...)``
+    does internally.
+    """
+    canonical = json.dumps(np.asarray(values).tolist())
+    return hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+
+
 def _population_note(target_name: str, n_total: int, n_labeled: int, n_dropped: int) -> str:
     if n_dropped == 0:
         return f"Evaluated on all {n_total} row(s) — '{target_name}' had no missing values."
@@ -186,6 +209,7 @@ def train_challenger(
             and the result is attached as ``TrainedChallenger.champion_metrics``.
     """
     target_arr = np.asarray(target)
+    target_fingerprint = fingerprint_labels(target_arr)
     if champion_predictions is not None and len(champion_predictions) != len(target_arr):
         raise ValueError(
             f"champion_predictions must have one entry per row of target "
@@ -264,6 +288,7 @@ def train_challenger(
         n_samples_total=n_total,
         n_samples_dropped_unlabeled=n_dropped,
         population_note=_population_note(target_name, n_total, n_labeled, n_dropped),
+        target_fingerprint=target_fingerprint,
         champion_metrics=champion_metrics,
     )
 
@@ -286,6 +311,13 @@ def score_champion(
 
     Returns ``{"f1":..., "accuracy":...}`` for classification or ``{"r2":...}``
     for regression — the same shape as ``TrainedChallenger.metrics``.
+
+    If you're calling this decoupled from ``train_challenger()`` (i.e. not
+    via its ``champion_predictions=`` param), pass the same ``labels`` you
+    used here as ``champion_labels=`` to ``to_challenger_upload()`` — that
+    lets the upload endpoint confirm the challenger and champion were
+    actually scored on the same data, catching an accidental mismatched
+    file before it silently produces a misleading comparison.
     """
     return score_predictions(np.asarray(labels), np.asarray(predictions), task=task)
 
@@ -295,6 +327,7 @@ def to_challenger_upload(
     *,
     n_samples: int | None = None,
     champion_metrics: dict[str, float] | None = None,
+    champion_labels: np.ndarray | list | None = None,
     sdk_version: str | None = None,
     proxyml_core_version: str | None = None,
 ) -> dict[str, Any]:
@@ -327,11 +360,21 @@ def to_challenger_upload(
         champion_metrics: the champion's real-world performance, from
             ``score_champion()`` — same metric keys as ``result.metrics``.
             Defaults to ``result.champion_metrics``.
+        champion_labels: the ``labels`` array you passed to a standalone
+            ``score_champion()`` call, if ``champion_metrics`` didn't come
+            from ``train_challenger()``'s internal ``champion_predictions=``
+            path. Used only to compute ``champion_data_fingerprint`` — the
+            labels themselves are never included in the payload. If
+            ``champion_metrics`` resolves from ``result.champion_metrics``
+            instead, the fingerprint defaults to ``result.target_fingerprint``
+            (guaranteed identical, since that internal path scores against
+            the exact same data).
         sdk_version: defaults to the installed ``proxyml`` version.
         proxyml_core_version: defaults to the installed ``proxyml-core`` version.
     """
     if n_samples is None:
         n_samples = result.n_samples_total - result.n_samples_dropped_unlabeled
+    used_internal_champion_metrics = champion_metrics is None
     if champion_metrics is None:
         champion_metrics = result.champion_metrics
     if sdk_version is None:
@@ -352,6 +395,11 @@ def to_challenger_upload(
     }
     if champion_metrics is not None:
         payload["champion_metrics"] = champion_metrics
+        payload["challenger_data_fingerprint"] = result.target_fingerprint
+        if champion_labels is not None:
+            payload["champion_data_fingerprint"] = fingerprint_labels(champion_labels)
+        elif used_internal_champion_metrics:
+            payload["champion_data_fingerprint"] = result.target_fingerprint
     return payload
 
 

{proxyml-0.6.0 → proxyml-0.8.0}/src/proxyml.egg-info/PKG-INFO

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

{proxyml-0.6.0 → proxyml-0.8.0}/tests/test_local_challenger.py

@@ -8,6 +8,7 @@ from proxyml.local import (
     Complexity,
     LADDERS,
     TrainedChallenger,
+    fingerprint_labels,
     score_champion,
     to_challenger_upload,
     train_auto_challenger,
@@ -402,3 +403,92 @@ def test_train_auto_challenger_passes_immutable_cols_to_get_schema():
     called_kwargs = mock_get_schema.call_args.kwargs
     assert list(called_df.columns) == list(features_df.columns)
     assert called_kwargs["immutable_cols"] == ["age"]
+
+
+def test_target_fingerprint_is_deterministic_for_identical_data():
+    df = _labeled_df(seed=29)
+    result_a = train_auto_challenger(df, "approved", task="classification")
+    result_b = train_auto_challenger(df, "approved", task="classification")
+
+    assert result_a.target_fingerprint == result_b.target_fingerprint
+
+
+def test_target_fingerprint_differs_for_different_data():
+    df_a = _labeled_df(seed=29)
+    df_b = _labeled_df(seed=30)
+    result_a = train_auto_challenger(df_a, "approved", task="classification")
+    result_b = train_auto_challenger(df_b, "approved", task="classification")
+
+    assert result_a.target_fingerprint != result_b.target_fingerprint
+
+
+def test_to_challenger_upload_includes_matching_fingerprints_on_internal_champion_path():
+    df = _labeled_df(seed=31)
+    champion_predictions = df["approved"].tolist()
+    result = train_auto_challenger(
+        df, "approved", task="classification", champion_predictions=champion_predictions
+    )
+
+    payload = to_challenger_upload(result)
+
+    assert payload["challenger_data_fingerprint"] == result.target_fingerprint
+    assert payload["champion_data_fingerprint"] == result.target_fingerprint
+
+
+def test_to_challenger_upload_champion_labels_fingerprint_for_decoupled_path():
+    df = _labeled_df(seed=32)
+    target = df["approved"]
+    result = train_challenger(df, target, _schema(), task="classification")
+    champion_metrics = score_champion(target, target, task="classification")
+
+    payload = to_challenger_upload(result, champion_metrics=champion_metrics, champion_labels=target)
+
+    assert payload["challenger_data_fingerprint"] == result.target_fingerprint
+    assert payload["champion_data_fingerprint"] == result.target_fingerprint
+
+
+def test_to_challenger_upload_champion_labels_fingerprint_differs_for_different_data():
+    df = _labeled_df(seed=33)
+    target = df["approved"]
+    result = train_challenger(df, target, _schema(), task="classification")
+    champion_metrics = score_champion(target, target, task="classification")
+    other_labels = ~target
+
+    payload = to_challenger_upload(
+        result, champion_metrics=champion_metrics, champion_labels=other_labels
+    )
+
+    assert payload["challenger_data_fingerprint"] != payload["champion_data_fingerprint"]
+
+
+def test_to_challenger_upload_omits_champion_fingerprint_without_labels_or_internal_path():
+    df = _labeled_df(seed=34)
+    target = df["approved"]
+    result = train_challenger(df, target, _schema(), task="classification")
+    champion_metrics = score_champion(target, target, task="classification")
+
+    payload = to_challenger_upload(result, champion_metrics=champion_metrics)
+
+    assert payload["challenger_data_fingerprint"] == result.target_fingerprint
+    assert "champion_data_fingerprint" not in payload
+
+
+def test_to_challenger_upload_without_champion_metrics_omits_fingerprints():
+    df = _labeled_df(seed=35)
+    result = train_auto_challenger(df, "approved", task="classification")
+
+    payload = to_challenger_upload(result)
+
+    assert "challenger_data_fingerprint" not in payload
+    assert "champion_data_fingerprint" not in payload
+
+
+def test_fingerprint_labels_is_public_and_matches_target_fingerprint():
+    """Exercises the exact use case this was made public for: a caller with
+    no TrainedChallenger in hand (e.g. a decoupled score_champion() call)
+    computing the same fingerprint train_challenger() would have."""
+    df = _labeled_df(seed=36)
+    target = df["approved"]
+    result = train_challenger(df, target, _schema(), task="classification")
+
+    assert fingerprint_labels(target) == result.target_fingerprint