> 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/research-guide/hosted-training.md).

# Hosted training

Train on the platform's compute: presets, custom code, hardware tiers, cost preview.

The `train` tool trains a model on Everesteer's hosted compute. Nothing executes on your machine, and no data is uploaded: the platform loads the same obfuscated dataset you download, runs exped-purged cross-validation with the tournament embargo, computes the canonical metrics, and pickles the final model. Downloads give you the model and a feature manifest so you can reproduce predictions locally.

The tool is exposed three ways:

| Surface | Name                         |
| ------- | ---------------------------- |
| REST    | `POST /api/v1/compute/train` |
| SDK     | `client.train(...)`          |
| MCP     | `train`                      |

The SDK also ships `quick_train(...)`, a deprecated shim that forwards to `train`. The older `custom_train(...)` was removed; it raises. Use `train` with `model="custom"`.

## Presets

`model` selects the estimator:

* `lightgbm`, `xgboost`, `ridge`, `mlp`, `random_forest`: built-in presets. Every tree and linear preset is CPU-only code, so `gpu="CPU"` gives identical results at the cheapest rate.
* `custom`: run your own code. Pass `custom_model_fn`, a Python source string defining `build_model(params)` returning an estimator. The code runs inside an isolated, network-denied sandbox with no filesystem access; it never sees held-out targets. A script rejected by the static safety scanner returns 400. An optional `custom_feature_fn` adds server-side feature engineering on the resident data.

## Target and features

`target` names the target column to fit, `features` the feature set. The trainer fits one target per job: train a separate job per target and blend the predictions yourself (see [Ensembling and auxiliary targets](/research-guide/ensembling-and-auxiliary-targets.md)). Read the live feature-set names and target list from `eiq_features.json`; the tournament dataset declares a single set, `all`.

## Hardware tiers and seed

`gpu` selects the compute tier: `CPU`, `T4`, `A10G`, `A100`. `CPU` is the cheapest and the right choice for tree-model presets. The default is `T4`; pass `gpu="CPU"` explicitly for cheap scouts.

Seed a preset through `params`, for example `params={"seed": 7}` for LightGBM or `params={"random_state": 7}` for scikit-learn presets. A top-level `seed=` argument is rejected.

## Preview cost before committing

`train(..., dry_run=True)` validates the call, resolves defaults, and returns a cost estimate without reserving credits or launching anything. It reports the estimated hold, the resolved tier, model and universe, and any warnings (for example, a GPU tier a preset cannot use).

Do not hardcode prices. Read the live per-tier rate card and your balance from `get_compute_credits`; an event grant is reported as `hosted_train_funded` by `get_started`.

## Job lifecycle

`train` returns immediately with a job id and runs in the background.

| Step     | Call                                                             |
| -------- | ---------------------------------------------------------------- |
| Poll     | `get_job_status(job_id)`                                         |
| Progress | `get_job_log(job_id)` (lifecycle events and fold-level messages) |
| List     | `list_compute_jobs()`                                            |
| Wait     | `wait_for_job(job_id)` (blocks with backoff)                     |
| Cancel   | `cancel_job(job_id)`                                             |

The job transitions through pending, running, completed, failed, timeout and cancelled. On completion the result carries the metrics and a predictions download URL; the model file is fetched separately.

## Artifacts

| Artifact    | Call                              |
| ----------- | --------------------------------- |
| Model       | `get_model_download_url(job_id)`  |
| Predictions | `get_job_predictions_url(job_id)` |

The model download ships with a feature manifest: the exact ordered feature-column list plus the fill, cast-to-float32 preprocessing the bare pickle needs to reproduce a prediction. The predictions artifact is a validation-predictions file.

## What the reported CV is, and is not

The trainer reports exped-purged cross-validation numbers computed on the labeled `train` split only. The validation split is never scored in-job: its targets are blanked on the public volume. The AIMC the trainer reports is a pre-submission estimate against a static proxy of the designated benchmark; official AIMC is scored server-side.

Two limits follow:

1. **The CV numbers are honest only for the train split they were computed on.** They fit the whole train split. If you carve a hold-out from the trainer's artifacts, that hold-out is in-sample, not an independent check. Carve your own hold-out from the labeled data and score it with the offline toolkit (see [Evaluation protocol](/research-guide/evaluation-protocol.md)).
2. **`train` does not produce round predictions.** The job's predictions artifact is scored against the dataset tree the trainer read, which can lag the served split and shares no id namespace with it. The always-correct path: download the returned model and feature manifest, predict on the split `download_dataset` currently serves, and submit that.


---

# 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/research-guide/hosted-training.md?ask=<question>&goal=<endgoal>
```

`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.