Getting Started

Getting Started

Every mojo-kernels package installs like the library it accelerates — pip for Python, npm for Node — and then behaves identically to it. No Mojo toolchain is ever needed on your machine.

Install patterns

Python — per-platform wheel. Each package publishes self-contained wheels for macOS arm64 and Linux x86_64 (py3-none-macosx_*_arm64, py3-none-manylinux_*_x86_64). The wheel carries the compiled kernel with the Mojo runtime vendored in (via delocate / auditwheel repair); there is no sdist, because a source tarball cannot rebuild the native library. On any other platform — including Windows — the same API runs on the vendored pure-Python fallback.

pip install bm25-mojo          # or cclib-mojo, jsonschema-mojo, nx-mojo, ...

The 22 Python packages: ase-mojo, bio-mojo, bm25-mojo, cclib-mojo, croniter-mojo, dynesty-mojo, elephant-mojo, jmespath-mojo, jsonpath-mojo, jsonschema-mojo, langdetect-mojo, metpy-mojo, nx-mojo, obspy-mojo, pykalman-mojo, pypdf-filters-mojo, ruptures-mojo, sacrebleu-mojo, ta-mojo, toml-mojo, uproot-mojo, vader-mojo. Full list with links: Kernels.

TypeScript — core + platform packages. Each npm workspace is a @…-mojo/core package that pulls the prebuilt native library for your platform in as an optionalDependencies entry (@…-mojo/darwin-arm64, @…-mojo/linux-x64), loaded with koffi. If the platform package is missing or fails to load, core transparently uses its vendored fallback.

npm install @fuse-mojo/core    # or @ckmeans-mojo/core, @minisearch-mojo/core, @natural-mojo/core

The fallback contract (every package)

There is no Windows Mojo toolchain today, and a shared library can always go missing — so the fallback is a first-class feature, not an error path:

• Resolution order: $<NAME>_MOJO_NATIVE_LIB (explicit override) → the library bundled in the wheel / platform package → the repo development build output.
• Force the fallback: set <NAME>_MOJO_DISABLE_NATIVE=1 (e.g. BM25_MOJO_DISABLE_NATIVE=1, FUSE_MOJO_DISABLE_NATIVE=1). Every differential test suite runs twice — once native, once forced-fallback — and asserts both against the real reference package, so the two backends cannot silently disagree.
• ABI handshake: the wrapper checks the library's <name>mojo_abi_version() before any native call; a mismatch falls back cleanly instead of crashing.
• Inspect what's active: each package exposes a diagnostic — backend_info() in Python, Fuse.backendInfo() / per-instance fuse.backend in Node — reporting native source, ABI version, and any load errors.
• Same results: the fallback is the same algorithm in vendored pure Python/JS, asserted against the same oracle at the same tolerance. You lose speed, never correctness.

Quickstart: bm25-mojo (Python)

pip install bm25-mojo, then use it exactly like rank_bm25:

from bm25_mojo import BM25Okapi

corpus = [
    "Hello there good man!",
    "It is quite windy in London",
    "How is the weather today?",
]
tokenized_corpus = [doc.split(" ") for doc in corpus]

bm25 = BM25Okapi(tokenized_corpus)                   # same call shape as rank_bm25
scores = bm25.get_scores(["windy", "in", "London"])  # np.ndarray, one score per doc
top = bm25.get_top_n(["windy", "in", "London"], corpus, n=2)

BM25Okapi, BM25L, and BM25Plus all match their rank_bm25 counterparts' constructor arguments, index attributes, and methods. Measured 116×–8,769× on 1k–100k document corpora, max abs diff 3.6e-15 — details: Kernel: bm25.

Quickstart: fuse-mojo (TypeScript / Node)

npm install @fuse-mojo/core, then use it exactly like Fuse.js:

import Fuse from '@fuse-mojo/core'

const books = [
  { title: "Old Man's War", author: { firstName: 'John', lastName: 'Scalzi' } },
  { title: 'The Lock Artist', author: { firstName: 'Steve', lastName: 'Hamilton' } },
]

const fuse = new Fuse(books, { keys: ['title', 'author.firstName'] })
fuse.search('lock')   // → [{ item: {...}, refIndex: 1 }]

CommonJS works too: const Fuse = require('@fuse-mojo/core'). The 90% option surface (keys, threshold, location, distance, minMatchCharLength, includeScore, includeMatches, …) is bit-exact vs Fuse.js 7.1.0; unsupported options throw UnsupportedOptionError on both backends. Measured 8.8×–38.7× warm — details: Kernel: Fuse.

Verifying a release download

Every asset on a GitHub Release ships with a keyless Sigstore signature bundle (<asset>.sigstore.json) and SLSA build provenance (multiple.intoto.jsonl), produced by the release workflow itself. The verification commands (cosign verify-blob, slsa-verifier) are in RELEASING.md.

Next steps

• How It Works — what just happened inside that wheel
• Benchmarks — the measured numbers and how to reproduce them
• Kernels — the full catalog
• FAQ

---

Apache-2.0, © 2026 Algenta