OPENNLP-1919: Expose dependency parses as a typed Document annotation layer

opennlp-api/src/main/java/opennlp/tools/depparse/DependencyArc.java

@@ -0,0 +1,65 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package opennlp.tools.depparse;
+
+import opennlp.tools.util.StringUtil;
+
+/**
+ * One labeled edge of a {@link DependencyGraph}: the token at {@code dependent} is governed
+ * by the token at {@code head} under the given {@code relation}.
+ *
+ * <p>Indices are zero-based positions in the token array the graph was built over. A
+ * {@code head} of {@link #ROOT_HEAD} marks the dependent as the sentence root, which is
+ * attached to the artificial root node rather than to another token.</p>
+ *
+ * @param head The zero-based index of the governing token, or {@link #ROOT_HEAD} when the
+ *             dependent is the sentence root.
+ * @param dependent The zero-based index of the governed token.
+ * @param relation The dependency relation label, for example {@code nsubj}.
+ *
+ * @since 3.0.0
+ */
+public record DependencyArc(int head, int dependent, String relation) {
+
+  /**
+   * The {@code head} value marking an arc from the artificial root node.
+   */
+  public static final int ROOT_HEAD = -1;
+
+  /**
+   * Validates the arc invariants.
+   *
+   * @throws IllegalArgumentException Thrown if {@code dependent} is negative, {@code head}
+   *         is less than {@link #ROOT_HEAD}, the arc is a self-loop, or {@code relation}
+   *         is {@code null} or blank.
+   */
+  public DependencyArc {
+    if (dependent < 0) {
+      throw new IllegalArgumentException("dependent must not be negative: " + dependent);
+    }
+    if (head < ROOT_HEAD) {
+      throw new IllegalArgumentException("head must be a token index or ROOT_HEAD: " + head);
+    }
+    if (head == dependent) {
+      throw new IllegalArgumentException("arc must not be a self-loop: " + head);
+    }
+    if (relation == null || StringUtil.isBlank(relation)) {
+      throw new IllegalArgumentException("relation must not be null or blank");
+    }
+  }
+}

opennlp-api/src/main/java/opennlp/tools/depparse/DependencyGraph.java

@@ -0,0 +1,190 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package opennlp.tools.depparse;
+
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.List;
+
+import opennlp.tools.util.StringUtil;
+
+/**
+ * An immutable dependency tree over one sentence: for every token, the index of its head
+ * and the label of the relation to that head.
+ *
+ * <p>Token indices are zero-based positions in the sentence the graph was built for.
+ * Exactly one token carries the head value {@link DependencyArc#ROOT_HEAD}, marking it as
+ * the sentence root. Instances are immutable and safe to share between threads.</p>
+ *
+ * @since 3.0.0
+ */
+public final class DependencyGraph {
+
+  private final int[] heads;
+  private final String[] relations;
+
+  /**
+   * Wraps already validated arrays; instances are created through {@link #of}.
+   */
+  private DependencyGraph(int[] heads, String[] relations) {
+    this.heads = heads;
+    this.relations = relations;
+  }
+
+  /**
+   * Creates a {@link DependencyGraph} from parallel head and relation arrays.
+   *
+   * @param heads For each token, the zero-based index of its head token, or
+   *              {@link DependencyArc#ROOT_HEAD} for the sentence root. Must not be
+   *              {@code null} or empty, every value must be a valid token index or
+   *              {@link DependencyArc#ROOT_HEAD}, no token may head itself, and exactly
+   *              one token must be the root.
+   * @param relations For each token, the label of the relation to its head. Must not be
+   *                  {@code null}, must have the same length as {@code heads}, and no
+   *                  entry may be {@code null} or blank.
+   * @return A validated {@link DependencyGraph}. Never {@code null}.
+   * @throws IllegalArgumentException Thrown if any of the above constraints is violated.
+   */
+  public static DependencyGraph of(int[] heads, String[] relations) {
+    if (heads == null || relations == null) {
+      throw new IllegalArgumentException("heads and relations must not be null");
+    }
+    if (heads.length == 0) {
+      throw new IllegalArgumentException("a dependency graph needs at least one token");
+    }
+    if (heads.length != relations.length) {
+      throw new IllegalArgumentException("heads and relations must have the same length: "
+          + heads.length + " != " + relations.length);
+    }
+    int roots = 0;
+    for (int i = 0; i < heads.length; i++) {
+      if (heads[i] == DependencyArc.ROOT_HEAD) {
+        roots++;
+      } else if (heads[i] < 0 || heads[i] >= heads.length) {
+        throw new IllegalArgumentException("head of token " + i
+            + " is out of range: " + heads[i]);
+      } else if (heads[i] == i) {
+        throw new IllegalArgumentException("token " + i + " must not head itself");
+      }
+      if (relations[i] == null || StringUtil.isBlank(relations[i])) {
+        throw new IllegalArgumentException("relation of token " + i + " must not be blank");
+      }
+    }
+    if (roots != 1) {
+      throw new IllegalArgumentException("expected exactly one root, found " + roots);
+    }
+    return new DependencyGraph(heads.clone(), relations.clone());
+  }
+
+  /**
+   * @return The number of tokens the graph spans.
+   */
+  public int size() {
+    return heads.length;
+  }
+
+  /**
+   * Retrieves the head of a token.
+   *
+   * @param index The zero-based token index. Must be within {@code [0, size())}.
+   * @return The zero-based index of the head token, or {@link DependencyArc#ROOT_HEAD}
+   *         when the token is the sentence root.
+   * @throws IllegalArgumentException Thrown if {@code index} is out of range.
+   */
+  public int headOf(int index) {
+    checkIndex(index);
+    return heads[index];
+  }
+
+  /**
+   * Retrieves the relation label of a token.
+   *
+   * @param index The zero-based token index. Must be within {@code [0, size())}.
+   * @return The label of the relation between the token and its head. Never {@code null}.
+   * @throws IllegalArgumentException Thrown if {@code index} is out of range.
+   */
+  public String relationOf(int index) {
+    checkIndex(index);
+    return relations[index];
+  }
+
+  /**
+   * @return The zero-based index of the sentence root token.
+   */
+  public int root() {
+    for (int i = 0; i < heads.length; i++) {
+      if (heads[i] == DependencyArc.ROOT_HEAD) {
+        return i;
+      }
+    }
+    throw new IllegalStateException("graph invariant violated: no root present");
+  }
+
+  /**
+   * @return All arcs of the graph in token order, one per token. Never {@code null}.
+   */
+  public List<DependencyArc> arcs() {
+    final List<DependencyArc> arcs = new ArrayList<>(heads.length);
+    for (int i = 0; i < heads.length; i++) {
+      arcs.add(new DependencyArc(heads[i], i, relations[i]));
+    }
+    return Collections.unmodifiableList(arcs);
+  }
+
+  /**
+   * Rejects a token index outside {@code [0, size())}.
+   *
+   * @param index The zero-based token index to check.
+   * @throws IllegalArgumentException Thrown if {@code index} is out of range.
+   */
+  private void checkIndex(int index) {
+    if (index < 0 || index >= heads.length) {
+      throw new IllegalArgumentException("token index out of range: " + index
+          + ", size: " + heads.length);
+    }
+  }
+
+  @Override
+  public boolean equals(Object obj) {
+    if (this == obj) {
+      return true;
+    }
+    if (!(obj instanceof DependencyGraph other)) {
+      return false;
+    }
+    return Arrays.equals(heads, other.heads) && Arrays.equals(relations, other.relations);
+  }
+
+  @Override
+  public int hashCode() {
+    return 31 * Arrays.hashCode(heads) + Arrays.hashCode(relations);
+  }
+
+  @Override
+  public String toString() {
+    final StringBuilder sb = new StringBuilder();
+    for (int i = 0; i < heads.length; i++) {
+      if (i > 0) {
+        sb.append(' ');
+      }
+      sb.append(i).append("<-").append(heads[i]).append(':').append(relations[i]);
+    }
+    return sb.toString();
+  }
+}

opennlp-api/src/main/java/opennlp/tools/depparse/DependencyParser.java

@@ -0,0 +1,49 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package opennlp.tools.depparse;
+
+/**
+ * The interface for dependency parsers, which assign every token of a sentence a syntactic
+ * head and a relation label, forming a single-rooted tree over the sentence.
+ *
+ * <p>Dependency parsing complements the constituency {@link opennlp.tools.parser.Parser}:
+ * where a constituency parse groups tokens into nested phrases, a dependency parse links
+ * each token directly to the token it modifies. The result is a {@link DependencyGraph}
+ * whose indices refer back to the input token array, so spans computed for those tokens
+ * remain valid for the parse.</p>
+ *
+ * <p>Thread safety is implementation specific.</p>
+ *
+ * @see DependencyGraph
+ * @since 3.0.0
+ */
+public interface DependencyParser {
+
+  /**
+   * Parses a sentence into a {@link DependencyGraph}.
+   *
+   * @param tokens The tokens of one sentence. Must not be {@code null} and must contain
+   *               at least one token.
+   * @param tags The part-of-speech tags aligned with {@code tokens}. Must not be
+   *             {@code null} and must have the same length as {@code tokens}.
+   * @return A {@link DependencyGraph} over the given tokens. Never {@code null}.
+   * @throws IllegalArgumentException Thrown if {@code tokens} or {@code tags} is
+   *         {@code null}, empty, or of mismatched length.
+   */
+  DependencyGraph parse(String[] tokens, String[] tags);
+}