Reasoning Fit

curl --request POST \
  --url https://api.example.com/v1/reasoning/fit \
  --header 'Content-Type: application/json' \
  --data '
{
  "dataset_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "filter": {
    "col": "<string>",
    "kind": "cmp",
    "value": "<string>"
  },
  "task": {
    "label_column": "<string>",
    "task_kind": "regression"
  },
  "model_types": [
    "<string>"
  ],
  "n_hyperopt_steps": 5,
  "random_state": 42,
  "teacher_model_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "teacher_predict_url": "<string>",
  "teacher_predict_headers": {},
  "teacher_get_grads_url": "<string>"
}
'

{
  "job_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "message": "<string>",
  "dataset_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

training

Reasoning Fit

Submit a reasoning fit and return immediately.

Two routing modes share the entry point:

Both modes use the same scheduler-owned submission path — the router never touches jobs or computation_node, only compiles + ships.

Standard path — build the ReasoningTrainer, compile its ComputationGraph (synth-gen runs synchronously inside compile to materialize the augmented dataset; the returned DAG is the trainer’s HPO graph plus a reasoning/finalize leaf), pickle the trainer to S3, and put a :class:RequestToComputeGraph carrying the wire-form graph on the scheduler’s in-process inbox.
DiffModel path — when teacher_get_grads_url points at this server’s /v1/models/{id}/get_grads, there’s no stage-1 fan-out and no ReasoningTrainer: we pickle a :class:DiffModelBundle (dataset + finalize_only_fit args) to S3 and submit a single-node graph (reasoning/diffmodel_finalize). The runner loads the bundle and runs the one Modal finalize call + schema upload; the scheduler’s terminal recording flips the job to completed and finalize_job_result writes the models row — same single-writer path as everything else.

POST

reasoning

fit

Reasoning Fit

curl --request POST \
  --url https://api.example.com/v1/reasoning/fit \
  --header 'Content-Type: application/json' \
  --data '
{
  "dataset_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "filter": {
    "col": "<string>",
    "kind": "cmp",
    "value": "<string>"
  },
  "task": {
    "label_column": "<string>",
    "task_kind": "regression"
  },
  "model_types": [
    "<string>"
  ],
  "n_hyperopt_steps": 5,
  "random_state": 42,
  "teacher_model_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "teacher_predict_url": "<string>",
  "teacher_predict_headers": {},
  "teacher_get_grads_url": "<string>"
}
'

{
  "job_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "message": "<string>",
  "dataset_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

Headers

authorization

string | null

refresh-token

string | null

Body

application/json

POST /v1/reasoning/fit — fit a ReasoningModel against a registered dataset.

When a teacher is set (teacher_model_id or teacher_predict_url), task becomes evaluation-only — the teacher provides the training target.

dataset_id

required

Id of a dataset registered via POST /v1/datasets. The server looks it up and proceeds with the fit pipeline.

filter

Comparison · object

A single column comparison, e.g. col("ts") >= "2024-01-01".

value is unused for is_null / is_not_null and is a list for in / not_in. Timestamps travel as ISO-8601 strings and are coerced to the column dtype trainer-side.

Comparison
BoolExpr
Not

Show child attributes

task

Regression · object

Predict a continuous target.

Show child attributes

model_types

string[] | null

Candidate model-family identifiers. reasoning.fit pins the surrogate via force_model_type, so at most one entry is accepted.

n_hyperopt_steps

integer

default:5

Required range: 1 <= x <= 200

random_state

integer

default:42

teacher_model_id

Distill from a same-server trained model identified by id. The synth-gen worker calls the inference worker in-process — no HTTP self-loop. Mutually exclusive with teacher_predict_url.

teacher_predict_url

string | null

If set, distil an external teacher at this URL instead of training on labels. Use teacher_model_id for same-server teachers.

teacher_predict_headers

Teacher Predict Headers · object

Headers to send when calling teacher_predict_url.

Show child attributes

teacher_get_grads_url

string | null

If set, the teacher is a DiffModel that exposes a per-sample Jacobian endpoint. Reasoning skips synth-gen and trainer.run and runs finalize directly against this URL plus teacher_predict_url. Requires teacher_predict_url.

Response

Successful Response

POST /v1/reasoning/fit -- async reasoning-fit job submission response.

dataset_id echoes the dataset this fit trained against.

job_id

required

Server-assigned id of the submitted job

status

enum<string>

required

Available options:

pending,

running,

completed,

failed

message

string

required

dataset_id

required

Id of the dataset this fit trained against.

Trainer Run Get Status