matra
NLP library. Text in, structured analysis out.
UDPipe-based structured parse (full CoNLL-U: tokens, lemmas, POS, dependency trees), base text metrics (readability, lexical density, compression), summarization (TF-IDF, TextRank), and keyphrase extraction (RAKE, YAKE). Rust core with Python bindings via PyO3.
If you are an agent, run uvx 'matra>=0.3' --skill, which needs nothing installed, or matra --skill if you already have the binary. Either way the program prints skills/matra/SKILL.md out of its own binary, so the text always matches the version you are running. Keep the version floor: 0.2's command line spells its commands and its JSON differently, and 0.1.0's has no --skill at all.
A pure, performant NLP library, built to be adaptable, composable, and extensible. Hex architecture, domain has zero internal dependencies, public enums and structs with public fields are #[non_exhaustive]. The library is small and stable; the interpretation lives in your code.
No setup
Nothing installed, nothing configured, no flags. Each of these resolves the model directory and downloads the English model (~16MB) on first use.
let engine = new?;
The uvx line carries a version floor for the same reason the --skill line above does. Both registries serve 0.3.x, so a bare uvx matra resolves to it today; the floor says what these commands need rather than leaving it to whichever release is newest when you run them. 0.2 is still published too, and its command line and JSON are the ones the migration guide moves you off. 0.1.0 is still published, and its analyze is a separate Python implementation and not this one missing a flag: --json prints a bare document with no envelope, the table is a different renderer, and the model cache is hardcoded to ~/.matra/models. That line does not fail, it succeeds and hands you something else.
The directory is the one you pass explicitly, else MATRA_MODEL_DIR, else the models subdirectory of the data root (MATRA_DATA_DIR, else $XDG_DATA_HOME/matra, else ~/.local/share/matra); a non-empty ~/.matra/models from an older install is still used when the new location does not exist yet. The config file does not move the model directory: its [models] embedding key names the embedding model's subdirectory inside it, and nothing selects the parsing model, which is pinned in the source. To put it somewhere specific, pass it explicitly (--model-dir, Config::with_model_dir), or set MATRA_MODEL_DIR, which is how Python names it. matra config show prints every resolved value and where it came from.
Install
# Rust library
# Rust CLI
# Python library and the matra command
Each command names a version for the reason the uvx line above does. A bare cargo add matra or pip install matra takes whatever the registry hands out, which is 0.3.x today and will not stay that way, and 0.1.0 and 0.2 are still there for anything already pinned to them: that route does not fail, it succeeds and gives you a different program. The Python routes take a floor, and uv add 'matra>=0.3' is that same floor for uv. The cargo routes take a caret requirement, which is how cargo states a version, so they accept 0.3.0 or a later release semver-compatible with it and stop short of 0.4.0. Coming from 0.2, read Migrate from 0.2 to 0.3 first: nothing keeps its old name.
The Python package's matra command is the Rust CLI reached through the extension module, not a second implementation, so the flags, the output and the exit codes are the same either way. Wheels ship for Linux x86_64, Linux aarch64, macOS x86_64 and macOS arm64. They are built against the CPython stable ABI, so one wheel per platform serves 3.12 and every later 3.x on GIL-enabled CPython, and the Linux ones are manylinux2014, which installs on glibc 2.17 or newer and so reaches back through Debian 11, Ubuntu 20.04, RHEL 8 and Amazon Linux 2. Anything else builds from the sdist, which needs a Rust toolchain and a C++ compiler, because UDPipe is C++. On Windows that path is untested rather than known to work, and it needs the MSVC build tools rather than any of the packages the installation page names. Free-threaded CPython also falls here, which takes a different ABI tag than the one these wheels carry.
Usage (Rust)
use ;
let engine = new?;
// One document: a file, read as its extension and bytes say.
let doc = engine.analyze?;
println!;
println!;
println!;
// Outcomes are functions of the document: no second parse.
let summary = summarize?;
let phrases = keyphrases_with?;
println!;
// Many documents, lazily and in order; a failure is one item, not an abort.
for item in engine.analyze_all
Input also takes text in a named format (Input::text), bytes from anywhere (Input::bytes), and headings and paragraphs you supply for a format matra has no reader for (Input::blocks). Every heading, paragraph, sentence and token carries a span into the analysed text, in UTF-8 bytes, and skipped lists what the reader saw and did not analyse (a table, a code block, front matter).
summarize, keyphrases and clusters take the analysed Document and need no engine, so they also run in a build without UDPipe. The method is optional (summarize_with(&doc, n, SummaryMethod::TextRank)), and every result records the method that ran and its parameters in its provenance. clusters(&doc, &embedder, 0.85) takes the embedder from you, always. Engine::new() reads no configuration file; Engine::from_config(&Config::resolve()?) reads one, and Config::with_model_dir(dir) puts the model somewhere specific.
Usage (Python)
=
= # a str alone is text, never a path
=
=
# lazily, one item per file
# a failure: path, kind, message, details
A Document is read-only and reads as its JSON (doc.to_dict() for the whole). Python spells every word Rust spells: analyze(text=, file=, bytes=, blocks=, format=) for the Input constructors, and method= for the _with forms.
Usage (CLI)
Under --json every command writes one envelope, {format_version, command, input, result, error}, and a failure is an envelope too: result null, error its kind, message and details, and exit code 2.
Metrics
Per sentence: word count, POS tags, dependency labels, passive voice, tree depth.
Per paragraph: sentence count, readability grade, lexical density, compression ratio.
Per document: word, sentence and paragraph counts, passive ratio, mean and spread of sentence length, vocabulary TTR, nominalization ratio. Each document also records its provenance: the parser and its model, the format, and the SHA-256 of the input, with the schema version (2.0) its JSON follows.
Architecture
Hex architecture. The pipeline depends on port traits (Source, Decomposer, NlpProvider), not on adapters directly. All three are public, so a parser, a reader or a source of your own plugs in through Engine::with_parser, with_reader and with_source, and the engine checks everything a parser or a reader returns before it reaches a Document. The shipped adapters, detection, the step that turns blocks into sections, the metric suite and the ranking methods are private to the crate: a caller hands in an Input and asks for an outcome. Embedder is the fourth port, which clusters takes. UDPipe is the default NLP adapter, behind the udpipe feature flag.
The domain sits at the centre and depends on nothing. Four ports (Source, Decomposer, NlpProvider, Embedder) depend only on the domain. Adapters implement one port each, and nlp/udpipe.rs is the only file that imports the UDPipe bindings. Metrics and the outcome methods are plain functions over the domain. lib.rs wires it together and is the only file that knows the whole shape.
The full walkthrough, with what is resident at each stage and what can fail where, is in the architecture chapter.
How this project is run
matra is a Claude-managed open-source project, intended as an exemplar for both Claude-managed repositories and human–AI collaborative intelligence. The owner collaborates with Claude (Anthropic's AI) to plan, implement, and review changes. Claude reviews and merges a pull request once CI is green and the review raises no blockers, and leaves a comment with its rationale as the audit trail. The owner makes the decisions: only the owner merges the change that accepts an enhancement proposal, and only the owner approves the release workflow's deployment environments, which is the release decision. How matra is maintained explains the whole arrangement. The working values are transparency (decisions are visible), auditability (every change has a trail), and reversibility (every change can be backed out cleanly).
The repository is built on two non-negotiable disciplines:
- ACES: Adaptable, Composable, Extensible. The structural design
philosophy that resists the stasis/drag/opacity decay cycle every long-lived
library faces. See
.claude/skills/aces/SKILL.md. - Antifragility: the operational discipline. Size caps at the gate,
panic boundaries at the C/C++ FFI, atomic file writes, TOCTOU-closed hash
verification, cycle-safe graph walks. See
.claude/skills/resilience-floor/SKILL.md.
The agent organization in .claude/agents/
and skill library in .claude/skills/
operationalize these disciplines so any contributor, human or AI, can
participate without re-deriving the design.
| Where to look | What's there |
|---|---|
.claude/arch/ |
Rejected-decision history: what was proposed, why it was turned down. The architecture itself is in the docsite's architecture page |
blueprints/ |
Enhancement proposals (substantial changes, accepted by the owner), enhancement plans (work several agents carry out in parallel), and the legacy RFCs and EPs behind the code that exists |
CHANGELOG.md |
What changed and why, per release |
CONTRIBUTING.md |
How to participate, commit conventions, decision flow |
SECURITY.md |
Vulnerability disclosure policy, and how to verify a release with gh attestation verify |
CITATION.cff |
How to cite matra |
Citing matra
If you report matra's numbers in published work, cite two things. Cite the
software with the entry in CITATION.cff, which identifies
the implementation and its version. Then cite the publication behind each
measure you used, which identifies the method. matra implements published
methods with documented departures, so neither citation substitutes for the
other. The per-measure references, and the departures, are in
the methodology reference.
To make a result reproducible, record the matra version, the model file name and its SHA-256, the format the document was analyzed under, and the parameters you passed. The methodology page gives the exact form.
License
MIT, Copyright (c) 2026 mox labs. See
LICENSE.
The models matra downloads are separate files with their own licenses.
The English parsing model, english-ewt-ud-2.5-191206.udpipe from
LINDAT, is
CC BY-NC-SA 4.0,
which does not permit commercial use. The embedding model,
potion-base-8M, is MIT per its model card. See
model licenses.