# matra

matra parses English text into sections, paragraphs, sentences and words, and returns measures, summaries and keyphrases over them, from Rust, Python or the command line.

## Quick start

Install matra, save one sentence, and run matra on it.

Rust:

Install:

```bash
cargo new quickstart && cd quickstart
cargo add matra@0.3 serde_json
```

Save the text:

```bash
echo 'The committee approved the budget on Tuesday.' > note.txt
```

Save the program below as `src/main.rs` and run it with `cargo run`:

```rust
// cargo add matra@0.3 serde_json
use matra::{Engine, Input};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Loads the English model, downloading it on first use.
    let engine = Engine::new()?;
    let doc = engine.analyze(Input::file("note.txt"))?;
    println!("{}", serde_json::to_string_pretty(&doc)?);
    Ok(())
}
```

Python:

Install:

```bash
pip install 'matra>=0.3'
```

Save the text:

```bash
echo 'The committee approved the budget on Tuesday.' > note.txt
```

Save the program below as `quickstart.py` and run it with `python quickstart.py`:

```python
# pip install 'matra>=0.3'
import json

import matra

engine = matra.Engine()  # downloads the English model on first use
doc = engine.analyze(file="note.txt")  # a str alone would be text, not a path
print(json.dumps(doc.to_dict(), indent=2, ensure_ascii=False))
```

The command line:

Install:

```bash
pip install 'matra>=0.3'   # or: cargo install matra --version '^0.3' --features cli
```

Save the text:

```bash
echo 'The committee approved the budget on Tuesday.' > note.txt
```

```bash
matra analyze --json note.txt
```
It prints JSON; here is the first word:

```jsonc
[
  {
    "id": 1,
    "span": {
      "byte_start": 0,
      "byte_end": 3
    },
    "text": "The",
    "lemma": "the",
    "pos": "DET",
    "xpos": "DT",
    "features": {
      "Definite": "Def",
      "PronType": "Art"
    },
    "head": 2,
    "dep": "det",
    "deps": "_",
    "misc": "",
    "is_punct": false
  }
  // … 7 more
]
```

The whole output: https://mox-labs.github.io/matra/example-files/quickstart/output.json, and what the CLI prints: https://mox-labs.github.io/matra/example-files/quickstart/cli.json.
Every word, drawn. Each arc runs from a word to the word that depends on it:

<figure-parse input="quickstart" />

## Where to go next

- **[Tutorial](tutorials/first-analysis.md):** run matra on two short paragraphs and find each part of what it returns. About ten minutes.
- **[How-to guides](examples/README.md):** one task each on real texts: summarize a document, extract keyphrases, find negations and modals, compare readability, cluster sentences by meaning.
- **[Explanation](explanation/concepts.md):** why the output has the shape it has, with figures you can step through.
- **[Reference](capabilities.md):** every type and field, the Rust, Python and command-line surfaces, the methods behind each measure, and every error.
