Situation model

on this page

What matra is for

grade7.0density0.52compressionnone

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.

grade5.1density0.35compressionnone

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

grade4.1density0.47compressionnone

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.

gradenonedensity0.67compressionnone

That split runs through every tier:

matra reportsYour code decides
a sentence carries nsubj:passwhether the missing agent matters here
clausal_complements names a verb governing a ccompwhether that verb is evidential and whether the source is credible
hearst_pairs names a construction that conventionally signals hypernymywhether the hypernymy relation actually holds
modals names must on an aux arcwhether that must is obligation or inference
a Cluster groups sentences whose vectors cleared your thresholdwhether those sentences say the same thing
grade4.8density0.43compressionnone

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

gradenonedensity0.67compressionnone

Upstream of interpretation, downstream of ingestion.

files or strings  ->  matra  ->  rule evaluation
                                 scoring and dashboards
                                 retrieval and chunking
                                 LLM prompt construction
grade12.8density0.53compression0.57

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

grade9.4density0.58compression0.57

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.

grade11.9density0.58compression0.53

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.

grade7.8density0.50compression0.63

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.

grade5.8density0.56compressionnone

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.

grade10.4density0.54compressionnone

Those pinned model fetches are the only network access anywhere in the library.

The split, on five sentences

grade8.3density0.53compressionnone

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. 1

    The committee did not¬ negation · √ root adverbial approve¬ negated the budget.

    root mood Ind
  2. 2

    Members must◇ modal submit◇ governs revised estimates by Friday.

  3. 3

    The chair“ subject reported“ governs a clause that the vote was postponed“ complement.

    root mood Ind
  4. 4

    Reportedly√ root adverbial, the new figures could◇ modal arrive◇ governs next week.

  5. 5

    Agencies⊂ hypernym such as the treasury⊂ hyponym and the audit office⊂ hyponym publish quarterly reports.

    root mood Ind
show the data
#PrimitiveRead fromAttaches toField and detail
1negation4not5approvenegations
1root adverbial4notnoneroot_adverbials
1root mood5approvenoneroot_mood, mood Ind
2modal2must3submitmodals
3clausal complement3reported8postponedclausal_complements, subject 2 chair
3root mood3reportednoneroot_mood, mood Ind
4modal6could7arrivemodals
4root adverbial1Reportedlynoneroot_adverbials
5Hearst pair5treasury1Agencieshearst_pairs, such_as, hyponym span 4 to 5
5Hearst pair9office1Agencieshearst_pairs, such_as, hyponym span 7 to 9
5root mood10publishnoneroot_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