Funciones Matemáticas, CLI y API

Cuando defines un modelo en MatrixAI (con un archivo .mxai o .mx), describes qué cálculos debe hacer ese modelo usando funciones matemáticas. Es como una hoja de cálculo potente, pero que además puede aprender de datos.

Hay tres capas que vale la pena distinguir:

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

Son las matemáticas de toda la vida: disponibles como funciones en cualquier expresión .mx.

# candidatos.mx
puntuacion(c)     = 0.5 * c.experiencia + 0.5 * c.prueba_tecnica
diferencia(c1,c2) = sub(puntuacion(c1), puntuacion(c2))
mejor(c1, c2)     = max(puntuacion(c1), puntuacion(c2))

normalize(x) — Recortar al rango [0, 1]

normalize(1.5)   → 1.0   # recortado al máximo
normalize(-0.3)  → 0.0   # recortado al mínimo
normalize(0.7)   → 0.7   # sin cambios

clip(x, lo, hi) — Recortar a cualquier rango

clip(150, 0, 100)  → 100.0
clip(-5, 0, 10)   → 0.0
clip(7, 0, 10)    → 7.0

scale(x, old_min, old_max, new_min, new_max) — Reescalar de un rango a otro

# Convertir nota del 0-10 al 0-100
scale(7.5, 0, 10, 0, 100)  → 75.0

# Temperatura Celsius a escala 0-1
scale(37, 35, 42, 0, 1)    → 0.285...

sigmoid(x) — Convertir cualquier número a una probabilidad

sigmoid(0)    → 0.5      # punto de equilibrio: 50% de probabilidad
sigmoid(5)    → 0.993    # muy probablemente sí
sigmoid(-5)   → 0.007    # muy probablemente no

# riesgo_credito.mxai
riesgo(cliente) = sigmoid(2.5 * cliente.historial_impagos - 1.8 * cliente.ingresos + 0.3)

softmax(values) — Convertir puntuaciones en probabilidades que sumen 1

softmax([2.0, 1.0, 0.5]) → [0.626, 0.230, 0.143]
# 62,6% de probabilidad para la primera opción

# ranking.mx
valor_respuesta(r) = 0.4 * relevance(r) + 0.3 * coherence(r) + 0.2 * confidence(r) + 0.1 * safety(r)

# eficiencia.mx
utilidad(opcion) = quality(opcion) - 0.3 * cost(opcion) - 0.2 * latency(opcion)

# candidatos = ["A", "B", "C"] con scores: A=0.7, B=0.9, C=0.4
argmax(candidatos, mi_score_fn)          → "B"
topk(candidatos, mi_score_fn, 2)         → ["B", "A"]
threshold(candidatos, mi_score_fn, 0.6)  → ["A", "B"]
rank(candidatos, mi_score_fn)            → ["B", "A", "C"]

Clasificación multiclase — softmax_linear

# email_classifier.mxai (fragmento)
predict(email) = softmax(W1 * email + b1)
# W1 y b1 se aprenden de ejemplos etiquetados — pérdida: cross_entropy

Casos de uso: clasificar emails, categorizar incidencias, reconocer intención de usuario.

Clasificación binaria / riesgo — sigmoid_linear

# riesgo_caida.mxai (fragmento)
riesgo(paciente) = sigmoid(W1 * paciente + b1)
# Entrenado con binary_cross_entropy

Casos de uso: riesgo de crédito, detección de fraude, riesgo médico binario, churn.

Lo que aún no es entrenable (pero es ejecutable)

• Sumas ponderadas manuales (symbolic_weighted_sum)
• Normalización y escalado
• Agregaciones (mean, max, min sobre listas)
• Reglas discretas (argmax, vote)
• Atención, embeddings entrenables, transformers, redes profundas

mathematize traduce reglas tipo «si X entonces Y» a expresiones matemáticas continuas que los modelos pueden procesar y auditar.

si riesgo > 0.8 entonces alertar
si ingresos < 20000 y deuda > 0.5 entonces rechazar

matrixai eval score.mx --input datos.json
matrixai eval score.mx --input datos.json --trace
matrixai eval score.mx --input datos.json --call score

matrixai mathematize mis_reglas.txt
echo "si riesgo > 0.8 entonces alertar" | matrixai mathematize -

matrixai validate mi_modelo.mxai
matrixai lint mi_modelo.mxai
matrixai backend-report mi_modelo.mxai --target torch
matrixai graph mi_modelo.mxai --format mermaid

matrixai train-supervised "un modelo que clasifica emails como spam, normal o urgente" \
  --train-data emails_train.csv \
  --eval-data emails_eval.csv \
  -o runs/email_v1/

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

matrixai studio --port 8765 --open

# Autenticación
curl -H "Authorization: Bearer mi_clave" http://localhost:8000/predict ...
curl -H "X-API-Key: mi_clave" http://localhost:8000/predict ...

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

# Entrenamiento asíncrono
curl -X POST http://localhost:8080/api/train-start \
  -d '{ "mxai_text": "...", "training_text": "...", "csv_text": "..." }'
# → { "ok": true, "job_id": "job-20260603-xyz789" }

curl http://localhost:8080/api/train-status/job-20260603-xyz789
# status: running | done | error | cancelled | timeout

Ejemplo 1: clasificador de emails desde cero

matrixai prompt "clasifica emails como spam, normal o urgente" -o email.mxai
matrixai lint email.mxai
matrixai generate-training email.mxai "clasificar emails" -o email.mxtrain
matrixai generate-dataset email.mxai --training email.mxtrain --rows 500 --mode coherent -o datos/
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
matrixai run email.mxai --params runs/email_v1/params.best.json \
  --input '{"subject": "Oferta exclusiva", "sender_score": 0.15}'
matrixai serve email.mxai --params runs/email_v1/params.best.json --api-key mi_clave --port 8000

Ejemplo 2: traducir reglas de negocio a expresiones matemáticas

# reglas_credito.txt
# si historial_impagos > 0.6 entonces rechazar_automatico
# si ingresos < 15000 y deuda > 0.5 entonces alto_riesgo
# clasificar solicitud en aprobada, revision_manual, rechazada

matrixai mathematize reglas_credito.txt