Situation model
on this page
What matra is for
matra reports the structure of text and measurements over it. Text goes in; a typed tree, a set of measures, and a set of ranked extractions come out. Everything it returns is a value your code can read, store, and reason over.
It is a library, not an application. The analysis on top of it is yours to write.
What it reports and what it leaves to you
matra reports passive_ratio = 0.4. Whether 0.4 is too passive for the document at hand is your call, and the answer differs between a statute, a lab report, and a landing page.
That split runs through every tier:
| matra reports | Your code decides |
|---|---|
a sentence carries nsubj:pass | whether the missing agent matters here |
clausal_complements names a verb governing a ccomp | whether that verb is evidential and whether the source is credible |
hearst_pairs names a construction that conventionally signals hypernymy | whether the hypernymy relation actually holds |
modals names must on an aux arc | whether that must is obligation or inference |
a Cluster groups sentences whose vectors cleared your threshold | whether those sentences say the same thing |
The reason for the split is reuse. A judgment is fitted to one purpose and is dead weight to the next caller; the arc it was computed from is not.
Where it sits in a pipeline
Upstream of interpretation, downstream of ingestion.
files or strings -> matra -> rule evaluation
scoring and dashboards
retrieval and chunking
LLM prompt construction
Two properties make it usable that far downstream. Every value is serde-serializable, so the parse crosses into Python as a plain dict and can be stored as JSON. And every value has a place in the tree: a token id is scoped to its sentence, a sentence belongs to the paragraph whose text was parsed to produce it, and every heading, paragraph, sentence and token carries a span into the analysed text, so a value can be traced back to the bytes it came from.
What it needs from the environment
Nothing has to be set up first. Engine::new() in Rust, matra.Engine() in Python, and any matra command resolve where models live and fetch what is missing. The directory comes from an explicit argument if you pass one, else MATRA_MODEL_DIR, else the models subdirectory of the data root (MATRA_DATA_DIR, else $XDG_DATA_HOME/matra, else ~/.local/share/matra), with a non-empty ~/.matra/models from an older install used when the new location does not exist yet. The config file does not move the model directory, and it does not choose the parsing model, which is pinned in the source. Programming model has the resolution order.
Models are fetched, not bundled, and only against a pinned digest. The UDPipe English model arrives on the first call to Engine::new or Engine::from_config, in Rust or in Python; the reference embedding model arrives on the first call to Model2Vec::potion_base_8m or Model2Vec::from_config. Both fetch from URLs written in the source and load nothing whose SHA-256 does not equal a constant written beside them. A download that fails verification is fetched once more, in memory, and a second failed download raises without anything having been written. Exactly one artifact set can arrive this way for each.
Bringing your own embedding model is a first-class path. Model2Vec::from_dir loads what you supply and touches no network, whatever the directory holds. The parsing model is a pin. For those, the digest is identity rather than proof: it says which artifacts produced a value, not that they are the ones you meant to fetch.
Verification and load share one read. Bytes are hashed in memory and the model is loaded from those same bytes. Nothing re-reads the disk between the two.
Those pinned model fetches are the only network access anywhere in the library.
The split, on five sentences
The primitive fields from the table above, as matra fills them for five short sentences written to carry one each. Every mark is a construction in the tree; whether it matters for a text stays with the reader.
Structural primitives
- 1
The committee did not approve the budget.
root mood Ind - 2
Members must submit revised estimates by Friday.
- 3
The chair reported that the vote was postponed.
root mood Ind - 4
Reportedly, the new figures could arrive next week.
- 5
Agencies such as the treasury and the audit office publish quarterly reports.
root mood Ind
show the data
| # | Primitive | Read from | Attaches to | Field and detail |
|---|---|---|---|---|
| 1 | negation | 4not | 5approve | negations |
| 1 | root adverbial | 4not | none | root_adverbials |
| 1 | root mood | 5approve | none | root_mood, mood Ind |
| 2 | modal | 2must | 3submit | modals |
| 3 | clausal complement | 3reported | 8postponed | clausal_complements, subject 2 chair |
| 3 | root mood | 3reported | none | root_mood, mood Ind |
| 4 | modal | 6could | 7arrive | modals |
| 4 | root adverbial | 1Reportedly | none | root_adverbials |
| 5 | Hearst pair | 5treasury | 1Agencies | hearst_pairs, such_as, hyponym span 4 to 5 |
| 5 | Hearst pair | 9office | 1Agencies | hearst_pairs, such_as, hyponym span 7 to 9 |
| 5 | root mood | 10publish | none | root_mood, mood Ind |
- negation
- modal
- clausal complement
- root adverbial
- Hearst pair
- root mood
Each primitive is a field matra fills on Sentence from its dependency tree: the tinted
word is the one it is read from, the underlined word the one it attaches to. The root mood is read
off the whole root clause: the Mood feature on the root or its auxiliary. What any of
it means for a text is the reader's call; matra reports the construction.
Input: Five sentences, one structural primitive each: a negation, a modal, a reporting, a root adverbial, a Hearst pair, matra contributors. MIT, as part of the matra repository.
Produced by matra 0.3.0 with the UDPipe model english-ewt-ud-2.5-191206
(SHA-256 784bd0fa85e3). Data: primitives/primitives.json.
This page, measured by matra 0.3.0 with english-ewt-ud-2.5-191206: 13 paragraphs, in the margin. the data