Referencia CLI y Flujos de Trabajo

matrixai init <nombre_proyecto> [--template <nombre>] [--output-dir <dir>] [--list-templates]

Lo que genera: un fichero .mxai, un .mxtrain, un CSV de ejemplo y un fichero de instrucciones de inicio rápido.

matrixai init --list-templates
matrixai init mi_clasificador_emails
matrixai init riesgo_credito --template classification
matrixai init detector_fraude --output-dir ~/proyectos/

matrixai prompt <descripción...> [-o <fichero>] [--semantic] [--json]

matrixai prompt "clasifica emails como spam, normal o urgente"
matrixai prompt "clasifica emails como spam, normal o urgente" -o email.mxai
matrixai prompt "evalúa el riesgo de caída de pacientes mayores" --semantic
cat descripcion.txt | matrixai prompt - -o modelo.mxai
matrixai prompt "detecta transacciones fraudulentas" --json

# Propuestas con LLM
matrixai propose "clasifica documentos legales" --max-candidates 3
matrixai propose "sistema de dispensación farmacéutica" --provider chat-completions-compatible
matrixai propose "predictor de churn" --json --include-compiled

# Supervisar un .semantic existente
matrixai supervise-prompt "mi modelo" --proposal mi_modelo.semantic

# Convertir .semantic a .mxai directamente
matrixai architect mi_modelo.semantic -o mi_modelo.mxai

# Validar (0 = OK, 1 = error)
matrixai validate email_classifier.mxai
matrixai validate-plan mi_modelo.semantic

# Lint: errores + advertencias + sugerencias
matrixai lint email_classifier.mxai
matrixai lint email_classifier.mxai --strict   # falla ante cualquier advertencia (CI)
matrixai lint email_classifier.mxai --json

# Formatear
matrixai format email_classifier.mxai           # ver resultado
matrixai format email_classifier.mxai --write  # formatear en su lugar
matrixai format email_classifier.mxai --check  # verificar en CI

# Verificar tipos y ver representación interna
matrixai typecheck email_classifier.mxai
matrixai parse email_classifier.mxai

matrixai graph email_classifier.mxai                           # Mermaid (pégalo en mermaid.live)
matrixai graph email_classifier.mxai --format dot -o grafo.dot # Graphviz
matrixai graph email_classifier.mxai --format json

Ejecuta el modelo con los mismos datos en el intérprete y en el compilador Python, compara resultados y detecta discrepancias numéricas entre backends.

echo '{"subject": "Oferta", "sender_score": 0.2, "body_length": 450}' > entrada.json
matrixai diagnose email_classifier.mxai --input entrada.json
matrixai diagnose email_classifier.mxai --input entrada.json --tolerance 1e-6 --json

optimize analiza y sugiere mejoras sin modificar nada; permissions muestra permisos de sandbox para acciones; mathematize convierte reglas de negocio discretas en expresiones continuas para entrenamiento y auditoría.

# Sugerencias de optimización (solo lee, nunca modifica)
matrixai optimize email_classifier.mxai

# Revisar permisos de sandbox para acciones
matrixai permissions email_classifier.mxai

# Traducir reglas if/then a matemáticas continuas
matrixai mathematize reglas_negocio.txt
echo "si riesgo > 0.8 entonces alertar" | matrixai mathematize -

# Salida esperada:
# si historial_impagos > 0.6 entonces rechazar
#   -> sigmoid(20 * (historial_impagos - 0.6))
# si ingresos < 15000 y deuda > 0.5 entonces revisar
#   -> sigmoid(20 * (15000 - ingresos)) * sigmoid(20 * (deuda - 0.5))
# clasificar solicitud en aprobada, revision, rechazada
#   -> softmax([score_aprobada, score_revision, score_rechazada])

matrixai compile email_classifier.mxai -o email_compiled.py
matrixai compile email_classifier.mxai --target differentiable-python -o email_diff.py

# scoring.mx: utilidad(op) = quality(op) - 0.3 * cost(op) - 0.2 * latency(op)
matrixai eval scoring.mx --input '{"quality": 0.9, "cost": 0.4, "latency": 0.3}'
matrixai eval scoring.mx --input datos.json --trace
matrixai eval scoring.mx --input datos.json --call utilidad

# Informe de portabilidad
matrixai backend-report email_classifier.mxai
matrixai backend-report email_classifier.mxai --target torch

# Ejecutar con backend diferenciable
matrixai backend-run email_classifier.mxai --input entrada.json --parameters initial
matrixai backend-run email_classifier.mxai   --input entrada.json --target torch --device cuda   --parameters runs/email_v1/params.best.json

# Inspeccionar parámetros esperados
matrixai backend-parameters email_classifier.mxai
matrixai backend-parameters email_classifier.mxai --validate runs/email_v1/params.best.json

# Salida típica de backend-report:
# Backend: differentiable_python
# Compatibilidad: PARCIAL
# OK: softmax_linear entrenable, sigmoid_threshold ejecutable
# ADVERTENCIAS: symbolic_weighted_sum aplazada en torch
# BLOQUEANTE para torch: select_argmax no diferenciable

# Validar contrato de entrenamiento
matrixai validate-training email.mxtrain

# Generar contrato de entrenamiento
matrixai generate-training email_classifier.mxai   "clasifica emails como spam, normal o urgente"   -o email.mxtrain --dataset-output email_template.csv

matrixai generate-training email_classifier.mxai "clasifica emails"   -o email.mxtrain --epochs 200 --learning-rate 0.01

matrixai generate-training riesgo_credito.mxai "clasificar solicitudes de crédito"   -o credito.mxtrain --labels "aprobada,rechazada,revision" --target-name "decision"

# Generar modelo + contrato de una vez
matrixai generate-supervised   "clasifica emails como spam, normal o urgente"   -o modelos/email/ --stem email_classifier

# Generar datos sintéticos (200-50.000 filas)
matrixai generate-dataset email_classifier.mxai   --training email.mxtrain --rows 500 --mode coherent -o datos/
matrixai generate-dataset email_classifier.mxai   --training email.mxtrain --rows 1000 --seed 123 --mode coherent -o datos/

Artefactos generados: params.best.json, params.final.json, metrics.json, training_trace.json, evaluation_report.json

matrixai train email_classifier.mxai --training email.mxtrain -o runs/email_v1/
matrixai train email_classifier.mxai --training email.mxtrain -o runs/email_v1/ --backend torch --device cuda
matrixai train email_classifier.mxai --training email.mxtrain -o runs/email_v1/ --json

matrixai train-supervised   "clasifica emails como spam, normal o urgente"   --train-data datos/emails_train.csv --eval-data datos/emails_eval.csv   --epochs 150 -o runs/email_v1/

matrixai evaluate email_classifier.mxai   --params runs/email_v1/params.best.json --training email.mxtrain   --data datos/emails_test.csv -o informes/evaluacion_v1.json

Ejecuta el modelo con una entrada concreta y muestra el resultado. Es ideal para pruebas rápidas antes de entrenar, después de entrenar o antes de servir.

matrixai run email_classifier.mxai   --input '{"subject": "URGENTE", "sender_score": 0.95, "body_length": 120}'
matrixai run email_classifier.mxai --input entrada.json --params runs/email_v1/params.best.json --json

matrixai serve email_classifier.mxai   --params runs/email_v1/params.best.json --api-key mi_clave_secreta

matrixai serve email_classifier.mxai   --params runs/email_v1/params.best.json   --host 0.0.0.0 --port 8080   --api-key CLAVE_ESCRITURA --api-key-read CLAVE_LECTURA

matrixai serve --registry matrixai_registry/ --api-key mi_clave_secreta

matrixai serve email_classifier.mxai   --params runs/email_v1/params.best.json --api-key mi_clave_secreta   --continual-policy politica_drift.mxcontinual --reference-accuracy 0.923

matrixai serve email_classifier.mxai   --params runs/email_v1/params.best.json --api-key mi_clave_secreta   --cors-origin https://mi-app.com

matrixai playground --open
matrixai playground --port 9000 --open
matrixai playground --open

matrixai pack email_classifier.mxai   --params runs/email_v1/params.best.json --outdir dist/email_v1/
matrixai pack email_classifier.mxai   --params runs/email_v1/params.best.json --docker --outdir dist/email_v1/
cd dist/email_v1/ && docker compose up

matrixai init clasificador_emails && cd clasificador_emails/
matrixai generate-supervised \
  "clasifica emails entrantes como spam, normal o urgente" \
  -o . --stem email_classifier --epochs 200
matrixai lint email_classifier.mxai
matrixai graph email_classifier.mxai --format mermaid
matrixai generate-dataset email_classifier.mxai \
  --training email_classifier.mxtrain --rows 1000 --mode coherent -o datos/
matrixai train email_classifier.mxai --training email_classifier.mxtrain -o runs/v1/
cat runs/v1/evaluation_report.json
matrixai run email_classifier.mxai --params runs/v1/params.best.json \
  --input '{"subject": "Oferta exclusiva", "sender_score": 0.1, "body_length": 800}'
matrixai registry push runs/v1/ --name email-classifier --version v1.0
matrixai registry tag email-classifier@v1.0 prod
matrixai serve email_classifier.mxai \
  --params runs/v1/params.best.json --api-key $MATRIXAI_API_KEY --port 8000

matrixai validate email_classifier.mxai
matrixai lint email_classifier.mxai
matrixai graph email_classifier.mxai
matrixai backend-report email_classifier.mxai
matrixai diagnose email_classifier.mxai --input entrada_prueba.json
matrixai optimize email_classifier.mxai
matrixai typecheck email_classifier.mxai
matrixai parse email_classifier.mxai

matrixai continual status politica_drift.mxcontinual
matrixai continual audit politica_drift.mxcontinual \
  --drift-report informes/drift_semana.json \
  --prompt "clasifica emails como spam, normal o urgente"
matrixai refine "clasifica emails como spam, normal o urgente" \
  --evaluation runs/v1/evaluation_report.json --mxai email_classifier.mxai \
  --hint "mejorar recall en emails urgentes" \
  --accept --mxai-output email_v2.mxai --chain-output cadena_v2.json --iteration 2
matrixai train email_v2.mxai --training email_classifier.mxtrain -o runs/v2/
matrixai registry push runs/v2/ --name email-classifier --version v2.0
matrixai continual promote politica_drift.mxcontinual \
  --approval-report informes/aprobacion_v2.json \
  --candidate-params runs/v2/params.best.json \
  --human-approved --approved-by "nombre@empresa.com"
# Si algo sale mal:
matrixai continual rollback politica_drift.mxcontinual --dry-run
matrixai continual rollback politica_drift.mxcontinual

# ONNX para runtime externo
matrixai export-onnx email_classifier.mxai --params runs/v1/params.best.json \
  -o exports/email_v1.onnx --validate --manifest exports/email_v1_manifest.json
# Bundle completo para edge
matrixai export-bundle email_classifier.mxai --params runs/v1/params.best.json \
  --outdir exports/edge_bundle/
# Bundle para navegador (WebAssembly)
matrixai export-wasm email_classifier.mxai --params runs/v1/params.best.json \
  --outdir exports/wasm_bundle/
# Imagen Docker lista para desplegar
matrixai pack email_classifier.mxai --params runs/v1/params.best.json \
  --docker --outdir dist/email_v1/
cd dist/email_v1/ && docker compose up