# Analyses and context

The stored word-by-word analyses and context notes: what they hold, when they exist, and why the API never makes new ones.

Canonical: https://interlinea.aeterna-institute.org/docs/analyses

Interlinea's reader explains every word of a text. The API and the MCP server give you those explanations once they are stored. They never call a language model, so they cost nothing and answer the same way every time.

## When an analysis exists

- Every graded passage is analysed in full.
- A library section is analysed the first time a reader opens it in Interlinea. From then on everyone gets the stored analysis, here and in the reader.
- A sentence with no stored analysis comes back with `translation: null` and `words: null`. `analysed` and `total` say how much of a text is covered.

To have a section analysed, open its `url` in Interlinea.

## What a word carries

Each word follows the Universal Dependencies conventions for parts of speech, features and relations:

| Field | Type | Description |
|---|---|---|
| `i` | integer | 1-based index of the word in its sentence. |
| `form` | string | The word as printed. |
| `lemma` | string | Dictionary headword; Latin with macrons, Greek polytonic. |
| `entry` | string or null | Dictionary entry: principal parts, or genitive and gender. |
| `upos` | string | Universal Dependencies part of speech. |
| `feats` | string | Universal Dependencies features, e.g. "Case=Acc\|Gender=Neut\|Number=Plur"; "_" if none. |
| `head` | integer | Index of the word this one depends on; 0 for the root. |
| `deprel` | string | Universal Dependencies relation to its head: nsubj, obj, amod, … |
| `gloss` | string | Meaning in this sentence, 1 to 4 words. |
| `note` | string or null | One sentence on the word's role. |
| `enclitic` | object | Optional. Present only when an enclitic rides on the word, e.g. -que "and". |
| `enclitic.form` | string |  |
| `enclitic.gloss` | string |  |

A language model makes the analyses, and rules check them: each word analysed exactly once, one root per sentence, no loops, and grammar labels valid for the language. They can still be wrong, especially in Greek. Treat them as a careful reading, not an answer key.

## Context notes

Context notes say where a text sits in its work: what has happened so far, what happens here (never a translation), the people, gods and places named, what comes next, and a few lines on the work.

| Field | Type | Description |
|---|---|---|
| `machineWritten` | boolean | False for the graded passages' hand-written notes. |
| `section` | object or null | Null until someone has opened Context for this part in the reader. |
| `section.soFar` | string or null | What has happened in the work before this part. |
| `section.here` | string or null | What happens in this part, never a translation. |
| `section.people` | array of object | People, gods and places named here. |
| `section.people[].name` | string |  |
| `section.people[].note` | string |  |
| `section.people[].forms` | array of string | The words in the text that name them. |
| `section.people[].wikipedia` | string or null | English Wikipedia article title, when certain. |
| `section.next` | string or null | What comes next. |
| `work` | object or null | A few lines about the work. |
| `work.intro` | string or null |  |
| `work.note` | string or null |  |

- Graded passages have hand-written, checked notes, with `machineWritten` false.
- A library section's notes are written by a model the first time a reader opens Context in Interlinea, then stored, with `machineWritten` true. Until then `section` is null.

## Getting them

- `include=analysis,context` on a text endpoint adds both to the text. Over MCP, pass `include: ["analysis", "context"]` to `get_text`.
- [`/api/v1/analysis`](https://interlinea.aeterna-institute.org/docs/api/analysis.md) and [`get_analysis`](https://interlinea.aeterna-institute.org/docs/mcp/get_analysis.md) return the analysis on its own; `sentence` picks one sentence, counting from 0.
- [`/api/v1/context`](https://interlinea.aeterna-institute.org/docs/api/context.md) and [`get_context`](https://interlinea.aeterna-institute.org/docs/mcp/get_context.md) return the notes on their own.
- [`/api/v1/words`](https://interlinea.aeterna-institute.org/docs/api/words.md) and [`lookup_word`](https://interlinea.aeterna-institute.org/docs/mcp/lookup_word.md) find a headword across every stored analysis, with cited sentences.

`include` is opt-in because analyses are large: a graded passage with its analysis is about 22 KB of JSON, against about 3 KB for its text.

---

Previous: [Editions and licences](https://interlinea.aeterna-institute.org/docs/licences.md)
Next: [Caching, limits and errors](https://interlinea.aeterna-institute.org/docs/limits.md)