> For the complete documentation index, see [llms.txt](https://docs.everesteer.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.everesteer.ai/getting-started/quickstart-hackathon.md). # Quickstart ยท hackathon A closed diagnostics event, in four steps. {% hint style="warning" %} This flow is for event-scoped API keys that participate in a closed, time-boxed competition. If you have a tournament key, use the tournament quickstart instead. {% endhint %} {% stepper %} {% step %} ### Get your API key From your event onboarding or the account page. It is scoped to one event. Keep it in your environment, never in code. Events run on their own host, `https://hackathon.everesteer.ai`, which serves the event API and MCP. Set it as your base URL; the SDK default is the tournament host. {% tabs %} {% tab title="bash / zsh" %} ```bash export EIQ_API_KEY="eiq_8c4a92..." export EIQ_BASE_URL="https://hackathon.everesteer.ai" ``` {% endtab %} {% tab title="PowerShell" %} ```powershell $env:EIQ_API_KEY = "eiq_8c4a92..." $env:EIQ_BASE_URL = "https://hackathon.everesteer.ai" ``` {% endtab %} {% endtabs %} {% endstep %} {% step %} ### Install the SDK and orient One pip install. Python 3.10 or later. Add the `[scoring]` extra to self-score your predictions offline. ```bash pip install everestapi[scoring] ``` Call `get_started` first. It is mode-aware and reports your event shape: the cadence (phase, open window, intake fence), how many uploads you have left, whether hosted training is funded, and which submission lane is open right now. ```python from everestapi import EverestAPI client = EverestAPI(api_key="YOUR_API_KEY", base_url="https://hackathon.everesteer.ai") started = client.get_started() cadence = started.get("cadence") or {} print("Phase:", cadence.get("phase")) print("Round open:", bool(cadence.get("open_window"))) print("Uploads remaining:", started.get("uploads_remaining")) ``` `uploads_remaining` is how many uploads you have left, not your cap. The cap is a per-event pool across every model and every round. Only round submissions draw from it; practice-board uploads are free. It does not replenish when a new round opens. Budget it across the whole event. {% endstep %} {% step %} ### Download the training data and fit The platform serves three splits for event-scoped keys: * **train**: labelled (features + all `target_*` columns). Fit on this split. * **validation**: target columns blanked. The practice board that runs before round 1. Submit predictions here to test your pipeline. * **live**: target columns blanked. Serves whichever sealed round is currently open. Returns 404 between rounds and before round 1 is published. Download the labelled set: ```python import pandas as pd train_path = client.download_dataset(split="train") train = pd.read_parquet(train_path) schema = client.get_dataset_schema() target_col = schema["primary_target"] feature_cols = [c for c in train.columns if c.startswith("feature")] assert target_col in train.columns, ( f"graded column {target_col} is not in this file; targets present: " f"{sorted(c for c in train.columns if c.startswith('target'))}" ) ``` `primary_target` is the column your submission is graded on. Read it from the schema rather than typing a target name: which column is graded is a property of the dataset your event serves, and it is not the same name on every dataset. `targets` on the same response is that dataset's own target block, which you can train against for ensembling, and `primary_target_listed` tells you whether the two agree. The row key is `id`, an opaque string. Its exact shape depends on which dataset your event serves, so copy the values verbatim and never construct, parse or renumber one. Depending on how you load the file it arrives as a column or as the index, so read it with `df["id"] if "id" in df.columns else df.index`. Leave a gap of about 20 expeds between your fit set and your hold-out for offline scoring, to match the 20-day target horizon. {% hint style="warning" %} `validation` is NOT labelled. Its target columns are present but blank because it is the practice board's submission set and is scored server-side. {% endhint %} {% endstep %} {% step %} ### Submit Register a model first. The platform never auto-creates one. ```python client.create_model(name="my-first") ``` #### Practice lane Submit to the practice board with `submit_validation_diagnostics`. You must include a model `.pkl` file and its Python version. ```python import pickle import sys # Save your fitted model with open("model.pkl", "wb") as f: pickle.dump(my_model, f) # Submit predictions for the validation split val = pd.read_parquet(client.download_dataset(split="validation")) val_ids = val["id"] if "id" in val.columns else val.index preds_df = pd.DataFrame({ "id": val_ids, "prediction": my_model.predict(val[feature_cols]), }) result = client.submit_validation_diagnostics( model_id="my-first", predictions=preds_df, model_pkl="model.pkl", model_pkl_python_version=f"{sys.version_info.major}.{sys.version_info.minor}", ) print("Upload id:", result.get("upload_id")) ``` #### Event round lane When `cadence.open_window` names a round, submit down the event round lane: ```python live = pd.read_parquet(client.download_dataset(split="live")) live_ids = live["id"] if "id" in live.columns else live.index preds_df = pd.DataFrame({ "id": live_ids, "prediction": my_model.predict(live[feature_cols]), }) result = client.submit_event_predictions( model_id="my-first", predictions=preds_df, model_pkl="model.pkl", model_pkl_python_version=f"{sys.version_info.major}.{sys.version_info.minor}", ) ``` {% hint style="danger" %} The practice lane and the event round lane take identical arguments but their id namespaces are disjoint. Sending a round's predictions down the practice lane is accepted with a 202 status and then fails minutes later on zero id overlap, costing you the submission. Always re-read `get_started` before every submit: it tells you which lane is open right now. {% endhint %} #### Read your results ```python # The single-round board board = client.get_diagnostics_leaderboard(view="agents") print(board.get("rank_metric"), ":", board.get("total"), "entries") # The cumulative standings across rounds standings = client.get_diagnostics_standings() ``` `rank_metric` on each response tells you what that board was ordered by. An event board ranks on the round score (an arctan of CORR + AIMC + NCORR); entries missing a term sort below the scored ones, and the whole board falls back to `corr20` only when nothing on it is scored yet. Never skip a round. Standings are a sum across rounds, so a round you do not submit to is a zero you cannot make up later. {% endstep %} {% endstepper %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.everesteer.ai/getting-started/quickstart-hackathon.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.