iris-vector-graph 2.1.1__tar.gz → 2.2.0__tar.gz

{iris_vector_graph-2.1.1 → iris_vector_graph-2.2.0}/.gitignore

@@ -105,6 +105,7 @@ docs/dc_contest_raw.md
 
 # Agent-specific config (not project docs)
 CLAUDE.md
+AGENTS.md
 CODEX.md
 TABNINE.md
 DOCS_IRIS_PYTHON_ISSUES.md

{iris_vector_graph-2.1.1 → iris_vector_graph-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iris-vector-graph
-Version: 2.1.1
+Version: 2.2.0
 Summary: Transactional Graph + Vector retrieval system for InterSystems IRIS with hybrid search, openCypher, and GraphQL APIs
 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
@@ -19,6 +19,7 @@ Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Database
 Classifier: Topic :: Scientific/Engineering
 Classifier: Topic :: Scientific/Engineering :: Bio-Informatics

{iris_vector_graph-2.1.1 → iris_vector_graph-2.2.0}/iris_vector_graph/__init__.py

@@ -112,4 +112,7 @@ __all__ = [
     "EmbeddingsMissingError",
     "IndexNotSyncedError",
     "NodeNotFoundError",
+    "ApiKeyMiddleware",
+    "ReadOnlyMiddleware",
+    "is_mutation_cypher",
 ]

{iris_vector_graph-2.1.1 → iris_vector_graph-2.2.0}/iris_vector_graph/_engine/query.py

@@ -354,22 +354,21 @@ class QueryMixin:
         predicates = vl0.get("types", [])
         max_hops = vl0.get("max_hops", 5)
         direction = vl0.get("direction", "out")
-        max_results = 0
-        if sql_str:
-            m = _re.search(r"\bLIMIT\s+(\d+)", sql_str, _re.IGNORECASE)
-            if m:
-                max_results = int(m.group(1))
+        def _extract_limit(s: str) -> int:
+            # IRIS SQL uses FETCH FIRST N ROWS ONLY; fall back to LIMIT N
+            m = _re.search(r"FETCH\s+FIRST\s+(\d+)\s+ROWS\s+ONLY", s, _re.IGNORECASE)
+            if not m:
+                m = _re.search(r"\bLIMIT\s+(\d+)", s, _re.IGNORECASE)
+            return int(m.group(1)) if m else 0
+
+        max_results = _extract_limit(sql_str) if sql_str else 0
 
         if count_match:
             col_name = count_match.group(1)
             bfs_result = self._store.execute_bfs(source_id, predicates, max_hops, direction, 0)
             cnt = len(bfs_result.rows) if not bfs_result.error else 0
             return IVGResult(columns=[col_name], rows=[[cnt]], metadata=sql_query.query_metadata)
-        max_results = 0
-        if sql_str:
-            m = _re.search(r"\bLIMIT\s+(\d+)", sql_str, _re.IGNORECASE)
-            if m:
-                max_results = int(m.group(1))
+        max_results = _extract_limit(sql_str) if sql_str else 0
 
         direction = vl0.get("direction", "out")
         predicates = vl0.get("types", [])
@@ -564,7 +563,10 @@ class QueryMixin:
         import re as _re
         sql_str = sql_query.sql if isinstance(sql_query.sql, str) else (sql_query.sql[0] if sql_query.sql else "")
         if sql_query.sql:
-            m = _re.search(r"\bLIMIT\s+(\d+)", sql_str, _re.IGNORECASE)
+            # IRIS SQL uses "FETCH FIRST N ROWS ONLY" (not LIMIT N)
+            m = _re.search(r"FETCH\s+FIRST\s+(\d+)\s+ROWS\s+ONLY", sql_str, _re.IGNORECASE)
+            if not m:
+                m = _re.search(r"\bLIMIT\s+(\d+)", sql_str, _re.IGNORECASE)
             if m:
                 max_results = int(m.group(1))
 

iris_vector_graph-2.2.0/iris_vector_graph/api_auth.py

@@ -0,0 +1,133 @@
+"""Shared API authentication and access-control middleware for iris-vector-graph.
+
+Provides:
+- ApiKeyMiddleware: opt-in API key gate (IVG_API_KEY env var)
+- ReadOnlyMiddleware: mutation rejection (IVG_READ_ONLY env var)
+
+Both are no-ops when their respective env vars are unset, preserving full
+backward compatibility for existing deployments.
+
+Usage in FastAPI app::
+
+    from iris_vector_graph.api_auth import ApiKeyMiddleware, ReadOnlyMiddleware
+
+    app.add_middleware(ReadOnlyMiddleware)
+    app.add_middleware(ApiKeyMiddleware)
+"""
+from __future__ import annotations
+
+import os
+from typing import Callable
+
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import JSONResponse, Response
+
+# Routes that are always exempt from authentication — health checks, API docs.
+_AUTH_EXEMPT: frozenset[str] = frozenset({
+    "/health",
+    "/docs",
+    "/openapi.json",
+    "/redoc",
+})
+
+# Route prefixes that require authentication when IVG_API_KEY is set.
+_PROTECTED_PREFIXES: tuple[str, ...] = (
+    "/api/",
+    "/fhir-event/",
+    "/fhir-event",
+    "/graphql",
+)
+
+# Cypher keywords that constitute mutations (case-insensitive word-boundary check).
+_MUTATION_KEYWORDS: tuple[str, ...] = (
+    "CREATE",
+    "DELETE",
+    "MERGE",
+    "SET",
+    "REMOVE",
+    "FOREACH",
+)
+
+# HTTP methods that constitute writes on the fhir-event endpoint.
+_WRITE_METHODS: frozenset[str] = frozenset({"POST", "PUT", "PATCH", "DELETE"})
+
+
+class ApiKeyMiddleware(BaseHTTPMiddleware):
+    """Opt-in API key authentication middleware.
+
+    Activated only when ``IVG_API_KEY`` env var is non-empty.
+    When active, all protected routes require the ``X-Api-Key`` header with
+    the matching value.  Exempt routes (/health, /docs, etc.) always pass.
+    """
+
+    async def dispatch(self, request: Request, call_next: Callable) -> Response:
+        expected = os.environ.get("IVG_API_KEY", "")
+        if not expected:
+            return await call_next(request)
+
+        path = request.url.path
+        if path in _AUTH_EXEMPT:
+            return await call_next(request)
+
+        if not any(path.startswith(prefix) for prefix in _PROTECTED_PREFIXES):
+            return await call_next(request)
+
+        provided = request.headers.get("X-Api-Key", "")
+        if provided != expected:
+            return JSONResponse(
+                status_code=401,
+                content={"error": "unauthorized", "message": "X-Api-Key header required"},
+            )
+
+        return await call_next(request)
+
+
+class ReadOnlyMiddleware(BaseHTTPMiddleware):
+    """Opt-in read-only enforcement middleware.
+
+    Activated when ``IVG_READ_ONLY`` env var is ``"true"`` (case-insensitive).
+
+    When active:
+    - Blocks write HTTP methods (POST/PUT/PATCH/DELETE) on ``/fhir-event/``
+      unless ``IVG_ALLOW_FHIR_WRITES=true``.
+    - GraphQL mutation blocking is handled at the resolver level (see
+      ``api/gql/schema.py``) — this middleware does not inspect GraphQL bodies.
+    - Cypher mutation keyword blocking is handled in the Cypher router
+      (``api/routers/cypher.py``) — this middleware does not inspect request bodies.
+    """
+
+    async def dispatch(self, request: Request, call_next: Callable) -> Response:
+        if os.environ.get("IVG_READ_ONLY", "").lower() != "true":
+            return await call_next(request)
+
+        path = request.url.path
+        method = request.method.upper()
+
+        # Block write methods on fhir-event unless explicitly allowed.
+        if (path.startswith("/fhir-event")
+                and method in _WRITE_METHODS
+                and os.environ.get("IVG_ALLOW_FHIR_WRITES", "").lower() != "true"):
+            return JSONResponse(
+                status_code=403,
+                content={
+                    "error": "read_only_mode",
+                    "detail": "fhir-event writes are disabled; set IVG_ALLOW_FHIR_WRITES=true to allow",
+                },
+            )
+
+        return await call_next(request)
+
+
+def is_mutation_cypher(query: str) -> bool:
+    """Return True if the Cypher query string contains a mutation keyword.
+
+    Used by the Cypher router to enforce ``IVG_READ_ONLY`` on query content.
+    Case-insensitive, whole-word match to avoid false positives in strings.
+    """
+    import re
+    upper = query.upper()
+    for kw in _MUTATION_KEYWORDS:
+        if re.search(rf"\b{kw}\b", upper):
+            return True
+    return False

{iris_vector_graph-2.1.1 → iris_vector_graph-2.2.0}/iris_vector_graph/cypher/translator.py

@@ -670,12 +670,13 @@ def _translate_bm25_search(
         )
 
     bm25_fn = f"{_schema_prefix}.kg_BM25" if _schema_prefix else "kg_BM25"
-    safe_idx = idx_name.replace("'", "''")
-    safe_query = str(query).replace("'", "''")
+    # Bind idx_name and query as parameters (? placeholders) rather than
+    # interpolating them inline.  k_int is an integer cast — safe as inline literal.
+    context.all_stage_params.extend([str(idx_name), str(query)])
     cte_sql = (
         f"SELECT j.node_id AS node, j.score\n"
         f"FROM JSON_TABLE(\n"
-        f"  {bm25_fn}('{safe_idx}', '{safe_query}', {k_int}),\n"
+        f"  {bm25_fn}(?, ?, {k_int}),\n"
         f"  '$[*]' COLUMNS(\n"
         f"    node_id VARCHAR(256) PATH '$.id',\n"
         f"    score DOUBLE PATH '$.score'\n"
@@ -713,16 +714,16 @@ def _translate_retrieve(
     bm25_limit = limit * 2
     emb_table = f"{_schema_prefix}.kg_NodeEmbeddings" if _schema_prefix else "Graph_KG.kg_NodeEmbeddings"
     bm25_fn = f"{_schema_prefix}.kg_BM25" if _schema_prefix else "Graph_KG.kg_BM25"
-    safe_query = str(query).replace("'", "''")
-    safe_bm25 = bm25_name.replace("'", "''")
-    safe_config = embedding_config.replace("'", "''")
 
-    vec_where = "" if vec_label == "*" else f" WHERE n.label = '{vec_label.replace(chr(39), chr(39)*2)}'"
+    # Bind all string user inputs as ? parameters; integer args stay inline (safe).
+    # Order: bm25_name, query (for BM25 CTE), then query again (for Vec EMBEDDING()),
+    # then embedding_config, then vec_label filter (if not wildcard).
+    context.all_stage_params.extend([str(bm25_name), str(query)])
 
     bm25_cte = (
         f"SELECT j.node_id AS node, j.score\n"
         f"FROM JSON_TABLE(\n"
-        f"  {bm25_fn}('{safe_bm25}', '{safe_query}', {bm25_limit}),\n"
+        f"  {bm25_fn}(?, ?, {bm25_limit}),\n"
         f"  '$[*]' COLUMNS(\n"
         f"    node_id VARCHAR(256) PATH '$.id',\n"
         f"    score DOUBLE PATH '$.score'\n"
@@ -730,9 +731,17 @@ def _translate_retrieve(
         f") j"
     )
 
-    context.all_stage_params.append(str(query))
+    context.all_stage_params.append(str(query))   # for EMBEDDING(?, ...)
+    context.all_stage_params.append(str(embedding_config))
+
+    if vec_label == "*":
+        vec_where = ""
+    else:
+        vec_where = " WHERE n.label = ?"
+        context.all_stage_params.append(str(vec_label))
+
     vec_cte = (
-        f"SELECT TOP {vec_limit} e.id AS node, VECTOR_COSINE(e.emb, EMBEDDING(?, '{safe_config}')) AS score\n"
+        f"SELECT TOP {vec_limit} e.id AS node, VECTOR_COSINE(e.emb, EMBEDDING(?, ?)) AS score\n"
         f"FROM {emb_table} e{vec_where}\n"
         f"ORDER BY score DESC"
     )
@@ -803,12 +812,13 @@ def _translate_ivf_search(
         )
 
     ivf_fn = f"{_schema_prefix}.kg_IVF" if _schema_prefix else "kg_IVF"
-    safe_idx = idx_name.replace("'", "''")
+    # Bind idx_name and query_json as ? parameters; k_int/nprobe_int are safe int literals.
+    context.all_stage_params.extend([str(idx_name), _json.dumps(floats)])
 
     cte_sql = (
         f"SELECT j.node, j.score\n"
         f"FROM JSON_TABLE(\n"
-        f"  {ivf_fn}('{safe_idx}', '{query_json}', {k_int}, {nprobe_int}),\n"
+        f"  {ivf_fn}(?, ?, {k_int}, {nprobe_int}),\n"
         f"  '$[*]' COLUMNS(\n"
         f"    node VARCHAR(256) PATH '$.id',\n"
         f"    score DOUBLE PATH '$.score'\n"

{iris_vector_graph-2.1.1 → iris_vector_graph-2.2.0}/iris_vector_graph/cypher_api.py

@@ -84,18 +84,10 @@ def browser_redirect():
     return RedirectResponse("/browser/")
 
 
-@app.middleware("http")
-async def api_key_middleware(request: Request, call_next):
-    path = request.url.path
-    if path.startswith("/api/") or path.startswith("/db/"):
-        expected = os.environ.get("IVG_API_KEY", "")
-        provided = request.headers.get("X-API-Key", "")
-        if expected and provided != expected:
-            return JSONResponse(
-                status_code=401,
-                content={"error": "unauthorized", "message": "X-API-Key required"},
-            )
-    return await call_next(request)
+# API key authentication — shared implementation from iris_vector_graph.api_auth.
+# Uses X-Api-Key header (canonical form); IVG_API_KEY env var activates it.
+from iris_vector_graph.api_auth import ApiKeyMiddleware as _ApiKeyMiddleware
+app.add_middleware(_ApiKeyMiddleware)
 
 
 from iris_vector_graph.bolt_server import BoltSession

{iris_vector_graph-2.1.1 → iris_vector_graph-2.2.0}/iris_vector_graph/stores/iris_sql_store.py

@@ -348,7 +348,7 @@ class IRISGraphStore:
                 raw = self._arno_call(
                     "Graph.KG.NKGAccel", "BFSJson",
                     source_id, predicates_json, str(max_hops),
-                    str(max_results), direction,
+                    str(max_results),
                 )
                 raw_val = raw if isinstance(raw, str) else str(raw)
                 if raw_val.startswith("SORTED:"):

{iris_vector_graph-2.1.1 → iris_vector_graph-2.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "iris-vector-graph"
-version = "2.1.1"
+version = "2.2.0"
 description = "Transactional Graph + Vector retrieval system for InterSystems IRIS with hybrid search, openCypher, and GraphQL APIs"
 readme = "README.md"
 license = "MIT"
@@ -30,6 +30,7 @@ classifiers = [
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
     "Topic :: Scientific/Engineering :: Bio-Informatics",
     "Topic :: Database",
     "Topic :: Scientific/Engineering"
@@ -200,7 +201,8 @@ addopts = [
     "-v",
     "--tb=short",
     "--strict-markers",
-    "--disable-warnings"
+    "--disable-warnings",
+    "-m", "not perf"
 ]
 markers = [
     "slow: marks tests as slow (deselect with '-m \"not slow\"')",
@@ -220,7 +222,13 @@ omit = [
     "*/.venv/*",
     "*/build/*",
     "*/dist/*",
+    # Bolt server: network I/O — covered by integration tests (ivg-iris container required)
     "iris_vector_graph/bolt_server.py",
+    # IRIS-native store layer: ~95% of lines call IRIS ObjectScript directly;
+    # meaningful coverage only via integration tests (ivg-iris or ivg-iris-enterprise).
+    # Unit coverage intentionally omitted — see docs/coverage.md
+    "iris_vector_graph/stores/iris_sql_store.py",
+    "iris_vector_graph/stores/arno_bridge.py",
 ]
 
 [tool.coverage.report]

{iris_vector_graph-2.1.1 → iris_vector_graph-2.2.0}/tests/conftest.py

@@ -21,31 +21,19 @@ def _deploy_objectscript(container_name: str) -> None:
         ["docker", "cp", "iris_src/src/.", f"{container_name}:/tmp/src/"],
         capture_output=True,
     )
-    load_cmd = (
-        'Do $system.OBJ.Compile("Graph.KG.GraphIndex","ck-d")\n'
-        'Do $system.OBJ.LoadDir("/tmp/src","ck",.err,1)\n'
-        'Do $system.OBJ.Compile("Graph.KG.Edge","ck-d")\n'
-        'Do $system.OBJ.Compile("Graph.KG.TestEdge","ck-d")\n'
-        'H\n'
-    )
-    subprocess.run(
-        ["docker", "exec", "-i", container_name, "iris", "session", "IRIS", "-U", "USER"],
-        input=load_cmd,
-        capture_output=True,
-        text=True,
-        errors="replace",
-        timeout=120,
-    )
-    for _cls in [
-        "Graph.KG.ArnoAccel",
-        "Graph.KG.TraversalBuild", "Graph.KG.TraversalBFS",
-        "Graph.KG.TraversalPaths", "Graph.KG.TraversalKHop", "Graph.KG.Traversal",
-        "Graph.KG.NKGAccelLoader", "Graph.KG.NKGAccelAdjacency",
-        "Graph.KG.NKGAccelTraversal", "Graph.KG.NKGAccelCentrality", "Graph.KG.NKGAccel",
-    ]:
+    # Load each .cls file individually with "ck-d" (no background workers).
+    # Community Edition is limited to 2 CPU cores; LoadDir with parallel compilation
+    # fails with ERROR #7802 on machines with many cores because the IRIS work queue
+    # manager spawns more background jobs than the CE license allows.
+    # Loading files one at a time avoids the worker queue entirely.
+    import glob as _glob
+    cls_files = sorted(_glob.glob("iris_src/src/**/*.cls", recursive=True))
+    for cls_file in cls_files:
+        # Get the container path relative to /tmp/src/
+        rel = os.path.relpath(cls_file, "iris_src/src").replace(os.sep, "/")
         subprocess.run(
             ["docker", "exec", "-i", container_name, "iris", "session", "IRIS", "-U", "USER"],
-            input=f'Do $system.OBJ.Compile("{_cls}","cdk")\nH\n',
+            input=f'Do $system.OBJ.Load("/tmp/src/{rel}","ck-d")\nH\n',
             capture_output=True, text=True, timeout=30,
         )
 
@@ -53,14 +41,34 @@ def _deploy_objectscript(container_name: str) -> None:
 @pytest.fixture(scope="session")
 def iris_test_container():
     from iris_devtester import IRISContainer
+    import subprocess as _sp
+
+    # Candidate names to try in order before starting a new container.
+    # "iris_vector_graph" is the docker-compose service name; it's a valid
+    # Community container even though it differs from the default fixture name.
+    _FALLBACK_NAMES = ["iris_vector_graph"]
 
     attached = False
+    container = None
+
+    # 1. Try the configured name.
     try:
         container = IRISContainer.attach(_GQS_CONTAINER)
         attached = True
         logger.info("Attached to existing container: %s", _GQS_CONTAINER)
     except Exception:
-        import subprocess as _sp
+        pass
+
+    # 2. If not found, skip rather than start a new container —
+    #    unless IVG_AUTO_START_CONTAINER=1 (default when running in CI).
+    if container is None:
+        auto_start = os.environ.get("IVG_AUTO_START_CONTAINER", "0") not in ("0", "false", "no")
+        if not auto_start:
+            pytest.skip(
+                f"IRIS container '{_GQS_CONTAINER}' not running. "
+                f"Start with: scripts/test-container.sh up  "
+                f"(or set IVG_TEST_CONTAINER=ivg-iris-enterprise for enterprise container)"
+            )
         _sp.run(["docker", "rm", "-f", _GQS_CONTAINER], capture_output=True)
         logger.info("Starting fresh Community IRIS container: %s", _GQS_CONTAINER)
         container = (

iris_vector_graph-2.2.0/tests/integration/test_sql_parameterization.py

@@ -0,0 +1,80 @@
+"""Integration tests for SQL parameterization of BM25/retrieve/IVF procedures.
+
+Runs against a live IRIS instance to verify that the parameterized SQL produced
+by the Cypher translator executes correctly — no syntax errors from parameterization,
+and no injection risk from special characters in query text.
+
+Requires: ivg-iris or ivg-iris-enterprise container running.
+"""
+from __future__ import annotations
+
+import pytest
+
+
+@pytest.mark.parametrize("cypher,desc", [
+    (
+        "CALL ivg.bm25.search('nonexistent_idx', 'heart failure', 5) YIELD node RETURN node",
+        "bm25 with normal query text",
+    ),
+    (
+        "CALL ivg.bm25.search('nonexistent_idx', 'query with spaces and numbers 123', 3) YIELD node RETURN node",
+        "bm25 with spaces and numbers",
+    ),
+])
+def test_bm25_parameterized_executes_on_iris(iris_connection, cypher, desc):
+    """BM25 queries with parameterized args should execute without SQL errors."""
+    from iris_vector_graph.engine import IRISGraphEngine
+    engine = IRISGraphEngine(iris_connection)
+    # Will error on SQL syntax/parse if parameterization broke the query structure.
+    # Empty result is fine — index likely doesn't exist in test DB.
+    try:
+        result = engine.execute_cypher(cypher)
+        # Empty result or rows — both acceptable; no exception = parameterization worked
+        assert result is not None
+    except Exception as e:
+        err = str(e).lower()
+        # "index not found" or "table not found" are acceptable — means SQL was valid
+        # but the BM25 index/function doesn't exist in the test DB.
+        if any(x in err for x in ["not found", "does not exist", "unknown function",
+                                    "no such", "sqlcode", "undefined"]):
+            pytest.skip(f"BM25 function not available in test IRIS: {e}")
+        raise
+
+
+def test_retrieve_parameterized_executes_on_iris(iris_connection):
+    """ivg.retrieve with parameterized query text should not cause SQL injection."""
+    from iris_vector_graph.engine import IRISGraphEngine
+    engine = IRISGraphEngine(iris_connection)
+    cypher = "CALL ivg.retrieve('test query text', 3) YIELD node RETURN node"
+    try:
+        result = engine.execute_cypher(cypher)
+        assert result is not None
+    except Exception as e:
+        err = str(e).lower()
+        if any(x in err for x in ["not found", "does not exist", "unknown function",
+                                    "no such", "sqlcode", "undefined"]):
+            pytest.skip(f"BM25/vector function not available in test IRIS: {e}")
+        raise
+
+
+def test_injection_attempt_safe_on_iris(iris_connection):
+    """Single-quote injection in BM25 query text must not cause SQL errors."""
+    from iris_vector_graph.engine import IRISGraphEngine
+    engine = IRISGraphEngine(iris_connection)
+    # This would cause SQL errors if interpolated inline; with ? binding it's safe.
+    cypher = "CALL ivg.bm25.search('idx', 'it\\'s a test query', 5) YIELD node RETURN node"
+    try:
+        result = engine.execute_cypher(cypher)
+        assert result is not None
+    except Exception as e:
+        err = str(e).lower()
+        # Acceptable: function not found. NOT acceptable: syntax error from injection.
+        if "syntax" in err or "parse" in err:
+            raise AssertionError(
+                f"SQL injection via single-quote produced a syntax error — "
+                f"parameterization failed: {e}"
+            ) from e
+        if any(x in err for x in ["not found", "does not exist", "unknown function",
+                                    "no such", "sqlcode", "undefined"]):
+            pytest.skip(f"BM25 function not available in test IRIS: {e}")
+        raise