matrixai-core 1.0.0

Auditable AI model language, runtime and deployment framework

MatrixAI

MatrixAI is a language for AI, not for humans. Describe a model in a prompt, train it, audit every decision it makes, and deploy it where trust is not optional.

Models are not black boxes — they are auditable programs: explicit inputs, explicit transformations, explicit outputs, explicit audit trail. Every decision is traceable to a named node in the computation graph. That is the core value for critical environments: healthcare, finance, legal, industrial.

Website & Studio: matrixaistudio.org — browser-based model development environment, downloads, documentation and member resources.

---

Get started

pip install matrixai-core
matrixai --help

→ Quickstart (5 min) 🇬🇧 · Quickstart (5 min) 🇪🇸

---

What MatrixAI does

1. Describe — write a model in a natural-language prompt or in .mxai directly.
2. Generate — the system builds a verifiable computation graph and training contract.
3. Train — supervised training with versioned parameters, reproducible metrics and full trace.
4. Audit — every prediction is traceable; every action is signed and logged.
5. Deploy — serve over HTTP, export to ONNX/WASM, package as Docker, or register in the model registry.
6. Monitor — detect drift, trigger retraining, rollback automatically or manually.

---

Key features

• Prompt → model: matrixai prompt "..." generates a runnable .mxai program
• Auditable graph: computation graph with named nodes, explicit types and audit trail
• Supervised training: classification, risk scoring and regression with .mxtrain specs
• Model registry: versioned, signed, verifiable — matrixai registry push/pull/verify
• Real actions: .mxact contracts with HMAC-signed traces, dry-run and rollback
• Continual learning: .mxcontinual policies with drift detection and automatic versioning
• HTTP server: /predict, /metrics (Prometheus), /execute-action, /feedback with API key auth
• ONNX / WASM export: edge deployment bundles and browser-ready WASM packages
• Studio: browser-based model development environment (matrixai studio)

---

Quick example

# Create a project from a template
python -m matrixai init my-model --template classification

# Train
python -m matrixai train my-model/my-model.mxai \
  --training my-model/my-model.mxtrain \
  --output my-model/runs/v1

# Predict
python -m matrixai run my-model/my-model.mxai \
  --params my-model/runs/v1/params.best.json \
  --input my-model/input/sample.json

# Serve over HTTP
python -m matrixai serve my-model/my-model.mxai \
  --params my-model/runs/v1/params.best.json \
  --api-key my-secret
# → http://127.0.0.1:8000/docs

---

Examples

Example	Domain	Mode
examples/credit-scoring/	Credit approval	Risk scoring
examples/clinical-risk/	Fall risk assessment	Risk scoring
examples/agent-alert/	Alert monitoring with real action	Classification + action
examples/text-routing/	Support ticket routing	Multi-class classification
examples/email-agent.typed.mxai	Email classification	Classification
examples/celsius_to_kelvin.mxai	Temperature conversion	Regression
examples/transformer-classifier.mxai	Transformer encoder	Classification

---

Documentation

Topic	English	Español
Quickstart	QUICKSTART.md	QUICKSTART.md
Tutorial	TUTORIAL.md	TUTORIAL.md
Language spec	LANGUAGE_SPEC.md	LANGUAGE_SPEC.md
CLI reference	CLI_REFERENCE.md	CLI_REFERENCE.md
REST API	REST_API.md	REST_API.md
Use cases	USE_CASES.md	CASOS_DE_USO.md
Benchmarks	INDEX.md	INDEX.md
Deployment	DEPLOYMENT.md	DEPLOYMENT.md
Observability	OBSERVABILITY.md	OBSERVABILITY.md
Runbook	RUNBOOK.md	RUNBOOK.md
Key rotation	KEY_ROTATION.md	KEY_ROTATION.md
Server hardening	SERVER_HARDENING.md	SERVER_HARDENING.md
Versioning policy	VERSIONING.md	VERSIONING.md
Changelog	CHANGELOG.md	CHANGELOG.md
Business model	BUSINESS_MODEL.md	MODELO_NEGOCIO.md

---

Install

pip install matrixai-core

With optional export dependencies (ONNX / WASM):

pip install "matrixai-core[export]"

With GPU training support (PyTorch):

pip install "matrixai-core[torch]"

All extras:

pip install "matrixai-core[export,torch,dev]"

From source:

git clone https://github.com/robertollweb/matrixAI.git
cd matrixAI
pip install -e .

Requirements: Python 3.10+ must be installed on your system (python.org/downloads).

Windows note: use python instead of python3 in all commands below.
If matrixai is not found after install, use python -m matrixai (or python3 -m matrixai on Linux/macOS).

---

Running MatrixAI

After installing, you can call MatrixAI in two equivalent ways:

# Option A — direct command (works when pip scripts directory is in PATH)
matrixai --help

# Option B — via Python module (always works, recommended on Windows)
python -m matrixai --help       # Windows
python3 -m matrixai --help      # Linux / macOS

---

LLM configuration (optional)

MatrixAI works without any LLM — it uses a built-in deterministic engine by default. To enable LLM-powered model generation, copy the example config and fill in your API key:

cp .env.example .env

Then edit .env and set your provider and key. Minimal example for OpenAI:

MATRIXAI_LLM_PROVIDER_NAME=openai
MATRIXAI_LLM_MODEL=gpt-4o-mini
MATRIXAI_LLM_API_KEY=sk-...your-key...

For Anthropic (Claude):

MATRIXAI_LLM_PROVIDER_NAME=anthropic
MATRIXAI_LLM_MODEL=claude-opus-4-8
MATRIXAI_LLM_API_KEY=sk-ant-...your-key...
MATRIXAI_LLM_MAX_TOKENS=4096

For Google Gemini or DeepSeek — see the full list of providers and example configs in .env.example.

Without a .env file (or with MATRIXAI_LLM_API_KEY empty), MatrixAI runs in deterministic mode: all features work except LLM-generated model suggestions.

---

Studio

Browser-based model development environment. Generate models from prompts, train, evaluate and explore — no CLI required.

python -m matrixai studio
# → http://127.0.0.1:8765

The /expert route opens the full technical workbench for .mxai editing, pipeline inspection and runtime diagnostics.

---

Run the tests

python -m pytest tests/
# 3606 passed, 16 skipped

---

LLM integration (optional)

MatrixAI can use an external LLM to generate model proposals from prompts. Without configuration it falls back to the deterministic local mode.

# .env (ignored by git)
MATRIXAI_LLM_API_KEY=your-key
MATRIXAI_LLM_MODEL=external-model-id
MATRIXAI_LLM_ENDPOINT=https://provider.example/v1/chat/completions

Variable	Default	Description
MATRIXAI_LLM_API_KEY	—	External provider key
MATRIXAI_LLM_MODEL	configured by you	Model identifier sent to the external provider
MATRIXAI_LLM_ENDPOINT	chat-completions-compatible endpoint	Provider endpoint
MATRIXAI_LLM_CANDIDATES	1	Number of candidates to generate
MATRIXAI_LLM_TEMPERATURE	0	Generation temperature
MATRIXAI_LLM_TOKEN_BUDGET	0 (unlimited)	Max tokens per call

Any chat-completions-compatible API can be used, including local model servers.

---

License

See LICENSE — AGPL v3. License verification: English · Español.
© Roberto Llamosas Conde — robertollweb/matrixAI