Machina: open machine intelligence you can audit

Why Machina

TL;DR. Machina is an open harness for machine intelligence: it turns a window of sensor data into a diagnosis, a remaining-life estimate, an energy or process-quality finding and an evidence brief, and it does so with models you can read, abstention you can tune and an audit trail you can trust. The ethos fits one line: signals stay legible, models stay portable, actions stay governed.

Industrial machine learning usually fails for dull reasons: a model that is accurate on a lab bench and unusable on a factory floor, a score nobody can explain to the engineer who has to act on it, a log that stores too much, a pipeline that can silently skip a human. Machina is a bet that most of the value is in the plumbing around the model: honest abstention, inspectable features, replaceable parts, and a boundary where the software stops and a qualified person starts.

Bearing faults: from 0.59 to 0.99, and why to distrust 0.99

The first capability classifies a vibration window as normal, ball, inner-race or outer-race fault, using the Case Western Reserve University bearing dataset (the raw files are kept outside the repository). Two checkpoints ship: a four-feature RandomForest baseline, and the enhanced model used by the container.

Does it survive a speed it has not seen?

A random split lets nearly identical windows sit on both sides. The enhanced run therefore splits by file (whole recordings held out) and also by motor speed: leave-one-RPM-out over the dataset’s four speeds (1730, 1750, 1772, 1797 rpm).

Anomaly detection and energy: rules you can check by hand

Not everything should be a model. The anomaly detector is a robust z-score of the latest value against the window’s median and median absolute deviation, mapped to a 0–1 score per sensor; the window score is the worst sensor, and the three most responsible sensors are reported. Energy analytics is the same idea for efficiency: energy per unit of output relative to a median baseline.

Remaining useful life: the honest number is 62 cycles

The second capability estimates how many cycles an engine has left, trained on NASA’s C-MAPSS turbofan degradation simulations (subset FD001). At runtime it returns a point estimate with an interval taken from the spread of the forest’s individual trees.

Process quality: accuracy 98%, macro-F1 55%

The third capability predicts a process failure mode from six machine settings, using the synthetic UCI AI4I 2020 dataset: tool wear, heat dissipation, power, overstrain or random failure, as a probability that something other than “normal” is happening.

The agent: routing, not reasoning from scratch

Machina’s design splits intelligence in two. Specialist models operate on machine signals; a small language model translates a natural-language request into the right tool call. The agent is a Mistral-7B-Instruct adapter, trained with QLoRA to emit one structured tool call.

The training set is a synthetic, grounded routing set: it teaches routing and response style, not machine facts. It contains 1,200 examples, exactly 120 for each of ten tools, built from 50 distinct user strings. That makes it a good fit for a router and a poor basis for claims about generalisation, which is why the repository says to validate the adapter on held-out routing examples before calling it production-ready.

Evidence for the language layer

The “reasoning” side of the platform is a retrieval brief. Maintenance documents are indexed in an SQLite full-text table and searched with BM25; prepare_maintenance_brief returns the asset record, the top evidence passages, the registered model ids and three fixed instructions for whatever language model consumes them:

Use only the returned evidence and model outputs as factual support.
Separate observed signals from hypotheses.
Recommend qualified human inspection for safety-critical decisions.

Governance as code

The least glamorous part of the repository is the part most worth copying. The platform treats every analysis as something that may be audited, challenged and overridden.

Portability and the edge

“Portable” here has a concrete meaning: the models are plain scikit-learn joblib files with a metadata JSON and a model card, they are registered as plugins that can be swapped, and path overrides let a deployment point to its own checkpoints. They run on a CPU with no network access at inference.

Run it

Python 3.10 or newer. Fetch the large files with Git LFS, install the package and start the API; the interactive documentation is at /docs.

git clone https://github.com/Clerktree/machina-intelligence && cd machina-intelligence
git lfs pull                                   # model.joblib files are Git LFS objects
python3 -m venv .venv && source .venv/bin/activate
pip install -e '.[dev]'                        # extras: dev, train, mcp, runtime, agent
uvicorn machina_harness.api:app --reload       # http://127.0.0.1:8000/docs

curl -X POST http://127.0.0.1:8000/v1/analyze \
  -H 'content-type: application/json' -d @configs/sample-window.json
curl http://127.0.0.1:8000/v1/model-health

# container (the key is mandatory)
export MACHINA_API_KEY="replace-with-a-long-random-secret"
docker compose up --build -d
curl http://127.0.0.1:8000/ready -H "X-Machina-API-Key: $MACHINA_API_KEY"

# MCP over stdio (e.g. for Grok Build)
pip install -e '.[mcp]' && python3 -m machina_harness.mcp_server

A few practical notes. The classifier imports scipy.signal.hilbert, which arrives through scikit-learn rather than being declared on its own. The model cards declare Apache-2.0. The capability registry is the source of truth for what is live: fault diagnosis, anomaly detection, remaining useful life, energy intelligence and quality prediction are available, while the maintenance copilot and machine knowledge capabilities are marked as planned.

The decision-support framing is repeated in the repository, and it is worth repeating here: the model is decision support, not a safety controller. Human inspection and site-specific validation are required before any maintenance action.