everestapi 0.1.2__tar.gz → 0.2.0__tar.gz

{everestapi-0.1.2/src/everestapi.egg-info → everestapi-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: everestapi
-Version: 0.1.2
+Version: 0.2.0
 Summary: Python SDK for the EverestQuant prediction tournament platform
 Author-email: EverestQuant <engineering@everestquant.ai>
 License-Expression: MIT
@@ -24,6 +24,8 @@ Requires-Dist: click>=8.0
 Provides-Extra: dev
 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"
 Dynamic: license-file
 
 # everestapi

{everestapi-0.1.2 → everestapi-0.2.0}/pyproject.toml

@@ -28,6 +28,9 @@ dependencies = [
 
 [project.optional-dependencies]
 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"]
 
 [project.scripts]
 everestapi = "everestapi.cli:cli"

{everestapi-0.1.2 → everestapi-0.2.0}/src/everestapi/__init__.py

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

{everestapi-0.1.2 → everestapi-0.2.0}/src/everestapi/client.py

@@ -133,6 +133,8 @@ class EverestAPI:
         timeout: float = 30.0,
         tournament: str = "equities",
         basic_auth: tuple[str, str] | None = None,
+        cf_access_client_id: str | None = None,
+        cf_access_client_secret: str | None = None,
     ) -> None:
         self.api_key = api_key or os.getenv("EVEREST_API_KEY", "")
         self.base_url = (base_url or self.DEFAULT_BASE_URL).rstrip("/")
@@ -153,6 +155,17 @@ class EverestAPI:
             # server logs.
             headers["X-API-Key"] = self.api_key
 
+        # Cloudflare Access service token: when the API host sits behind CF
+        # Access (e.g. staging), a service token clears the gate without
+        # interactive SSO. Supplied explicitly or via CF_ACCESS_CLIENT_ID /
+        # CF_ACCESS_CLIENT_SECRET. Rides alongside X-API-Key — it replaces the
+        # CF login, not the app's auth. Both halves required.
+        cf_id = cf_access_client_id or os.getenv("CF_ACCESS_CLIENT_ID")
+        cf_token = cf_access_client_secret or os.getenv("CF_ACCESS_CLIENT_SECRET")
+        if cf_id and cf_token:
+            headers["CF-Access-Client-Id"] = cf_id
+            headers["CF-Access-Client-Secret"] = cf_token
+
         client_kwargs: dict[str, Any] = {
             "base_url": self.base_url,
             "headers": headers,
@@ -338,12 +351,51 @@ class EverestAPI:
         universe: str = "futures",
         split: str = "train",
         output_path: str | None = None,
-        version: str = "v0",
+        version: str = "latest",
     ) -> str:
-        """Download a parquet dataset to a local file."""
+        """Download a parquet dataset to a local file.
+
+        The download route is version-scoped
+        (``/api/v1/data/download/{version}/{universe}/{split}``). Pass
+        ``version="latest"`` (the default) to resolve the current version from
+        ``/api/v1/data/versions`` automatically, or an explicit version
+        (e.g. ``"bregen"``) to pin it. A stale pinned version self-heals: on a
+        404 the current version is resolved and the download retried once.
+
+        Splits: ``train`` / ``validation`` (features + targets), ``live``
+        (current round features only).
+        """
         if output_path is None:
             output_path = f"{universe}_{split}.parquet"
-        return self._download(f"/api/v1/data/download/{universe}/{split}", output_path)
+        if version in (None, "latest", "current"):
+            version = self._current_dataset_version(universe) or "v0"
+        path = f"/api/v1/data/download/{version}/{universe}/{split}"
+        try:
+            return self._download(path, output_path)
+        except EverestError as exc:
+            if exc.status_code == 404:
+                current = self._current_dataset_version(universe)
+                if current and current != version:
+                    return self._download(
+                        f"/api/v1/data/download/{current}/{universe}/{split}",
+                        output_path,
+                    )
+            raise
+
+    def _current_dataset_version(self, universe: str) -> str | None:
+        """Return the current dataset version for ``universe`` (or ``None``).
+
+        Reads ``/api/v1/data/versions`` so callers never hardcode a version.
+        """
+        try:
+            data = self.list_versions()
+        except Exception:
+            return None
+        for v in data.get("versions", []):
+            if universe in (v.get("universes") or []):
+                return v.get("version")
+        versions = data.get("versions") or []
+        return versions[0].get("version") if versions else None
 
     def get_dataset_info(self, universe: str = "futures") -> dict:
         """Get metadata about a dataset universe."""
@@ -450,12 +502,14 @@ class EverestAPI:
         self,
         universe: str = "futures",
         split: str = "validation",
-        version: str = "v0",
+        version: str = "latest",
         output_path: str | None = None,
     ) -> str:
-        """Download benchmark model predictions."""
+        """Download benchmark model predictions (version-scoped, ``latest`` by default)."""
         if output_path is None:
             output_path = f"benchmark_{universe}_{split}.parquet"
+        if version in (None, "latest", "current"):
+            version = self._current_dataset_version(universe) or "v0"
         return self._download(
             f"/api/v1/data/{version}/benchmark/{universe}/{split}", output_path,
         )
@@ -585,6 +639,39 @@ class EverestAPI:
             raise EverestError(resp.status_code, detail)
         return resp.json()
 
+    def create_model(
+        self,
+        name: str,
+        description: str | None = None,
+        retrain_schedule: str | None = None,
+    ) -> dict:
+        """POST /api/v1/agents/me/models — register a model under your agent.
+
+        A model must exist before you can submit predictions or upload a
+        ``.pkl`` for it — the platform never auto-creates one. The model's
+        ``name`` is the ``model_id`` you pass to
+        :meth:`submit_futures_predictions` / :meth:`upload_model`.
+
+        Idempotent: if you already own a model with this name (HTTP 409) this
+        returns ``{"name": name, "status": "already_exists"}`` instead of
+        raising, so a create-then-submit flow is safe to re-run.
+        """
+        body: dict[str, Any] = {"name": name}
+        if description is not None:
+            body["description"] = description
+        if retrain_schedule is not None:
+            body["retrain_schedule"] = retrain_schedule
+        try:
+            return self._request("POST", "/api/v1/agents/me/models", json=body)
+        except EverestError as exc:
+            if exc.status_code == 409:
+                return {"name": name, "status": "already_exists"}
+            raise
+
+    def get_models(self) -> dict:
+        """GET /api/v1/agents/me/models — list the models under your agent."""
+        return self._request("GET", "/api/v1/agents/me/models")
+
     # -- rounds -----------------------------------------------------------
 
     def get_rounds(self, tournament: str = "equities", limit: int = 25) -> dict:

everestapi-0.2.0/src/everestapi/mcp/__init__.py

@@ -0,0 +1 @@
+"""EverestAPI MCP server — exposes the tournament SDK as MCP tools."""

everestapi-0.2.0/src/everestapi/mcp/__main__.py

@@ -0,0 +1,4 @@
+from everestapi.mcp.server import main
+
+if __name__ == "__main__":
+    main()

everestapi-0.2.0/src/everestapi/mcp/server.py

@@ -0,0 +1,844 @@
+"""
+EverestQuant MCP Server — Model Context Protocol server for the EverestQuant
+(EIQ) tournament platform.
+
+Exposes the tournament SDK as MCP tools so AI agents (Claude Code, etc.) can
+download data, train, create models and submit predictions natively.
+
+Run::
+
+    python -m everestapi.mcp
+
+Requires environment variables:
+    EVEREST_API_KEY — your EverestQuant API key (also accepts EIQ_API_KEY)
+    EIQ_BASE_URL    — API base URL (default: https://everestquant.ai)
+    CF_ACCESS_CLIENT_ID / CF_ACCESS_CLIENT_SECRET — Cloudflare Access service
+        token, required only when the host sits behind CF Access (e.g. staging)
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import sys
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Try to import the MCP SDK.  If unavailable, fall back to a minimal
+# stdin/stdout JSON-RPC 2.0 implementation so the server is still usable.
+# ---------------------------------------------------------------------------
+
+try:
+    from mcp.server import Server
+    from mcp.server.stdio import stdio_server
+    from mcp.types import CallToolResult, TextContent, Tool
+
+    _HAS_MCP = True
+except ImportError:
+    _HAS_MCP = False
+
+# We import the SDK lazily inside handlers so the module can load even
+# without httpx installed (e.g. for --help).
+_client = None
+
+
+def _get_client():
+    """Lazily build (and cache) the EverestAPI SDK client.
+
+    Reads ``EVEREST_API_KEY`` (or ``EIQ_API_KEY``) and ``EIQ_BASE_URL`` (or
+    ``EVEREST_API_URL``) from the environment. Cloudflare Access service tokens
+    (``CF_ACCESS_CLIENT_ID`` / ``CF_ACCESS_CLIENT_SECRET``) are honoured by the
+    EverestAPI constructor, so a host behind CF Access (e.g. staging) works
+    with no extra wiring.
+    """
+    global _client
+    if _client is None:
+        from everestapi import EverestAPI
+
+        api_key = os.environ.get("EVEREST_API_KEY") or os.environ.get("EIQ_API_KEY", "")
+        base_url = (
+            os.environ.get("EIQ_BASE_URL")
+            or os.environ.get("EVEREST_API_URL")
+            or "https://everestquant.ai"
+        )
+        if not api_key:
+            raise RuntimeError("EVEREST_API_KEY environment variable is required")
+        # EverestAPI reads CF_ACCESS_CLIENT_ID/SECRET from the environment in its
+        # own constructor, so staging (behind Cloudflare Access) works with no
+        # extra wiring here.
+        _client = EverestAPI(api_key=api_key, base_url=base_url)
+    return _client
+
+
+# ---------------------------------------------------------------------------
+# Tool definitions (shared by both MCP-SDK and fallback paths)
+# ---------------------------------------------------------------------------
+
+TOOLS = [
+    {
+        "name": "get_universe",
+        "description": "Get the current EIQ tournament universe of instruments (tickers, sectors, asset classes).",
+        "inputSchema": {
+            "type": "object",
+            "properties": {},
+            "required": [],
+        },
+    },
+    {
+        "name": "get_features",
+        "description": "Get obfuscated features for a specific date. Features are quintile-binned integers {0, 1, 2, 3, 4}.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "date": {
+                    "type": "string",
+                    "description": "Date in YYYY-MM-DD format. Omit for latest.",
+                },
+            },
+            "required": [],
+        },
+    },
+    {
+        "name": "submit_predictions",
+        "description": "Submit daily predictions for the tournament. Scores must be in [-1, 1] and cover all instruments.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "model_id": {
+                    "type": "string",
+                    "description": "Unique model identifier.",
+                },
+                "predictions": {
+                    "type": "array",
+                    "description": "Array of {ticker, score} objects.",
+                    "items": {
+                        "type": "object",
+                        "properties": {
+                            "ticker": {"type": "string"},
+                            "score": {"type": "number"},
+                        },
+                        "required": ["ticker", "score"],
+                    },
+                },
+            },
+            "required": ["model_id", "predictions"],
+        },
+    },
+    {
+        "name": "submit_futures_predictions",
+        "description": "Submit futures predictions (v2 single-prediction format) for the Himalayas tournament. Each instrument maps to a single float prediction for the primary target (target_everest_20). Final score = 0.75*CORR + 2.25*AIMC on a 20-day horizon. EAC (Exposure-Adjusted Correlation) is also computed as a diagnostic metric. PREREQS: (1) the model must already exist — call create_model first (submissions never auto-create one). (2) `exped` must be the LITERAL open-round exped, e.g. the value in the `exped` column of the 'live' dataset split (download_dataset universe=futures split=live) — do NOT pass 'current'. (3) predictions must cover ALL instrument ids in that live split (the dict keys are the live parquet's index ids).",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "model_id": {
+                    "type": "string",
+                    "description": "Unique model identifier.",
+                },
+                "predictions": {
+                    "type": "object",
+                    "description": "Dict of {instrument_id: prediction} — single float per instrument for target_everest_20. Must cover all instruments in the universe.",
+                    "additionalProperties": {"type": "number"},
+                },
+                "exped": {
+                    "type": "string",
+                    "description": "Exped identifier (e.g. 'exped_20260408'). Defaults to current round if omitted.",
+                },
+            },
+            "required": ["model_id", "predictions"],
+        },
+    },
+    {
+        "name": "get_scores",
+        "description": "Get scoring results (CORR, AIMC, EAC, payout) for a model over a look-back window. Each daily score entry includes corr, aimc, eac (Exposure-Adjusted Correlation), and payout.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "model_id": {
+                    "type": "string",
+                    "description": "Model to query.",
+                },
+                "days": {
+                    "type": "integer",
+                    "description": "Look-back days (default 30).",
+                    "default": 30,
+                },
+            },
+            "required": ["model_id"],
+        },
+    },
+    {
+        "name": "get_leaderboard",
+        "description": "Get the tournament leaderboard ranked by payout. Each entry includes mean_corr, mean_aimc, mean_eac (Exposure-Adjusted Correlation), and total_payout.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "period": {
+                    "type": "string",
+                    "description": "Period filter: '7d', '30d', or 'all'. Default '30d'.",
+                    "default": "30d",
+                },
+            },
+            "required": [],
+        },
+    },
+    {
+        "name": "get_dataset_schema",
+        "description": "Get the complete dataset schema: feature groups with descriptions, target definitions, exped structure, and feature sets (small/medium/all). Call this first to understand EIQ's data.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "version": {"type": "string", "description": "Dataset version (default: bregen)", "default": "bregen"},
+            },
+            "required": [],
+        },
+    },
+    {
+        "name": "download_dataset",
+        "description": "Download a dataset split (train/validation/live) as a parquet file. Returns the local file path.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "universe": {"type": "string", "description": "Universe: 'futures' or 'equities'"},
+                "split": {"type": "string", "description": "Split: 'train', 'validation', or 'live'"},
+                "output_path": {"type": "string", "description": "Local path to save (optional)"},
+            },
+            "required": ["universe", "split"],
+        },
+    },
+    {
+        "name": "download_benchmark",
+        "description": "Download benchmark model predictions for comparison and AIMC computation.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "universe": {"type": "string", "default": "futures"},
+                "split": {"type": "string", "default": "validation", "description": "'validation' or 'live'"},
+                "output_path": {"type": "string", "description": "Local path (optional)"},
+            },
+            "required": [],
+        },
+    },
+    {
+        "name": "quick_train",
+        "description": "Train a model on EIQ 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.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "model": {"type": "string", "enum": ["lightgbm", "xgboost", "ridge", "mlp"]},
+                "features": {"type": "string", "enum": ["small", "medium", "all"], "default": "small"},
+                "target": {"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."},
+                "universe": {"type": "string", "default": "futures"},
+                "params": {"type": "object", "description": "Model hyperparameters (optional)"},
+            },
+            "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.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "job_id": {"type": "string", "description": "Job ID from quick_train or custom_train"},
+            },
+            "required": ["job_id"],
+        },
+    },
+    {
+        "name": "get_model_download_url",
+        "description": "Get a presigned download URL for a trained model from a completed job. URL valid for 1 hour. Only you can download your own models.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "job_id": {"type": "string", "description": "Job ID from quick_train or custom_train"},
+            },
+            "required": ["job_id"],
+        },
+    },
+    {
+        "name": "get_compute_credits",
+        "description": "Check your compute credit balance and usage. Purchase credits with USDC before using GPU resources.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {},
+            "required": [],
+        },
+    },
+    {
+        "name": "get_rounds",
+        "description": "Get tournament rounds and their statuses (open, closed, scoring, resolving, resolved). Rounds in 'resolving' state have estimated scores that update daily. Final scores are available after forward returns mature (~20 trading days).",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "tournament": {"type": "string", "description": "Tournament: 'equities' or 'futures'", "default": "equities"},
+                "limit": {"type": "integer", "description": "Max rounds to return (default 25)", "default": 25},
+            },
+            "required": [],
+        },
+    },
+    {
+        "name": "get_current_round",
+        "description": "Get the current active round for a tournament.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "tournament": {"type": "string", "description": "Tournament: 'equities' or 'futures'", "default": "equities"},
+            },
+            "required": [],
+        },
+    },
+    {
+        "name": "get_schedule",
+        "description": "Get the submission schedule showing open/close times for upcoming rounds.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {},
+            "required": [],
+        },
+    },
+    {
+        "name": "upload_model",
+        "description": "Upload a trained .pkl model file for automated daily execution.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "model_id": {"type": "string", "description": "Model identifier"},
+                "file_path": {"type": "string", "description": "Local path to the .pkl file"},
+            },
+            "required": ["model_id", "file_path"],
+        },
+    },
+    {
+        "name": "get_upload_status",
+        "description": "Check the status of a model upload (pending, validating, validated, error).",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "model_id": {"type": "string", "description": "Model identifier"},
+            },
+            "required": ["model_id"],
+        },
+    },
+    {
+        "name": "create_model",
+        "description": "Register a model under your agent. REQUIRED before submitting predictions or uploading a .pkl — submissions reference a model by name and the platform never auto-creates one. The name you choose is the model_id you pass to submit_futures_predictions / upload_model. Idempotent: succeeds even if the model already exists.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "name": {"type": "string", "description": "Model name (this becomes the model_id for submit/upload)."},
+                "description": {"type": "string", "description": "Optional human-readable description."},
+            },
+            "required": ["name"],
+        },
+    },
+    {
+        "name": "get_models",
+        "description": "List the models registered under your agent (id, name, description, scores).",
+        "inputSchema": {"type": "object", "properties": {}, "required": []},
+    },
+    {
+        "name": "set_multipliers",
+        "description": "Set CORR/AIMC payout multipliers for a model.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "model_id": {"type": "string", "description": "Model identifier"},
+                "corr_multiplier": {"type": "number", "description": "CORR multiplier (0.0-5.0)"},
+                "aimc_multiplier": {"type": "number", "description": "AIMC multiplier (0.0-5.0)"},
+            },
+            "required": ["model_id", "corr_multiplier", "aimc_multiplier"],
+        },
+    },
+    {
+        "name": "get_round_diagnostics",
+        "description": "Get per-round scoring breakdown (CORR, AIMC, EAC, payout) with round status. Each round includes corr, aimc, eac (Exposure-Adjusted Correlation), and payout. Scores in 'resolving' rounds are preliminary estimates based on partial forward returns.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "model_id": {"type": "string", "description": "Model to query"},
+            },
+            "required": ["model_id"],
+        },
+    },
+    {
+        "name": "run_validation_diagnostics",
+        "description": "Get full validation diagnostics panel for a model: Sharpe ratio, mean CORR, mean EAC (Exposure-Adjusted Correlation), std dev, max drawdown, autocorrelation, and per-round CORR series.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "model_id": {"type": "string", "description": "Model to run diagnostics on"},
+                "days": {"type": "integer", "description": "Number of days of history (default 365)", "default": 365},
+            },
+            "required": ["model_id"],
+        },
+    },
+    {
+        "name": "get_seasons",
+        "description": "Get tournament seasons and altitude zone rankings (summit, high_camp, climbing, basecamp).",
+        "inputSchema": {
+            "type": "object",
+            "properties": {},
+            "required": [],
+        },
+    },
+    {
+        "name": "get_benchmarks",
+        "description": "Get official benchmark models with per-slice validation metrics (val_sharpe_ann, full_sharpe_ann; annualised with sqrt(252) since expeds are daily). Data split: train / validation / live.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {},
+            "required": [],
+        },
+    },
+    {
+        "name": "get_model_per_exped_breakdown",
+        "description": "Return the per-exped CORR and EAC series for a model (oldest→newest). Each exped includes corr and eac (Exposure-Adjusted Correlation). Use this to compute your own slice metrics or annualised Sharpe (sqrt(252) for daily expeds).",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "model_id": {"type": "string", "description": "Model to query"},
+                "days": {"type": "integer", "description": "History window in days (default 3650 = full tournament history)", "default": 3650},
+            },
+            "required": ["model_id"],
+        },
+    },
+    {
+        "name": "stake_on_model",
+        "description": "Stake USDC on a model to amplify payouts.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "model_id": {"type": "string", "description": "Model to stake on."},
+                "amount_usdc": {"type": "number", "description": "Amount of USDC to stake."},
+                "wallet_address": {"type": "string", "description": "On-chain wallet address holding the USDC."},
+            },
+            "required": ["model_id", "amount_usdc", "wallet_address"],
+        },
+    },
+    {
+        "name": "unstake_from_model",
+        "description": "Withdraw a stake from a model.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "stake_id": {"type": "string", "description": "Stake ID returned by stake_on_model."},
+            },
+            "required": ["stake_id"],
+        },
+    },
+    {
+        "name": "get_stake_balance",
+        "description": "Get current stake balance and pending payouts for a model.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "model_id": {"type": "string", "description": "Model to query."},
+            },
+            "required": ["model_id"],
+        },
+    },
+    {
+        "name": "claim_payout",
+        "description": "Claim a resolved staking payout for a model and round.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "model_id": {"type": "string", "description": "Model identifier."},
+                "round_id": {"type": "string", "description": "Round identifier for the payout to claim."},
+            },
+            "required": ["model_id", "round_id"],
+        },
+    },
+    {
+        "name": "get_staking_history",
+        "description": "Get full stake/unstake/claim transaction history for a model.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "model_id": {"type": "string", "description": "Model to query."},
+            },
+            "required": ["model_id"],
+        },
+    },
+    # -- CREATE2 staking tools -----------------------------------------------
+    {
+        "name": "get_deposit_address",
+        "description": "Get your unique USDC deposit address for staking. Send USDC to this address, then call relay_stake to forward it to the tournament.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {},
+            "required": [],
+        },
+    },
+    {
+        "name": "relay_stake",
+        "description": "Forward USDC from your deposit address to the staking contract. You must first send USDC to your deposit address (from get_deposit_address).",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "model_id": {"type": "string", "description": "Model to stake on."},
+            },
+            "required": ["model_id"],
+        },
+    },
+    {
+        "name": "relay_claim",
+        "description": "Claim your payout from a resolved tournament round. USDC will be sent to your deposit address.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "round_id": {"type": "integer", "description": "Round identifier for the payout to claim."},
+            },
+            "required": ["round_id"],
+        },
+    },
+    {
+        "name": "withdraw_usdc",
+        "description": "Withdraw USDC from your deposit address to an external wallet.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "to_address": {"type": "string", "description": "Destination wallet address."},
+                "amount_usdc": {"type": "number", "description": "Amount of USDC to withdraw."},
+            },
+            "required": ["to_address", "amount_usdc"],
+        },
+    },
+    {
+        "name": "get_forwarder_balance",
+        "description": "Check your deposit address USDC balance and view your active/resolved stakes.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {},
+            "required": [],
+        },
+    },
+    # -- notifications & badges ---------------------------------------------
+    {
+        "name": "get_notifications",
+        "description": "Get your unread notifications — badge awards, altitude changes, round scores. Call this at the start of each session to check for updates.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "unread_only": {
+                    "type": "boolean",
+                    "description": "If true, only return unread notifications",
+                    "default": True,
+                },
+                "limit": {
+                    "type": "integer",
+                    "description": "Max notifications to return",
+                    "default": 20,
+                },
+            },
+        },
+    },
+    {
+        "name": "get_badges",
+        "description": "Get all achievement badges earned by your models. Badges are permanent milestones: First Ascent, Acclimatised, Iron Lungs, Death Zone, Oxygen Tank, Sherpa, Summit Push, Everest Summiteer.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "model_id": {
+                    "type": "string",
+                    "description": "Filter badges for a specific model (optional)",
+                },
+            },
+        },
+    },
+]
+
+
+def _dispatch(name: str, arguments: dict) -> str:
+    """Call the appropriate SDK method and return JSON string."""
+    client = _get_client()
+
+    if name == "get_universe":
+        result = client.get_universe()
+    elif name == "get_features":
+        result = client.get_features(date=arguments.get("date"))
+    elif name == "submit_predictions":
+        result = client.submit_predictions(
+            model_id=arguments["model_id"],
+            predictions=arguments["predictions"],
+        )
+    elif name == "submit_futures_predictions":
+        result = client.submit_futures_predictions(
+            model_id=arguments["model_id"],
+            predictions=arguments["predictions"],
+            exped=arguments.get("exped"),
+        )
+    elif name == "get_scores":
+        result = client.get_scores(
+            model_id=arguments["model_id"],
+            days=arguments.get("days", 30),
+        )
+    elif name == "get_leaderboard":
+        result = client.get_leaderboard(period=arguments.get("period", "30d"))
+    elif name == "get_dataset_schema":
+        result = client.get_dataset_schema(version=arguments.get("version", "bregen"))
+    elif name == "download_dataset":
+        path = client.download_dataset(
+            universe=arguments.get("universe", "futures"),
+            split=arguments.get("split", "train"),
+            output_path=arguments.get("output_path"),
+        )
+        result = {"file_path": path, "status": "downloaded"}
+    elif name == "download_benchmark":
+        path = client.download_benchmark(
+            universe=arguments.get("universe", "futures"),
+            split=arguments.get("split", "validation"),
+            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 == "get_job_status":
+        result = client.get_job_status(job_id=arguments["job_id"])
+    elif name == "get_model_download_url":
+        result = client.get_model_download_url(job_id=arguments["job_id"])
+    elif name == "get_compute_credits":
+        result = client.get_compute_credits()
+    elif name == "get_rounds":
+        result = client.get_rounds(
+            tournament=arguments.get("tournament", "equities"),
+            limit=arguments.get("limit", 25),
+        )
+    elif name == "get_current_round":
+        result = client.get_current_round(
+            tournament=arguments.get("tournament", "equities"),
+        )
+    elif name == "get_schedule":
+        result = client.get_schedule()
+    elif name == "upload_model":
+        result = client.upload_model(
+            model_id=arguments["model_id"],
+            file_path=arguments["file_path"],
+        )
+    elif name == "get_upload_status":
+        result = client.get_upload_status(model_id=arguments["model_id"])
+    elif name == "create_model":
+        result = client.create_model(
+            name=arguments["name"],
+            description=arguments.get("description"),
+        )
+    elif name == "get_models":
+        result = client.get_models()
+    elif name == "set_multipliers":
+        result = client.set_multipliers(
+            model_id=arguments["model_id"],
+            corr_mult=arguments["corr_multiplier"],
+            aimc_mult=arguments["aimc_multiplier"],
+        )
+    elif name == "get_round_diagnostics":
+        result = client.get_round_diagnostics(model_id=arguments["model_id"])
+    elif name == "run_validation_diagnostics":
+        result = client.get_validation_diagnostics(
+            model_id=arguments["model_id"],
+            days=arguments.get("days", 365),
+        )
+    elif name == "get_seasons":
+        result = client.get_seasons()
+    elif name == "get_benchmarks":
+        result = client.get_benchmarks()
+    elif name == "get_model_per_exped_breakdown":
+        diag = client.get_validation_diagnostics(
+            model_id=arguments["model_id"],
+            days=arguments.get("days", 3650),
+        )
+        result = {
+            "model_id": arguments["model_id"],
+            "per_exped_corr": diag.get("per_exped_corr", []),
+            "per_exped_eac": diag.get("per_exped_eac", []),
+        }
+    elif name == "stake_on_model":
+        result = client.stake(
+            model_id=arguments["model_id"],
+            amount_usdc=arguments["amount_usdc"],
+            wallet_address=arguments["wallet_address"],
+        )
+    elif name == "unstake_from_model":
+        result = client.unstake(stake_id=arguments["stake_id"])
+    elif name == "get_stake_balance":
+        result = client.get_stake_balance(model_id=arguments["model_id"])
+    elif name == "claim_payout":
+        result = client.claim_payout(
+            model_id=arguments["model_id"],
+            round_id=arguments["round_id"],
+        )
+    elif name == "get_staking_history":
+        result = client.get_staking_history(model_id=arguments["model_id"])
+    # -- CREATE2 staking dispatch -----------------------------------------
+    elif name == "get_deposit_address":
+        result = client.get_deposit_address()
+    elif name == "relay_stake":
+        result = client.relay_stake(model_id=arguments["model_id"])
+    elif name == "relay_claim":
+        result = client.relay_claim(round_id=arguments["round_id"])
+    elif name == "withdraw_usdc":
+        result = client.withdraw_usdc(
+            to_address=arguments["to_address"],
+            amount_usdc=arguments["amount_usdc"],
+        )
+    elif name == "get_forwarder_balance":
+        result = client.get_forwarder_balance()
+    # -- notifications & badges dispatch ------------------------------------
+    elif name == "get_notifications":
+        result = client.get_notifications(
+            unread_only=arguments.get("unread_only", True),
+            limit=arguments.get("limit", 20),
+        )
+    elif name == "get_badges":
+        result = client.get_badges(model_id=arguments.get("model_id"))
+    else:
+        raise ValueError(f"Unknown tool: {name}")
+
+    return json.dumps(result, indent=2)
+
+
+# ===================================================================
+# MCP-SDK path (preferred)
+# ===================================================================
+
+def _build_mcp_server() -> Server:
+    """Build and return a configured MCP Server instance."""
+    server = Server("eiq-mcp")
+
+    @server.list_tools()
+    async def list_tools() -> list[Tool]:
+        return [
+            Tool(
+                name=t["name"],
+                description=t["description"],
+                inputSchema=t["inputSchema"],
+            )
+            for t in TOOLS
+        ]
+
+    @server.call_tool()
+    async def call_tool(name: str, arguments: dict):
+        try:
+            text = _dispatch(name, arguments)
+            return [TextContent(type="text", text=text)]
+        except Exception as exc:
+            return CallToolResult(
+                content=[TextContent(type="text", text=json.dumps({"error": str(exc)}))],
+                isError=True,
+            )
+
+    return server
+
+
+async def _run_mcp() -> None:
+    """Run the MCP server over stdin/stdout."""
+    server = _build_mcp_server()
+    async with stdio_server() as (read_stream, write_stream):
+        await server.run(read_stream, write_stream, server.create_initialization_options())
+
+
+# ===================================================================
+# Fallback: minimal JSON-RPC 2.0 over stdin/stdout
+# ===================================================================
+
+def _run_jsonrpc_fallback() -> None:
+    """Minimal JSON-RPC 2.0 loop for environments without the ``mcp`` package."""
+    import sys
+
+    sys.stderr.write("MCP SDK not found — running JSON-RPC 2.0 fallback\n")
+
+    for line in sys.stdin:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            req = json.loads(line)
+        except json.JSONDecodeError:
+            _jsonrpc_respond(None, error={"code": -32700, "message": "Parse error"})
+            continue
+
+        req_id = req.get("id")
+        method = req.get("method", "")
+        params = req.get("params", {})
+
+        if method == "initialize":
+            _jsonrpc_respond(req_id, result={
+                "protocolVersion": "2024-11-05",
+                "capabilities": {"tools": {"listChanged": False}},
+                "serverInfo": {"name": "eiq-mcp", "version": "0.1.0"},
+            })
+        elif method == "tools/list":
+            _jsonrpc_respond(req_id, result={"tools": TOOLS})
+        elif method == "tools/call":
+            tool_name = params.get("name", "")
+            arguments = params.get("arguments", {})
+            try:
+                text = _dispatch(tool_name, arguments)
+                _jsonrpc_respond(req_id, result={
+                    "content": [{"type": "text", "text": text}],
+                })
+            except Exception as exc:
+                _jsonrpc_respond(req_id, result={
+                    "content": [{"type": "text", "text": json.dumps({"error": str(exc)})}],
+                    "isError": True,
+                })
+        elif method == "notifications/initialized":
+            pass  # no response needed for notifications
+        else:
+            _jsonrpc_respond(req_id, error={"code": -32601, "message": f"Unknown method: {method}"})
+
+
+def _jsonrpc_respond(req_id, *, result=None, error=None) -> None:
+    """Write a JSON-RPC 2.0 response to stdout."""
+    resp: dict = {"jsonrpc": "2.0", "id": req_id}
+    if error is not None:
+        resp["error"] = error
+    else:
+        resp["result"] = result
+    sys.stdout.write(json.dumps(resp) + "\n")
+    sys.stdout.flush()
+
+
+# ===================================================================
+# Entry point
+# ===================================================================
+
+def main() -> None:
+    """Run the MCP server over stdio (the transport Claude Code / Cursor use)."""
+    if _HAS_MCP:
+        import asyncio
+        asyncio.run(_run_mcp())
+    else:
+        _run_jsonrpc_fallback()
+
+
+if __name__ == "__main__":
+    main()

{everestapi-0.1.2 → everestapi-0.2.0/src/everestapi.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: everestapi
-Version: 0.1.2
+Version: 0.2.0
 Summary: Python SDK for the EverestQuant prediction tournament platform
 Author-email: EverestQuant <engineering@everestquant.ai>
 License-Expression: MIT
@@ -24,6 +24,8 @@ Requires-Dist: click>=8.0
 Provides-Extra: dev
 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"
 Dynamic: license-file
 
 # everestapi

{everestapi-0.1.2 → everestapi-0.2.0}/src/everestapi.egg-info/SOURCES.txt

@@ -12,5 +12,9 @@ src/everestapi.egg-info/dependency_links.txt
 src/everestapi.egg-info/entry_points.txt
 src/everestapi.egg-info/requires.txt
 src/everestapi.egg-info/top_level.txt
+src/everestapi/mcp/__init__.py
+src/everestapi/mcp/__main__.py
+src/everestapi/mcp/server.py
 tests/test_cli.py
-tests/test_client.py
+tests/test_client.py
+tests/test_mcp_and_models.py

{everestapi-0.1.2 → everestapi-0.2.0}/src/everestapi.egg-info/requires.txt

@@ -4,3 +4,6 @@ click>=8.0
 [dev]
 pytest>=8.0
 pytest-httpx>=0.34.0
+
+[mcp]
+mcp>=1.0

{everestapi-0.1.2 → everestapi-0.2.0}/tests/test_client.py

@@ -88,3 +88,49 @@ def test_safe_output_path_rejects_traversal(api, tmp_path):
     with pytest.raises(ValueError):
         _safe_output_path("..", server_supplied=True)
     assert _safe_output_path(str(tmp_path / "ok.bin")) == str(tmp_path / "ok.bin")
+
+
+# --- Cloudflare Access service token ---------------------------------------
+# Staging sits behind Cloudflare Access; a service token clears the gate
+# programmatically. Headers ride alongside X-API-Key and stay absent by default.
+
+_K = "eiq_test_key"
+_URL = "http://test"
+
+
+def test_cf_service_token_absent_by_default(monkeypatch):
+    monkeypatch.delenv("CF_ACCESS_CLIENT_ID", raising=False)
+    monkeypatch.delenv("CF_ACCESS_CLIENT_SECRET", raising=False)
+    client = EverestAPI(api_key=_K, base_url=_URL)
+    h = client._client.headers
+    assert "cf-access-client-id" not in h
+    assert "cf-access-client-secret" not in h
+
+
+def test_cf_service_token_from_env(monkeypatch):
+    cfid, cftok = "abc.access", "shh"
+    monkeypatch.setenv("CF_ACCESS_CLIENT_ID", cfid)
+    monkeypatch.setenv("CF_ACCESS_CLIENT_SECRET", cftok)
+    client = EverestAPI(api_key=_K, base_url=_URL)
+    h = client._client.headers
+    assert h["cf-access-client-id"] == cfid
+    assert h["cf-access-client-secret"] == cftok
+    assert h["x-api-key"] == _K
+
+
+def test_cf_service_token_kwargs_override_env(monkeypatch):
+    monkeypatch.setenv("CF_ACCESS_CLIENT_ID", "env.access")
+    monkeypatch.setenv("CF_ACCESS_CLIENT_SECRET", "envv")
+    kid, ksec = "kw.access", "kwv"
+    client = EverestAPI(api_key=_K, base_url=_URL,
+                        cf_access_client_id=kid, cf_access_client_secret=ksec)
+    h = client._client.headers
+    assert h["cf-access-client-id"] == kid
+    assert h["cf-access-client-secret"] == ksec
+
+
+def test_cf_service_token_needs_both_halves(monkeypatch):
+    monkeypatch.setenv("CF_ACCESS_CLIENT_ID", "abc.access")
+    monkeypatch.delenv("CF_ACCESS_CLIENT_SECRET", raising=False)
+    client = EverestAPI(api_key=_K, base_url=_URL)
+    assert "cf-access-client-id" not in client._client.headers

everestapi-0.2.0/tests/test_mcp_and_models.py

@@ -0,0 +1,120 @@
+"""Tests for the MCP server module + the model-management / versioned-download
+client methods added alongside it (everestapi 0.2.0)."""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+
+from everestapi import EverestAPI, EverestError
+
+
+@pytest.fixture
+def api(monkeypatch):
+    for var in (
+        "EVEREST_API_URL",
+        "EVEREST_API_KEY",
+        "CF_ACCESS_CLIENT_ID",
+        "CF_ACCESS_CLIENT_SECRET",
+        "EIQ_BASIC_AUTH_USER",
+        "EIQ_BASIC_AUTH_PASS",
+    ):
+        monkeypatch.delenv(var, raising=False)
+    return EverestAPI(api_key="eiq_test_key", base_url="http://test")
+
+
+# -- client: model management --------------------------------------------
+
+def test_create_model_posts_body(httpx_mock, api):
+    httpx_mock.add_response(
+        url="http://test/api/v1/agents/me/models", method="POST",
+        json={"id": "m1", "name": "my-model"},
+    )
+    out = api.create_model("my-model", description="d")
+    assert out["name"] == "my-model"
+    assert json.loads(httpx_mock.get_request().content) == {
+        "name": "my-model", "description": "d",
+    }
+
+
+def test_create_model_idempotent_on_409(httpx_mock, api):
+    httpx_mock.add_response(
+        url="http://test/api/v1/agents/me/models", method="POST",
+        status_code=409, json={"detail": "exists"},
+    )
+    assert api.create_model("dup") == {"name": "dup", "status": "already_exists"}
+
+
+def test_create_model_reraises_non_409(httpx_mock, api):
+    httpx_mock.add_response(
+        url="http://test/api/v1/agents/me/models", method="POST",
+        status_code=400, json={"detail": "bad"},
+    )
+    with pytest.raises(EverestError):
+        api.create_model("x")
+
+
+def test_get_models(httpx_mock, api):
+    httpx_mock.add_response(
+        url="http://test/api/v1/agents/me/models", method="GET",
+        json={"agent_id": "a", "models": []},
+    )
+    assert api.get_models()["models"] == []
+
+
+# -- client: versioned dataset download (the #558 fix) -------------------
+
+def test_download_dataset_uses_versioned_route(httpx_mock, api, tmp_path):
+    httpx_mock.add_response(
+        url="http://test/api/v1/data/download/bregen/futures/train",
+        content=b"PAR1data",
+    )
+    out = api.download_dataset(
+        universe="futures", split="train", version="bregen",
+        output_path=str(tmp_path / "t.parquet"),
+    )
+    assert httpx_mock.get_request().url.path == "/api/v1/data/download/bregen/futures/train"
+    with open(out, "rb") as f:
+        assert f.read() == b"PAR1data"
+
+
+def test_download_dataset_latest_resolves_version(httpx_mock, api, tmp_path):
+    httpx_mock.add_response(
+        url="http://test/api/v1/data/versions",
+        json={"versions": [{"version": "bregen", "universes": ["futures"]}]},
+    )
+    httpx_mock.add_response(
+        url="http://test/api/v1/data/download/bregen/futures/live",
+        content=b"PAR1live",
+    )
+    out = api.download_dataset(
+        universe="futures", split="live", version="latest",
+        output_path=str(tmp_path / "l.parquet"),
+    )
+    with open(out, "rb") as f:
+        assert f.read() == b"PAR1live"
+
+
+# -- MCP server -----------------------------------------------------------
+
+def test_mcp_tools_include_loop_and_model_tools():
+    from everestapi.mcp import server
+    names = {t["name"] for t in server.TOOLS}
+    for needed in (
+        "download_dataset", "create_model", "get_models",
+        "submit_futures_predictions", "get_current_round", "get_scores",
+    ):
+        assert needed in names, needed
+
+
+def test_mcp_dispatch_create_model_uses_client(monkeypatch):
+    from everestapi.mcp import server
+
+    class FakeClient:
+        def create_model(self, name, description=None):
+            return {"name": name, "description": description}
+
+    monkeypatch.setattr(server, "_client", FakeClient())
+    out = json.loads(server._dispatch("create_model", {"name": "z", "description": "d"}))
+    assert out == {"name": "z", "description": "d"}