iris-vector-graph 2.18.9__tar.gz → 2.19.1__tar.gz

{iris_vector_graph-2.18.9 → iris_vector_graph-2.19.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: iris-vector-graph
-Version: 2.18.9
+Version: 2.19.1
 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
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: pydantic>=2.0.0
 Provides-Extra: ai
 Requires-Dist: iris-agentic-dev>=1.0; extra == 'ai'
 Provides-Extra: biodata

{iris_vector_graph-2.18.9 → iris_vector_graph-2.19.1}/iris_src/src/Graph/KG/TemporalIndex.cls

@@ -51,7 +51,7 @@ ClassMethod InsertEdge(source As %String, predicate As %String, target As %Strin
 	If weight = "" Set weight = 1
 	// Resolve effective mode: explicit mode overrides legacy upsert boolean.
 	// mode="" falls back to upsert semantics for backward compat.
-	If mode = "" { Set mode = $Select(upsert: "skip", 1: "insert") }
+	If mode = "" { Set mode = $Select(upsert: "update", 1: "insert") }
 	If mode = "skip" && $Data(^KG("tout", timestamp, source, predicate, target)) { Return 1 }
 	If mode = "update" {
 		// Kill stale edgeprop subtree before rewriting attrs.

{iris_vector_graph-2.18.9 → iris_vector_graph-2.19.1}/iris_vector_graph/_engine/temporal.py

@@ -44,6 +44,21 @@ class TemporalMixin:
     ) -> bool:
         """Create a timestamped edge in the temporal index.
 
+        Args:
+            upsert: When ``True``, if an edge with the same ``(source, predicate,
+                target, timestamp)`` key already exists, its weight and attrs are
+                **replaced** with the new values (last-write-wins semantics). When
+                ``False`` (default), the edge is inserted unconditionally; a second
+                write at the same timestamp overwrites via the underlying global set,
+                which is equivalent to ``mode="insert"`` behavior.
+
+                **Note on bucket aggregates**: ``upsert=True`` replaces the edge's
+                weight in ``^KG("tout")`` but does NOT adjust the pre-computed bucket
+                aggregates in ``^KG("tagg")``. Aggregate counters (count/sum/min/max)
+                remain based on the original value. If aggregate fidelity is required,
+                call ``Purge()`` and rebuild, or use ``get_edges_in_window()`` for
+                exact per-edge statistics.
+
         ADJACENCY CONTRACT: TemporalIndex.InsertEdge writes the temporal globals
         (^KG "tout"/"tin"/buckets/aggregates) AND a shadow ^KG("out",0,...)
         adjacency entry — so temporal edges ARE visible to the ^KG-based readers
@@ -156,6 +171,18 @@ class TemporalMixin:
         non-suppressed edges in inbound queries.
 
         source="" returns edges from all sources (QueryWindow all-sources path).
+
+        **Return shape**: each dict has keys ``{s, p, o, ts, w}`` (plus long-form
+        aliases ``source``, ``predicate``, ``target``, ``timestamp``, ``weight``).
+
+        **Edge attributes are NOT included.** Attrs written via
+        ``create_edge_temporal(attrs={...})`` are stored separately in
+        ``^KG("edgeprop")`` and are never returned by this method. To retrieve attrs
+        for a specific edge, call ``get_edge_attrs(ts, source, predicate, target)``::
+
+            edges = engine.get_edges_in_window("svc-auth", "CALLS", ts_start, ts_end)
+            for edge in edges:
+                attrs = engine.get_edge_attrs(edge["ts"], edge["s"], edge["p"], edge["o"])
         """
         result = self._store.execute_temporal_window_query(source, predicate, start, end, direction)
         if result.error:
@@ -214,7 +241,23 @@ class TemporalMixin:
         """Return the canonical JSON for a known label set hash, or '' if unknown."""
         return self._store.resolve_label_set(hash_hex)
 
-    def get_edge_velocity(self, node_id: str, window_seconds: int = 300, window: int = None, now_ts: int = 0) -> int:
+    def get_edge_velocity(
+        self,
+        node_id: str,
+        window_seconds: int = 300,
+        window: int = None,
+        now_ts: int = 0,
+    ) -> int:
+        """Count edges arriving at ``node_id`` within the last ``window_seconds``.
+
+        Args:
+            node_id: Source node ID.
+            window_seconds: Width of the time window in seconds.
+            now_ts: Unix timestamp to use as "now". Default 0 = wall clock.
+                **Pass an explicit value when testing with historical fixture data**
+                (e.g., ``now_ts = fixture_epoch + window_seconds``) to ensure the
+                window covers the fixture timestamps.
+        """
         w = window if window is not None else window_seconds
         result = self._iris_obj().classMethodValue(
             "Graph.KG.TemporalIndex", "GetVelocity", node_id, w, now_ts
@@ -222,14 +265,41 @@ class TemporalMixin:
         return int(result)
 
     def find_burst_nodes(
-        self, predicate: str = "", window_seconds: int = 300, threshold: int = 50
+        self,
+        predicate: str = "",
+        window_seconds: int = 300,
+        threshold: int = 50,
+        now_ts: int = 0,
     ) -> list:
+        """Find nodes whose inbound edge count in the last window exceeds threshold.
+
+        Args:
+            predicate: Filter to edges with this predicate. Empty = all predicates.
+            window_seconds: Width of the detection window in seconds.
+            threshold: Minimum edge count to qualify as a burst.
+            now_ts: Unix timestamp to use as "now". Default 0 = wall clock.
+                **Pass an explicit value when testing with historical fixture data**
+                so the detection window covers the fixture timestamps.
+        """
         result = self._iris_obj().classMethodValue(
-            "Graph.KG.TemporalIndex", "FindBursts", predicate, window_seconds, threshold
+            "Graph.KG.TemporalIndex", "FindBursts", predicate, window_seconds, threshold,
+            now_ts,
         )
         return json.loads(str(result))
 
     def get_edge_attrs(self, ts: int, source: str, predicate: str, target: str) -> dict:
+        """Return the attribute dict for a specific temporal edge.
+
+        This is the companion to ``create_edge_temporal(attrs=...)``. Attrs are stored
+        in ``^KG("edgeprop")`` and are NOT included in ``get_edges_in_window()``
+        results — call this per edge when you need them::
+
+            attrs = engine.get_edge_attrs(
+                edge["ts"], edge["s"], edge["p"], edge["o"]
+            )
+
+        Returns an empty dict when no attrs were stored for this edge.
+        """
         result = self._iris_obj().classMethodValue(
             "Graph.KG.TemporalIndex", "GetEdgeAttrs", ts, source, predicate, target
         )
@@ -274,6 +344,26 @@ class TemporalMixin:
                 avg       (float) — mean weight (None if count == 0)
                 min       (float) — minimum weight (None if no edges)
                 max       (float) — maximum weight (None if no edges)
+
+        **No target field.** Aggregates are computed per ``(source, predicate)``
+        only — the target dimension is not preserved in ``^KG("tagg")``. When
+        multiple targets share the same ``(source, predicate)`` pair (e.g.
+        per-metric baselines), the aggregated values span all targets and cannot
+        be disaggregated.
+
+        **Workaround for per-target statistics**: use
+        ``get_bucket_group_targets(source, predicate, ts_start, ts_end)`` to get
+        distinct targets, then aggregate per target in Python::
+
+            targets = engine.get_bucket_group_targets(
+                "acme|prod", "SEGMENT_BASELINE", ts_start, ts_end
+            )
+            for target in targets:
+                edges = engine.get_edges_in_window(
+                    "acme|prod", "SEGMENT_BASELINE", ts_start, ts_end
+                )
+                target_edges = [e for e in edges if e["o"] == target]
+                avg = sum(e["w"] for e in target_edges) / len(target_edges)
         """
         result = self._iris_obj().classMethodValue(
             "Graph.KG.TemporalIndex",
@@ -292,7 +382,12 @@ class TemporalMixin:
         ts_start: int,
         ts_end: int,
     ) -> list[str]:
-        """Return distinct target node IDs for a source+predicate over a time window."""
+        """Return distinct target node IDs for a source+predicate over a time window.
+
+        Use as the first step in per-target aggregation when ``get_bucket_groups()``
+        is insufficient because it lacks the target dimension. See
+        ``get_bucket_groups()`` for a full workaround pattern.
+        """
         result = self._iris_obj().classMethodValue(
             "Graph.KG.TemporalIndex",
             "GetBucketGroupTargets",

{iris_vector_graph-2.18.9 → iris_vector_graph-2.19.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "iris-vector-graph"
-version = "2.18.9"
+version = "2.19.1"
 description = "Native graph database layer for InterSystems IRIS — openCypher, hybrid vector search, temporal property graph, RDF export, SHACL validation"
 readme = "README.md"
 license = "MIT"
@@ -46,6 +46,12 @@ dependencies = [
     # standard connection seam — base dependency so `import iris` always resolves to
     # the superset. See iris_vector_graph/embedded.py for the embedded context.
     "iris-embedded-python-wrapper>=0.5.20",
+    # pydantic and numpy are imported unconditionally at module level in result.py,
+    # _validate.py, cypher/translator.py, fusion.py, and vector_utils.py — all of
+    # which load when IRISGraphEngine is imported. They must be declared here, not
+    # only in [full], so that a bare `pip install iris-vector-graph` works.
+    "pydantic>=2.0.0",
+    "numpy>=1.24.0",
 ]
 
 [project.optional-dependencies]

iris_vector_graph-2.19.1/tests/integration/test_221_upsert_weight_e2e.py

@@ -0,0 +1,56 @@
+"""E2E integration tests for spec 221 — upsert=True must update weight.
+
+Requires ivg-iris-enterprise (port 31972).
+"""
+import os
+import uuid
+import pytest
+from iris_vector_graph.engine import IRISGraphEngine
+
+SKIP_IRIS_TESTS = os.environ.get("SKIP_IRIS_TESTS", "false").lower() == "true"
+_PREFIX = f"u221_{uuid.uuid4().hex[:8]}"
+
+
+@pytest.fixture(scope="module")
+def eng(iris_connection):
+    e = IRISGraphEngine(iris_connection, embedding_dimension=768)
+    e.initialize_schema()
+    yield e
+    try:
+        e._store._iris_obj().classMethodVoid("Graph.KG.TemporalIndex", "Purge")
+    except Exception:
+        pass
+
+
+@pytest.mark.skipif(SKIP_IRIS_TESTS, reason="SKIP_IRIS_TESTS=true")
+class TestUpsertWeightUpdate:
+
+    def test_upsert_updates_weight(self, eng):
+        """T001: upsert=True with new weight → new weight returned by get_edges_in_window."""
+        src = f"{_PREFIX}_s1"; tgt = f"{_PREFIX}_t1"
+        eng.create_edge_temporal(src, "METRIC", tgt, timestamp=2000, weight=0.5, upsert=True)
+        eng.create_edge_temporal(src, "METRIC", tgt, timestamp=2000, weight=0.9, upsert=True)
+        edges = eng.get_edges_in_window(src, "METRIC", 0, 999999999)
+        weights = [e["w"] for e in edges if e["ts"] == 2000]
+        assert len(weights) == 1, f"Expected 1 edge at ts=2000, got {len(weights)}"
+        assert abs(weights[0] - 0.9) < 1e-6, f"Expected weight 0.9, got {weights[0]}"
+
+    def test_upsert_true_idempotent_on_same_weight(self, eng):
+        """T002: upsert=True is idempotent when weight unchanged."""
+        src = f"{_PREFIX}_s2"; tgt = f"{_PREFIX}_t2"
+        eng.create_edge_temporal(src, "METRIC", tgt, timestamp=3000, weight=0.7, upsert=True)
+        eng.create_edge_temporal(src, "METRIC", tgt, timestamp=3000, weight=0.7, upsert=True)
+        edges = eng.get_edges_in_window(src, "METRIC", 0, 999999999)
+        weights = [e["w"] for e in edges if e["ts"] == 3000]
+        assert len(weights) == 1
+        assert abs(weights[0] - 0.7) < 1e-6
+
+    def test_upsert_updates_attrs(self, eng):
+        """US-1 AC2: upsert=True replaces attrs (edgeprop) with new value."""
+        src = f"{_PREFIX}_s3"; tgt = f"{_PREFIX}_t3"
+        eng.create_edge_temporal(src, "METRIC", tgt, timestamp=4000, weight=1.0,
+                                  attrs={"status": "old"}, upsert=True)
+        eng.create_edge_temporal(src, "METRIC", tgt, timestamp=4000, weight=1.0,
+                                  attrs={"status": "new"}, upsert=True)
+        attrs = eng.get_edge_attrs(4000, src, "METRIC", tgt)
+        assert attrs.get("status") == "new", f"Expected attrs.status='new', got {attrs}"

iris_vector_graph-2.19.1/tests/unit/test_219_attrs_doc.py

@@ -0,0 +1,18 @@
+"""Unit tests for spec 219 — get_edges_in_window docstring documents attrs limitation."""
+
+
+class TestAttrsDocumentation:
+
+    def test_get_edges_in_window_docstring_documents_attrs(self):
+        """T001: get_edges_in_window docstring mentions attrs and get_edge_attrs."""
+        from iris_vector_graph._engine.temporal import TemporalMixin
+        doc = TemporalMixin.get_edges_in_window.__doc__ or ""
+        assert "attrs" in doc.lower() or "get_edge_attrs" in doc, (
+            "get_edges_in_window docstring must document the attrs limitation"
+        )
+
+    def test_get_edge_attrs_docstring_present(self):
+        """T003: get_edge_attrs docstring is meaningful."""
+        from iris_vector_graph._engine.temporal import TemporalMixin
+        doc = TemporalMixin.get_edge_attrs.__doc__ or ""
+        assert len(doc.strip()) > 20, "get_edge_attrs should have a substantive docstring"

iris_vector_graph-2.19.1/tests/unit/test_220_bucket_groups_doc.py

@@ -0,0 +1,21 @@
+"""Unit tests for spec 220 — get_bucket_groups docstring documents no-target limitation."""
+
+
+class TestBucketGroupsDocumentation:
+
+    def test_get_bucket_groups_docstring_documents_no_target(self):
+        """T001: get_bucket_groups docstring mentions target limitation."""
+        from iris_vector_graph._engine.temporal import TemporalMixin
+        doc = TemporalMixin.get_bucket_groups.__doc__ or ""
+        assert "target" in doc.lower(), (
+            "get_bucket_groups docstring must document that target is not included"
+        )
+        assert "get_bucket_group_targets" in doc, (
+            "get_bucket_groups docstring must reference get_bucket_group_targets workaround"
+        )
+
+    def test_get_bucket_group_targets_docstring_present(self):
+        """T003: get_bucket_group_targets docstring is meaningful."""
+        from iris_vector_graph._engine.temporal import TemporalMixin
+        doc = TemporalMixin.get_bucket_group_targets.__doc__ or ""
+        assert len(doc.strip()) > 20, "get_bucket_group_targets should have a docstring"

iris_vector_graph-2.19.1/tests/unit/test_222_now_ts.py

@@ -0,0 +1,57 @@
+"""Unit tests for spec 222 — now_ts parameter documentation and find_burst_nodes fix."""
+import pytest
+from unittest.mock import MagicMock, patch
+
+
+class TestNowTsParams:
+
+    def _make_engine(self):
+        from iris_vector_graph.engine import IRISGraphEngine
+        eng = MagicMock(spec=IRISGraphEngine)
+        eng._schema_prefix = "Graph_KG"
+        eng.conn = MagicMock()
+        return eng
+
+    def test_get_edge_velocity_passes_now_ts(self):
+        """T001: get_edge_velocity(now_ts=T) passes T to ObjectScript."""
+        from iris_vector_graph._engine.temporal import TemporalMixin
+
+        iris_obj = MagicMock()
+        iris_obj.classMethodValue.return_value = "3"
+        mixin = MagicMock()
+        mixin._iris_obj.return_value = iris_obj
+
+        TemporalMixin.get_edge_velocity(mixin, "src-node", window_seconds=300, now_ts=12345)
+
+        call_args = iris_obj.classMethodValue.call_args[0]
+        assert call_args[0] == "Graph.KG.TemporalIndex"
+        assert call_args[1] == "GetVelocity"
+        assert call_args[4] == 12345
+
+    def test_find_burst_nodes_accepts_now_ts(self):
+        """T002: find_burst_nodes(now_ts=T) passes T to FindBursts ObjectScript."""
+        from iris_vector_graph._engine.temporal import TemporalMixin
+
+        iris_obj = MagicMock()
+        iris_obj.classMethodValue.return_value = "[]"
+        mixin = MagicMock()
+        mixin._iris_obj.return_value = iris_obj
+
+        TemporalMixin.find_burst_nodes(mixin, predicate="METRIC", now_ts=99999)
+
+        call_args = iris_obj.classMethodValue.call_args[0]
+        assert call_args[0] == "Graph.KG.TemporalIndex"
+        assert call_args[1] == "FindBursts"
+        assert 99999 in call_args, f"now_ts=99999 not passed; args={call_args}"
+
+    def test_get_edge_velocity_docstring_documents_now_ts(self):
+        """T001 extra: get_edge_velocity docstring mentions now_ts."""
+        from iris_vector_graph._engine.temporal import TemporalMixin
+        doc = TemporalMixin.get_edge_velocity.__doc__ or ""
+        assert "now_ts" in doc, "get_edge_velocity docstring should document now_ts"
+
+    def test_find_burst_nodes_docstring_documents_now_ts(self):
+        """T002 extra: find_burst_nodes docstring mentions now_ts."""
+        from iris_vector_graph._engine.temporal import TemporalMixin
+        doc = TemporalMixin.find_burst_nodes.__doc__ or ""
+        assert "now_ts" in doc, "find_burst_nodes docstring should document now_ts"

{iris_vector_graph-2.18.9 → iris_vector_graph-2.19.1}/tests/unit/test_temporal_edges.py

@@ -523,15 +523,25 @@ class TestTemporalAPIGapsE2E:
         assert f"{self.PREFIX}:a" in sources
         assert f"{self.PREFIX}:b" in sources
 
-    def test_upsert_temporal_edge_no_duplicate(self):
+    def test_upsert_temporal_edge_updates_weight(self):
+        """upsert=True replaces weight in ^KG("tout"); bucket aggregate count still increments.
+
+        Known caveat (spec 221 FR-004): ^KG("tagg") aggregates are NOT corrected when
+        upsert overwrites an edge. Use get_edges_in_window() for exact per-edge stats.
+        """
         now = int(time.time())
-        for _ in range(3):
-            self.engine.create_edge_temporal(
-                f"{self.PREFIX}:src", "COST_ON", f"Date:2026-03-18",
-                now, 27.7, upsert=True)
-        count = self.engine.get_temporal_aggregate(
-            f"{self.PREFIX}:src", "COST_ON", "count", now - 10, now + 10)
-        assert count == 1
+        self.engine.create_edge_temporal(
+            f"{self.PREFIX}:src", "COST_ON", "Date:2026-03-18",
+            now, 27.7, upsert=True)
+        self.engine.create_edge_temporal(
+            f"{self.PREFIX}:src", "COST_ON", "Date:2026-03-18",
+            now, 99.9, upsert=True)
+        # Weight is updated to the latest value
+        edges = self.engine.get_edges_in_window(
+            f"{self.PREFIX}:src", "COST_ON", now - 10, now + 10)
+        ts_edges = [e for e in edges if e["ts"] == now]
+        assert len(ts_edges) == 1, f"Expected 1 edge at ts={now}, got {len(ts_edges)}"
+        assert abs(ts_edges[0]["w"] - 99.9) < 1e-6, f"Expected w=99.9, got {ts_edges[0]['w']}"
 
     def test_upsert_false_allows_duplicates(self):
         now = int(time.time())