arango-query-core 0.2.8__tar.gz → 0.2.9__tar.gz

{arango_query_core-0.2.8 → arango_query_core-0.2.9}/CHANGELOG.md

@@ -6,6 +6,24 @@ exact versions (contextual-data-fabric CC-9) and re-run their golden /
 eval suites on every bump — pre-1.0, **minor** bumps may break the API
 and this file must say so explicitly.
 
+## [0.2.9] - 2026-11-12
+
+### Fixed
+
+- **Grounding finds a name told apart by a short token.** The scorer shared by
+  `LabelIndex` and `PredicateIndex` dropped every token under three
+  characters, so "HP Inc.", "GE Co.", "3M Co.", "AT&T Inc." or the "31" of
+  "Account Name 31" among "Account Name 1" to "200" was never retrieved, even
+  when the question gave the exact stored name. A token under three characters
+  now counts when the question holds it as a whole word, never as a substring
+  ("GE" is not found in "manager"). Before short words are read, possessive and
+  contraction endings are removed ("Media's", "don't"), accented words stay
+  whole ("Société" yields no "t"), a repeated short token counts once ("J&J"),
+  and one- and two-letter English words ("of", "at", "ok") are not counted.
+  Tokens of three or more characters match exactly as before. Retrieval can
+  only gain results; an item that matched before keeps its long-token hits, so
+  its rank changes only against items that now also match a short token.
+
 ## [0.2.7] - 2026-11-06
 
 ### Added

{arango_query_core-0.2.8 → arango_query_core-0.2.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: arango-query-core
-Version: 0.2.8
+Version: 0.2.9
 Summary: Shared conceptual-model and NL substrate for ArangoDB query transpilers (arango-cypher-py, arango-sparql-py)
 Project-URL: Repository, https://github.com/ArthurKeen/arango-query-core
 Project-URL: Changelog, https://github.com/ArthurKeen/arango-query-core/blob/main/CHANGELOG.md

{arango_query_core-0.2.8 → arango_query_core-0.2.9}/arango_query_core/nl/grounding.py

@@ -54,6 +54,29 @@ _STOP = frozenset(
     "please list show find get".split()
 )
 
+#: A token shorter than this matches only as a whole word of the other side,
+#: never as a substring: "ge" is inside "manager", but "GE" names a company.
+_SHORT = 3
+
+#: One- and two-letter English words a label can carry ("Bank of America")
+#: that would otherwise tie every question that uses them. Applied only to
+#: short tokens; longer stop words are in :data:`_STOP`.
+_SHORT_STOP = _STOP | frozenset("am as at be go he if it me ok pm so up us vs we".split())
+
+#: An English possessive or contraction ending: "Media's", "don't", "we'll".
+_CLITIC = re.compile(r"['’](?:s|t|d|m|ll|re|ve)\b")
+
+
+def _short_words(text: str) -> set[str]:
+    """The whole words of ``text`` under :data:`_SHORT` characters, as a short
+    token may match them: possessive and contraction endings removed first
+    (no "s" from "Media's", no "t" from "don't"), and words split on any
+    non-letter, accented letters included, so "Société" stays one word and
+    yields no "t" or "g". A set, so a label repeating one ("J&J") counts it once."""
+    words = re.findall(r"[^\W_]+", _CLITIC.sub("", text.lower()))
+    return {w for w in words if len(w) < _SHORT and w not in _SHORT_STOP}
+
+
 # C0 control chars (0x00-0x1F) + DEL (0x7F), including \n and \r — a
 # maliciously-labeled instance (e.g. rdfs:label containing "\nignore
 # previous instructions") must render on a single bullet line and
@@ -103,7 +126,10 @@ def _token_substring_retrieve(
     dump: bool = False,
 ) -> list[_T]:
     """Top-k items whose ``get_labels(item)`` tokens appear (as
-    substrings) in the question, or vice versa.
+    substrings) in the question, or vice versa. A token of three or more
+    characters matches as a substring; a shorter one ("HP", "3M", "31")
+    only as a whole word of the question (:func:`_short_words`), since as a
+    substring "ge" would be found in "manager".
 
     Both-direction substring matching survives plural/inflection
     mismatches (e.g. "Transistors" in the question vs. a "Transistor"
@@ -128,15 +154,19 @@ def _token_substring_retrieve(
     old ``if hits:`` guard dropped it before ``k`` was ever applied).
     """
     ql = question.lower()
-    q_tokens = {t for t in re.findall(r"[a-z0-9]+", ql) if len(t) >= 3 and t not in _STOP}
+    q_tokens = {t for t in re.findall(r"[a-z0-9]+", ql) if len(t) >= _SHORT and t not in _STOP}
+    q_short = _short_words(question)
     scored: list[tuple[int, int, _T]] = []
     for item in items:
         hits = 0
         best_len = 999
         for lab in get_labels(item):
             labl = lab.lower()
-            lab_tokens = [t for t in re.findall(r"[a-z0-9]+", labl) if len(t) >= 3]
+            lab_tokens = [t for t in re.findall(r"[a-z0-9]+", labl) if len(t) >= _SHORT]
             h = sum(1 for t in lab_tokens if t in ql)
+            # A short token ("HP", "3M", the "31" of "Account Name 31") counts
+            # only when the question has it as a whole word (:func:`_short_words`).
+            h += len(_short_words(lab) & q_short)
             h += sum(1 for t in q_tokens if t in labl and not any(t == lt for lt in lab_tokens))
             if h > hits:
                 hits, best_len = h, len(labl)

{arango_query_core-0.2.8 → arango_query_core-0.2.9}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "arango-query-core"
-version = "0.2.8"
+version = "0.2.9"
 description = "Shared conceptual-model and NL substrate for ArangoDB query transpilers (arango-cypher-py, arango-sparql-py)"
 readme = "README.md"
 license = { file = "LICENSE" }

{arango_query_core-0.2.8 → arango_query_core-0.2.9}/tests/test_nl_grounding.py

@@ -38,6 +38,81 @@ def test_topk_and_ranking() -> None:
     assert top2[1] == e2
 
 
+def _companies() -> list[GroundedEntity]:
+    """Short-named companies among longer names, as a CRM's account list holds them."""
+    names = ["HP", "GE", "3M", "EY", "AT&T", "Acme Holdings", "Meridian Logistics", "Bank of America"]
+    names += [f"{a} {n}" for a in ("Blue", "Atlas", "Golden") for n in ("Systems", "Energy", "Media")]
+    return [GroundedEntity(id=n, labels=(n,), type="Account") for n in names]
+
+
+def test_short_name_is_found_as_a_whole_word() -> None:
+    # A name whose only distinctive word is under three characters ("HP",
+    # "GE", "3M") was never retrieved: the scorer dropped every such token.
+    index = LabelIndex(_companies())
+    for question, name in [
+        ("Who owns HP?", "HP"),
+        ("What is the ARR of GE?", "GE"),
+        ("When does 3M renew?", "3M"),
+        ("Show EY's open opportunities", "EY"),
+        ("Who is the account owner for AT&T?", "AT&T"),
+    ]:
+        assert [e.id for e in index.retrieve(question)][:1] == [name], question
+
+
+def test_short_token_does_not_match_inside_a_longer_word() -> None:
+    # "ge" is inside "manager" and "changed"; "hp" and "ey" inside nothing here.
+    # A short token counts only as a whole word, so none of these are offered.
+    index = LabelIndex(_companies())
+    for question in ("Who is the account manager?", "What changed in usage?", "Which keys expire?"):
+        ids = {e.id for e in index.retrieve(question)}
+        assert not ids & {"HP", "GE", "3M", "EY", "AT&T"}, (question, ids)
+
+
+def test_short_stopword_in_a_label_matches_nothing() -> None:
+    # "of" in "Bank of America" must not tie every question that says "of".
+    index = LabelIndex(_companies())
+    assert "Bank of America" not in {e.id for e in index.retrieve("list of all renewals")}
+
+
+def test_possessive_and_contraction_leave_no_short_fragment() -> None:
+    # "Media's" and "don't" must not yield a token "s" or "t" that matches
+    # "S.p.A." or "AT&T"; a possessive still finds its exact name first.
+    names = ["Atlas Media", "Atlas Media S.p.A.", "AT&T", "Macy's", "Acme"]
+    index = LabelIndex([GroundedEntity(id=n, labels=(n,), type="") for n in names])
+    assert index.retrieve("What is Atlas Media's ARR?")[0].id == "Atlas Media"
+    assert index.retrieve("Which accounts don't renew?") == []
+    assert index.retrieve("Who's the owner?") == []
+    assert index.retrieve("Who owns Macy's?")[0].id == "Macy's"
+
+
+def test_accented_name_yields_no_short_fragments() -> None:
+    # "Société Générale" splits, ASCII-wise, into "soci t g n rale"; its short
+    # pieces must not match a question's stray letters.
+    entity = GroundedEntity(id="SG", labels=("Société Générale",), type="")
+    index = LabelIndex([entity])
+    assert index.retrieve("plan t for g n accounts") == []
+    assert index.retrieve("What is Société Générale's ARR?") == [entity]
+
+
+def test_repeated_short_token_counts_once() -> None:
+    # "J&J" holds "j" twice; counted twice it would outrank the label "J".
+    # Counted once, the two tie and the shorter label wins.
+    names = ["J&J", "J"]
+    index = LabelIndex([GroundedEntity(id=n, labels=(n,), type="") for n in names])
+    assert [e.id for e in index.retrieve("Who is J?")] == ["J", "J&J"]
+
+
+def test_number_in_a_name_ranks_its_own_name_first() -> None:
+    # "Account Name 31" differs from its neighbours only by a two-digit number;
+    # "31" must pick it out, and must not match inside "131" or "2031".
+    names = [f"Account Name {n}" for n in range(1, 201)]
+    index = LabelIndex([GroundedEntity(id=n, labels=(n,), type="") for n in names])
+    assert index.retrieve("Who is the owner of Account Name 31?")[0].id == "Account Name 31"
+    assert index.retrieve("Who is the owner of Account Name 7?")[0].id == "Account Name 7"
+    top = [e.id for e in index.retrieve("renewals of Account Name due in 2031")]
+    assert "Account Name 31" not in top[:1]
+
+
 def test_empty_on_no_match() -> None:
     entity = GroundedEntity(id="http://ex.org/x", labels=("Completely Unrelated",), type="")
     index = LabelIndex([entity])

arango_query_core-0.2.8/.claude/settings.json

@@ -1,8 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(gh run *)",
-      "Bash(git worktree *)"
-    ]
-  }
-}