NLP Assistance¶

Interpreting an act frame means deciding which words are the action, which are the actor, the object, and the recipient. The Norm Editor can do a first pass of this automatically, using a machine-learning model trained on Dutch normative text.

What it does¶

The nlp-api service wraps a fine-tuned model configured for token classification. Given a piece of Dutch text, it labels each token as one of:

Model label	Meaning in the editor
`ACTION`	Action
`ACTOR`	Actor
`OBJECT`	Object
`RECIPIENT`	Recipient
`O`	Not part of an act frame

Choosing a model¶

Since 2026.09.1 the model is chosen per request rather than fixed at deploy time. nlp-api carries a registry of selectable models and the request names one:

Key	Model
`bertje_2022_e4`	A fine-tuned BERTje (a Dutch BERT) — the default
`legal-bert-dutch-english`	A legal-domain bilingual model

The Act frame form exposes these in an NLP model dropdown. An unknown key, or no key at all, falls back to the default, and the response echoes the model that was actually used — so a caller can always tell which one produced the labels rather than assuming its request was honoured.

Adding an entry to the registry is what exposes it in the editor; there is no separate list to keep in step. Model files are not part of the service image — nlp-api takes its model root from configuration, backed by an Azure storage account, so adding a model does not mean rebuilding the service. A resolved path that does not exist is reported as an error rather than surfacing a loader traceback.

Word-piece tokens (those continuing a previous word) are merged back into whole words, so the suggestions are returned as readable word/label pairs rather than sub-word fragments.

Scope of the model

The model is trained specifically to recognise the constituents of an Act frame in Dutch text. It does not predict claim-duty roles or fact subdivisions. The model and its training are described in the FlintFillers project.

How it fits the workflow¶

sequenceDiagram
    participant U as Interpreter
    participant E as Editor (web)
    participant N as nlp-api
    U->>E: Request suggestions for a sentence
    E->>N: POST /api/predict { text }
    N->>N: BERTje token classification
    N-->>E: predicted_entities [(word, label), ...]
    E-->>U: Highlight suggested actor / action / object / recipient
    U->>E: Accept, adjust, or ignore

The interpreter stays in control. The model's output is a suggestion: the editor surfaces the predicted entities so they can be turned into facts and slotted into an act's roles, but the interpreter is free to correct or discard them. When the editor creates an agent fact from a model suggestion, it records the model's recommended role as a comment on the fact, so the provenance of the suggestion is preserved.

Practical considerations¶

Language — the model expects Dutch text. Running it over text in another language will produce unreliable labels.
Length — transformer models have a maximum token limit. The service is intended to be used on selected sentences or fragments, not on an entire source document at once; very long inputs can exceed the model's limit.
Availability — NLP assistance is optional. The editor is fully usable without it; the feature simply removes the manual first step of identifying act constituents.

For the request and response shapes, see the API Endpoints reference. For how to run the service, see Backend & API services.