iris-vector-graph 2.4.6__tar.gz → 2.4.8__tar.gz

{iris_vector_graph-2.4.6 → iris_vector_graph-2.4.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iris-vector-graph
-Version: 2.4.6
+Version: 2.4.8
 Summary: Native graph database layer for InterSystems IRIS — openCypher, hybrid vector search, temporal property graph, RDF export, SHACL validation
 Project-URL: Homepage, https://github.com/intersystems-community/iris-vector-graph
 Project-URL: Documentation, https://github.com/intersystems-community/iris-vector-graph/tree/main/docs
@@ -26,6 +26,8 @@ Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
 Requires-Python: >=3.10
 Requires-Dist: intersystems-iris>=1.0.0
 Requires-Dist: iris-embedded-python-wrapper>=0.5.20
+Provides-Extra: ai
+Requires-Dist: iris-agentic-dev>=1.0; extra == 'ai'
 Provides-Extra: biodata
 Requires-Dist: biopython>=1.81; extra == 'biodata'
 Requires-Dist: bioservices>=1.11.0; extra == 'biodata'
@@ -197,7 +199,7 @@ and [docs/performance/GRAPH_ALGORITHMS.md](docs/performance/GRAPH_ALGORITHMS.md)
 
 ## Architecture
 
-```
+```text
 ┌─────────────────────────────────────────────────────────────────────┐
 │                    iris-vector-graph  v2.1.0                        │
 ├─────────────────────────────────────────────────────────────────────┤
@@ -293,6 +295,29 @@ reference, SHACL shape writing, PROV-O vocabulary mapping, and integration patte
 
 ---
 
+## AI Agent Development
+
+When building agents that use IVG as a knowledge graph backend, install the
+[iris-agentic-dev](https://github.com/intersystems-community/iris-agentic-dev) MCP
+toolkit for ObjectScript compilation, global inspection, and IRIS method invocation
+from your agent's tool loop:
+
+```bash
+pip install iris-agentic-dev
+```
+
+This gives your agent `iris_compile`, `iris_execute`, `iris_global`, and related tools
+that work alongside IVG's Python API.
+
+Skill files with agent-oriented quickstarts:
+
+- [`skills/iris-vector-graph/SKILL.md`](skills/iris-vector-graph/SKILL.md) — IVG API,
+  temporal edges, SHACL, globals, container setup, common gotchas
+- [`skills/ivg-arno/SKILL.md`](skills/ivg-arno/SKILL.md) — Arno Rust acceleration,
+  BFS at scale, enterprise container, ASQ query syntax
+
+---
+
 ## License
 
 MIT. See [LICENSE](LICENSE).

{iris_vector_graph-2.4.6 → iris_vector_graph-2.4.8}/README.md

@@ -105,7 +105,7 @@ and [docs/performance/GRAPH_ALGORITHMS.md](docs/performance/GRAPH_ALGORITHMS.md)
 
 ## Architecture
 
-```
+```text
 ┌─────────────────────────────────────────────────────────────────────┐
 │                    iris-vector-graph  v2.1.0                        │
 ├─────────────────────────────────────────────────────────────────────┤
@@ -201,6 +201,29 @@ reference, SHACL shape writing, PROV-O vocabulary mapping, and integration patte
 
 ---
 
+## AI Agent Development
+
+When building agents that use IVG as a knowledge graph backend, install the
+[iris-agentic-dev](https://github.com/intersystems-community/iris-agentic-dev) MCP
+toolkit for ObjectScript compilation, global inspection, and IRIS method invocation
+from your agent's tool loop:
+
+```bash
+pip install iris-agentic-dev
+```
+
+This gives your agent `iris_compile`, `iris_execute`, `iris_global`, and related tools
+that work alongside IVG's Python API.
+
+Skill files with agent-oriented quickstarts:
+
+- [`skills/iris-vector-graph/SKILL.md`](skills/iris-vector-graph/SKILL.md) — IVG API,
+  temporal edges, SHACL, globals, container setup, common gotchas
+- [`skills/ivg-arno/SKILL.md`](skills/ivg-arno/SKILL.md) — Arno Rust acceleration,
+  BFS at scale, enterprise container, ASQ query syntax
+
+---
+
 ## License
 
 MIT. See [LICENSE](LICENSE).

{iris_vector_graph-2.4.6 → iris_vector_graph-2.4.8}/iris_src/src/Graph/KG/BM25Index.cls

@@ -13,6 +13,9 @@
 ///   ^BM25Idx(name, "tf",   term, docId) integer — term frequency (term-first!)
 ///   ^BM25Idx(name, "len",  docId)       integer — document token count
 ///
+/// Stopwords: common English function words stored in ^BM25Idx("__stop__", word)
+/// at class-load time. Filtered out during Tokenize to reduce IDF noise.
+///
 /// Usage:
 ///   set result = ##class(Graph.KG.BM25Index).Build("ncit", $ListBuild("name","definition"))
 ///   set hits   = ##class(Graph.KG.BM25Index).Search("ncit", "ankylosing spondylitis", 10)
@@ -20,29 +23,54 @@ Class Graph.KG.BM25Index Extends %RegisteredObject
 {
 
 // ================================================================
-// Tokenize — private helper used by Build, Search, Insert
+// InitStopwords — populate ^BM25Idx("__stop__") once per process
+// ================================================================
+
+ClassMethod InitStopwords() [ Private ]
+{
+    If $Data(^BM25Idx("__stop__", "the")) Return
+    Set words = "a,an,the,and,or,but,in,on,at,to,for,of,with,by,from,is,are,was,were,be,been,being,have,has,had,do,does,did,will,would,could,should,may,might,shall,this,that,these,those,it,its,i,we,you,he,she,they,them,their,our,your,his,her,not,no,nor,so,yet,both,either,neither,each,all,any,such,as,if,than,then,there,here,when,where,which,who,what,how"
+    Set n = $LENGTH(words, ",")
+    For i = 1:1:n {
+        Set w = $PIECE(words, ",", i)
+        Set ^BM25Idx("__stop__", w) = 1
+    }
+}
+
+// ================================================================
+// Tokenize — private helper used by Build, Search, Insert, Delete
 // ================================================================
 
 ClassMethod Tokenize(text As %String) As %List [ Private ]
 {
+    Do ..InitStopwords()
     Set lower = $ZCONVERT(text, "L")
     // Try iFind tokenizer first (better punctuation handling, base IRIS)
+    Set raw = ""
     Try {
-        Set tokens = ##class(%iFind.Utils).Analyze(lower, "en", 1)
-        Return tokens
+        Set raw = ##class(%iFind.Utils).Analyze(lower, "en", 1)
     } Catch {}
-    // Fallback: iterate chars, accumulate alphanumeric runs
-    Set result = "", tok = ""
-    For i = 1:1:$LENGTH(lower) {
-        Set c = $EXTRACT(lower, i)
-        If c?1AN {
-            Set tok = tok_c
-        } ElseIf tok '= "" {
-            Set result = result_$LISTBUILD(tok)
-            Set tok = ""
+    If raw = "" {
+        // Fallback: iterate chars, accumulate alphanumeric runs
+        Set tok = ""
+        For i = 1:1:$LENGTH(lower) {
+            Set c = $EXTRACT(lower, i)
+            If c?1AN {
+                Set tok = tok_c
+            } ElseIf tok '= "" {
+                Set raw = raw_$LISTBUILD(tok)
+                Set tok = ""
+            }
         }
+        If tok '= "" Set raw = raw_$LISTBUILD(tok)
+    }
+    // Filter stopwords
+    Set result = "", tIdx = 0
+    While $LISTNEXT(raw, tIdx, tok) {
+        If tok = "" Continue
+        If $Data(^BM25Idx("__stop__", tok)) Continue
+        Set result = result_$LISTBUILD(tok)
     }
-    If tok '= "" Set result = result_$LISTBUILD(tok)
     Return result
 }
 
@@ -54,85 +82,71 @@ ClassMethod Build(name As %String, propsCSV As %String, k1 As %Double = 1.5, b A
 {
     Kill ^BM25Idx(name)
 
-    Set N = 0
-    Set totalLen = 0
+    // Build an IN-list literal from propsCSV for the single batch query.
+    // e.g. "name,definition" → "'name','definition'"
+    Set inList = ""
+    Set nProps = $LENGTH(propsCSV, ",")
+    For pi = 1:1:nProps {
+        Set propKey = $ZSTRIP($PIECE(propsCSV, ",", pi), "<>W")
+        If propKey = "" Continue
+        Set escaped = $Replace(propKey, "'", "''")
+        Set inList = inList _ $Select(inList="":"", 1:",") _ "'" _ escaped _ "'"
+    }
+    If inList = "" Return "{""indexed"":0,""avgdl"":0,""vocab_size"":0}"
 
-    Set sql = "SELECT node_id FROM Graph_KG.nodes"
+    // One query fetches all (node_id, val) pairs for the requested properties.
+    // Ordered by node_id so we can accumulate per-doc by scanning in sequence.
+    Set sql = "SELECT n.node_id, p.val FROM Graph_KG.nodes n "
+            _ "LEFT JOIN Graph_KG.rdf_props p ON p.s = n.node_id AND p.key IN ("_inList_") "
+            _ "ORDER BY n.node_id"
     Set stmt = ##class(%SQL.Statement).%New()
     Do stmt.%Prepare(sql)
     Set rs = stmt.%Execute()
 
+    Set N = 0
+    Set totalLen = 0
+    Set curDoc = ""
+    Set docText = ""
+
     While rs.%Next() {
         Set docId = rs.%Get("node_id")
+        Set val = rs.%GetData(2)  // p.val (NULL when no matching prop row)
 
-        Set docText = ""
-        Set nProps = $LENGTH(propsCSV, ",")
-        For pi = 1:1:nProps {
-            Set propKey = $PIECE(propsCSV, ",", pi)
-            Set propKey = $ZSTRIP(propKey, "<>W")
-            If propKey = "" Continue
-            Set pSql = "SELECT val FROM Graph_KG.rdf_props WHERE s = ? AND key = ?"
-            Set pStmt = ##class(%SQL.Statement).%New()
-            Do pStmt.%Prepare(pSql)
-            Set pRs = pStmt.%Execute(docId, propKey)
-            While pRs.%Next() {
-                Set docText = docText_" "_pRs.%Get("val")
+        If docId '= curDoc {
+            // Flush previous doc
+            If curDoc '= "" {
+                Do ..IndexDoc(name, curDoc, docText, .N, .totalLen)
             }
+            Set curDoc = docId
+            Set docText = $Select(val="":"", 1:val)
+        } Else {
+            If val '= "" Set docText = docText _ " " _ val
         }
-
-        Set tokens = ..Tokenize(docText)
-        Set docLen = $LISTLENGTH(tokens)
-        If docLen = 0 Continue
-
-        Kill tfMap
-        Set tIdx = 0
-        While $LISTNEXT(tokens, tIdx, tok) {
-            If tok = "" Continue
-            Set tfMap(tok) = $Get(tfMap(tok), 0) + 1
-        }
-
-        Set tok = ""
-        For { 
-            Set tok = $Order(tfMap(tok))
-            Quit:tok=""
-            Set ^BM25Idx(name, "tf", tok, docId) = tfMap(tok)
-        }
-
-        Set ^BM25Idx(name, "len", docId) = docLen
-        Set N = N + 1
-        Set totalLen = totalLen + docLen
+    }
+    // Flush last doc
+    If curDoc '= "" {
+        Do ..IndexDoc(name, curDoc, docText, .N, .totalLen)
     }
 
-    // Compute and store IDF for all terms
+    // Compute IDF for all terms from accumulated tf subscripts
     Set avgdl = $Select(N > 0: totalLen / N, 1: 0)
     Set vocabSize = 0
     Set term = ""
-    For {
-        Set term = $Order(^BM25Idx(name, "idf", term))
-        Quit:term=""
-        Kill ^BM25Idx(name, "idf", term)
-    }
-
-    // Compute IDF from df (document frequency) via tf subscripts
-    Set term = ""
     For {
         Set term = $Order(^BM25Idx(name, "tf", term))
         Quit:term=""
-        // Count df = number of docs containing this term
         Set df = 0
-        Set docId = ""
+        Set d = ""
         For {
-            Set docId = $Order(^BM25Idx(name, "tf", term, docId))
-            Quit:docId=""
+            Set d = $Order(^BM25Idx(name, "tf", term, d))
+            Quit:d=""
             Set df = df + 1
         }
-        // Robertson IDF: log((N - df + 0.5) / (df + 0.5) + 1)
         Set idf = $ZLN((N - df + 0.5) / (df + 0.5) + 1)
         Set ^BM25Idx(name, "idf", term) = idf
         Set vocabSize = vocabSize + 1
     }
 
-    // Store config
     Set ^BM25Idx(name, "cfg", "N") = N
     Set ^BM25Idx(name, "cfg", "avgdl") = avgdl
     Set ^BM25Idx(name, "cfg", "k1") = k1
@@ -142,6 +156,29 @@ ClassMethod Build(name As %String, propsCSV As %String, k1 As %Double = 1.5, b A
     Return "{""indexed"":"_N_",""avgdl"":"_avgdl_",""vocab_size"":"_vocabSize_"}"
 }
 
+// Accumulate tf and length for one document — shared by Build batch loop.
+ClassMethod IndexDoc(name As %String, docId As %String, docText As %String, ByRef N As %Integer, ByRef totalLen As %Integer) [ Private ]
+{
+    Set tokens = ..Tokenize(docText)
+    Set docLen = $LISTLENGTH(tokens)
+    If docLen = 0 Return
+    Kill tfMap
+    Set tIdx = 0
+    While $LISTNEXT(tokens, tIdx, tok) {
+        If tok = "" Continue
+        Set tfMap(tok) = $Get(tfMap(tok), 0) + 1
+    }
+    Set tok = ""
+    For {
+        Set tok = $Order(tfMap(tok))
+        Quit:tok=""
+        Set ^BM25Idx(name, "tf", tok, docId) = tfMap(tok)
+    }
+    Set ^BM25Idx(name, "len", docId) = docLen
+    Set N = N + 1
+    Set totalLen = totalLen + docLen
+}
+
 // ================================================================
 // Search — BM25 ranked retrieval
 // ================================================================
@@ -185,29 +222,31 @@ ClassMethod Search(name As %String, queryText As %String, k As %Integer = 10) As
     }
 
     // Sort by score descending — collect top k
-    // Use inverted score as subscript for natural $Order sorting
+    // Scale score to a 12-decimal fixed-point integer subscript so $Order
+    // gives ascending-numeric order; we iterate in reverse with $Order(...,-1).
+    // This avoids the "10M offset" overflow that breaks when BM25 scores exceed it.
     Kill ^||bm25sorted
     Set docId = ""
     For {
         Set docId = $Order(^||bm25scores(docId), 1, score)
         Quit:docId=""
-        // Negate score for descending sort (use large offset to avoid negative subscripts)
-        Set negScore = 10000000 - score
-        Set ^||bm25sorted(negScore, docId) = score
+        // Multiply by 1e12 and round to integer → subscript safe for any BM25 score
+        Set sortKey = $NUMBER(score * 1000000000000, 0)
+        Set ^||bm25sorted(sortKey, docId) = score
     }
 
-    // Build JSON result array
+    // Walk in descending order using $Order with direction -1
     Set result = "["
     Set count = 0
-    Set negScore = ""
+    Set sortKey = ""
     For {
         If count >= k Quit
-        Set negScore = $Order(^||bm25sorted(negScore))
-        Quit:negScore=""
+        Set sortKey = $Order(^||bm25sorted(sortKey), -1)
+        Quit:sortKey=""
         Set docId = ""
         For {
             If count >= k Quit
-            Set docId = $Order(^||bm25sorted(negScore, docId), 1, score)
+            Set docId = $Order(^||bm25sorted(sortKey, docId), 1, score)
             Quit:docId=""
             If count > 0 Set result = result_","
             Set safeId = $Replace(docId, """", "\""")
@@ -284,10 +323,11 @@ ClassMethod Insert(name As %String, docId As %String, text As %String) As %Integ
             Quit:d=""
             Set df = df + 1
         }
+        // Check for new term BEFORE overwriting idf entry
+        Set isNewTerm = '$Data(^BM25Idx(name, "idf", tok))
         Set idf = $ZLN((N - df + 0.5) / (df + 0.5) + 1)
         Set ^BM25Idx(name, "idf", tok) = idf
-        // Update vocab_size if this is a new term
-        If '$Data(^BM25Idx(name, "idf", tok)) {
+        If isNewTerm {
             Set ^BM25Idx(name, "cfg", "vocab_size") = $Increment(^BM25Idx(name, "cfg", "vocab_size"))
         }
     }
@@ -295,6 +335,63 @@ ClassMethod Insert(name As %String, docId As %String, text As %String) As %Integ
     Return 1
 }
 
+// ================================================================
+// Delete — remove a single document from the index
+// ================================================================
+
+ClassMethod Delete(name As %String, docId As %String) As %Integer
+{
+    Set oldLen = +$Get(^BM25Idx(name, "len", docId), 0)
+    If oldLen = 0 Return 0  // doc not in index
+
+    Set N = +$Get(^BM25Idx(name, "cfg", "N"), 0)
+    Set totalLen = N * +$Get(^BM25Idx(name, "cfg", "avgdl"), 0)
+
+    // Collect terms this doc contributed to
+    Kill affectedTerms
+    Set term = ""
+    For {
+        Set term = $Order(^BM25Idx(name, "tf", term))
+        Quit:term=""
+        If $Data(^BM25Idx(name, "tf", term, docId)) {
+            Kill ^BM25Idx(name, "tf", term, docId)
+            Set affectedTerms(term) = 1
+        }
+    }
+    Kill ^BM25Idx(name, "len", docId)
+
+    // Update doc count and avgdl
+    Set N = N - 1
+    Set totalLen = totalLen - oldLen
+    Set ^BM25Idx(name, "cfg", "N") = N
+    Set ^BM25Idx(name, "cfg", "avgdl") = $Select(N > 0: totalLen / N, 1: 0)
+
+    // Recompute IDF for affected terms; remove terms that now have df=0
+    Set term = ""
+    For {
+        Set term = $Order(affectedTerms(term))
+        Quit:term=""
+        Set df = 0
+        Set d = ""
+        For {
+            Set d = $Order(^BM25Idx(name, "tf", term, d))
+            Quit:d=""
+            Set df = df + 1
+        }
+        If df = 0 {
+            Kill ^BM25Idx(name, "idf", term)
+            Set ^BM25Idx(name, "cfg", "vocab_size") = $Increment(^BM25Idx(name, "cfg", "vocab_size"), -1)
+        } Else {
+            If N > 0 {
+                Set idf = $ZLN((N - df + 0.5) / (df + 0.5) + 1)
+                Set ^BM25Idx(name, "idf", term) = idf
+            }
+        }
+    }
+
+    Return 1
+}
+
 // ================================================================
 // Drop — remove entire index
 // ================================================================

{iris_vector_graph-2.4.6 → iris_vector_graph-2.4.8}/iris_vector_graph/_engine/vector.py

@@ -685,10 +685,14 @@ class VectorMixin:
 
         try:
             for idx_name in self._index_registry:
-                if self._index_registry[idx_name] == "ivf":
+                idx_type = self._index_registry[idx_name]
+                if idx_type == "ivf":
                     raw = self.ivf_search(idx_name, vec_list, k=k1)
                     vec_results = [(r["id"], float(r.get("score", 0))) for r in raw]
                     break
+                if idx_type == "hnsw":
+                    vec_results = self.kg_KNN_VEC(query_vector, k=k1)
+                    break
             for idx_name in self._index_registry:
                 if self._index_registry[idx_name] == "bm25":
                     txt_results = self.bm25_search(idx_name, query_text, k=k2)
@@ -956,6 +960,12 @@ class VectorMixin:
             "Graph.KG.BM25Index", "Insert", name, doc_id, text
         )
         return bool(int(str(result)))
+    def bm25_delete(self, name: str, doc_id: str) -> bool:
+        result = self._iris_obj().classMethodValue(
+            "Graph.KG.BM25Index", "Delete", name, doc_id
+        )
+        return bool(int(str(result)))
+
     def bm25_drop(self, name: str) -> None:
         self._iris_obj().classMethodVoid("Graph.KG.BM25Index", "Drop", name)
     def bm25_info(self, name: str) -> dict:
@@ -997,19 +1007,20 @@ class VectorMixin:
         import struct
 
         cursor = self.conn.cursor()
+        emb_table = _table("kg_NodeEmbeddings")
         if node_ids is not None:
             if not node_ids:
                 raise ValueError("ivf_build: node_ids list is empty")
             placeholders = ",".join(["?"] * len(node_ids))
             cursor.execute(
-                f"SELECT id, emb FROM Graph_KG.kg_NodeEmbeddings WHERE id IN ({placeholders})",
+                f"SELECT id, emb FROM {emb_table} WHERE id IN ({placeholders})",
                 node_ids,
             )
         else:
-            cursor.execute("SELECT id, emb FROM Graph_KG.kg_NodeEmbeddings")
+            cursor.execute(f"SELECT id, emb FROM {emb_table}")
         rows = cursor.fetchall()
         if not rows:
-            raise ValueError("ivf_build: no vectors found in kg_NodeEmbeddings")
+            raise ValueError(f"ivf_build: no vectors found in {emb_table}")
 
         node_ids = []
         vecs = []

{iris_vector_graph-2.4.6 → iris_vector_graph-2.4.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "iris-vector-graph"
-version = "2.4.6"
+version = "2.4.8"
 description = "Native graph database layer for InterSystems IRIS — openCypher, hybrid vector search, temporal property graph, RDF export, SHACL validation"
 readme = "README.md"
 license = "MIT"
@@ -120,6 +120,9 @@ biodata = [
 demo = [
     "python-fasthtml>=0.12.0"
 ]
+ai = [
+    "iris-agentic-dev>=1.0",
+]
 browser = [
     "fastapi>=0.118.0",
     "uvicorn>=0.37.0",

{iris_vector_graph-2.4.6 → iris_vector_graph-2.4.8}/tests/unit/test_bm25_index.py

@@ -215,6 +215,31 @@ class TestBM25IndexUnit:
         context = TranslationContext()
         translate_procedure_call(proc, context)
 
+    def test_bm25_delete_calls_classmethod(self):
+        """bm25_delete calls Graph.KG.BM25Index.Delete with correct args."""
+        engine = _make_engine()
+        iris_mock = MagicMock()
+        iris_mock.classMethodValue.return_value = "1"
+        engine._iris_obj = lambda: iris_mock
+
+        engine.bm25_delete("idx", "doc1")
+
+        calls = iris_mock.classMethodValue.call_args_list
+        del_calls = [c for c in calls if len(c.args) > 1 and c.args[1] == "Delete"]
+        assert del_calls, "Delete classMethod not called"
+        assert del_calls[0].args[2] == "idx"
+        assert del_calls[0].args[3] == "doc1"
+
+    def test_bm25_delete_missing_doc_returns_false(self):
+        """bm25_delete returns False when doc not in index."""
+        engine = _make_engine()
+        iris_mock = MagicMock()
+        iris_mock.classMethodValue.return_value = "0"
+        engine._iris_obj = lambda: iris_mock
+
+        result = engine.bm25_delete("idx", "nonexistent_doc")
+        assert result is False
+
     # T041 ─────────────────────────────────────────────────────────
     def test_ivg_bm25_search_yields_node_score(self):
         """ivg.bm25.search registers variable_aliases for node and score."""
@@ -397,6 +422,84 @@ class TestBM25IndexE2E:
         results_after = self.engine.bm25_search(idx, "some", 3)
         assert results_after == []
 
+    def test_delete_removes_doc(self):
+        """After bm25_delete, doc is no longer findable."""
+        run = self._test_run_id
+        node_id = f"bm25del_{run}"
+        unique = f"deletemeterm{run}"
+        self.engine.create_node(node_id, labels=["TestBM25"], properties={"name": unique})
+        idx = f"test44del_{run}"
+        self.engine.bm25_build(idx, ["name"])
+
+        results_before = self.engine.bm25_search(idx, unique, 5)
+        assert any(r[0] == node_id for r in results_before), "doc should be findable before delete"
+
+        ok = self.engine.bm25_delete(idx, node_id)
+        assert ok is True
+
+        results_after = self.engine.bm25_search(idx, unique, 5)
+        ids_after = [r[0] for r in results_after]
+        assert node_id not in ids_after, "deleted doc should not appear in search results"
+        self.engine.bm25_drop(idx)
+
+    def test_insert_vocab_size_grows(self):
+        """Inserting a doc with new terms increments vocab_size."""
+        run = self._test_run_id
+        self._create_node_with_name(f"bm25vocab_{run}", "some baseline text")
+        idx = f"test44vocab_{run}"
+        self.engine.bm25_build(idx, ["name"])
+
+        info_before = self.engine.bm25_info(idx)
+        vocab_before = info_before.get("vocab_size", 0)
+
+        unique_term = f"xquorumzyx{run}"
+        self.engine.bm25_insert(idx, f"vocabdoc_{run}", f"{unique_term} word")
+
+        info_after = self.engine.bm25_info(idx)
+        vocab_after = info_after.get("vocab_size", 0)
+        assert vocab_after > vocab_before, "vocab_size should grow after inserting new terms"
+        self.engine.bm25_drop(idx)
+
+    def test_build_batch_same_result_as_sequential(self):
+        """Build produces same vocab_size and ranking whether 1 or many nodes exist."""
+        run = self._test_run_id
+        terms = [
+            ("bm25batch_a", "diabetes mellitus glucose"),
+            ("bm25batch_b", "insulin resistance glucose"),
+            ("bm25batch_c", "rheumatoid arthritis inflammation"),
+            ("bm25batch_d", "lupus erythematosus autoimmune"),
+            ("bm25batch_e", "ankylosing spondylitis hla"),
+        ]
+        for nid, text in terms:
+            self.engine.create_node(f"{nid}_{run}", labels=["TestBM25"], properties={"name": text})
+
+        idx = f"test44batch_{run}"
+        result = self.engine.bm25_build(idx, ["name"])
+        assert result.get("indexed", 0) >= 5
+        assert result.get("vocab_size", 0) > 0
+
+        hits = self.engine.bm25_search(idx, "glucose", 5)
+        ids = [r[0] for r in hits]
+        assert f"bm25batch_a_{run}" in ids or f"bm25batch_b_{run}" in ids, \
+            "glucose-containing docs should rank"
+        self.engine.bm25_drop(idx)
+
+    def test_high_score_doc_ranked_first(self):
+        """Doc with 20M-range score is still sorted correctly — no negated-score overflow."""
+        run = self._test_run_id
+        for i in range(50):
+            self.engine.create_node(
+                f"bm25overflow_{run}_{i}", labels=["TestBM25"],
+                properties={"name": " ".join([f"rare{run}term"] * 20)}
+            )
+        idx = f"test44overflow_{run}"
+        self.engine.bm25_build(idx, ["name"])
+        results = self.engine.bm25_search(idx, f"rare{run}term", 5)
+        assert results, "should get results on saturated-term query"
+        scores = [s for _, s in results]
+        assert scores == sorted(scores, reverse=True), "results must be descending by score"
+        self.engine.bm25_drop(idx)
+
     # T035 ─────────────────────────────────────────────────────────
     def test_kgtxt_returns_bm25_scores_not_like_scores(self):
         n1 = self._create_node_with_name("bm25test:H1", "diabetes mellitus type 2")