[jira] [Created] (OPENNLP-1919) Expose dependency parses as a typed Document annotation layer

["Kristian Rickert (Jira)" <ji...@apache.org>]

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)