everestapi 0.3.1__tar.gz → 0.3.2__tar.gz

{everestapi-0.3.1/src/everestapi.egg-info → everestapi-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: everestapi
-Version: 0.3.1
+Version: 0.3.2
 Summary: Python SDK for the Everesteer prediction tournament platform
 Author-email: Everesteer <support@everesteer.ai>
 License-Expression: MIT
@@ -116,20 +116,31 @@ 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.
+The hackathon is a display-only diagnostics event. **Tune offline on the labeled
+`train` set** (features + `target_*` columns), then **predict on the blank-target
+`validation` (leaderboard) set and submit predictions plus your model `.pkl`**
+(required; store-only, never executed). Each upload is scored server-side on
+**two windows**: the public leaderboard window (ranked live during the event)
+and a later held-out **final window that stays sealed until the event's
+reveal**. Both rank out-of-sample CORR on `target_everest_20`; in-sample fit is
+not rewarded, and the answers are never downloadable. After submissions close,
+pick up to 2 of your models as final entries during the grace window (otherwise
+your best 2 public models are entered automatically).
 
 ```python
-# Labeled practice set — tune + self-score offline with everestapi.scoring:
+# Labeled training set — tune offline with everestapi.scoring on your own holdout:
+api.download_dataset(universe="futures", split="train")
+
+# Blank-target leaderboard set (features + id; target columns all-NaN).
+# Predict on its ids, then submit with your model pickle:
 api.download_dataset(universe="futures", split="validation")
+api.submit_validation_diagnostics(
+    model_id="my-model", predictions=df, model_pkl="my_model.pkl"
+)
 
-# 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_diagnostics_leaderboard()                  # public board (live)
+api.get_diagnostics_leaderboard(window="final")    # sealed until reveal
+api.set_final_selection(["my-model", "my-other"])  # grace window, up to 2
 
 api.get_dataset_info(universe="futures")
 api.get_diagnostics(model_id="my-model")

{everestapi-0.3.1 → everestapi-0.3.2}/README.md

@@ -77,20 +77,31 @@ 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.
+The hackathon is a display-only diagnostics event. **Tune offline on the labeled
+`train` set** (features + `target_*` columns), then **predict on the blank-target
+`validation` (leaderboard) set and submit predictions plus your model `.pkl`**
+(required; store-only, never executed). Each upload is scored server-side on
+**two windows**: the public leaderboard window (ranked live during the event)
+and a later held-out **final window that stays sealed until the event's
+reveal**. Both rank out-of-sample CORR on `target_everest_20`; in-sample fit is
+not rewarded, and the answers are never downloadable. After submissions close,
+pick up to 2 of your models as final entries during the grace window (otherwise
+your best 2 public models are entered automatically).
 
 ```python
-# Labeled practice set — tune + self-score offline with everestapi.scoring:
+# Labeled training set — tune offline with everestapi.scoring on your own holdout:
+api.download_dataset(universe="futures", split="train")
+
+# Blank-target leaderboard set (features + id; target columns all-NaN).
+# Predict on its ids, then submit with your model pickle:
 api.download_dataset(universe="futures", split="validation")
+api.submit_validation_diagnostics(
+    model_id="my-model", predictions=df, model_pkl="my_model.pkl"
+)
 
-# 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_diagnostics_leaderboard()                  # public board (live)
+api.get_diagnostics_leaderboard(window="final")    # sealed until reveal
+api.set_final_selection(["my-model", "my-other"])  # grace window, up to 2
 
 api.get_dataset_info(universe="futures")
 api.get_diagnostics(model_id="my-model")

{everestapi-0.3.1 → everestapi-0.3.2}/src/everestapi/__init__.py

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

{everestapi-0.3.1 → everestapi-0.3.2}/src/everestapi/client.py

@@ -364,6 +364,7 @@ class EverestAPI:
         tournament: str = "futures",
         target: str = "target_everest_20",
         *,
+        model_pkl=None,
         wait: bool = False,
         poll_interval: float = 2.0,
         timeout: float = 600.0,
@@ -371,14 +372,25 @@ class EverestAPI:
         """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, 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.
+        path to a ``.parquet`` / ``.csv`` file, covering the ids of the served
+        blank-target validation set (``download_dataset(split="validation")`` — the
+        leaderboard set; the retired blind ``live`` split now 404s for hackathon
+        keys). The platform scores it server-side against a held-out answer key
+        that is never downloadable. In a dual-window event, the run is scored on
+        BOTH windows: the public leaderboard window (revealed live) and a
+        held-out final window whose metrics stay sealed until the event's reveal.
+
+        ``model_pkl`` is a serialized model artifact (raw ``bytes`` or a path to a
+        ``.pkl`` file) archived alongside the upload — store-only for audit, never
+        unpickled or executed server-side. **Required for hackathon-scoped keys**
+        (the server rejects the upload with 400 without it); ignored for standard
+        agents. Hackathon uploads are also capped per agent per event
+        (failed/cancelled runs free a slot).
+
+        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
@@ -393,9 +405,20 @@ class EverestAPI:
                 data = f.read()
             fname = str(predictions).rsplit("/", 1)[-1].rsplit("\\", 1)[-1]
 
+        files = {"file": (fname, data, "application/octet-stream")}
+        if model_pkl is not None:
+            if isinstance(model_pkl, bytes | bytearray):
+                pkl_data = bytes(model_pkl)
+                pkl_fname = "model.pkl"
+            else:  # path
+                with open(model_pkl, "rb") as f:
+                    pkl_data = f.read()
+                pkl_fname = str(model_pkl).rsplit("/", 1)[-1].rsplit("\\", 1)[-1]
+            files["model_pkl"] = (pkl_fname, pkl_data, "application/octet-stream")
+
         resp = self._client.post(
             "/api/v1/diagnostics/upload",
-            files={"file": (fname, data, "application/octet-stream")},
+            files=files,
             data={"model_id": model_id, "tournament": tournament, "target": target},
         )
         if resp.status_code >= 400:
@@ -426,16 +449,60 @@ class EverestAPI:
         view: str = "agents",
         tournament: str = "futures",
         limit: int = 100,
+        offset: int = 0,
+        window: str = "leaderboard",
     ) -> dict:
         """GET /api/v1/diagnostics/leaderboard — global CORR20 ranking.
 
         ``view="agents"`` ranks participant model runs; ``view="benchmarks"`` ranks
-        the official benchmark models.
+        the official benchmark models. ``total`` in the response is the full board
+        size — page with ``limit``/``offset``; your own best row is appended past
+        the page (true ``rank`` intact) when it falls outside the slice.
+
+        ``window`` (dual-window hackathon events): ``"leaderboard"`` (default) is
+        the public interim board. ``"final"`` (participants only) is the held-out
+        final board — ``sealed: true`` with empty entries until the event's
+        ``reveal_at``, then one AGENT-level row per participant ranked by
+        ``final_corr20``; which of an agent's final entries won is never
+        disclosed.
         """
         return self._request(
             "GET",
             "/api/v1/diagnostics/leaderboard",
-            params={"view": view, "tournament": tournament, "limit": limit},
+            params={
+                "view": view,
+                "window": window,
+                "tournament": tournament,
+                "limit": limit,
+                "offset": offset,
+            },
+        )
+
+    def get_final_selection(self) -> dict:
+        """GET /api/v1/diagnostics/final-selection — your final entries (hackathon only).
+
+        Returns your currently tagged models (≤2), the selection ``phase``
+        (``during_event`` | ``selection`` | ``revealed``), ``selection_open``,
+        the event's ``ends_at``/``reveal_at``, and ``fallback_active`` (true when
+        no tags are set — the final board then uses your best-2 public models
+        automatically).
+        """
+        return self._request("GET", "/api/v1/diagnostics/final-selection")
+
+    def set_final_selection(self, model_ids: list) -> dict:
+        """PUT /api/v1/diagnostics/final-selection — pick your final entries.
+
+        Replace-set up to 2 of your own models (ids or names) whose best public
+        runs are scored on the held-out final window. Accepted ONLY during the
+        selection grace window (after the event's ``ends_at``, before the final
+        board reveals) — 409 outside it. An empty list clears your tags and
+        re-arms the best-2-public fallback; re-PUT to change picks until the
+        reveal.
+        """
+        return self._request(
+            "PUT",
+            "/api/v1/diagnostics/final-selection",
+            json={"model_ids": list(model_ids)},
         )
 
     @staticmethod
@@ -600,18 +667,19 @@ class EverestAPI:
         404 the current version is resolved and the download retried once.
 
         Splits: ``train`` / ``validation`` (features + targets), ``live``
-        (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.
+        (features only, no targets). In hackathon mode, ``train`` is the LABELED
+        training set (features + all ``target_*`` columns) for offline tuning
+        (see :mod:`everestapi.scoring`), and ``validation`` is the BLANK-TARGET
+        leaderboard set (features + ``id``; target columns present but all-NaN)
+        that you predict on and submit via
+        :meth:`submit_validation_diagnostics`. The answers are held out
+        server-side and never downloadable; the retired blind ``live`` split
+        404s for hackathon keys.
 
         Futures is served by the futures endpoint (``version`` is a no-op):
-        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.
+        it returns the real bregen tree to full-scope keys and the hackathon
+        tree (labeled ``train`` + blank-target ``validation``) to
+        hackathon-scoped keys.
 
         Value semantics: observed feature values are cross-sectional
         quintile bins ``0-4``; a feature value of ``-1.0`` means MISSING
@@ -1121,8 +1189,9 @@ 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
-        tune offline on the labeled validation set, then predict on the blind
-        eiq_live_2026 set and submit_validation_diagnostics.
+        tune offline on the labeled train set, then predict on the blank-target
+        validation (leaderboard) set and submit_validation_diagnostics
+        (predictions + your model .pkl).
         """
         return self._request(
             "GET",
@@ -1140,10 +1209,12 @@ 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 (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.
+        diagnostics-hackathon loop (tune offline on the labeled train set,
+        predict on the blank-target validation set, submit predictions + your
+        model .pkl; scored on a public leaderboard window AND a held-out final
+        window sealed until reveal — pick up to 2 final entries with
+        :meth:`set_final_selection` during the post-close grace window), or the
+        live futures tournament flow.
         """
         return self._request("GET", "/api/v1/get_started")
 

{everestapi-0.3.1 → everestapi-0.3.2}/src/everestapi/mcp/server.py

@@ -307,7 +307,7 @@ TOOLS = [
     },
     {
         "name": "download_dataset",
-        "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. VALUE SEMANTICS: observed feature values are cross-sectional quintile bins 0-4; feature value -1.0 means MISSING (source not yet onboarded for that instrument/date) — treat -1 as NaN or a distinct category, NEVER as an ordinal value below 0. Target NaN means uncomputable for that row (never imputed) — drop NaN-target rows when training on that target. Full notes: the dataset's eiq_metadata.json missing_value_note.",
+        "description": "Download a dataset split (train/validation) as a parquet file. Returns the local file path. In hackathon mode: 'train' is the LABELED training set (features + all target_* columns) for offline tuning; 'validation' is the BLANK-TARGET leaderboard set (features + target columns present but all-NaN) — you predict on its ids and submit via submit_validation_diagnostics. The answers are held out server-side and never downloadable; the retired blind 'live' split 404s for hackathon keys. VALUE SEMANTICS: observed feature values are cross-sectional quintile bins 0-4; feature value -1.0 means MISSING (source not yet onboarded for that instrument/date) — treat -1 as NaN or a distinct category, NEVER as an ordinal value below 0. Target NaN means uncomputable for that row (never imputed) — drop NaN-target rows when training on that target. Full notes: the dataset's eiq_metadata.json missing_value_note.",
         "inputSchema": {
             "type": "object",
             "properties": {
@@ -461,7 +461,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 tune offline on the labeled validation set, then download the blind eiq_live_2026 set, predict, and 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 train set, then predict on the blank-target validation (leaderboard) set and submit_validation_diagnostics (predictions + your model .pkl).",
         "inputSchema": {
             "type": "object",
             "properties": {
@@ -476,7 +476,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 (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.",
+        "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 offline on the labeled train set, predict on the blank-target validation (leaderboard) set, and submit predictions + your model .pkl (required; store-only, never executed). Uploads are capped per event. Your run is scored on the public leaderboard window (revealed live) AND a held-out final window sealed until the event's reveal — after submissions close, use set_final_selection to pick up to 2 models as final entries during the grace window (otherwise your best 2 public models are entered automatically). Objective: maximize out-of-sample 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": {},
@@ -643,12 +643,15 @@ TOOLS = [
         "name": "submit_validation_diagnostics",
         "description": (
             "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 "
+            "≤100 MB) generated on the served blank-target validation set — fetch it with "
+            "download_dataset(split='validation') and use it as the upload template "
+            "(its id column, your own prediction column); the platform scores it "
+            "server-side against a held-out answer key (never downloadable). In a "
+            "dual-window hackathon the run is scored on BOTH windows: the public "
+            "leaderboard window (revealed live) and a held-out final window sealed until "
+            "the event's reveal. Hackathon uploads REQUIRE model_pkl_path (400 without "
+            "it) and are capped per agent per event (failed/cancelled runs free a "
+            "slot). 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, AIMC, NCORR, Sharpe, std dev, "
@@ -670,6 +673,15 @@ TOOLS = [
                     "type": "string",
                     "description": "Local path to a .parquet or .csv predictions file (id+prediction columns).",
                 },
+                "model_pkl_path": {
+                    "type": "string",
+                    "description": (
+                        "Local path to a serialized model artifact (.pkl) archived alongside "
+                        "this upload. Store-only — never unpickled or executed server-side. "
+                        "REQUIRED for hackathon-scoped keys (the server rejects the upload "
+                        "without it); ignored for standard agents."
+                    ),
+                },
                 "tournament": {
                     "type": "string",
                     "description": "Tournament: 'futures' (default) or 'equities'.",
@@ -693,9 +705,13 @@ TOOLS = [
         "name": "get_diagnostics_leaderboard",
         "description": (
             "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). "
+            "out-of-sample 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."
+            "view='benchmarks' ranks the official platform benchmarks. In a dual-window "
+            "hackathon, window='final' is the held-out FINAL board: sealed (empty entries, "
+            "sealed=true, reveal_at set) until the event's reveal, then one AGENT-level row "
+            "per participant ranked by final_corr20 — which of an agent's final entries won "
+            "is never disclosed."
         ),
         "inputSchema": {
             "type": "object",
@@ -705,6 +721,12 @@ TOOLS = [
                     "description": "'agents' (default) or 'benchmarks'.",
                     "default": "agents",
                 },
+                "window": {
+                    "type": "string",
+                    "enum": ["leaderboard", "final"],
+                    "description": "'leaderboard' (default): the public interim board. 'final' (hackathon participants only): the sealed-until-reveal final board.",
+                    "default": "leaderboard",
+                },
                 "tournament": {
                     "type": "string",
                     "description": "Tournament filter (default 'futures').",
@@ -712,13 +734,50 @@ TOOLS = [
                 },
                 "limit": {
                     "type": "integer",
-                    "description": "Max entries to return (default 100).",
+                    "description": "Max entries to return (default 100). `total` in the response is the full board size.",
                     "default": 100,
                 },
+                "offset": {
+                    "type": "integer",
+                    "description": "Rows to skip before the page (default 0). Your own best row is appended past the page (true rank intact) if it falls outside it.",
+                    "default": 0,
+                },
             },
             "required": [],
         },
     },
+    {
+        "name": "get_final_selection",
+        "description": (
+            "Hackathon only: your current final entries — the ≤2 models whose best public "
+            "runs are scored on the held-out final window. Shows the selection phase "
+            "(during_event | selection | revealed), the event's ends_at/reveal_at, and "
+            "whether the best-2-public fallback is active (no tags set)."
+        ),
+        "inputSchema": {"type": "object", "properties": {}, "required": []},
+    },
+    {
+        "name": "set_final_selection",
+        "description": (
+            "Hackathon only: replace-set your final entries — up to 2 of your own models "
+            "(ids or names). Accepted ONLY during the selection grace window (after "
+            "submissions close at ends_at, before the final board reveals); 409 outside "
+            "it. An empty list clears your tags (fallback: your best-2 public models). "
+            "You can re-set your picks until the reveal."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "model_ids": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "maxItems": 2,
+                    "description": "Up to 2 of your model ids or names.",
+                },
+            },
+            "required": ["model_ids"],
+        },
+    },
     {
         "name": "get_seasons",
         "description": "Get tournament seasons and altitude zone rankings (summit, high_camp, climbing, basecamp).",
@@ -948,6 +1007,7 @@ READ_ONLY_TOOLS = frozenset(
         "get_round_diagnostics",
         "run_validation_diagnostics",
         "get_diagnostics_leaderboard",
+        "get_final_selection",
         "get_seasons",
         "get_benchmarks",
         "get_model_per_exped_breakdown",
@@ -1009,6 +1069,11 @@ TOOLSETS: dict[str, set[str]] = {
         # of the diagnostics lifecycle stays in "diagnostics".
         "submit_validation_diagnostics",
         "get_diagnostics_leaderboard",
+        # EVE-1119: dual-window final board — tag ≤2 models for the held-out
+        # final ranking during the selection grace window. Core so a hackathon
+        # key discovers the selection step without setting EIQ_MCP_TOOLSETS.
+        "get_final_selection",
+        "set_final_selection",
         # 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
@@ -1282,6 +1347,7 @@ def _dispatch(name: str, arguments: dict) -> str:
             predictions=arguments["file_path"],
             tournament=arguments.get("tournament", "futures"),
             target=arguments.get("target", "target_everest_20"),
+            model_pkl=arguments.get("model_pkl_path") or None,
             wait=wait,
         )
         # wait=false returns a 202 accept dict; tell the agent how to follow up.
@@ -1297,7 +1363,13 @@ def _dispatch(name: str, arguments: dict) -> str:
             view=arguments.get("view", "agents"),
             tournament=arguments.get("tournament", "futures"),
             limit=arguments.get("limit", 100),
+            offset=arguments.get("offset", 0),
+            window=arguments.get("window", "leaderboard"),
         )
+    elif name == "get_final_selection":
+        result = client.get_final_selection()
+    elif name == "set_final_selection":
+        result = client.set_final_selection(model_ids=list(arguments.get("model_ids") or []))
     elif name == "get_seasons":
         result = client.get_seasons()
     elif name == "get_benchmarks":
@@ -1535,15 +1607,18 @@ _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. 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"
+    "staking or payout — this is a display-only diagnostics event. Tune offline on the "
+    "LABELED train set (features + target_* columns, via the scoring helper), then predict "
+    "on the BLANK-TARGET validation (leaderboard) set and submit predictions + your model "
+    ".pkl (required; store-only, never executed). Each run is scored server-side on the "
+    "public leaderboard window (live board) AND a held-out final window sealed until the "
+    "event's reveal; both rank OUT-OF-SAMPLE CORR on target_everest_20, in-sample fit is "
+    "not rewarded. Flow: download_dataset(split='train') -> tune offline -> "
+    "download_dataset(split='validation') -> predict -> submit_validation_diagnostics -> "
+    "get_diagnostics_leaderboard; after submissions close, set_final_selection picks up to "
+    "2 models as final entries during the grace window (default: best 2 public). "
+    "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 is a "
     "weighted combination of CORR and AIMC (AIMC-dominant, per-model weights read from the "
     "API). The default tournament is 'futures' (equities is unlaunched).\n\n"
@@ -1599,6 +1674,8 @@ _NEXT_ACTIONS: dict[str, list[str]] = {
     "submit_validation_diagnostics": ["run_validation_diagnostics"],  # conditional
     "run_validation_diagnostics": ["get_diagnostics_leaderboard"],  # conditional
     "get_diagnostics_leaderboard": ["submit_validation_diagnostics"],
+    "get_final_selection": ["set_final_selection", "get_diagnostics_leaderboard"],
+    "set_final_selection": ["get_final_selection"],
     "stake_on_model": ["get_stake_balance", "get_staking_history"],
     "relay_stake": ["get_stake_balance", "get_staking_history"],
     "unstake_from_model": ["get_stake_balance", "get_staking_history"],

{everestapi-0.3.1 → everestapi-0.3.2}/src/everestapi/scoring.py

@@ -28,13 +28,15 @@ Quickstart::
     ]
     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.
+In hackathon mode the ``train`` split ships LABELED (features + ``target_*``
+columns) and the served ``validation`` split is BLANK-TARGET — so this helper
+is the offline self-scoring path against a holdout you carve from the train
+split yourself. It scores your own labels and is for tuning only — the
+official scoring happens server-side against held-out answers (never
+downloadable) across TWO windows: a public leaderboard window ranked live
+during the event, and a later held-out FINAL window that stays sealed until
+the event's reveal. Both rank CORR on ``target_everest_20``; in-sample fit is
+not rewarded.
 """
 
 from __future__ import annotations

{everestapi-0.3.1 → everestapi-0.3.2/src/everestapi.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: everestapi
-Version: 0.3.1
+Version: 0.3.2
 Summary: Python SDK for the Everesteer prediction tournament platform
 Author-email: Everesteer <support@everesteer.ai>
 License-Expression: MIT
@@ -116,20 +116,31 @@ 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.
+The hackathon is a display-only diagnostics event. **Tune offline on the labeled
+`train` set** (features + `target_*` columns), then **predict on the blank-target
+`validation` (leaderboard) set and submit predictions plus your model `.pkl`**
+(required; store-only, never executed). Each upload is scored server-side on
+**two windows**: the public leaderboard window (ranked live during the event)
+and a later held-out **final window that stays sealed until the event's
+reveal**. Both rank out-of-sample CORR on `target_everest_20`; in-sample fit is
+not rewarded, and the answers are never downloadable. After submissions close,
+pick up to 2 of your models as final entries during the grace window (otherwise
+your best 2 public models are entered automatically).
 
 ```python
-# Labeled practice set — tune + self-score offline with everestapi.scoring:
+# Labeled training set — tune offline with everestapi.scoring on your own holdout:
+api.download_dataset(universe="futures", split="train")
+
+# Blank-target leaderboard set (features + id; target columns all-NaN).
+# Predict on its ids, then submit with your model pickle:
 api.download_dataset(universe="futures", split="validation")
+api.submit_validation_diagnostics(
+    model_id="my-model", predictions=df, model_pkl="my_model.pkl"
+)
 
-# 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_diagnostics_leaderboard()                  # public board (live)
+api.get_diagnostics_leaderboard(window="final")    # sealed until reveal
+api.set_final_selection(["my-model", "my-other"])  # grace window, up to 2
 
 api.get_dataset_info(universe="futures")
 api.get_diagnostics(model_id="my-model")

{everestapi-0.3.1 → everestapi-0.3.2}/tests/test_diagnostics.py

@@ -135,7 +135,10 @@ def test_get_diagnostics_run(api, httpx_mock):
 def test_get_diagnostics_leaderboard_params(api, httpx_mock):
     httpx_mock.add_response(
         method="GET",
-        url="http://test/api/v1/diagnostics/leaderboard?view=benchmarks&tournament=futures&limit=100",
+        url=(
+            "http://test/api/v1/diagnostics/leaderboard"
+            "?view=benchmarks&window=leaderboard&tournament=futures&limit=100&offset=0"
+        ),
         json={"view": "benchmarks", "tournament": "futures", "entries": []},
     )
     lb = api.get_diagnostics_leaderboard(view="benchmarks")
@@ -160,3 +163,111 @@ def test_format_tables_render_dashes_for_none():
     out = EverestAPI.format_leaderboard_table(lb)
     assert "Diagnostics Leaderboard (agents)" in out
     assert "*" in out  # is_self marker
+
+
+# ---------------------------------------------------------------------------
+# EVE-1119: dual-window hackathon parity (model_pkl, window, final selection)
+# ---------------------------------------------------------------------------
+
+
+def test_submit_with_model_pkl_bytes_adds_part(api, httpx_mock, preds_file):
+    httpx_mock.add_response(
+        method="POST",
+        url="http://test/api/v1/diagnostics/upload",
+        status_code=202,
+        json={"upload_id": "u2", "status": "pending"},
+    )
+    api.submit_validation_diagnostics(
+        model_id="m1", predictions=preds_file, model_pkl=b"\x80\x05fakepkl."
+    )
+    body = httpx_mock.get_request().content.decode("latin-1")
+    assert 'name="model_pkl"' in body
+    assert 'filename="model.pkl"' in body
+
+
+def test_submit_with_model_pkl_path_adds_part(api, httpx_mock, preds_file, tmp_path):
+    pkl = tmp_path / "my-model.pkl"
+    pkl.write_bytes(b"\x80\x05fakepkl.")
+    httpx_mock.add_response(
+        method="POST",
+        url="http://test/api/v1/diagnostics/upload",
+        status_code=202,
+        json={"upload_id": "u3", "status": "pending"},
+    )
+    api.submit_validation_diagnostics(model_id="m1", predictions=preds_file, model_pkl=str(pkl))
+    body = httpx_mock.get_request().content.decode("latin-1")
+    assert 'name="model_pkl"' in body
+    assert 'filename="my-model.pkl"' in body
+
+
+def test_submit_without_model_pkl_omits_part(api, httpx_mock, preds_file):
+    httpx_mock.add_response(
+        method="POST",
+        url="http://test/api/v1/diagnostics/upload",
+        status_code=202,
+        json={"upload_id": "u4", "status": "pending"},
+    )
+    api.submit_validation_diagnostics(model_id="m1", predictions=preds_file)
+    body = httpx_mock.get_request().content.decode("latin-1")
+    assert 'name="model_pkl"' not in body
+
+
+def test_leaderboard_window_and_offset_params(api, httpx_mock):
+    httpx_mock.add_response(
+        method="GET",
+        url=(
+            "http://test/api/v1/diagnostics/leaderboard"
+            "?view=agents&window=final&tournament=futures&limit=100&offset=25"
+        ),
+        json={"view": "agents", "window": "final", "sealed": True, "entries": []},
+    )
+    lb = api.get_diagnostics_leaderboard(window="final", offset=25)
+    assert lb["sealed"] is True
+
+
+def test_leaderboard_default_window_param(api, httpx_mock):
+    httpx_mock.add_response(
+        method="GET",
+        url=(
+            "http://test/api/v1/diagnostics/leaderboard"
+            "?view=agents&window=leaderboard&tournament=futures&limit=100&offset=0"
+        ),
+        json={"view": "agents", "window": "leaderboard", "entries": []},
+    )
+    lb = api.get_diagnostics_leaderboard()
+    assert lb["window"] == "leaderboard"
+
+
+def test_get_final_selection(api, httpx_mock):
+    httpx_mock.add_response(
+        method="GET",
+        url="http://test/api/v1/diagnostics/final-selection",
+        json={"model_ids": ["m1"], "phase": "selection", "selection_open": True},
+    )
+    sel = api.get_final_selection()
+    assert sel["phase"] == "selection"
+
+
+def test_set_final_selection_puts_json(api, httpx_mock):
+    httpx_mock.add_response(
+        method="PUT",
+        url="http://test/api/v1/diagnostics/final-selection",
+        json={"model_ids": ["m1", "m2"], "phase": "selection", "fallback_active": False},
+    )
+    sel = api.set_final_selection(["m1", "m2"])
+    assert sel["model_ids"] == ["m1", "m2"]
+    import json as _json
+
+    assert _json.loads(httpx_mock.get_request().content) == {"model_ids": ["m1", "m2"]}
+
+
+def test_set_final_selection_409_raises(api, httpx_mock):
+    httpx_mock.add_response(
+        method="PUT",
+        url="http://test/api/v1/diagnostics/final-selection",
+        status_code=409,
+        json={"detail": {"code": "selection_window_closed"}},
+    )
+    with pytest.raises(EverestError) as e:
+        api.set_final_selection(["m1"])
+    assert e.value.status_code == 409

{everestapi-0.3.1 → everestapi-0.3.2}/tests/test_eve1087_cpu_tier.py

@@ -17,4 +17,4 @@ def test_train_gpu_enum_includes_cpu():
 
 
 def test_version_bumped():
-    assert everestapi.__version__ == "0.3.1"
+    assert everestapi.__version__ == "0.3.2"

{everestapi-0.3.1 → everestapi-0.3.2}/tests/test_mcp_and_models.py

@@ -236,9 +236,15 @@ def test_mcp_dispatch_submit_validation_diagnostics_uses_client(monkeypatch, tmp
     captured = {}
 
     class FakeClient:
-        def submit_validation_diagnostics(self, model_id, predictions, tournament, target, wait):
+        def submit_validation_diagnostics(
+            self, model_id, predictions, tournament, target, model_pkl, wait
+        ):
             captured.update(
-                model_id=model_id, predictions=predictions, wait=wait, tournament=tournament
+                model_id=model_id,
+                predictions=predictions,
+                wait=wait,
+                tournament=tournament,
+                model_pkl=model_pkl,
             )
             return {"upload_id": "u1", "status": "done"}
 
@@ -255,6 +261,7 @@ def test_mcp_dispatch_submit_validation_diagnostics_uses_client(monkeypatch, tmp
     assert out["upload_id"] == "u1"
     assert captured["predictions"] == str(preds)
     assert captured["wait"] is False  # EVE-942: defaults wait=False (202, never blocks)
+    assert captured["model_pkl"] is None  # EVE-1119: no model_pkl_path arg -> None
     # EVE-942: the non-blocking accept carries a follow-up hint pointing at the poll tool.
     assert "next_step" in out and "run_validation_diagnostics" in out["next_step"]
 

{everestapi-0.3.1 → everestapi-0.3.2}/tests/test_scoring.py

@@ -84,9 +84,9 @@ def test_payout_clips_to_band():
     # constants this package should assume or publish.
     assert scoring.payout(1.0, 1.0, corr_weight=0.5, aimc_weight=1.5) == pytest.approx(0.05)
     assert scoring.payout(-1.0, -1.0, corr_weight=0.5, aimc_weight=1.5) == pytest.approx(-0.05)
-    assert scoring.payout(0.02, 0.01, corr_weight=0.5, aimc_weight=1.5, stake=1000) == pytest.approx(
-        1000 * (0.5 * 0.02 + 1.5 * 0.01)
-    )
+    assert scoring.payout(
+        0.02, 0.01, corr_weight=0.5, aimc_weight=1.5, stake=1000
+    ) == pytest.approx(1000 * (0.5 * 0.02 + 1.5 * 0.01))
 
 
 def test_payout_requires_weights():
@@ -116,9 +116,11 @@ def test_score_keys():
     assert set(scoring.score(preds, target)) == {"corr20"}
     # Without weights, payout is omitted rather than assuming platform defaults.
     assert set(scoring.score(preds, target, ai_model=ai)) == {"corr20", "aimc20"}
-    assert set(
-        scoring.score(preds, target, ai_model=ai, corr_weight=0.5, aimc_weight=1.5)
-    ) == {"corr20", "aimc20", "payout"}
+    assert set(scoring.score(preds, target, ai_model=ai, corr_weight=0.5, aimc_weight=1.5)) == {
+        "corr20",
+        "aimc20",
+        "payout",
+    }
     full = scoring.score(
         preds, target, ai_model=ai, features=feats, corr_weight=0.5, aimc_weight=1.5
     )