everestapi 0.2.2__tar.gz → 0.2.4__tar.gz

{everestapi-0.2.2 → everestapi-0.2.4}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 EverestQuant
+Copyright (c) 2026 Everesteer
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

{everestapi-0.2.2/src/everestapi.egg-info → everestapi-0.2.4}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: everestapi
-Version: 0.2.2
-Summary: Python SDK for the EverestQuant prediction tournament platform
-Author-email: EverestQuant <support@everesteer.ai>
+Version: 0.2.4
+Summary: Python SDK for the Everesteer prediction tournament platform
+Author-email: Everesteer <support@everesteer.ai>
 License-Expression: MIT
 Project-URL: Homepage, https://everesteer.ai
 Project-URL: Documentation, https://docs.everesteer.ai
@@ -26,11 +26,13 @@ Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: pytest-httpx>=0.34.0; extra == "dev"
 Provides-Extra: mcp
 Requires-Dist: mcp>=1.0; extra == "mcp"
+Provides-Extra: viz
+Requires-Dist: plotnine>=0.13; extra == "viz"
 Dynamic: license-file
 
 # everestapi
 
-Python SDK for the [EverestQuant](https://everesteer.ai) prediction tournament platform.
+Python SDK for the [Everesteer](https://everesteer.ai) prediction tournament platform.
 
 ```bash
 pip install everestapi
@@ -109,9 +111,39 @@ api.download_dataset(universe="futures", split="train")
 api.download_benchmark(universe="futures", split="validation")
 api.get_dataset_info(universe="futures")
 api.get_diagnostics(model_id="my-model")
+
+# Validation diagnostics: eiq_validation_example_preds.parquet is the upload template
+# (same `id` set, your own `prediction` column).
+api.download_dataset(universe="futures", split="validation_example_preds")
 api.submit_validation_diagnostics(model_id="my-model", predictions=df)
 ```
 
+### Plotting (optional `viz` extra)
+
+The `viz` extra installs [plotnine](https://plotnine.org/) (a grammar-of-graphics /
+ggplot2 port). Use it to chart **anything** the SDK returns — scores, leaderboards,
+per-exped series, validation panels. `everestapi.plots.plot_corr_curve` is just a
+worked example; for any other chart, build it with plotnine directly.
+
+```bash
+pip install 'everestapi[viz]'
+```
+
+```python
+# Convenience helper — cumulative-CORR curve to a PNG:
+from everestapi.plots import plot_corr_curve
+corr = api.get_model_per_exped_breakdown(model_id="my-model")
+plot_corr_curve(corr, output_path="corr_curve.png")
+
+# Any other chart — plotnine on SDK data (matplotlib Agg backend, headless-safe):
+import matplotlib; matplotlib.use("Agg")
+import pandas as pd, plotnine as p9
+lb = api.get_leaderboard(period="30d")
+df = pd.DataFrame(lb["entries"])
+(p9.ggplot(df, p9.aes("model_name", "total_payout")) + p9.geom_col()
+ + p9.coord_flip()).save("leaderboard.png", verbose=False)
+```
+
 ### Serverless compute
 
 ```python
@@ -178,7 +210,7 @@ with EverestAPI(api_key="...") as api:
 
 ## Disclaimers
 
-- **Not financial advice.** EverestQuant tournaments are prediction competitions. Nothing in this SDK or on the platform constitutes investment advice, a solicitation, or a recommendation to buy or sell any financial instrument.
+- **Not financial advice.** Everesteer tournaments are prediction competitions. Nothing in this SDK or on the platform constitutes investment advice, a solicitation, or a recommendation to buy or sell any financial instrument.
 - **Testnet / beta.** The staking system and compute platform are in beta. Smart contract addresses, API endpoints, and payout mechanics may change without notice.
 - **API stability.** This SDK targets API v1. Breaking changes will be communicated via the platform changelog and will follow semver once the SDK reaches 1.0.
 - **Data is obfuscated.** All features and instrument identifiers served by the API are obfuscated. Attempting to reverse-engineer or de-obfuscate data violates the platform terms of service.

{everestapi-0.2.2 → everestapi-0.2.4}/README.md

@@ -1,6 +1,6 @@
 # everestapi
 
-Python SDK for the [EverestQuant](https://everesteer.ai) prediction tournament platform.
+Python SDK for the [Everesteer](https://everesteer.ai) prediction tournament platform.
 
 ```bash
 pip install everestapi
@@ -79,9 +79,39 @@ api.download_dataset(universe="futures", split="train")
 api.download_benchmark(universe="futures", split="validation")
 api.get_dataset_info(universe="futures")
 api.get_diagnostics(model_id="my-model")
+
+# Validation diagnostics: eiq_validation_example_preds.parquet is the upload template
+# (same `id` set, your own `prediction` column).
+api.download_dataset(universe="futures", split="validation_example_preds")
 api.submit_validation_diagnostics(model_id="my-model", predictions=df)
 ```
 
+### Plotting (optional `viz` extra)
+
+The `viz` extra installs [plotnine](https://plotnine.org/) (a grammar-of-graphics /
+ggplot2 port). Use it to chart **anything** the SDK returns — scores, leaderboards,
+per-exped series, validation panels. `everestapi.plots.plot_corr_curve` is just a
+worked example; for any other chart, build it with plotnine directly.
+
+```bash
+pip install 'everestapi[viz]'
+```
+
+```python
+# Convenience helper — cumulative-CORR curve to a PNG:
+from everestapi.plots import plot_corr_curve
+corr = api.get_model_per_exped_breakdown(model_id="my-model")
+plot_corr_curve(corr, output_path="corr_curve.png")
+
+# Any other chart — plotnine on SDK data (matplotlib Agg backend, headless-safe):
+import matplotlib; matplotlib.use("Agg")
+import pandas as pd, plotnine as p9
+lb = api.get_leaderboard(period="30d")
+df = pd.DataFrame(lb["entries"])
+(p9.ggplot(df, p9.aes("model_name", "total_payout")) + p9.geom_col()
+ + p9.coord_flip()).save("leaderboard.png", verbose=False)
+```
+
 ### Serverless compute
 
 ```python
@@ -148,7 +178,7 @@ with EverestAPI(api_key="...") as api:
 
 ## Disclaimers
 
-- **Not financial advice.** EverestQuant tournaments are prediction competitions. Nothing in this SDK or on the platform constitutes investment advice, a solicitation, or a recommendation to buy or sell any financial instrument.
+- **Not financial advice.** Everesteer tournaments are prediction competitions. Nothing in this SDK or on the platform constitutes investment advice, a solicitation, or a recommendation to buy or sell any financial instrument.
 - **Testnet / beta.** The staking system and compute platform are in beta. Smart contract addresses, API endpoints, and payout mechanics may change without notice.
 - **API stability.** This SDK targets API v1. Breaking changes will be communicated via the platform changelog and will follow semver once the SDK reaches 1.0.
 - **Data is obfuscated.** All features and instrument identifiers served by the API are obfuscated. Attempting to reverse-engineer or de-obfuscate data violates the platform terms of service.

{everestapi-0.2.2 → everestapi-0.2.4}/pyproject.toml

@@ -5,11 +5,11 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "everestapi"
 dynamic = ["version"]
-description = "Python SDK for the EverestQuant prediction tournament platform"
+description = "Python SDK for the Everesteer prediction tournament platform"
 readme = "README.md"
 license = "MIT"
 requires-python = ">=3.10"
-authors = [{ name = "EverestQuant", email = "support@everesteer.ai" }]
+authors = [{ name = "Everesteer", email = "support@everesteer.ai" }]
 keywords = ["quant", "tournament", "prediction", "staking", "machine-learning"]
 classifiers = [
     "Development Status :: 4 - Beta",
@@ -31,6 +31,9 @@ dev = ["pytest>=8.0", "pytest-httpx>=0.34.0"]
 # MCP server (`python -m everestapi.mcp`). Optional — the server falls back to a
 # built-in JSON-RPC stdio loop when the official `mcp` SDK isn't installed.
 mcp = ["mcp>=1.0"]
+# Plotting helpers (`everestapi.plots`). Heavy — pulls matplotlib/pandas/numpy/
+# scipy/statsmodels/mizani. Optional: the SDK and MCP server never import it.
+viz = ["plotnine>=0.13"]
 
 [project.scripts]
 everestapi = "everestapi.cli:cli"

{everestapi-0.2.2 → everestapi-0.2.4}/src/everestapi/__init__.py

@@ -1,6 +1,6 @@
-"""EverestAPI — Python SDK for the EverestQuant prediction tournament platform."""
+"""EverestAPI — Python SDK for the Everesteer prediction tournament platform."""
 
-__version__ = "0.2.2"
+__version__ = "0.2.4"
 
 from everestapi.client import EverestAPI, EverestError
 from everestapi.types import (

{everestapi-0.2.2 → everestapi-0.2.4}/src/everestapi/cli.py

@@ -1,4 +1,4 @@
-"""EverestAPI CLI — command-line interface for the EverestQuant tournament platform.
+"""EverestAPI CLI — command-line interface for the Everesteer tournament platform.
 
 Usage:
     everestapi health
@@ -32,7 +32,7 @@ def _print_json(data: dict) -> None:
 @click.group()
 @click.version_option(__version__, prog_name="everestapi")
 def cli() -> None:
-    """EverestQuant tournament CLI."""
+    """Everesteer tournament CLI."""
 
 
 @cli.command()
@@ -134,7 +134,7 @@ def submit(model: str, file_path: str, tournament: str, api_key: str | None) ->
             sys.exit(1)
 
         _print_json(result)
-    except (EverestError, KeyError, FileNotFoundError) as e:
+    except (EverestError, KeyError, FileNotFoundError, ValueError) as e:
         click.echo(f"Error: {e}", err=True)
         sys.exit(1)
 

{everestapi-0.2.2 → everestapi-0.2.4}/src/everestapi/client.py

@@ -1,4 +1,4 @@
-"""EverestAPI — Python client for the EverestQuant prediction tournament platform.
+"""EverestAPI — Python client for the Everesteer prediction tournament platform.
 
 Usage::
 
@@ -95,21 +95,96 @@ def _open_no_symlink(path: str):
 
 
 class EverestError(Exception):
-    """Error returned by the EverestQuant API."""
+    """Error returned by the Everesteer API."""
 
     def __init__(self, status_code: int, detail: Any) -> None:
         self.status_code = status_code
         self.detail = detail
-        super().__init__(f"EverestQuant API error {status_code}: {detail}")
+        super().__init__(f"Everesteer API error {status_code}: {detail}")
+
+
+def _raise_for_error(resp: httpx.Response) -> None:
+    """Raise :class:`EverestError` for any >= 400 response.
+
+    Falls back to ``resp.text`` when the error body isn't JSON (e.g. an
+    S3/Cloudflare error page), so the caller gets the body instead of a
+    secondary JSON-decode failure.
+    """
+    if resp.status_code >= 400:
+        try:
+            detail = resp.json()
+        except Exception:
+            detail = resp.text
+        raise EverestError(resp.status_code, detail)
+
+
+def _json_or_raise(resp: httpx.Response) -> dict:
+    """Return parsed JSON, or raise a clear :class:`EverestError`.
+
+    Beyond the >= 400 check, this guards the *success* path: when an edge
+    proxy (e.g. Cloudflare Access) answers with a non-error status but an HTML
+    challenge page, a bare ``resp.json()`` blows up with a raw
+    ``JSONDecodeError`` and a traceback. Detect that and raise an actionable
+    error pointing at the missing credentials instead.
+    """
+    _raise_for_error(resp)
+    try:
+        return resp.json()
+    except Exception:
+        body = (resp.text or "").strip()
+        looks_like_cf = (
+            "<html" in body[:200].lower()
+            or "cloudflare" in body.lower()
+            or "AccessDenied" in body
+        )
+        hint = (
+            " — this looks like a Cloudflare Access challenge; set "
+            "CF_ACCESS_CLIENT_ID / CF_ACCESS_CLIENT_SECRET (and EIQ_API_KEY)"
+            if looks_like_cf
+            else ""
+        )
+        raise EverestError(
+            resp.status_code,
+            f"expected a JSON response but received non-JSON content{hint}: "
+            f"{body[:200]}",
+        )
+
+
+def _check_prediction_range(
+    values: dict[str, float], *, lo: float = 0.0, hi: float = 1.0
+) -> None:
+    """Raise ``ValueError`` if any prediction is non-finite or outside ``[lo, hi]``.
+
+    Mirrors the server-side futures bound so a bad submission fails fast
+    locally with a clear message instead of a rejected round-trip.
+    """
+    import math
+
+    bad: list[str] = []
+    for key, val in values.items():
+        try:
+            f = float(val)
+        except (TypeError, ValueError):
+            bad.append(f"{key}={val!r}")
+            continue
+        if not math.isfinite(f) or f < lo or f > hi:
+            bad.append(f"{key}={val}")
+    if bad:
+        preview = ", ".join(bad[:5])
+        more = f" (+{len(bad) - 5} more)" if len(bad) > 5 else ""
+        raise ValueError(
+            f"{len(bad)} prediction(s) must be finite and within "
+            f"[{lo}, {hi}]: {preview}{more}"
+        )
 
 
 class EverestAPI:
-    """Synchronous client for the EverestQuant tournament API.
+    """Synchronous client for the Everesteer tournament API.
 
     Parameters
     ----------
     api_key : str, optional
-        EverestQuant API key. Falls back to ``EIQ_API_KEY`` (or legacy ``EVEREST_API_KEY``) env var.
+        Everesteer API key. Falls back to ``EIQ_API_KEY`` (or legacy ``EVEREST_API_KEY``) env var.
     base_url : str, optional
         Base URL for the API. Defaults to ``https://everesteer.ai`` (apex
         domain), overridable via ``EVEREST_API_URL`` env var.
@@ -186,22 +261,11 @@ class EverestAPI:
 
     def _request(self, method: str, path: str, **kwargs: Any) -> dict:
         resp = self._client.request(method, path, **kwargs)
-        if resp.status_code >= 400:
-            try:
-                detail = resp.json()
-            except Exception:
-                detail = resp.text
-            raise EverestError(resp.status_code, detail)
-        return resp.json()
+        return _json_or_raise(resp)
 
     def _download(self, path: str, output_path: str) -> str:
         resp = self._client.request("GET", path)
-        if resp.status_code >= 400:
-            try:
-                detail = resp.json()
-            except Exception:
-                detail = resp.text
-            raise EverestError(resp.status_code, detail)
+        _raise_for_error(resp)
         safe_path = _safe_output_path(output_path)
         with _open_no_symlink(safe_path) as f:
             f.write(resp.content)
@@ -267,56 +331,182 @@ class EverestAPI:
                 files={"file": (fname, f, "application/octet-stream")},
                 params={"model_id": model_name, "tournament": tourn},
             )
+        return _json_or_raise(resp)
+
+    def submit_validation_diagnostics(
+        self,
+        model_id: str,
+        predictions,
+        tournament: str = "futures",
+        target: str = "target_everest_20",
+        *,
+        wait: bool = False,
+        poll_interval: float = 2.0,
+        timeout: float = 600.0,
+    ) -> dict:
+        """POST /api/v1/diagnostics/upload (multipart) — score validation predictions.
+
+        ``predictions`` is a pandas DataFrame (``id`` + ``prediction`` columns) or a
+        path to a ``.parquet`` / ``.csv`` file. Returns the 202 accept dict; with
+        ``wait=True`` polls ``runs/{upload_id}`` until ``done`` (returns the run) and
+        raises :class:`EverestError` on ``failed`` or timeout. Display-only; results
+        also surface in the website Validation Diagnostics rail.
+        """
+        import io
+        import time
+
+        if hasattr(predictions, "to_parquet"):  # DataFrame
+            buf = io.BytesIO()
+            predictions.to_parquet(buf)
+            data = buf.getvalue()
+            fname = "predictions.parquet"
+        else:  # path
+            with open(predictions, "rb") as f:
+                data = f.read()
+            fname = str(predictions).rsplit("/", 1)[-1].rsplit("\\", 1)[-1]
+
+        resp = self._client.post(
+            "/api/v1/diagnostics/upload",
+            files={"file": (fname, data, "application/octet-stream")},
+            data={"model_id": model_id, "tournament": tournament, "target": target},
+        )
         if resp.status_code >= 400:
             try:
                 detail = resp.json()
             except Exception:
                 detail = resp.text
             raise EverestError(resp.status_code, detail)
-        return resp.json()
-
-    def submit_validation_diagnostics(
+        accepted = resp.json()
+        if not wait:
+            return accepted
+        deadline = time.time() + timeout
+        while time.time() < deadline:
+            run = self.get_diagnostics_run(accepted["upload_id"])
+            if run.get("status") == "done":
+                return run
+            if run.get("status") == "failed":
+                raise EverestError(500, run.get("error") or "diagnostics run failed")
+            time.sleep(poll_interval)
+        raise EverestError(504, "diagnostics run timed out")
+
+    def get_diagnostics_run(self, upload_id: str) -> dict:
+        """GET /api/v1/diagnostics/runs/{upload_id} — status + metrics for one run."""
+        return self._request("GET", f"/api/v1/diagnostics/runs/{upload_id}")
+
+    def get_diagnostics_leaderboard(
         self,
-        model_id: str,
-        predictions,
+        view: str = "agents",
         tournament: str = "futures",
-        target: str = "target_everest_20",
+        limit: int = 100,
     ) -> dict:
-        """POST /api/v1/diagnostics/upload — score predictions against validation data."""
-        if hasattr(predictions, "to_dict"):
-            preds_list = predictions.to_dict(orient="records")
+        """GET /api/v1/diagnostics/leaderboard — global CORR20 ranking.
+
+        ``view="agents"`` ranks participant model runs; ``view="benchmarks"`` ranks
+        the official benchmark models.
+        """
+        return self._request(
+            "GET",
+            "/api/v1/diagnostics/leaderboard",
+            params={"view": view, "tournament": tournament, "limit": limit},
+        )
+
+    @staticmethod
+    def _fmt(v) -> str:
+        """Format a metric value for console display."""
+        return "—" if v is None else f"{v:.4f}"
+
+    @staticmethod
+    def format_diagnostics_table(status: dict) -> str:
+        """Render a run status dict (from get_diagnostics_run / wait=True) as a table."""
+        rows = [
+            ("CORR20", status.get("corr20")),
+            ("BMC", status.get("bmc")),
+            ("FNC", status.get("fnc")),
+            ("Sharpe Ratio", status.get("sharpe_ratio")),
+            ("Std Dev", status.get("std_dev")),
+            ("Max Drawdown", status.get("max_drawdown")),
+            ("Autocorr", status.get("autocorrelation")),
+            ("Example-preds Corr", status.get("example_preds_corr")),
+        ]
+        lines = [
+            f"Validation Diagnostics — {status.get('model_id', '')} [{status.get('status', '')}]",
+            f"{'Metric':<20} {'Value':>10}",
+            "-" * 31,
+        ]
+        lines += [f"{k:<20} {EverestAPI._fmt(v):>10}" for k, v in rows]
+        return "\n".join(lines)
+
+    @staticmethod
+    def format_leaderboard_table(lb: dict) -> str:
+        """Render a get_diagnostics_leaderboard dict as a table (agents or benchmarks view)."""
+        view = lb.get("view", "agents")
+        if view == "benchmarks":
+            hdr = f"{'#':>3}  {'Label':<18} {'CORR20':>9} {'BMC':>9} {'FNC':>9} {'Sharpe':>9}"
+            lines = [
+                f"Diagnostics Leaderboard (benchmarks) — {lb.get('tournament', '')}",
+                hdr,
+                "-" * len(hdr),
+            ]
+            for e in lb.get("entries", []):
+                mark = "*" if e.get("is_ensemble") else " "
+                lines.append(
+                    f"{e.get('rank', '?'):>3}{mark} {e.get('label', ''):<18} "
+                    f"{EverestAPI._fmt(e.get('corr20')):>9} {EverestAPI._fmt(e.get('bmc')):>9} "
+                    f"{EverestAPI._fmt(e.get('fnc')):>9} {EverestAPI._fmt(e.get('sharpe_ratio')):>9}"
+                )
         else:
-            preds_list = list(predictions)
-        body = {
-            "model_id": model_id,
-            "tournament": tournament,
-            "target": target,
-            "predictions": preds_list,
-        }
-        return self._request("POST", "/api/v1/diagnostics/upload", json=body)
+            hdr = f"{'#':>3}  {'Model':<14} {'Agent':<12} {'CORR20':>9} {'BMC':>9} {'FNC':>9} {'Sharpe':>9}"
+            lines = [
+                f"Diagnostics Leaderboard (agents) — {lb.get('tournament', '')} "
+                f"(your best rank: {lb.get('your_best_rank')})",
+                hdr,
+                "-" * len(hdr),
+            ]
+            for e in lb.get("entries", []):
+                mark = "*" if e.get("is_self") else " "
+                lines.append(
+                    f"{e.get('rank', '?'):>3}{mark} {e.get('model_name', ''):<14} "
+                    f"{e.get('agent_name', ''):<12} "
+                    f"{EverestAPI._fmt(e.get('corr20')):>9} {EverestAPI._fmt(e.get('bmc')):>9} "
+                    f"{EverestAPI._fmt(e.get('fnc')):>9} {EverestAPI._fmt(e.get('sharpe_ratio')):>9}"
+                )
+        return "\n".join(lines)
+
+    def get_validation_panel(
+        self, model_id: str, days: int = 365, source: str = "auto"
+    ) -> dict:
+        """GET /api/v1/models/{model_id}/diagnostics/validation — full validation metrics.
 
-    def get_validation_panel(self, model_id: str, days: int = 365) -> dict:
-        """GET /api/v1/models/{model_id}/diagnostics/validation — full validation metrics."""
+        ``source="auto"`` (default) returns the latest completed validation-diagnostics
+        UPLOAD run — the same panel the website tab shows — falling back to tournament
+        scored-round history only when the model has never uploaded. ``source="scored"``
+        forces the tournament scored-round time-series panel.
+        """
         return self._request(
             "GET",
             f"/api/v1/models/{model_id}/diagnostics/validation",
-            params={"days": days},
+            params={"days": days, "source": source},
         )
 
-    def get_validation_diagnostics(self, model_id: str, days: int = 365) -> dict:
+    def get_validation_diagnostics(
+        self, model_id: str, days: int = 365, source: str = "auto"
+    ) -> dict:
         """Alias for :meth:`get_validation_panel` — full validation diagnostics panel."""
-        return self.get_validation_panel(model_id=model_id, days=days)
+        return self.get_validation_panel(model_id=model_id, days=days, source=source)
 
     def get_model_per_exped_breakdown(
         self,
         model_id: str,
         days: int = 3650,
     ) -> list[float]:
-        """Return the per-exped CORR series for a model (oldest→newest).
+        """Return the per-exped tournament CORR series for a model (oldest→newest).
 
-        Thin convenience wrapper over :meth:`get_validation_diagnostics`.
+        Thin convenience wrapper over :meth:`get_validation_diagnostics` with
+        ``source="scored"`` — the model's tournament scored-round history (daily
+        expeds, sqrt(252)-annualisable). For the validation-UPLOAD panel instead,
+        call :meth:`get_validation_diagnostics` with the default ``source="auto"``.
         """
-        resp = self.get_validation_diagnostics(model_id, days=days)
+        resp = self.get_validation_diagnostics(model_id, days=days, source="scored")
         return list(resp.get("per_exped_corr", []))
 
     def get_job_output(
@@ -442,10 +632,12 @@ class EverestAPI:
         model_id : str
             Model identifier.
         predictions : dict[str, float]
-            {instrument_id: prediction} for the primary target.
+            {instrument_id: prediction} for the primary target. Each prediction
+            must be finite and within ``[0, 1]``.
         exped : str, optional
             Exped identifier. Defaults to current round.
         """
+        _check_prediction_range(predictions)
         body = {
             "model_id": model_id,
             "exped": exped or "current",
@@ -463,9 +655,14 @@ class EverestAPI:
     ) -> dict:
         """POST /api/v1/futures/submit — submit per-target predictions (legacy v1 format).
 
+        Each per-target prediction must be finite and within ``[0, 1]``.
+
         .. deprecated::
             Use :meth:`submit_futures_predictions` (v2) instead.
         """
+        _check_prediction_range(
+            {f"{iid}:{tgt}": v for iid, tv in predictions.items() for tgt, v in tv.items()}
+        )
         preds_list = [{"instrument_id": k, "targets": v} for k, v in sorted(predictions.items())]
         body = {"model_id": model_id, "exped": exped, "predictions": preds_list}
         return self._request("POST", "/api/v1/futures/submit", json=body)
@@ -639,13 +836,7 @@ class EverestAPI:
             timeout=self._client.timeout,
             auth=self.basic_auth,
         )
-        if resp.status_code >= 400:
-            try:
-                detail = resp.json()
-            except Exception:
-                detail = resp.text
-            raise EverestError(resp.status_code, detail)
-        return resp.json()
+        return _json_or_raise(resp)
 
     def create_model(
         self,
@@ -710,19 +901,28 @@ class EverestAPI:
     # -- model uploads ----------------------------------------------------
 
     def upload_model(self, model_id: str, file_path: str) -> dict:
-        """POST /api/v1/models/{model_id}/upload — upload a .pkl model file."""
+        """POST /api/v1/models/{model_id}/upload — upload a .pkl model file.
+
+        The platform runs the pickle in a sandbox that calls
+        ``model.predict(features)`` each round, so the file MUST unpickle to one of:
+
+        * a fitted estimator with a ``.predict(X)`` method — sklearn / LightGBM /
+          XGBoost, saved with ``pickle.dump(model, f)``; or
+        * a stacked ensemble as a ``dict`` with a ``"meta"`` key, e.g.
+          ``{"base_lgbm": est, "base_ridge": est, "meta": est}`` (every value must
+          have ``.predict``).
+
+        A bare ``dict`` without ``"meta"``, or a joblib/torch file renamed ``.pkl``,
+        fails the sandbox run. The upload itself succeeds (the run is async); poll
+        :meth:`get_upload_status` — on failure its ``error_message`` carries the
+        exact reason (e.g. "Model type dict has no predict() method").
+        """
         with open(file_path, "rb") as f:
             resp = self._client.post(
                 f"/api/v1/models/{model_id}/upload",
                 files={"file": (f.name, f, "application/octet-stream")},
             )
-        if resp.status_code >= 400:
-            try:
-                detail = resp.json()
-            except Exception:
-                detail = resp.text
-            raise EverestError(resp.status_code, detail)
-        return resp.json()
+        return _json_or_raise(resp)
 
     def get_upload_status(self, model_id: str) -> dict:
         """GET /api/v1/models/{model_id}/upload/status"""