You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@opennlp.apache.org by kr...@apache.org on 2026/08/22 01:01:01 UTC

(opennlp) 07/15: relation: Match triggers through the project case mapping and reject triggers that could never match

This is an automated email from the ASF dual-hosted git repository.

krickert pushed a commit to branch OPENNLP-1920-relation-extraction
in repository https://gitbox.apache.org/repos/asf/opennlp.git

commit db0deb1b94484fcd30c4435dba6ecb8d50b2d558
Author: Kristian Rickert <kr...@gmail.com>
AuthorDate: Thu Jul 16 22:05:06 2026 -0400

    relation: Match triggers through the project case mapping and reject triggers that could never match
---
 .../opennlp/tools/relation/RelationAnnotator.java  |  4 +-
 .../opennlp/tools/relation/RelationPattern.java    | 26 ++++++---
 .../tools/relation/RelationAnnotatorTest.java      | 64 ++++++++++++++++++++++
 .../tools/relation/RelationPatternTest.java        | 54 ++++++++++++++++++
 4 files changed, 138 insertions(+), 10 deletions(-)

diff --git a/opennlp-core/opennlp-runtime/src/main/java/opennlp/tools/relation/RelationAnnotator.java b/opennlp-core/opennlp-runtime/src/main/java/opennlp/tools/relation/RelationAnnotator.java
index a7f89cc20..3e4afec4b 100644
--- a/opennlp-core/opennlp-runtime/src/main/java/opennlp/tools/relation/RelationAnnotator.java
+++ b/opennlp-core/opennlp-runtime/src/main/java/opennlp/tools/relation/RelationAnnotator.java
@@ -20,7 +20,6 @@ package opennlp.tools.relation;
 import java.util.ArrayList;
 import java.util.Collection;
 import java.util.List;
-import java.util.Locale;
 import java.util.Set;
 
 import opennlp.tools.depparse.DependencyAnnotator;
@@ -31,6 +30,7 @@ import opennlp.tools.document.DocumentAnnotator;
 import opennlp.tools.document.LayerKey;
 import opennlp.tools.document.Layers;
 import opennlp.tools.util.Span;
+import opennlp.tools.util.StringUtil;
 
 /**
  * Extracts typed relations between entity pairs by matching {@link RelationPattern}
@@ -189,7 +189,7 @@ public class RelationAnnotator implements DocumentAnnotator {
       steps.add(">" + relations[objectChain.get(o)]);
     }
     final int pivot = subjectChain.get(pivotOnSubject);
-    final String pivotForm = tokens.get(pivot).value().toLowerCase(Locale.ROOT);
+    final String pivotForm = StringUtil.toLowerCase(tokens.get(pivot).value());
 
     for (int p = 0; p < patterns.size(); p++) {
       final RelationPattern pattern = patterns.get(p);
diff --git a/opennlp-core/opennlp-runtime/src/main/java/opennlp/tools/relation/RelationPattern.java b/opennlp-core/opennlp-runtime/src/main/java/opennlp/tools/relation/RelationPattern.java
index b6b88c990..6e202c011 100644
--- a/opennlp-core/opennlp-runtime/src/main/java/opennlp/tools/relation/RelationPattern.java
+++ b/opennlp-core/opennlp-runtime/src/main/java/opennlp/tools/relation/RelationPattern.java
@@ -37,14 +37,18 @@ import opennlp.tools.util.StringUtil;
  * {@code >nmod} matches an object directly attached below the subject.</p>
  *
  * <p>The optional trigger constrains the pivot token, the highest token on the path: the
- * pattern matches only when the pivot's lowercased form equals the trigger. Without a
- * trigger the path shape alone decides.</p>
+ * pattern matches only when the pivot's form, lowercased with
+ * {@link StringUtil#toLowerCase(CharSequence)}, equals the trigger. Without a trigger the
+ * path shape alone decides. The trigger must already be lowercased under that same
+ * mapping and is rejected otherwise, because a trigger the mapping would change can never
+ * equal any pivot form and the pattern would silently match nothing. The trigger is never
+ * rewritten, so {@code founded} is a valid trigger while {@code Founded} is rejected.</p>
  *
  * @param type The relation type to emit. Must not be {@code null} or blank.
  * @param path The path shape as described above. Must not be {@code null} or blank, and
  *             every up step must come before the first down step.
- * @param trigger The required lowercased pivot form, or {@code null} for any pivot. Must
- *                not be blank.
+ * @param trigger The required pivot form, or {@code null} for any pivot. Must not be
+ *                blank, and must be unchanged by {@link StringUtil#toLowerCase(CharSequence)}.
  *
  * @since 3.0.0
  */
@@ -54,8 +58,9 @@ public record RelationPattern(String type, String path, String trigger) {
    * Validates the rule.
    *
    * @throws IllegalArgumentException Thrown if {@code type} or {@code path} is
-   *         {@code null} or blank, {@code path} is malformed, or {@code trigger} is
-   *         blank.
+   *         {@code null} or blank, {@code path} is malformed, or {@code trigger} is blank
+   *         or not already lowercased under
+   *         {@link StringUtil#toLowerCase(CharSequence)}.
    */
   public RelationPattern {
     if (type == null || type.isBlank()) {
@@ -64,8 +69,13 @@ public record RelationPattern(String type, String path, String trigger) {
     if (path == null || path.isBlank()) {
       throw new IllegalArgumentException("path must not be null or blank");
     }
-    if (trigger != null && trigger.isBlank()) {
-      throw new IllegalArgumentException("trigger must not be blank");
+    if (trigger != null) {
+      if (trigger.isBlank()) {
+        throw new IllegalArgumentException("trigger must not be blank");
+      }
+      if (!StringUtil.toLowerCase(trigger).equals(trigger)) {
+        throw new IllegalArgumentException("trigger must be lowercased, but was: " + trigger);
+      }
     }
     boolean down = false;
     for (final String step : splitSteps(path)) {
diff --git a/opennlp-core/opennlp-runtime/src/test/java/opennlp/tools/relation/RelationAnnotatorTest.java b/opennlp-core/opennlp-runtime/src/test/java/opennlp/tools/relation/RelationAnnotatorTest.java
index 712c358e9..374201638 100644
--- a/opennlp-core/opennlp-runtime/src/test/java/opennlp/tools/relation/RelationAnnotatorTest.java
+++ b/opennlp-core/opennlp-runtime/src/test/java/opennlp/tools/relation/RelationAnnotatorTest.java
@@ -38,6 +38,9 @@ import opennlp.tools.util.Span;
  */
 public class RelationAnnotatorTest {
 
+  /** {@code Istanbul} with the Turkish capital I with dot above, U+0130, as its initial. */
+  private static final String DOTTED_CAPITAL_ISTANBUL = "\u0130stanbul";
+
   /**
    * Builds the parsed document "Acme Corp acquired Bolt in 2024." with entities for
    * Acme Corp (index 0), Bolt (index 1), and 2024 (index 2). The dependency layer marks
@@ -302,6 +305,67 @@ public class RelationAnnotatorTest {
     Assertions.assertEquals("patterns must not contain null", e.getMessage());
   }
 
+  /**
+   * Builds the parsed document "Istanbul, home of Bolt." whose first token is written
+   * with the Turkish capital I with dot above (U+0130), with entities for that city
+   * (index 0) and Bolt (index 1). The city is the sentence root, {@code home} is its
+   * apposition, and {@code Bolt} is an {@code nmod} of {@code home}, so the path from the
+   * city down to Bolt is {@code >appos >nmod} and the city itself is the pivot.
+   *
+   * @return A document with aligned token, entity, and dependency layers. Never
+   *         {@code null}.
+   */
+  private static Document dottedCapitalPivotDocument() {
+    final String text = "\u0130stanbul, home of Bolt.";
+    final List<Annotation<String>> tokens = List.of(
+        new Annotation<>(new Span(0, 8), DOTTED_CAPITAL_ISTANBUL),
+        new Annotation<>(new Span(8, 9), ","),
+        new Annotation<>(new Span(10, 14), "home"),
+        new Annotation<>(new Span(15, 17), "of"),
+        new Annotation<>(new Span(18, 22), "Bolt"),
+        new Annotation<>(new Span(22, 23), "."));
+    final List<DependencyArc> arcs = List.of(
+        new DependencyArc(DependencyArc.ROOT_HEAD, 0, "root"),
+        new DependencyArc(2, 1, "punct"),
+        new DependencyArc(0, 2, "appos"),
+        new DependencyArc(4, 3, "case"),
+        new DependencyArc(2, 4, "nmod"),
+        new DependencyArc(0, 5, "punct"));
+    final List<Annotation<DependencyArc>> dependencies = new ArrayList<>();
+    for (final DependencyArc arc : arcs) {
+      dependencies.add(new Annotation<>(tokens.get(arc.dependent()).span(), arc));
+    }
+    return Document.of(text)
+        .with(Layers.TOKENS, tokens)
+        .with(Layers.ENTITIES, List.of(
+            new Annotation<>(new Span(0, 8), "location"),
+            new Annotation<>(new Span(18, 22), "organization")))
+        .with(DependencyAnnotator.DEPENDENCIES, dependencies);
+  }
+
+  /**
+   * Verifies that the pivot form is lowercased with the project's case mapping: the pivot
+   * token written with the Turkish capital I with dot above (U+0130) lowercases per code
+   * point to {@code istanbul}, so a pattern carrying that trigger matches. The JDK's
+   * locale-independent lowercasing instead expands U+0130 to an i followed by U+0307, a
+   * form no constructible trigger can equal, which would silently drop the relation.
+   */
+  @Test
+  void testPivotFormUsesTheProjectCaseMapping() {
+    final RelationAnnotator annotator = new RelationAnnotator(List.of(
+        new RelationPattern("located_in", ">appos >nmod", "istanbul")));
+
+    final Document document = annotator.annotate(dottedCapitalPivotDocument());
+
+    final List<Annotation<RelationMention>> relations =
+        document.get(RelationAnnotator.RELATIONS);
+    Assertions.assertEquals(1, relations.size());
+    Assertions.assertEquals(new RelationMention("located_in", 0, 1),
+        relations.get(0).value());
+    Assertions.assertEquals(DOTTED_CAPITAL_ISTANBUL + ", home of Bolt", document.text().subSequence(
+        relations.get(0).span().getStart(), relations.get(0).span().getEnd()).toString());
+  }
+
   /**
    * Verifies that annotating a document that already carries a relations layer fails:
    * documents reject duplicate layers, so the second annotation pass throws.
diff --git a/opennlp-core/opennlp-runtime/src/test/java/opennlp/tools/relation/RelationPatternTest.java b/opennlp-core/opennlp-runtime/src/test/java/opennlp/tools/relation/RelationPatternTest.java
index bd34f7980..07291edec 100644
--- a/opennlp-core/opennlp-runtime/src/test/java/opennlp/tools/relation/RelationPatternTest.java
+++ b/opennlp-core/opennlp-runtime/src/test/java/opennlp/tools/relation/RelationPatternTest.java
@@ -38,6 +38,15 @@ public class RelationPatternTest {
   private static final char FILE_SEPARATOR = (char) 0x001C;
   private static final char UNIT_SEPARATOR = (char) 0x001F;
 
+  /** {@code Istanbul} with the Turkish capital I with dot above, U+0130, as its initial. */
+  private static final String DOTTED_CAPITAL_ISTANBUL = "\u0130stanbul";
+
+  /** {@code Istanbul} as the JDK lowercases U+0130: an i plus U+0307 combining dot above. */
+  private static final String JDK_LOWERCASED_ISTANBUL = "i\u0307stanbul";
+
+  /** The German {@code Strasse} spelled with U+00DF, the small sharp s. */
+  private static final String SHARP_S_STRASSE = "stra\u00DFe";
+
   /**
    * Verifies splitting on ASCII blanks and tabs, including runs of separators at the
    * start and end of the path, which never produce empty steps.
@@ -156,6 +165,51 @@ public class RelationPatternTest {
         new RelationPattern("t", "\u00A0<nsubj\u00A0>obj\u00A0", null).steps());
   }
 
+  /**
+   * Verifies that a trigger which is not already lowercased is rejected at construction
+   * with a message naming the offending trigger. Such a trigger could never equal the
+   * lowercased pivot form the annotator compares it against, so the pattern would match
+   * nothing without any error; the check turns that silent dead rule into a failure at
+   * the boundary where the user can fix it.
+   */
+  @Test
+  void testNonLowercasedTriggerFailsLoudWithExactMessage() {
+    final IllegalArgumentException e = Assertions.assertThrows(
+        IllegalArgumentException.class,
+        () -> new RelationPattern("t", "<nsubj >obj", "Founded"));
+    Assertions.assertEquals("trigger must be lowercased, but was: Founded", e.getMessage());
+    Assertions.assertEquals("founded",
+        new RelationPattern("t", "<nsubj >obj", "founded").trigger());
+  }
+
+  /**
+   * Verifies that the trigger check follows {@link StringUtil#toLowerCase(CharSequence)},
+   * the same mapping {@link RelationAnnotator} applies to the pivot form: a trigger is
+   * accepted exactly when that mapping leaves it unchanged. The expectation is derived
+   * from the mapping itself rather than pinned per character, so this test asserts the
+   * contract that construction accepts exactly the forms a pivot can lowercase to, and it
+   * stays correct when the mapping's character set changes. The candidates include
+   * {@code Istanbul} written with the Turkish capital I with dot above (U+0130), whose
+   * JDK lowercasing expands beyond the per code point mapping, and the German sharp s,
+   * which is already lowercase while its uppercase form expands.
+   */
+  @Test
+  void testTriggerCheckFollowsTheProjectCaseMapping() {
+    for (final String candidate : new String[] {"founded", "Founded",
+        DOTTED_CAPITAL_ISTANBUL, "istanbul", JDK_LOWERCASED_ISTANBUL, "STRASSE",
+        SHARP_S_STRASSE}) {
+      final String message = "trigger acceptance for " + candidate
+          + " must follow StringUtil.toLowerCase";
+      if (StringUtil.toLowerCase(candidate).equals(candidate)) {
+        Assertions.assertEquals(candidate,
+            new RelationPattern("t", "<nsubj", candidate).trigger(), message);
+      } else {
+        Assertions.assertThrows(IllegalArgumentException.class,
+            () -> new RelationPattern("t", "<nsubj", candidate), message);
+      }
+    }
+  }
+
   /**
    * Documents the boundary between the blank guard and the whitespace scan: the blank
    * check only recognizes the whitespace characters the JDK does, while the step scan