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