Build a CLI or agent

This page is the full contract in one place. A coding agent should be able to read it and produce a working client without opening anything else.

If you are an agent: read this page top to bottom before writing code. Everything you need is here. The only values the user supplies are MATHFI_BASE_URL, MATHFI_EMAIL and MATHFI_PASSWORD. Take all three as configuration. Do not hard-code them, do not write the credentials to disk, do not log them.

Machine-readable sources:

Source	URL
OpenAPI 3.0 spec	`https://docs.mathfi.ai/api-reference/openapi.yaml`
This site as one text file	`https://docs.mathfi.ai/llms-full.txt`
Page index for retrieval	`https://docs.mathfi.ai/llms.txt`
Any single page as Markdown	append `.md`, e.g. `https://docs.mathfi.ai/developers/agents.md`

The contract in brief

base_url:
  pattern: https://{tenant}-api.mathfi.ai   # per-customer; NEVER hard-code a host
  source: MATHFI_BASE_URL                   # take it as configuration
auth:
  endpoint: POST /api/login
  body: { username: <email>, password: <password> }
  response_field: access_token
  header: "Authorization: Bearer <access_token>"
  lifetime_seconds: 3600        # sliding; 86400 absolute from login
  api_keys: none
credentials:                    # the only inputs a client needs
  MATHFI_BASE_URL: string       # your tenant's API root
  MATHFI_EMAIL: string
  MATHFI_PASSWORD: string
conventions:
  keys: uuid, opaque, pass back verbatim
  timestamps: ISO-8601 UTC
  list_params: offset and limit are REQUIRED on every list endpoint
  multipart_part_name: _file    # underscore is required
  null_metric: means undefined, not zero
limits:
  upload_bytes_max: 534773760
  signed_url_ttl_seconds: 3600
  refinery_max_columns: 70
  train_min_rows_rarest_class: 25      # checked on the TRAIN file, after your split
  source_min_rows_rarest_class: 31     # what a stratified 80/20 needs to leave 25 in train
  refinery_buckets_allowed: [4, 10, 20]
  concurrent_refinements_per_user: 5
  concurrent_training_jobs_per_user: 5
  models_kept_per_run: 3
  scaling_factor_range: [8, 499]
  scaling_factor_default: 19

Products and the pipeline

Two products, run in sequence or independently.

Feature Refinery                        Model Crucible
────────────────                        ──────────────
create ──▶ upload TRAIN+TEST ──▶ start   create dataset ──▶ [upload+clean | nothing]
       ──▶ poll ──▶ result                              ──▶ poll dataset
                    │                                   ──▶ create training job
                    └── featureRefinementKey ──────────▶ ──▶ poll job
                                                        ──▶ read candidates
                                                        ──▶ (optional) set champion
                                                        ──▶ create prediction ──▶ poll ──▶ download

The handoff is one field: pass featureRefinementKey when creating the dataset and no files move.

Endpoints

Everything below is relative to your tenant’s API root, written here as $BASE. All need Authorization: Bearer <token> except POST /api/login.

Authentication

Method	Path	Body	Returns
POST	`/api/login`	`{username, password}`	`{access_token, token_type, expires_in}`

Feature Refinery

Method	Path	Body / params	Returns
POST	`/api/v1/feature-refinery`	`{name, numberOfBuckets, trainFileName?, testFileName?}`	`{featureRefinementKey, uploadTargets[], startUrl, progressUrl}`
POST	`/api/v1/feature-refinery/{key}/start`	none	`{featureRefinementKey, state}`
GET	`/api/v1/feature-refinery/{key}/progress`		`{state, elapsedSeconds, progressCompleted, progressTotal, errorReason, baselineTopPerformances[], currentTopPerformances[]}`
GET	`/api/v1/feature-refinery/{key}/result`		`{columnStatus[], refinedTrainUrl, refinedPredictionUrl, refinedColumnStatusUrl}`

columnStatus[] is one {columnIndex, columnName, outcome} per original column, in header order, with outcome either KEEP or REMOVE. refinedTrainUrl and refinedPredictionUrl are the reduced files; refinedColumnStatusUrl is the same decisions as a file, so the same columns can be dropped from a later prediction file. | GET | /api/v1/feature-refinery/{key} | | {state, inputs[], totalColumns, columnsRemoved, ...} | | GET | /api/v1/feature-refinery | offset, limit (≤100) | {refinements[], total} | | POST | /api/v1/feature-refinery/{key}/cancel | none | {state} | | DELETE | /api/v1/feature-refinery/{key} | | 204 — non-destructive; retires the run from your list, keeps its data | name must match ^[A-Za-z0-9 _-]{1,100}$ and be unique among your unfinished runs. numberOfBuckets must be 4, 10 or 20.

Datasets

Method	Path	Body / params	Returns
POST	`/api/v1/datasets`	`{datasetName, numberOfBuckets?, description?, featureRefinementKey?}`	`{datasetKey, status, uploadTargets[]}`
POST	`/api/v1/datasets/{key}/clean`	none	`202`
GET	`/api/v1/datasets/{key}`		`{status, metadata, inputs[], inputDatasource, recommendedThreshold, recommendedNumberOfBuckets, errors, warnings}`
GET	`/api/v1/datasets`	`offset`, `limit`, `state?`, `withModelOnly?`	`{datasets[], total}`
DELETE	`/api/v1/datasets/{key}`		`204` — non-destructive; nothing is removed

datasetName is 3 to 30 characters. numberOfBuckets is 4 to 1000.

Training

Method	Path	Body / params	Returns
POST	`/api/v1/training/datasets/{datasetKey}`	`{performanceThreshold, scalingFactor}`	`{trainingJobKey, status}`
GET	`/api/v1/training/{key}/progress`		`{status, targetPerformance, jobs[], nextPollAfterSeconds}`
GET	`/api/v1/training/{key}`		`{status, achievedPerformance, modelKey, winnerAlgorithm, performance:{candidates[], champion}}`
POST	`/api/v1/training/{key}/champion`	`{attemptNumber, observations?}`	`{attemptNumber, version, selectedBy, observations}`
PATCH	`/api/v1/training/{key}/cancel`	none	`{status}`
GET	`/api/v1/training`	`offset`, `limit`, `parentOnly?`	`{trainingJobs[], total}`
GET	`/api/v1/training/datasets/{datasetKey}`	`offset`, `limit`	`{trainingJobs[], total}`

Models

Method	Path	Returns
GET	`/api/v1/models/{modelKey}`	`{modelKey, version, achievedPerformance, versions[]}`
GET	`/api/v1/models/datasets/{datasetKey}`	`{models[], total}`

Predictions

Method	Path	Body / params	Returns
POST	`/api/v1/predictions`	query `modelKey`, `applyColumnStatusFilter?`; multipart `_file`	`{predictionKey, status}`
POST	`/api/v1/predictions/models/{modelKey}`	multipart `_file`	`{predictionKey, status}`
GET	`/api/v1/predictions/{key}/progress`		`{status}`
GET	`/api/v1/predictions/{key}`		`{status, modelVersion, predictionResultDownloadUrl, metadata, errors}`
GET	`/api/v1/predictions/models/{modelKey}`	`offset`, `limit`	`{predictions[], total}`
GET	`/api/v1/predictions/datasets/{datasetKey}`	`offset`, `limit`	`{predictions[], total}`

State machines

Poll until terminal. Never match on intermediate states; they can change.

feature_refinement:
  terminal_success: [REFINEMENT_COMPLETED]
  terminal_failure: [ERROR, TIMEOUT, CANCELLED]
  progression: PENDING -> SETUP_* -> MEASURE_INITIAL_THRESHOLD* -> BASELINE_RUN_*
               -> REFINING_LOOP_* -> CREATING_RESULT -> REFINEMENT_COMPLETED
  poll_interval_seconds: 60
  typical_duration: tens of minutes to hours; scales with column count

dataset:
  terminal_success: [COMPLETED]
  terminal_failure: [FAILED]
  progression: PENDING -> PROCESSING -> COMPLETED
  poll_interval_seconds: 15

training_job:
  terminal_success: [COMPLETED]
  terminal_failure: [TIMED_OUT, CANCELLED, FAILED, NOT_COMPLETED]
  progression: PENDING -> RUNNING -> COMPLETED
  poll_interval_seconds: read nextPollAfterSeconds, else 15
  typical_duration: minutes on small data

prediction:
  terminal_success: [COMPLETED]
  terminal_failure: [FAILED, TIMEOUT]
  progression: PENDING -> RUNNING -> COMPLETED
  poll_interval_seconds: 15

Uploading to a signed URL

uploadTargets[] entries look like:

{ "kind": "TRAIN",
  "url": "https://storage.googleapis.com/...",
  "requiredHeader": "X-Goog-Content-Length-Range:10,534773760" }

method: PUT
body: the raw CSV bytes
headers_required:
  - "Content-Type: text/csv"
  - the requiredHeader value, split on the FIRST colon (skip when null)
headers_forbidden:
  - Authorization        # breaks the signature -> 403
expiry: 60 minutes after the create call; no re-sign endpoint
on_expiry: create the resource again under a new name

Decision rules a client must get right

These are the five places a naive client goes wrong. The first one happens before you call anything.

1. How to split the file

If you are asked to prepare and split a CSV, this is the rule that decides whether the run works. The train file needs at least 25 rows of the least common target value, counted after the split. Clearing the floor in the source data does not clear it in the file you upload.

rows     = read source CSV                  # header, then labelled rows
by_class = group rows by the LAST column     # the target
smallest = min(len(group) for group in by_class.values())

# A stratified 80/20 cut, rounding the train side up, needs 31 rows of the rarest
# class to land 25 in train: ceil(31 * 0.8) == 25. Below that no split satisfies the
# floor, so stop here and say so rather than uploading something that cannot train.
if smallest < 31:
    FAIL: "the rarest class has {smallest} rows; at least 31 are needed to split
           and still leave the 25 the platform requires in the train file"

# Split each class, NOT the file. An unstratified cut does not respect class ratios.
train, test = [], []
for label, group in by_class.items():
    shuffle(group)
    cut = ceil(len(group) * 0.8)
    train += group[:cut]
    test  += group[cut:]

shuffle(train)
shuffle(test)

# The platform enforces this. If it does not hold, the run starts and then fails.
assert min(count of each label in train) >= 25

31 is the arithmetic minimum, not a comfortable one: it leaves exactly 25 with no margin. More rows of the rarest class is the single most useful thing to ask the human for. Write the test file with its labels. It is scored against them, and a test file without the target column is rejected.

2. Whether to call `/clean`

if dataset was created with featureRefinementKey:
    DO NOT call /clean        # creating it already started the work; /clean returns 409
else:
    PUT both files, THEN call /clean

3. Which training target to use

detail = GET /api/v1/datasets/{key}
if detail.recommendedThreshold is present:
    performanceThreshold = detail.recommendedThreshold
else:
    performanceThreshold = a value the data plausibly supports   # 0.7-0.8 on hard imbalanced data

Never default to 0.9 because it sounds better. A target above what the data supports produces a degenerate champion: it predicts one class for every row, accuracy looks plausible, F1 is exactly zero, and the run reports COMPLETED.

4. Validating the result before you trust it

After a run completes, check the champion before reporting success:

champion = run.performance.candidates[0]
if champion.f1Score == 0 or champion.recall == 0:
    warn: "degenerate model - the target was probably too high"
if champion.recall is null:
    # undefined, not zero. the test slice had no positive cases.
    warn: "recall undefined; check the class balance of the test file"

A dataset built from a refinement inherits recommendedNumberOfBuckets and it cannot be changed; the refined files were produced at that setting. Send your own value only on the upload route.

Error handling

400: bad input; message names the problem. NOT retryable as-is.
401: token missing or expired. Re-login ONCE, then retry. Second 401 = bad credentials.
403: on a signed URL only. Wrong headers or expired URL. Do not retry blindly.
404: unknown key, or not yours. Do not retry.
409: wrong state. Read the message:
       - "already exists"        -> name clash, pick another
       - "still needs ... upload"-> a file did not land
       - "already cleaned"       -> harmless on the handoff route, continue
       - "already started"       -> continue to polling
429: concurrency cap reached. Nothing was created. Wait and retry.
5xx: retry with exponential backoff, 3 attempts.

Retry-safe operations: every GET, and DELETE (idempotent, and non-destructive — nothing it touches is destroyed, so a retry cannot lose anything). Not retry-safe without checking first: every POST that creates something. On an ambiguous failure, list and look before creating again.

Reference CLI shape

A useful client exposes these commands. The tenant URL and credentials come from the environment; everything else is a flag.

mathfi login                                   # verify credentials, cache the token
mathfi refine start --name N --train F --test F [--buckets 4|10|20]
mathfi refine status <key>                     # state + progress %
mathfi refine wait <key>                       # block until terminal, non-zero exit on failure
mathfi refine result <key> [--out DIR]         # column decisions + refined files
mathfi refine list

mathfi dataset create --name N (--from-refinement <key> | --train F --test F [--buckets N])
mathfi dataset status <key>
mathfi dataset list

mathfi train start --dataset <key> [--target T] [--scaling 19]   # target defaults to recommended
mathfi train wait <key>
mathfi train candidates <key>                  # the table you choose from
mathfi train champion <key> --attempt N [--why "..."]

mathfi predict --model <key> --file F [--out result.csv] [--filter-columns]

mathfi pipeline --name N --train F --test F --predict F --out result.csv

mathfi pipeline is the whole flow: refine, hand over, train at the recommended target, take the default champion, predict, download. Design notes worth keeping:

wait commands block and exit non-zero on failure. That is what makes the CLI usable in a script.
Print state changes, not a tick per poll. A refinement can poll for an hour.
--json on every read command. Agents parse, humans read.
Never print the token.
Fail fast on a missing MATHFI_BASE_URL with a message that names the pattern. A client that silently defaults to some host will fail against a different tenant in a way nobody can read.

Whole pipeline, as pseudocode

base = env("MATHFI_BASE_URL")          # https://<tenant>-api.mathfi.ai
token = login(base, email, password)

# 0. split, stratified, before anything is uploaded (see Decision rule 1)
train, test = stratified_split(source_csv, train_fraction=0.8)
assert min(count of each label in train) >= 25      # else the run will fail, not 400

# 1. refine
fr = POST /api/v1/feature-refinery {name, numberOfBuckets: 10,
                                    trainFileName, testFileName}
for target in fr.uploadTargets:
    PUT target.url  headers={Content-Type: text/csv, **parse(target.requiredHeader)}
                    body=file_for(target.kind)        # NO Authorization
POST /api/v1/feature-refinery/{fr.key}/start
poll /progress every 60s until state in TERMINAL_FR
assert state == "REFINEMENT_COMPLETED"

# 2. dataset, by handoff
ds = POST /api/v1/datasets {datasetName, featureRefinementKey: fr.key}
# NO /clean here
poll /api/v1/datasets/{ds.key} every 15s until status in [COMPLETED, FAILED]
assert status == "COMPLETED"

# 3. train at the measured target
detail = GET /api/v1/datasets/{ds.key}
job = POST /api/v1/training/datasets/{ds.key}
        {performanceThreshold: detail.recommendedThreshold, scalingFactor: 19}
poll /api/v1/training/{job.key}/progress until status in TERMINAL_TRAIN
                                          sleeping nextPollAfterSeconds
assert status == "COMPLETED"

# 4. inspect, then choose
run = GET /api/v1/training/{job.key}
candidates = run.performance.candidates      # best first, by fewest falseDecisions
if candidates[0].f1Score == 0: warn("degenerate model; target was too high")
# optional: POST /api/v1/training/{job.key}/champion {attemptNumber: chosen}

# 5. predict
pred = POST /api/v1/predictions?modelKey={run.modelKey}&applyColumnStatusFilter=true
         multipart _file=unlabelled.csv
poll /api/v1/predictions/{pred.key}/progress until status in TERMINAL_PRED
download GET /api/v1/predictions/{pred.key} -> predictionResultDownloadUrl

Things that will bite you


There is no shared host: the API root is per tenant, `https://<tenant>-api.mathfi.ai`
The login field is `username` but holds an email
The multipart part is `_file`, with the underscore
`offset` and `limit` are required on list endpoints
Signed uploads must not carry `Authorization`
`/clean` on a refinement handoff returns `409`
A `null` metric means undefined, not zero
Signed URLs die after 60 minutes, with no way to re-sign
Refinement results vary run to run on identical input
The 25-row class floor is checked on the train file after your split, not on the data you split
A `COMPLETED` training run can still hold a useless model; check F1

Working curl flows

The same steps, runnable.

Endpoint reference

Schemas and responses, generated from the spec.

Getting started

Authentication

Feature Refinery

Model Crucible

Build a CLI or agent

The contract in brief

Products and the pipeline

Endpoints

Authentication

Feature Refinery

Datasets

Training

Models

Predictions

State machines

Uploading to a signed URL

Decision rules a client must get right

1. How to split the file

2. Whether to call `/clean`

3. Which training target to use

4. Validating the result before you trust it

5. Bucket count on a refinement handoff

Error handling

Reference CLI shape

Whole pipeline, as pseudocode

Things that will bite you

Working curl flows

Endpoint reference

​The contract in brief

​Products and the pipeline

​Endpoints

​Authentication

​Feature Refinery

​Datasets

​Training

​Models

​Predictions

​State machines

​Uploading to a signed URL

​Decision rules a client must get right

​1. How to split the file

​2. Whether to call /clean

​3. Which training target to use

​4. Validating the result before you trust it

​5. Bucket count on a refinement handoff

​Error handling

​Reference CLI shape

​Whole pipeline, as pseudocode

​Things that will bite you

Working curl flows

Endpoint reference

The contract in brief

Products and the pipeline

Endpoints

Authentication

Feature Refinery

Datasets

Training

Models

Predictions

State machines

Uploading to a signed URL

Decision rules a client must get right

1. How to split the file

2. Whether to call `/clean`

3. Which training target to use

4. Validating the result before you trust it

5. Bucket count on a refinement handoff

Error handling

Reference CLI shape

Whole pipeline, as pseudocode

Things that will bite you