everestapi 0.2.7__tar.gz → 0.2.9__tar.gz

{everestapi-0.2.7/src/everestapi.egg-info → everestapi-0.2.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: everestapi
-Version: 0.2.7
+Version: 0.2.9
 Summary: Python SDK for the Everesteer prediction tournament platform
 Author-email: Everesteer <support@everesteer.ai>
 License-Expression: MIT
@@ -116,16 +116,23 @@ everestapi submit --model my-model --file predictions.parquet
 
 ### Data & diagnostics
 
+The hackathon is a display-only diagnostics event. **Tune and self-score offline
+on the labeled validation set** (features + `target_*` columns), then **predict on
+the blind `eiq_live_2026` set and submit** — the leaderboard ranks your
+out-of-sample 2026 CORR on `target_everest_20`. In-sample fit is not rewarded. The
+labeled `eiq_live_2026` answers are held out server-side and are never downloadable.
+
 ```python
-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")
+# Labeled practice set — tune + self-score offline with everestapi.scoring:
+api.download_dataset(universe="futures", split="validation")
 
-# 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")
+# Blind scored set (columns: exped, exped_date, instrument, id — no targets).
+# Predict on it, then submit; it is also the upload id template.
+api.download_dataset(universe="futures", split="live")
 api.submit_validation_diagnostics(model_id="my-model", predictions=df)
+
+api.get_dataset_info(universe="futures")
+api.get_diagnostics(model_id="my-model")
 ```
 
 ### Plotting (optional `viz` extra)
@@ -157,11 +164,18 @@ df = pd.DataFrame(lb["entries"])
 ### Serverless compute
 
 ```python
-# Tier 1 — quick-train with built-in templates
-job = api.quick_train(model="lightgbm", features="small", target="target_everest_20")
-
-# Tier 2 — custom script on GPU
-job = api.custom_train(script_path="train.py", gpu="A100", max_hours=2.0)
+# Built-in preset (lightgbm/xgboost/ridge/mlp/random_forest) — no data upload,
+# the platform trains against the same obfuscated dataset you download.
+job = api.train(model="lightgbm", features="small", target="target_everest_20")
+
+# model="custom" — your own model factory, run server-side in an isolated,
+# network-denied sandbox (no filesystem access, never sees held-out targets)
+job = api.train(
+    model="custom",
+    custom_model_fn="def build_model(params):\n    from sklearn.linear_model import Ridge\n    return Ridge(**params)",
+    gpu="A100",
+    max_hours=2.0,
+)
 
 # Wait and download
 result = api.wait_for_job(job["job_id"])

{everestapi-0.2.7 → everestapi-0.2.9}/README.md

@@ -77,16 +77,23 @@ everestapi submit --model my-model --file predictions.parquet
 
 ### Data & diagnostics
 
+The hackathon is a display-only diagnostics event. **Tune and self-score offline
+on the labeled validation set** (features + `target_*` columns), then **predict on
+the blind `eiq_live_2026` set and submit** — the leaderboard ranks your
+out-of-sample 2026 CORR on `target_everest_20`. In-sample fit is not rewarded. The
+labeled `eiq_live_2026` answers are held out server-side and are never downloadable.
+
 ```python
-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")
+# Labeled practice set — tune + self-score offline with everestapi.scoring:
+api.download_dataset(universe="futures", split="validation")
 
-# 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")
+# Blind scored set (columns: exped, exped_date, instrument, id — no targets).
+# Predict on it, then submit; it is also the upload id template.
+api.download_dataset(universe="futures", split="live")
 api.submit_validation_diagnostics(model_id="my-model", predictions=df)
+
+api.get_dataset_info(universe="futures")
+api.get_diagnostics(model_id="my-model")
 ```
 
 ### Plotting (optional `viz` extra)
@@ -118,11 +125,18 @@ df = pd.DataFrame(lb["entries"])
 ### Serverless compute
 
 ```python
-# Tier 1 — quick-train with built-in templates
-job = api.quick_train(model="lightgbm", features="small", target="target_everest_20")
-
-# Tier 2 — custom script on GPU
-job = api.custom_train(script_path="train.py", gpu="A100", max_hours=2.0)
+# Built-in preset (lightgbm/xgboost/ridge/mlp/random_forest) — no data upload,
+# the platform trains against the same obfuscated dataset you download.
+job = api.train(model="lightgbm", features="small", target="target_everest_20")
+
+# model="custom" — your own model factory, run server-side in an isolated,
+# network-denied sandbox (no filesystem access, never sees held-out targets)
+job = api.train(
+    model="custom",
+    custom_model_fn="def build_model(params):\n    from sklearn.linear_model import Ridge\n    return Ridge(**params)",
+    gpu="A100",
+    max_hours=2.0,
+)
 
 # Wait and download
 result = api.wait_for_job(job["job_id"])

{everestapi-0.2.7 → everestapi-0.2.9}/src/everestapi/__init__.py

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

{everestapi-0.2.7 → everestapi-0.2.9}/src/everestapi/client.py

@@ -26,6 +26,7 @@ Usage::
 from __future__ import annotations
 
 import os
+import warnings
 from pathlib import PurePath
 from typing import Any
 
@@ -366,10 +367,14 @@ class EverestAPI:
         poll_interval: float = 2.0,
         timeout: float = 600.0,
     ) -> dict:
-        """POST /api/v1/diagnostics/upload (multipart) — score validation predictions.
+        """POST /api/v1/diagnostics/upload (multipart) — score out-of-sample predictions.
 
         ``predictions`` is a pandas DataFrame (``id`` + ``prediction`` columns) or a
-        path to a ``.parquet`` / ``.csv`` file. Returns the 202 accept dict; with
+        path to a ``.parquet`` / ``.csv`` file, generated on the blind eiq_live_2026
+        set (``download_dataset(split="live")``). The platform scores it server-side
+        against the held-out labeled eiq_live_2026 answers — those answers are never
+        downloadable. Tune and self-score offline on the labeled validation set first
+        (see :mod:`everestapi.scoring`). 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.
@@ -590,11 +595,18 @@ class EverestAPI:
         404 the current version is resolved and the download retried once.
 
         Splits: ``train`` / ``validation`` (features + targets), ``live``
-        (current round features only).
+        (features only, no targets). In hackathon mode, ``validation`` is the
+        LABELED practice set — features + all ``target_*`` columns — that you tune
+        and self-score on offline (see :mod:`everestapi.scoring`), and ``live`` is
+        the BLIND eiq_live_2026 out-of-sample set (columns exactly ``exped``,
+        ``exped_date``, ``instrument``, ``id`` — no targets) that you predict on and
+        submit. The labeled eiq_live_2026 answers are held out server-side and never
+        downloadable.
 
         Futures is served by the futures endpoint (``version`` is a no-op):
-        it returns the real bregen tree to full-scope keys and the
-        target-stripped hackathon tree to hackathon-scoped keys (EVE-931).
+        it returns the real bregen tree to full-scope keys and the hackathon tree
+        (labeled ``validation`` practice set + blind ``live`` eiq_live_2026 scored
+        set) to hackathon-scoped keys.
         """
         if output_path is None:
             output_path = f"{universe}_{split}.parquet"
@@ -775,50 +787,125 @@ class EverestAPI:
 
     # -- compute ----------------------------------------------------------
 
-    def quick_train(
+    def train(
         self,
         model: str = "lightgbm",
-        features: str = "small",
-        target: str = "target_everest_20",
+        *,
+        custom_model_fn: str | None = None,
+        custom_feature_fn: str | None = None,
+        features: str | list[str] = "small",
+        target: str | list[str] = "target_everest_20",
         universe: str = "futures",
         params: dict | None = None,
+        cv: dict | None = None,
+        train_filter: dict | None = None,
+        val_filter: dict | None = None,
+        transforms: dict | None = None,
+        gpu: str = "T4",
+        max_hours: float = 1.0,
     ) -> dict:
-        """Submit Tier 1 serverless training job."""
+        """Submit a unified training job (EVE-1013). Non-blocking.
+
+        train only — returns downloadable artifacts + metrics; does NOT
+        submit/host (use submit_futures_predictions / upload_model). Supply
+        a built-in ``model`` preset (lightgbm/xgboost/ridge/mlp/random_forest)
+        or ``model="custom"`` with a ``custom_model_fn`` factory; optionally
+        add ``custom_feature_fn`` for server-side feature engineering on the
+        resident data (no upload). The platform always runs exped-purged
+        cross-validation and computes canonical CORR20v2/AIMC/FNC/EAC — note
+        the pre-round AIMC is an ESTIMATE vs a static consensus proxy, not
+        the live stake-weighted crowd score used at round close.
+
+        Futures payout uses target_everest_20 (20-day forward return).
+        Final score = 0.75 * CORR + 2.25 * AIMC.
+
+        ``train_filter``/``val_filter`` (RowFilter) and ``transforms`` (fit-only
+        target transform + sample_weight override) are honored server-side,
+        diagnostic-only — never affects payout; see API_CONTRACT.md for the
+        full shape and the ``data_spec``/``canonical``/``slice_leak_note``
+        fields returned when a slice is applied.
+        """
         body: dict = {
             "model": model,
             "features": features,
             "target": target,
             "universe": universe,
+            "gpu": gpu,
+            "max_hours": max_hours,
         }
-        if params:
+        if custom_model_fn is not None:
+            body["custom_model_fn"] = custom_model_fn
+        if custom_feature_fn is not None:
+            body["custom_feature_fn"] = custom_feature_fn
+        if params is not None:
             body["params"] = params
-        return self._request("POST", "/api/v1/compute/quick-train", json=body)
+        if cv is not None:
+            body["cv"] = cv
+        if train_filter is not None:
+            body["train_filter"] = train_filter
+        if val_filter is not None:
+            body["val_filter"] = val_filter
+        if transforms is not None:
+            body["transforms"] = transforms
+        return self._request("POST", "/api/v1/compute/train", json=body)
 
-    def custom_train(
+    def quick_train(
         self,
-        script: str | None = None,
-        script_path: str | None = None,
-        files: dict[str, str] | None = None,
-        gpu: str = "T4",
-        max_hours: float = 1.0,
-        requirements: list[str] | None = None,
+        model: str = "lightgbm",
+        features: str = "small",
+        target: str = "target_everest_20",
+        universe: str = "futures",
+        params: dict | None = None,
     ) -> dict:
-        """Submit Tier 2 custom training job."""
-        if script_path and not script:
-            with open(script_path) as f:
-                script = f.read()
-        if files and not script:
-            parts = [f"# --- FILE: {name} ---\n{content}" for name, content in files.items()]
-            script = "\n\n".join(parts)
-        body: dict = {"script": script, "gpu": gpu, "max_hours": max_hours}
-        if requirements:
-            body["requirements"] = requirements
-        return self._request("POST", "/api/v1/compute/custom-train", json=body)
+        """Deprecated since 0.2.9 — forwards to :meth:`train`.
+
+        The Tier 1/Tier 2 split (``quick_train``/``custom_train``) was
+        replaced server-side by a single unified ``train`` tool (EVE-1013).
+        This shim keeps the old call signature working but always submits
+        through the new ``/api/v1/compute/train`` endpoint.
+        """
+        warnings.warn(
+            "quick_train() is deprecated; use train() instead (EVE-1013).",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.train(
+            model=model, features=features, target=target, universe=universe, params=params
+        )
+
+    def custom_train(self, *args: Any, **kwargs: Any) -> dict:
+        """Removed since 0.2.9 — the Tier-2 script-based training path no longer exists.
+
+        Use :meth:`train` with ``model="custom"`` and a ``custom_model_fn``
+        source string instead; it now runs inside a sandboxed, network-denied
+        environment rather than a dedicated GPU pod running an arbitrary script.
+        """
+        warnings.warn(
+            "custom_train() is removed; use train(model='custom', custom_model_fn=...).",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        raise EverestError(
+            410,
+            "custom_train (Tier-2 script) was removed. Use "
+            "train(model='custom', custom_model_fn='def build_model(params): ...').",
+        )
 
     def get_job_status(self, job_id: str) -> dict:
         """Poll compute job status."""
         return self._request("GET", f"/api/v1/compute/jobs/{job_id}")
 
+    def list_compute_jobs(self, limit: int = 50, status: str | None = None) -> dict:
+        """List your compute jobs, newest first (rows exclude config/output payloads)."""
+        params: dict = {"limit": limit}
+        if status is not None:
+            params["status"] = status
+        return self._request("GET", "/api/v1/compute/jobs", params=params)
+
+    def get_job_log(self, job_id: str) -> dict:
+        """Lifecycle event trail for one compute job — debug a failed/stuck job."""
+        return self._request("GET", f"/api/v1/compute/jobs/{job_id}/logs")
+
     def get_model_download_url(self, job_id: str) -> dict:
         """Get a presigned download URL for a trained model."""
         return self._request("GET", f"/api/v1/compute/jobs/{job_id}/model")
@@ -864,7 +951,7 @@ class EverestAPI:
         return self._request("GET", "/api/v1/compute/credits")
 
     def list_model_templates(self) -> dict:
-        """List available quick-train model templates."""
+        """List available train model templates."""
         return self._request("GET", "/api/v1/compute/models")
 
     # -- registration (no auth) ------------------------------------------
@@ -933,7 +1020,8 @@ class EverestAPI:
 
         With a hackathon-scoped key there is no live round — the response is a
         diagnostics-mode payload (mode='diagnostics_hackathon') directing you to
-        download_dataset + submit_validation_diagnostics.
+        tune offline on the labeled validation set, then predict on the blind
+        eiq_live_2026 set and submit_validation_diagnostics.
         """
         return self._request(
             "GET",
@@ -951,7 +1039,10 @@ class EverestAPI:
         """GET /api/v1/get_started — mode-aware orientation.
 
         Returns what to do next given this key's scope: the display-only
-        diagnostics-hackathon loop, or the live futures tournament flow.
+        diagnostics-hackathon loop (tune and self-score offline on the labeled
+        validation set, then predict on the blind eiq_live_2026 set and submit —
+        ranked on out-of-sample 2026 CORR on target_everest_20), or the live
+        futures tournament flow.
         """
         return self._request("GET", "/api/v1/get_started")
 

{everestapi-0.2.7 → everestapi-0.2.9}/src/everestapi/mcp/server.py

@@ -238,7 +238,7 @@ TOOLS = [
     },
     {
         "name": "download_dataset",
-        "description": "Download a dataset split (train/validation/live) as a parquet file. Returns the local file path.",
+        "description": "Download a dataset split (train/validation/live) as a parquet file. Returns the local file path. In hackathon mode: 'validation' is the LABELED practice set (features + all target_* columns) for offline tuning and self-scoring; 'live' is the BLIND eiq_live_2026 out-of-sample set (columns exactly exped, exped_date, instrument, id — NO targets) that you predict on and submit. The labeled 2026 answers are held out server-side and never downloadable.",
         "inputSchema": {
             "type": "object",
             "properties": {
@@ -270,42 +270,64 @@ TOOLS = [
         },
     },
     {
-        "name": "quick_train",
-        "description": "Train a model on Everesteer data using serverless GPU. Returns job_id. Poll with get_job_status(). Models: lightgbm, xgboost, ridge, mlp. Costs $0.005-0.05. Futures payout target: target_everest_20 (20-day forward return). Final score = 0.75*CORR + 2.25*AIMC.",
+        "name": "train",
+        "description": "Train a model on Everesteer data (no data upload — the platform uses the same obfuscated dataset you download). The PLATFORM loads data, runs exped-purged/embargoed cross-validation, computes canonical tournament metrics (0.75*CORR + 2.25*AIMC; AIMC before round close is a PRE-SUBMISSION ESTIMATE vs a static consensus proxy — real AIMC is scored vs the live stake-weighted crowd at round close), pickles the final model, and returns DOWNLOADABLE artifacts (model .pkl + validation/live prediction files) plus the metrics. Supply a built-in `model` preset (lightgbm/xgboost/ridge/mlp/random_forest), or `model='custom'` with a `custom_model_fn` (and optional `custom_feature_fn`) to run your own code — it executes inside an isolated, network-denied sandbox with no filesystem access and never sees held-out targets; a script rejected by the static safety scanner returns 400. `train` does NOT submit predictions or host a model on your behalf — use submit_futures_predictions/submit_predictions_file to submit and upload_model to host the .pkl. Poll with get_job_status() — the completed result carries the metrics + a predictions download URL; fetch the model file separately via get_model_download_url().",
         "inputSchema": {
             "type": "object",
             "properties": {
-                "model": {"type": "string", "enum": ["lightgbm", "xgboost", "ridge", "mlp"]},
-                "features": {
+                "model": {
+                    "type": "string",
+                    "enum": ["lightgbm", "xgboost", "ridge", "mlp", "random_forest", "custom"],
+                    "default": "lightgbm",
+                },
+                "custom_model_fn": {
+                    "type": "string",
+                    "description": "Python source defining build_model(params)->estimator, required when model='custom'. Runs in an isolated, network-denied sandbox with no filesystem access and never sees held-out targets. Rejected by the static safety scanner (returns 400) if it references disallowed modules/builtins.",
+                },
+                "custom_feature_fn": {
                     "type": "string",
-                    "enum": ["small", "medium", "all"],
+                    "description": "OPTIONAL Python source defining build_feature_transformer(params)->sklearn transformer for server-side feature engineering on the resident features. Usable with any model (preset or custom), in the same isolated sandbox as custom_model_fn. Same static-scanner gate (returns 400 on rejection).",
+                },
+                "params": {"type": "object", "description": "Model hyperparameters (optional)"},
+                "features": {
+                    "oneOf": [
+                        {"type": "string", "enum": ["small", "medium", "all"]},
+                        {"type": "array", "items": {"type": "string"}},
+                    ],
                     "default": "small",
+                    "description": "Preset (small/medium/all) or an explicit list of feature_* names.",
                 },
                 "target": {
-                    "type": "string",
+                    "oneOf": [
+                        {"type": "string"},
+                        {"type": "array", "items": {"type": "string"}},
+                    ],
                     "default": "target_everest_20",
-                    "description": "Target column. Futures payout uses target_everest_20 (20-day forward return). Multiple target types available. See get_dataset_schema for full list.",
+                    "description": "Target column. Futures payout uses target_everest_20 (20-day forward return).",
                 },
                 "universe": {"type": "string", "default": "futures"},
-                "params": {"type": "object", "description": "Model hyperparameters (optional)"},
+                "cv": {
+                    "type": "object",
+                    "description": "Cross-validation spec: {scheme, folds, embargo}. scheme is exped_purged (default), chain_group, or combined; embargo defaults to the label horizon when null.",
+                },
+                "train_filter": {
+                    "type": "object",
+                    "description": "Row filter (exped/climb_difficulty/sample/feature_filter) applied to the training split server-side, no re-upload — diagnostic-only, never affects payout. Full RowFilter shape in API_CONTRACT.md.",
+                },
+                "val_filter": {
+                    "type": "object",
+                    "description": "Same RowFilter shape as train_filter, applied to the validation split (layered under the platform's own validation clamp, if any) — diagnostic-only, never affects payout.",
+                },
+                "transforms": {
+                    "type": "object",
+                    "description": "Fit-only target transform (residualize_to_benchmark/subtract_benchmark_zscore) and/or sample_weight override — scoring always uses the untouched canonical target. Full shape in API_CONTRACT.md.",
+                },
+                "gpu": {"type": "string", "enum": ["T4", "A10G", "A100"], "default": "T4"},
+                "max_hours": {"type": "number", "minimum": 0.1, "maximum": 4.0, "default": 1.0},
             },
             "required": ["model"],
         },
     },
-    {
-        "name": "custom_train",
-        "description": "Run a custom Python script on a GPU pod. Pod has EverestAPI SDK + PyTorch + ML libs pre-installed. Costs $0.50-1.79/hr.",
-        "inputSchema": {
-            "type": "object",
-            "properties": {
-                "script": {"type": "string", "description": "Python script content"},
-                "gpu": {"type": "string", "enum": ["T4", "A40", "A100"], "default": "T4"},
-                "max_hours": {"type": "number", "default": 1},
-                "requirements": {"type": "array", "items": {"type": "string"}},
-            },
-            "required": ["script"],
-        },
-    },
     {
         "name": "get_job_status",
         "description": "Check status of a compute job. Returns status, cost, output files when complete.",
@@ -314,7 +336,7 @@ TOOLS = [
             "properties": {
                 "job_id": {
                     "type": "string",
-                    "description": "Job ID from quick_train or custom_train",
+                    "description": "Job ID from a train job",
                 },
             },
             "required": ["job_id"],
@@ -328,7 +350,7 @@ TOOLS = [
             "properties": {
                 "job_id": {
                     "type": "string",
-                    "description": "Job ID from quick_train or custom_train",
+                    "description": "Job ID from a train job",
                 },
             },
             "required": ["job_id"],
@@ -365,7 +387,7 @@ TOOLS = [
     },
     {
         "name": "get_current_round",
-        "description": "Get the current active round for a tournament (defaults to 'futures'; equities is unlaunched). With a hackathon key there is no live round — the response is a diagnostics-mode payload directing you to download_dataset + submit_validation_diagnostics.",
+        "description": "Get the current active round for a tournament (defaults to 'futures'; equities is unlaunched). With a hackathon key there is no live round — the response is a diagnostics-mode payload directing you to tune offline on the labeled validation set, then download the blind eiq_live_2026 set, predict, and submit_validation_diagnostics.",
         "inputSchema": {
             "type": "object",
             "properties": {
@@ -380,7 +402,7 @@ TOOLS = [
     },
     {
         "name": "get_started",
-        "description": "Mode-aware orientation: returns what to do next given your API key's scope. A hackathon key gets the display-only diagnostics loop (objective: maximize out-of-sample CORR on target_everest_20); a full key gets the live futures tournament flow. Start here.",
+        "description": "Mode-aware orientation: returns what to do next given your API key's scope. A hackathon key gets the display-only diagnostics loop (tune and self-score offline on the labeled validation set, then predict on the blind eiq_live_2026 set and submit; objective: maximize out-of-sample 2026 CORR on target_everest_20, in-sample fit is not rewarded); a full key gets the live futures tournament flow. Start here.",
         "inputSchema": {
             "type": "object",
             "properties": {},
@@ -546,13 +568,15 @@ TOOLS = [
     {
         "name": "submit_validation_diagnostics",
         "description": (
-            "Upload a NEW validation predictions file (parquet/CSV with id+prediction columns, "
-            "≤100 MB) and score it against eiq_validation.parquet. The required schema mirrors "
-            "eiq_validation_example_preds.parquet — fetch it with "
-            "download_dataset(split='validation_example_preds') and use it as the upload template "
-            "(same id set, your own prediction column). Use this only when you have fresh "
-            "predictions to score — to read the model's EXISTING latest result without re-scoring "
-            "(instant, no wait), call run_validation_diagnostics(model_id) instead. "
+            "Upload a NEW predictions file (parquet/CSV with id+prediction columns, "
+            "≤100 MB) generated on the blind eiq_live_2026 out-of-sample set; the platform "
+            "scores it server-side against the held-out labeled eiq_live_2026 answers (never "
+            "downloadable). The required id set is the blind eiq_live_2026 set — fetch it with "
+            "download_dataset(split='live') and use it as the upload template "
+            "(its id column, your own prediction column). Tune and self-score offline on the "
+            "labeled validation set first (see the scoring helper). Use this only when you have "
+            "fresh predictions to score — to read the model's EXISTING latest result without "
+            "re-scoring (instant, no wait), call run_validation_diagnostics(model_id) instead. "
             "The platform scores a 9-metric panel (CORR20, BMC, FNC, Sharpe, std dev, "
             "feature-exposure, Max Drawdown, autocorrelation, example-preds-corr) asynchronously "
             "and surfaces the run in the website Validation Diagnostics rail. By default "
@@ -594,9 +618,10 @@ TOOLS = [
     {
         "name": "get_diagnostics_leaderboard",
         "description": (
-            "Get the validation diagnostics leaderboard — global ranking of uploaded validation "
-            "runs by CORR20, BMC, FNC, and Sharpe. view='agents' (default) ranks participant model "
-            "runs and marks your own entries; view='benchmarks' ranks the official platform benchmarks."
+            "Get the validation diagnostics leaderboard — global ranking of agents by their "
+            "out-of-sample eiq_live_2026 CORR on target_everest_20 (in-sample fit is not rewarded). "
+            "view='agents' (default) ranks participant model runs and marks your own entries; "
+            "view='benchmarks' ranks the official platform benchmarks."
         ),
         "inputSchema": {
             "type": "object",
@@ -894,6 +919,19 @@ TOOLSETS: dict[str, set[str]] = {
         "get_scores",
         "get_leaderboard",
         "get_capabilities",
+        # EVE-967: the diagnostics upload + leaderboard are the entire hackathon
+        # flow get_started steers to; advertise them by default (core) so a
+        # hackathon key discovers them without setting EIQ_MCP_TOOLSETS. The rest
+        # of the diagnostics lifecycle stays in "diagnostics".
+        "submit_validation_diagnostics",
+        "get_diagnostics_leaderboard",
+        # EVE-970: hosted training is a first-class flow now that every account
+        # carries a compute grant — advertise train + get_compute_credits by
+        # default so agents discover the hosted-training entry point without
+        # setting EIQ_MCP_TOOLSETS. get_job_status stays in "compute" (hidden
+        # tools remain callable by name). Mirrors the platform MCP server.
+        "train",
+        "get_compute_credits",
     },
     "data": {
         "get_universe",
@@ -911,15 +949,12 @@ TOOLSETS: dict[str, set[str]] = {
     },
     "submit": {"submit_predictions", "upload_model", "get_upload_status"},
     "diagnostics": {
+        # submit_validation_diagnostics + get_diagnostics_leaderboard promoted to
+        # "core" (EVE-967) — every name still lives in exactly one group.
         "run_validation_diagnostics",
-        "submit_validation_diagnostics",
-        "get_diagnostics_leaderboard",
     },
     "compute": {
-        "quick_train",
-        "custom_train",
         "get_job_status",
-        "get_compute_credits",
     },
     "staking": {
         "stake_on_model",
@@ -1081,21 +1116,8 @@ def _dispatch(name: str, arguments: dict) -> str:
             output_path=arguments.get("output_path"),
         )
         result = {"file_path": path, "status": "downloaded"}
-    elif name == "quick_train":
-        result = client.quick_train(
-            model=arguments["model"],
-            features=arguments.get("features", "small"),
-            target=arguments.get("target", "target_everest_20"),
-            universe=arguments.get("universe", "futures"),
-            params=arguments.get("params"),
-        )
-    elif name == "custom_train":
-        result = client.custom_train(
-            script=arguments.get("script"),
-            gpu=arguments.get("gpu", "T4"),
-            max_hours=arguments.get("max_hours", 1),
-            requirements=arguments.get("requirements"),
-        )
+    elif name == "train":
+        result = client.train(**arguments)
     elif name == "get_job_status":
         result = client.get_job_status(job_id=arguments["job_id"])
     elif name == "get_model_download_url":
@@ -1275,9 +1297,14 @@ def _error_payload(exc: Exception) -> str:
 
     if isinstance(exc, EverestError):
         code = exc.status_code
+        # FastAPI wraps errors as {"detail": {"code": ..., "message": ...}} —
+        # pull the machine code so 403 can distinguish a scope restriction
+        # (not available in diagnostics mode) from a genuine auth failure.
+        inner = exc.detail.get("detail") if isinstance(exc.detail, dict) else None
+        err_code = inner.get("code") if isinstance(inner, dict) else None
+
         hints = {
             401: "Auth failed — set EIQ_API_KEY to your Everesteer API key.",
-            403: "Auth failed — set EIQ_API_KEY to your Everesteer API key.",
             404: "Not found — check the model_id / upload_id exists.",
             409: "A diagnostics run is already in flight for this model — read it with "
             "run_validation_diagnostics(model_id) or wait for it to finish.",
@@ -1285,10 +1312,19 @@ def _error_payload(exc: Exception) -> str:
             504: "Still computing — scoring can take 15-20 min; poll again shortly.",
         }
         hint = hints.get(code)
+        if code == 403:
+            if err_code in ("scope_mismatch", "scope_restricted"):
+                hint = (
+                    "Not available in diagnostics (hackathon) mode — this is a "
+                    "live-tournament / full-scope action. Use the diagnostics flow: "
+                    "submit_validation_diagnostics + get_diagnostics_leaderboard."
+                )
+            else:
+                hint = "Auth failed — set EIQ_API_KEY to your Everesteer API key."
         if hint is None and 400 <= code < 500:
-            hint = "Bad request — file needs id+prediction columns and an existing model_id."
+            hint = "Bad request — check the arguments match the tool schema."
         elif hint is None and code >= 500:
-            hint = "Server error — retry; if it persists the run may have failed (e.g. predictions didn't overlap the validation universe)."
+            hint = "Server error — retry; if it persists the request may have failed."
         return json.dumps({"error": exc.detail, "status": code, "hint": hint})
     return json.dumps({"error": str(exc)})
 
@@ -1402,9 +1438,13 @@ _MCP_INSTRUCTIONS = (
     "Everesteer tournament MCP server. Call get_started first — it is mode-aware and tells you "
     "what to do next based on your API key's scope.\n\n"
     "Hackathon mode (a hackathon-scoped key): there is no live tournament round and no "
-    "staking or payout — this is a display-only diagnostics event. Your objective is to "
-    "maximize OUT-OF-SAMPLE CORR on target_everest_20; in-sample fit is not rewarded. Flow: "
-    "download_dataset -> score offline -> submit_validation_diagnostics -> "
+    "staking or payout — this is a display-only diagnostics event. Tune and self-score "
+    "offline on the LABELED validation set (features + target_* columns, via the scoring "
+    "helper), then predict on the BLIND eiq_live_2026 set (columns exped, exped_date, "
+    "instrument, id — no targets) and submit; the leaderboard ranks your OUT-OF-SAMPLE 2026 "
+    "CORR on target_everest_20. In-sample fit is not rewarded. Flow: "
+    "download_dataset(split='validation') -> tune + self-score offline -> "
+    "download_dataset(split='live') -> predict -> submit_validation_diagnostics -> "
     "get_diagnostics_leaderboard. Round/universe/feature/benchmark reads return empty "
     "diagnostics-mode payloads, not live data.\n\n"
     "Tournament mode (a full-scope key): submit daily futures predictions; payout = "
@@ -1436,8 +1476,7 @@ _NEXT_ACTIONS: dict[str, list[str]] = {
     "download_dataset": ["create_model", "submit_futures_predictions"],
     "download_benchmark": ["submit_futures_predictions"],
     "get_benchmarks": ["download_benchmark"],
-    "quick_train": ["get_job_status"],
-    "custom_train": ["get_job_status"],
+    "train": ["get_job_status"],
     "get_job_status": ["get_model_download_url"],  # conditional
     "get_model_download_url": ["upload_model", "create_model"],
     "create_model": ["submit_futures_predictions", "upload_model"],
@@ -1469,7 +1508,7 @@ _NEXT_ACTIONS: dict[str, list[str]] = {
     "get_deposit_address": ["get_forwarder_balance", "relay_stake"],
     "get_forwarder_balance": ["relay_stake"],
     "withdraw_usdc": ["get_forwarder_balance"],
-    "get_compute_credits": ["quick_train"],
+    "get_compute_credits": ["train"],
     "get_notifications": [],
     "get_badges": [],
 }
@@ -1494,8 +1533,7 @@ _NARRATION: dict[str, str] = {
     "submit_predictions": (
         "Submitted predictions for model '{model_id}'. Scoring starts at round close."
     ),
-    "quick_train": "Training job queued.",
-    "custom_train": "Custom training job queued.",
+    "train": "Training job queued — returns downloadable artifacts + metrics, not a submission.",
     "get_job_status": "Training job status: {status}.",
     "get_model_download_url": "Generated a download URL for the trained model (valid ~1h).",
     "upload_model": "Model artifact uploaded; validation runs asynchronously.",
@@ -1555,7 +1593,7 @@ def _next_actions_for(name: str, arguments: dict, data: dict) -> list[str]:
         if status in ("completed", "done", "succeeded", "success"):
             return ["get_model_download_url", "create_model"]
         if status in ("failed", "error"):
-            return ["quick_train", "custom_train"]
+            return ["train"]
         return ["get_job_status"]  # still running — keep polling
     if name == "get_upload_status":
         if status in ("validated", "done", "success", "ready", "active"):

{everestapi-0.2.7 → everestapi-0.2.9}/src/everestapi/scoring.py

@@ -27,6 +27,14 @@ Quickstart::
         for e in val.exped.unique()
     ]
     print("mean CORR20:", sum(corrs) / len(corrs))
+
+In hackathon mode the validation set ships LABELED (features + ``target_*``
+columns), so this helper is the offline self-scoring path: use it to tune your
+model before you submit. It scores in-sample and is for tuning only — the
+official hackathon leaderboard scores your submitted predictions on the BLIND
+``eiq_live_2026`` out-of-sample set server-side (its labeled answers are held
+out and never downloadable), ranking your 2026 CORR on ``target_everest_20``.
+In-sample fit is not rewarded.
 """
 
 from __future__ import annotations

{everestapi-0.2.7 → everestapi-0.2.9/src/everestapi.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: everestapi
-Version: 0.2.7
+Version: 0.2.9
 Summary: Python SDK for the Everesteer prediction tournament platform
 Author-email: Everesteer <support@everesteer.ai>
 License-Expression: MIT
@@ -116,16 +116,23 @@ everestapi submit --model my-model --file predictions.parquet
 
 ### Data & diagnostics
 
+The hackathon is a display-only diagnostics event. **Tune and self-score offline
+on the labeled validation set** (features + `target_*` columns), then **predict on
+the blind `eiq_live_2026` set and submit** — the leaderboard ranks your
+out-of-sample 2026 CORR on `target_everest_20`. In-sample fit is not rewarded. The
+labeled `eiq_live_2026` answers are held out server-side and are never downloadable.
+
 ```python
-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")
+# Labeled practice set — tune + self-score offline with everestapi.scoring:
+api.download_dataset(universe="futures", split="validation")
 
-# 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")
+# Blind scored set (columns: exped, exped_date, instrument, id — no targets).
+# Predict on it, then submit; it is also the upload id template.
+api.download_dataset(universe="futures", split="live")
 api.submit_validation_diagnostics(model_id="my-model", predictions=df)
+
+api.get_dataset_info(universe="futures")
+api.get_diagnostics(model_id="my-model")
 ```
 
 ### Plotting (optional `viz` extra)
@@ -157,11 +164,18 @@ df = pd.DataFrame(lb["entries"])
 ### Serverless compute
 
 ```python
-# Tier 1 — quick-train with built-in templates
-job = api.quick_train(model="lightgbm", features="small", target="target_everest_20")
-
-# Tier 2 — custom script on GPU
-job = api.custom_train(script_path="train.py", gpu="A100", max_hours=2.0)
+# Built-in preset (lightgbm/xgboost/ridge/mlp/random_forest) — no data upload,
+# the platform trains against the same obfuscated dataset you download.
+job = api.train(model="lightgbm", features="small", target="target_everest_20")
+
+# model="custom" — your own model factory, run server-side in an isolated,
+# network-denied sandbox (no filesystem access, never sees held-out targets)
+job = api.train(
+    model="custom",
+    custom_model_fn="def build_model(params):\n    from sklearn.linear_model import Ridge\n    return Ridge(**params)",
+    gpu="A100",
+    max_hours=2.0,
+)
 
 # Wait and download
 result = api.wait_for_job(job["job_id"])

{everestapi-0.2.7 → everestapi-0.2.9}/src/everestapi.egg-info/SOURCES.txt

@@ -23,6 +23,7 @@ tests/test_diagnostics.py
 tests/test_eve953_mcp_progress.py
 tests/test_eve957_mcp_annotations_resources.py
 tests/test_eve959_toolsets.py
+tests/test_eve967_mcp_discoverability.py
 tests/test_json_or_raise.py
 tests/test_mcp_and_models.py
 tests/test_prediction_range.py

everestapi-0.2.9/tests/test_eve967_mcp_discoverability.py

@@ -0,0 +1,40 @@
+"""EVE-967 — the diagnostics upload + leaderboard tools are discoverable on the
+default (core) toolset, and MCP error hints don't mislead:
+- a 403 scope restriction points at the diagnostics flow, not "rotate your key";
+- the generic 400 fallback is tool-neutral (no diagnostics-upload bleed).
+"""
+
+from __future__ import annotations
+
+import json
+
+import everestapi.mcp.server as S
+from everestapi.client import EverestError
+
+
+def test_diagnostics_tools_advertised_by_default(monkeypatch):
+    monkeypatch.delenv("EIQ_MCP_TOOLSETS", raising=False)
+    enabled = S._enabled_tool_names()
+    assert "submit_validation_diagnostics" in enabled
+    assert "get_diagnostics_leaderboard" in enabled
+
+
+def test_403_scope_mismatch_hint_points_to_diagnostics():
+    exc = EverestError(403, {"detail": {"code": "scope_mismatch", "message": "x"}})
+    payload = json.loads(S._error_payload(exc))
+    assert payload["status"] == 403
+    assert "diagnostics" in payload["hint"].lower()
+    assert "set EIQ_API_KEY" not in payload["hint"]
+
+
+def test_403_plain_auth_still_says_set_key():
+    exc = EverestError(403, "forbidden")  # no machine code → generic auth hint
+    payload = json.loads(S._error_payload(exc))
+    assert "EIQ_API_KEY" in payload["hint"]
+
+
+def test_generic_400_hint_is_tool_neutral():
+    exc = EverestError(400, {"detail": "bad"})
+    payload = json.loads(S._error_payload(exc))
+    assert "id+prediction" not in payload["hint"]
+    assert "schema" in payload["hint"].lower()

{everestapi-0.2.7 → everestapi-0.2.9}/tests/test_mcp_and_models.py

@@ -514,6 +514,8 @@ _SDK_ONLY_SANCTIONED = {
     "get_multipliers",
     "get_current_season",
     "get_job_output",
+    "list_compute_jobs",  # EVE-1013 — job lookup, same category as get_job_output
+    "get_job_log",  # EVE-1013 — job lookup, same category as get_job_output
     "get_diagnostics_run",
     "get_validation_panel",
     "get_validation_diagnostics",
@@ -530,6 +532,11 @@ _SDK_ONLY_SANCTIONED = {
     "unstake",
     "confirm_stake",
     "cancel_job",
+    # EVE-1013 — quick_train/custom_train replaced by the unified `train` tool;
+    # both remain on the client as deprecated shims (quick_train forwards to
+    # train(), custom_train raises) but are no longer registered as MCP tools.
+    "quick_train",
+    "custom_train",
 }