Mathematical Functions, CLI & API

When you define a model in MatrixAI (using a .mxai or .mx file), you describe what calculations that model should perform using mathematical functions. Think of it as a powerful spreadsheet that can also learn from data.

There are three layers worth distinguishing:

Formulas are written in .mx files with syntax close to standard mathematical notation:

# Example: score.mx
score(x) = 0.6 * relevance(x) + 0.4 * coherence(x)
utility(x) = score(x) - 0.2 * cost(x)

MatrixAI first looks for a function you defined yourself. If it doesn't find one, it falls back to the native registry documented in this manual.

Standard arithmetic functions available in all .mx expressions:

# candidatos.mx — scoring candidates for a position
score(c)      = 0.5 * c.experience + 0.5 * c.technical_test
delta(c1, c2) = sub(score(c1), score(c2))
best(c1, c2)  = max(score(c1), score(c2))

These functions transform values: clamp them, rescale them, or convert them into probability distributions.

normalize(x) — Clip to [0, 1]

normalize(1.5)  → 1.0   # clamped to maximum
normalize(-0.3) → 0.0   # clamped to minimum
normalize(0.7)  → 0.7   # unchanged

clip(x, lo, hi) — Clip to any range

clip(150, 0, 100)  → 100.0   # score cannot exceed 100
clip(-5, 0, 10)   → 0.0     # cannot be negative
clip(7, 0, 10)    → 7.0     # within range, unchanged

scale(x, old_min, old_max, new_min, new_max) — Rescale ranges

# Convert a grade from 0-10 to 0-100
scale(7.5, 0, 10, 0, 100)  → 75.0

# Convert temperature Celsius to 0-1
scale(37, 35, 42, 0, 1)    → 0.285...

sigmoid(x) — Convert any number to a probability

sigmoid maps any real number to a value between 0 and 1. Ideal for binary decisions.

sigmoid(0)   → 0.5      # equilibrium: 50% probability
sigmoid(5)   → 0.993    # very likely yes
sigmoid(-5)  → 0.007    # very likely no
sigmoid(2)   → 0.88     # quite probable

# credit_risk.mxai
risk(client) = sigmoid(2.5 * client.default_history - 1.8 * client.income + 0.3)

softmax(values) — Scores → probabilities summing to 1

softmax([2.0, 1.0, 0.5]) → [0.626, 0.230, 0.143]
# 62.6% probability for option 1, 23% for option 2, 14.3% for option 3

Designed to evaluate conceptual properties of data: relevance, coherence, safety, etc. Very useful when models work with text or qualitative assessments. They accept both a direct number and a dictionary (from which they read a specific key automatically).

# ranking.mx — ranking search results
score(r) = 0.4 * relevance(r) + 0.3 * coherence(r) + 0.2 * confidence(r) + 0.1 * safety(r)
# r = {"relevance": 0.9, "coherence": 0.7, "confidence": 0.8, "safety": 1.0}

Complement scoring functions: while relevance or quality measure things you want to maximise, cost functions measure things you want to minimise.

# efficiency.mx — select the most efficient provider
utility(option) = quality(option) - 0.3 * cost(option) - 0.2 * latency(option)

These functions work with lists of options to select the best ones, sort them, or filter them.

# candidates = ["A", "B", "C"] with scores: A=0.7, B=0.9, C=0.4
argmax(candidates, my_score_fn)       → "B"
topk(candidates, my_score_fn, 2)      → ["B", "A"]
threshold(candidates, my_score_fn, 0.6) → ["A", "B"]
rank(candidates, my_score_fn)         → ["B", "A", "C"]

Not all functions can "learn". Trainable functions have parameters (weights) that are adjusted during training. Today MatrixAI supports two trainable types:

Multiclass classification — softmax_linear

Learns to classify inputs into multiple categories. Trained with cross_entropy.

# email_classifier.mxai (fragment)
predict(email) = softmax(W1 * email + b1)
# W1 (weights) and b1 (bias) are learned from labelled examples

Use cases: email classification (spam/normal/urgent), ticket categorisation, intent recognition.

Binary classification / risk — sigmoid_linear

Learns to estimate a probability from 0 to 1. Trained with binary_cross_entropy.

# fall_risk.mxai (fragment)
risk(patient) = sigmoid(W1 * patient + b1)

Use cases: credit risk (approve/reject), fraud detection, binary medical risk, churn prediction.

What is not yet trainable (but is executable)

These expressions work correctly in your models but won't learn from data:

• Manual weighted sums (symbolic_weighted_sum)
• Normalisation and scaling
• Aggregations (mean, max, min over lists)
• Discrete rules (argmax, vote)
• Attention, trainable embeddings, transformers, arbitrary deep networks

mathematize translates "if X then Y" rules into continuous mathematical expressions that models can process and audit.

Business rules are often written like this:

if risk > 0.8 then alert
if income < 20000 and debt > 0.5 then reject

This discrete logic is not differentiable, which prevents its use in training. MatrixAI converts it to continuous equivalents:

The MatrixAI CLI is the most direct way to work with mathematical functions, models and data from the terminal.

Installation and basic use

matrixai <command> [options]
# or directly from the repository:
python -m matrixai <command> [options]

Common flags

Evaluate a mathematical expression

matrixai eval score.mx --input data.json
matrixai eval score.mx --input data.json --trace       # step-by-step detail
matrixai eval score.mx --input data.json --call score  # specific function only

Translate discrete rules to continuous math

matrixai mathematize my_rules.txt
echo "if risk > 0.8 then alert" | matrixai mathematize -

Validate and inspect models

matrixai validate my_model.mxai
matrixai lint my_model.mxai
matrixai backend-report my_model.mxai
matrixai backend-report my_model.mxai --target torch
matrixai graph my_model.mxai --format mermaid
matrixai graph my_model.mxai --format dot -o graph.dot

Run a prediction

matrixai run my_model.mxai --input input.json --params params.json

matrixai run email_classifier.mxai \
  --input '{"subject": "Exclusive offer", "sender_score": 0.2}' \
  --params runs/email_v1/params.best.json

Train a model

# Full workflow in one command:
matrixai train-supervised "a model that classifies emails as spam, normal or urgent" \
  --train-data emails_train.csv \
  --eval-data emails_eval.csv \
  -o runs/email_v1/

# Step by step:
matrixai prompt "classify emails as spam, normal or urgent" -o email.mxai
matrixai generate-training email.mxai "classify emails" -o email.mxtrain
matrixai generate-dataset email.mxai --training email.mxtrain --rows 500 -o data/
matrixai train email.mxai --training email.mxtrain -o runs/email_v1/
matrixai evaluate email.mxai --params runs/email_v1/params.best.json --training email.mxtrain

Serve the model as an HTTP API

matrixai serve email.mxai \
  --params runs/email_v1/params.best.json \
  --port 8000 \
  --api-key my_secret_key

# Open Studio in browser:
matrixai studio --port 8765 --open

MatrixAI exposes two independent HTTP servers:

Authentication (production server)

# Option A: Authorization header
curl -H "Authorization: Bearer my_secret_key" http://localhost:8000/predict ...

# Option B: X-API-Key header
curl -H "X-API-Key: my_secret_key" http://localhost:8000/predict ...

Response format

// Success:
{ "ok": true, ...data }

// Error:
{ "ok": false, "error": "description", "code": "ERROR_CODE" }

Health check

curl http://localhost:8000/health
# → { "status": "ok", "service": "MatrixAI Server", "backend": "numpy", ... }

Run a prediction

curl -X POST http://localhost:8000/predict \
  -H "Authorization: Bearer my_key" \
  -H "Content-Type: application/json" \
  -d '{"age": 35, "income": 52000, "credit_history": "good"}'

# Batch — send an array, get an array back:
curl -X POST http://localhost:8000/predict \
  -H "Authorization: Bearer my_key" \
  -H "Content-Type: application/json" \
  -d '[{"age": 35, "income": 52000}, {"age": 28, "income": 31000}]'

Generate model from natural language (Studio)

curl -X POST http://localhost:8080/api/studio/generate \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A model that predicts 30-day hospital readmission risk",
    "input_json": "{"age": 72, "diagnosis": "CHF"}"
  }'

Async training

# 1. Start job — get job_id immediately
curl -X POST http://localhost:8080/api/train-start \
  -d '{ "mxai_text": "...", "training_text": "...", "csv_text": "..." }'
# → { "ok": true, "job_id": "job-20260603-xyz789" }

# 2. Poll status
curl http://localhost:8080/api/train-status/job-20260603-xyz789

# 3. Cancel if needed
curl -X POST http://localhost:8080/api/train-cancel \
  -d '{ "job_id": "job-20260603-xyz789" }'

# Status values: running | done | error | cancelled | timeout

Example 1: Email classifier from scratch

# Step 1: Generate model from a description
matrixai prompt "classify emails as spam, normal or urgent" -o email.mxai

# Step 2: Inspect and lint
matrixai lint email.mxai
matrixai graph email.mxai --format mermaid

# Step 3: Generate training contract + dataset template
matrixai generate-training email.mxai "classify emails" -o email.mxtrain --dataset-output template.csv

# Step 4: Generate 500 coherent synthetic examples
matrixai generate-dataset email.mxai --training email.mxtrain --rows 500 --mode coherent -o data/

# Step 5: Train
matrixai train email.mxai --training email.mxtrain -o runs/email_v1/

# Step 6: Evaluate
matrixai evaluate email.mxai --params runs/email_v1/params.best.json --training email.mxtrain

# Step 7: Test a single prediction
matrixai run email.mxai --params runs/email_v1/params.best.json \
  --input '{"subject": "Exclusive offer", "sender_score": 0.15}'

# Step 8: Serve as API
matrixai serve email.mxai --params runs/email_v1/params.best.json --api-key my_key --port 8000

Example 2: Evaluate a custom scoring formula

# File: my_scoring.mx
score(opt) = quality(opt) - 0.3 * cost(opt) - 0.2 * latency(opt)
best(a, b) = argmax([a, b], score)

# File: options.json
# { "a": {"quality": 0.9, "cost": 0.7, "latency": 0.8},
#   "b": {"quality": 0.75, "cost": 0.2, "latency": 0.3} }

matrixai eval my_scoring.mx --input options.json --trace

Example 3: Translate business rules to math

# File: credit_rules.txt
# if default_history > 0.6 then auto_reject
# if income < 15000 and debt > 0.5 then high_risk
# classify application into approved, manual_review, rejected

matrixai mathematize credit_rules.txt
# Output: sigmoid and softmax expressions ready to embed in your .mxai

Functions available in .mx

Most used CLI commands

HTTP error codes