Kristian Rickert created OPENNLP-1919:
-----------------------------------------
Summary: Expose dependency parses as a typed Document annotation
layer
Key: OPENNLP-1919
URL: https://issues.apache.org/jira/browse/OPENNLP-1919
Project: OpenNLP
Issue Type: Improvement
Components: language model
Reporter: Kristian Rickert
Assignee: Kristian Rickert
h3. Background
OPENNLP-547 introduces a native dependency-parser API and implementations that
return a {{DependencyGraph}} for one tokenized and POS-tagged sentence.
OPENNLP-1888 introduces the immutable, offset-anchored {{Document}} container
and typed annotation layers. Dependency parsing should integrate with that
pipeline without creating a second document representation or embedding
parser-specific objects into unrelated layers.
h3. Proposed work
Add a {{DependencyAnnotator}} that adapts any {{DependencyParser}} to the
document-shape API.
* Require the standard sentence, token, and POS-tag layers.
* Parse each sentence independently through the supplied {{DependencyParser}}.
* Add a typed {{dependencies}} layer containing one {{DependencyArc}}
annotation per token.
* Anchor each arc on its dependent token's original-document span.
* Store head and dependent references as indexes into the document-wide token
layer.
* Preserve the parser's root sentinel for root arcs.
* Shift sentence-local parser indexes into document-wide token indexes.
* Preserve every existing document layer and return a new immutable document.
* Declare required and provided layers through the {{DocumentAnnotator}}
contract.
* Validate token and POS-layer alignment, sentence containment, graph
cardinality, ordering, and parser output.
* Document the dependency layer and provide a mirror-tested pipeline example.
This issue depends on OPENNLP-547 and OPENNLP-1888. The gRPC representation
and frontend projection remain part of OPENNLP-1833 rather than this core
OpenNLP change.
h3. Acceptance criteria
* The annotator accepts any implementation of {{DependencyParser}}.
* Each input token produces exactly one dependency annotation.
* Every dependency annotation uses the dependent token's original-document
span.
* Non-root head and dependent indexes reference valid entries in the document
token layer.
* Sentence-local indexes are correctly shifted when a document contains
multiple sentences.
* Empty but present input layers produce an empty but present dependency
layer.
* Missing required layers fail with messages identifying the absent layer.
* Misaligned POS tags, tokens outside sentence spans, overlapping sentence
boundaries, invalid graph sizes, and invalid dependency indexes fail before an
invalid document is returned.
* Tests cover multiple sentences, roots, punctuation, Unicode spans, empty
documents, malformed parser output, immutable layer preservation, and pipeline
composition.
* The manual documents the layer contract and cites a test that verifies the
published example.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
