iris-vector-graph 1.94.0__tar.gz → 1.95.0__tar.gz

{iris_vector_graph-1.94.0 → iris_vector_graph-1.95.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iris-vector-graph
-Version: 1.94.0
+Version: 1.95.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
@@ -188,17 +188,19 @@ The single 2025.1 failure: `SKIP` clause uses `ORDER BY + OFFSET` on JSON_TABLE-
 
 Two live demos ship in `src/iris_demo_server/`:
 
-| Demo | URL | What it shows |
-|------|-----|--------------|
-| **Fraud Detection** | `http://localhost:8200/fraud` | Real-time fraud scoring, bitemporal audit trails, ring pattern detection |
-| **Biomedical Research** | `http://localhost:8200/bio` | Protein similarity search, pathway traversal, D3 network visualization |
+| Demo | URL | What it shows | Docs |
+|------|-----|--------------|------|
+| **Fraud Detection** | `http://localhost:8200/fraud` | Real-time fraud scoring, ring detection, money mule identification, bitemporal audit trails | [docs/demos/FRAUD_DEMO.md](docs/demos/FRAUD_DEMO.md) |
+| **Biomedical Research** | `http://localhost:8200/bio` | Protein similarity search, pathway traversal, hybrid vector+graph queries, D3 network visualization | [docs/demos/BIOMEDICAL_DEMO.md](docs/demos/BIOMEDICAL_DEMO.md) |
+
+The fraud demo is inspired by the [AWS Neptune fraud graph reference notebook](https://github.com/aws/graph-notebook/blob/main/src/graph_notebook/notebooks/01-Neptune-Database/03-Sample-Applications/01-Fraud-Graphs/01-Building-a-Fraud-Graph-Application.ipynb) — the same fraud ring and identity theft patterns (first-party and third-party fraud on credit card transaction data), running on IRIS with Cypher instead of Gremlin.
 
 ```bash
 # 1. Start IRIS
 docker compose up -d
 
 # 2. Install deps (once)
-pip install iris-vector-graph[full]
+pip install "iris-vector-graph[full]"
 
 # 3. Start demo server
 python -m uvicorn iris_demo_server.app:app --port 8200 --host 127.0.0.1 \
@@ -208,7 +210,7 @@ python -m uvicorn iris_demo_server.app:app --port 8200 --host 127.0.0.1 \
 open http://localhost:8200
 ```
 
-The demos use the generic IVG graph engine — no separate backend required. All data is created by the demo on first run.
+The demos use the generic IVG graph engine — no separate backend required.
 
 ---
 
@@ -1252,6 +1254,34 @@ Four openCypher gaps closed, all from structured gap analysis against the openCy
 
 ## Changelog
 
+### v1.95.0 (2026-05-15)
+
+**Admin API** — IVG now has a production-grade admin surface matching Neo4j/ArangoDB:
+
+**Fixed: `SHOW INDEXES` / `SHOW CONSTRAINTS`** — were empty stubs; now return actual BM25, IVF, HNSW, PLAID, ^KG, ^NKG indexes and uniqueness constraints. Neo4j Browser, LangChain, and all Neo4j-compatible tools now see the real index state on connect.
+
+**New REST endpoints on the Cypher API:**
+- `GET /schema` — labels, relationship types, property keys, counts
+- `GET /indexes` — full index inventory (all types)
+- `GET /server` — IVG version, IRIS version, namespace, schema status, BFS path
+- `GET /metrics` — Prometheus-format metrics (node/edge/embedding counts, status)
+- `GET /stats` — counts by label, predicate, embedding coverage
+- `POST /admin/schema/init` — initialize schema
+- `POST /admin/indexes/rebuild` — rebuild ^KG and ^NKG adjacency indexes
+- `POST /admin/embed` — trigger node embedding
+- `POST /admin/load` — stream NDJSON graph data
+- `GET /admin/export` — export graph as NDJSON
+- `POST /admin/snapshot` — save snapshot to disk
+- `GET /admin/queries` — list active IRIS queries
+- `DELETE /admin/queries/{id}` — kill a running query
+- `POST /admin/explain` — translate Cypher to SQL (debugging + optimization)
+
+**GraphStore protocol additions** (6 new methods):
+`get_node_count()`, `get_edge_count()`, `get_labels()`, `get_relationship_types()`, `list_indexes()`, `server_info()`
+
+**Engine additions:**
+`engine.list_active_queries()`, `engine.kill_query(id)`
+
 ### v1.94.0 (2026-05-15)
 
 **GraphStore Protocol** — `IRISGraphEngine` now has a pluggable storage backend (spec 156).

{iris_vector_graph-1.94.0 → iris_vector_graph-1.95.0}/README.md

@@ -116,17 +116,19 @@ The single 2025.1 failure: `SKIP` clause uses `ORDER BY + OFFSET` on JSON_TABLE-
 
 Two live demos ship in `src/iris_demo_server/`:
 
-| Demo | URL | What it shows |
-|------|-----|--------------|
-| **Fraud Detection** | `http://localhost:8200/fraud` | Real-time fraud scoring, bitemporal audit trails, ring pattern detection |
-| **Biomedical Research** | `http://localhost:8200/bio` | Protein similarity search, pathway traversal, D3 network visualization |
+| Demo | URL | What it shows | Docs |
+|------|-----|--------------|------|
+| **Fraud Detection** | `http://localhost:8200/fraud` | Real-time fraud scoring, ring detection, money mule identification, bitemporal audit trails | [docs/demos/FRAUD_DEMO.md](docs/demos/FRAUD_DEMO.md) |
+| **Biomedical Research** | `http://localhost:8200/bio` | Protein similarity search, pathway traversal, hybrid vector+graph queries, D3 network visualization | [docs/demos/BIOMEDICAL_DEMO.md](docs/demos/BIOMEDICAL_DEMO.md) |
+
+The fraud demo is inspired by the [AWS Neptune fraud graph reference notebook](https://github.com/aws/graph-notebook/blob/main/src/graph_notebook/notebooks/01-Neptune-Database/03-Sample-Applications/01-Fraud-Graphs/01-Building-a-Fraud-Graph-Application.ipynb) — the same fraud ring and identity theft patterns (first-party and third-party fraud on credit card transaction data), running on IRIS with Cypher instead of Gremlin.
 
 ```bash
 # 1. Start IRIS
 docker compose up -d
 
 # 2. Install deps (once)
-pip install iris-vector-graph[full]
+pip install "iris-vector-graph[full]"
 
 # 3. Start demo server
 python -m uvicorn iris_demo_server.app:app --port 8200 --host 127.0.0.1 \
@@ -136,7 +138,7 @@ python -m uvicorn iris_demo_server.app:app --port 8200 --host 127.0.0.1 \
 open http://localhost:8200
 ```
 
-The demos use the generic IVG graph engine — no separate backend required. All data is created by the demo on first run.
+The demos use the generic IVG graph engine — no separate backend required.
 
 ---
 
@@ -1180,6 +1182,34 @@ Four openCypher gaps closed, all from structured gap analysis against the openCy
 
 ## Changelog
 
+### v1.95.0 (2026-05-15)
+
+**Admin API** — IVG now has a production-grade admin surface matching Neo4j/ArangoDB:
+
+**Fixed: `SHOW INDEXES` / `SHOW CONSTRAINTS`** — were empty stubs; now return actual BM25, IVF, HNSW, PLAID, ^KG, ^NKG indexes and uniqueness constraints. Neo4j Browser, LangChain, and all Neo4j-compatible tools now see the real index state on connect.
+
+**New REST endpoints on the Cypher API:**
+- `GET /schema` — labels, relationship types, property keys, counts
+- `GET /indexes` — full index inventory (all types)
+- `GET /server` — IVG version, IRIS version, namespace, schema status, BFS path
+- `GET /metrics` — Prometheus-format metrics (node/edge/embedding counts, status)
+- `GET /stats` — counts by label, predicate, embedding coverage
+- `POST /admin/schema/init` — initialize schema
+- `POST /admin/indexes/rebuild` — rebuild ^KG and ^NKG adjacency indexes
+- `POST /admin/embed` — trigger node embedding
+- `POST /admin/load` — stream NDJSON graph data
+- `GET /admin/export` — export graph as NDJSON
+- `POST /admin/snapshot` — save snapshot to disk
+- `GET /admin/queries` — list active IRIS queries
+- `DELETE /admin/queries/{id}` — kill a running query
+- `POST /admin/explain` — translate Cypher to SQL (debugging + optimization)
+
+**GraphStore protocol additions** (6 new methods):
+`get_node_count()`, `get_edge_count()`, `get_labels()`, `get_relationship_types()`, `list_indexes()`, `server_info()`
+
+**Engine additions:**
+`engine.list_active_queries()`, `engine.kill_query(id)`
+
 ### v1.94.0 (2026-05-15)
 
 **GraphStore Protocol** — `IRISGraphEngine` now has a pluggable storage backend (spec 156).

{iris_vector_graph-1.94.0 → iris_vector_graph-1.95.0}/iris_vector_graph/__init__.py

@@ -10,6 +10,7 @@ from .result import IVGResult
 from .capabilities import IRISCapabilities
 from .store_protocol import GraphStore
 from .stores import IRISGraphStore
+from .cypher.aql import translate_aql, AQLParseError, AQLTranslationError
 from ._validate import (
     NodeIdInput, EdgeInput, CypherInput,
     IVFBuildInput, VectorSearchInput,
@@ -76,4 +77,7 @@ __all__ = [
     "GetPatientKGNeighborhoodTool",
     "GraphStore",
     "IRISGraphStore",
+    "translate_aql",
+    "AQLParseError",
+    "AQLTranslationError",
 ]

iris_vector_graph-1.95.0/iris_vector_graph/cypher/aql/__init__.py

@@ -0,0 +1,28 @@
+from typing import Optional
+
+
+class AQLParseError(Exception):
+    def __init__(self, message: str, line: int = 0, column: int = 0):
+        self.message = message
+        self.line = line
+        self.column = column
+        super().__init__(f"AQL syntax error at line {line}, col {column}: {message}")
+
+
+class AQLTranslationError(Exception):
+    def __init__(self, message: str, aql_construct: str = ""):
+        self.message = message
+        self.aql_construct = aql_construct
+        detail = f" ({aql_construct})" if aql_construct else ""
+        super().__init__(f"AQL translation error{detail}: {message}")
+
+
+def translate_aql(aql: str, bind_vars: Optional[dict] = None) -> tuple:
+    from iris_vector_graph.cypher.aql.lexer import AQLLexer
+    from iris_vector_graph.cypher.aql.parser import AQLParser
+    from iris_vector_graph.cypher.aql.translator import AQLTranslator
+    tokens = AQLLexer(aql).tokenize()
+    aql_ast = AQLParser(tokens).parse()
+    translator = AQLTranslator()
+    cypher_str, resolved_params = translator.translate_to_cypher(aql_ast, bind_vars or {})
+    return cypher_str, resolved_params

iris_vector_graph-1.95.0/iris_vector_graph/cypher/aql/ast.py

@@ -0,0 +1,148 @@
+import enum
+from dataclasses import dataclass, field
+from typing import Any, Optional, Union
+
+
+class AQLDirection(enum.Enum):
+    OUTBOUND = "OUTBOUND"
+    INBOUND = "INBOUND"
+    ANY = "ANY"
+
+
+@dataclass(slots=True)
+class AQLVariable:
+    name: str
+
+
+@dataclass(slots=True)
+class AQLPropertyAccess:
+    object: Any
+    property: str
+
+
+@dataclass(slots=True)
+class AQLKeyAccess:
+    object: Any
+    key: str
+
+
+@dataclass(slots=True)
+class AQLBindVar:
+    name: str
+
+
+@dataclass(slots=True)
+class AQLLiteral:
+    value: Any
+
+
+@dataclass(slots=True)
+class AQLBinaryOp:
+    operator: str
+    left: Any
+    right: Any
+
+
+@dataclass(slots=True)
+class AQLUnaryOp:
+    operator: str
+    operand: Any
+
+
+@dataclass(slots=True)
+class AQLFunctionCall:
+    name: str
+    args: list = field(default_factory=list)
+
+
+@dataclass(slots=True)
+class AQLObjectLiteral:
+    fields: dict = field(default_factory=dict)
+
+
+@dataclass(slots=True)
+class AQLArrayLiteral:
+    items: list = field(default_factory=list)
+
+
+AQLExpression = Union[
+    AQLVariable, AQLPropertyAccess, AQLKeyAccess, AQLBindVar, AQLLiteral,
+    AQLBinaryOp, AQLUnaryOp, AQLFunctionCall, AQLObjectLiteral, AQLArrayLiteral
+]
+
+
+@dataclass(slots=True)
+class ForClause:
+    vertex_var: str
+    edge_var: Optional[str]
+    path_var: Optional[str]
+    min_depth: int
+    max_depth: int
+    direction: AQLDirection
+    start_expr: Any
+    graph_or_collections: list
+    is_graph: bool
+
+
+@dataclass(slots=True)
+class ShortestPathClause:
+    vertex_var: str
+    edge_var: Optional[str]
+    direction: AQLDirection
+    start_expr: Any
+    end_expr: Any
+    graph_or_collections: list
+    is_graph: bool
+
+
+@dataclass(slots=True)
+class FilterClause:
+    condition: Any
+
+
+@dataclass(slots=True)
+class LetClause:
+    variable: str
+    value: Any
+
+
+@dataclass(slots=True)
+class CollectClause:
+    assignments: list
+    with_count_into: Optional[str]
+    aggregate: list
+    into_var: Optional[str]
+
+
+@dataclass(slots=True)
+class SortItem:
+    expression: Any
+    ascending: bool
+
+
+@dataclass(slots=True)
+class SortClause:
+    items: list
+
+
+@dataclass(slots=True)
+class LimitClause:
+    offset: Optional[int]
+    count: int
+
+
+@dataclass(slots=True)
+class ReturnClause:
+    distinct: bool
+    expression: Any
+
+
+@dataclass(slots=True)
+class AQLQuery:
+    for_clause: Any
+    filter_clauses: list = field(default_factory=list)
+    let_clauses: list = field(default_factory=list)
+    collect_clause: Optional[Any] = None
+    sort_clause: Optional[Any] = None
+    limit_clause: Optional[Any] = None
+    return_clause: Optional[Any] = None

iris_vector_graph-1.95.0/iris_vector_graph/cypher/aql/lexer.py

@@ -0,0 +1,190 @@
+import enum
+from dataclasses import dataclass
+
+
+class AQLTokenType(enum.Enum):
+    FOR = "FOR"; IN = "IN"; OUTBOUND = "OUTBOUND"; INBOUND = "INBOUND"; ANY = "ANY"
+    RETURN = "RETURN"; FILTER = "FILTER"; LET = "LET"; SORT = "SORT"; LIMIT = "LIMIT"
+    COLLECT = "COLLECT"; WITH = "WITH"; COUNT = "COUNT"; INTO = "INTO"; GRAPH = "GRAPH"
+    SHORTEST_PATH = "SHORTEST_PATH"; K_SHORTEST_PATHS = "K_SHORTEST_PATHS"; K_PATHS = "K_PATHS"
+    TO = "TO"; DISTINCT = "DISTINCT"; ASC = "ASC"; DESC = "DESC"
+    AND = "AND"; OR = "OR"; NOT = "NOT"; NULL = "NULL"; TRUE = "TRUE"; FALSE = "FALSE"
+    ALL = "ALL"; AGGREGATE = "AGGREGATE"; SEARCH = "SEARCH"
+    INSERT = "INSERT"; UPDATE = "UPDATE"; REMOVE = "REMOVE"; UPSERT = "UPSERT"
+    REPLACE = "REPLACE"; WINDOW = "WINDOW"
+    IDENT = "IDENT"; INT = "INT"; FLOAT = "FLOAT"; STRING = "STRING"
+    BIND_VAR = "BIND_VAR"; DYN_COLLECTION = "DYN_COLLECTION"
+    RANGE = ".."; EQ = "=="; NEQ = "!="; LTE = "<="; GTE = ">="; LT = "<"; GT = ">"
+    REGEX_MATCH = "=~"; REGEX_NOTMATCH = "!~"; ASSIGN = "="
+    PLUS = "+"; MINUS = "-"; MUL = "*"; DIV = "/"; MOD = "%"
+    DOT = "."; COMMA = ","; COLON = ":"; LPAREN = "("; RPAREN = ")"
+    LBRACKET = "["; RBRACKET = "]"; LBRACE = "{"; RBRACE = "}"; QUESTION = "?"
+    EOF = "EOF"
+
+
+_KW = {t.value: t for t in AQLTokenType
+       if t.value.replace('_', '').isalpha() and t not in (
+           AQLTokenType.IDENT, AQLTokenType.EOF)}
+
+
+@dataclass(slots=True)
+class AQLToken:
+    kind: AQLTokenType
+    value: str
+    line: int
+    column: int
+
+
+class AQLLexer:
+    def __init__(self, source: str):
+        self._src = self._strip_comments(source)
+        self._pos = 0
+        self._line = 1
+        self._col = 1
+
+    @staticmethod
+    def _strip_comments(src: str) -> str:
+        result = []
+        i = 0
+        while i < len(src):
+            if src[i:i+2] == "/*":
+                end = src.find("*/", i + 2)
+                if end == -1:
+                    break
+                result.append('\n' * src[i:end+2].count('\n'))
+                i = end + 2
+            elif src[i:i+2] == "//":
+                end = src.find('\n', i)
+                result.append('\n')
+                i = (end + 1) if end != -1 else len(src)
+            else:
+                result.append(src[i])
+                i += 1
+        return ''.join(result)
+
+    def _peek(self, offset: int = 0) -> str:
+        p = self._pos + offset
+        return self._src[p] if p < len(self._src) else ''
+
+    def _advance(self) -> str:
+        ch = self._src[self._pos]; self._pos += 1
+        if ch == '\n': self._line += 1; self._col = 1
+        else: self._col += 1
+        return ch
+
+    def _tok(self, kind: AQLTokenType, value: str, line: int, col: int) -> AQLToken:
+        return AQLToken(kind=kind, value=value, line=line, column=col)
+
+    def tokenize(self) -> list:
+        tokens = []
+        while self._pos < len(self._src):
+            while self._pos < len(self._src) and self._src[self._pos] in ' \t\r\n':
+                self._advance()
+            if self._pos >= len(self._src):
+                break
+            line, col = self._line, self._col
+            ch = self._peek()
+
+            if ch == '@':
+                self._advance()
+                if self._peek() == '@':
+                    self._advance()
+                    tokens.append(self._tok(AQLTokenType.DYN_COLLECTION, '@@' + self._read_ident(), line, col))
+                else:
+                    tokens.append(self._tok(AQLTokenType.BIND_VAR, '@' + self._read_ident(), line, col))
+
+            elif ch.isdigit():
+                tokens.append(self._read_number(line, col))
+
+            elif ch in ('"', "'", '`'):
+                tokens.append(self._read_string(line, col))
+
+            elif ch.isalpha() or ch == '_':
+                word = self._read_ident()
+                upper = word.upper()
+                kind = _KW.get(upper, AQLTokenType.IDENT)
+                tokens.append(self._tok(kind, word, line, col))
+
+            elif ch == '.' and self._peek(1) == '.':
+                self._advance(); self._advance()
+                tokens.append(self._tok(AQLTokenType.RANGE, '..', line, col))
+
+            elif ch == '.':
+                self._advance()
+                tokens.append(self._tok(AQLTokenType.DOT, '.', line, col))
+
+            elif ch == '=' and self._peek(1) == '~':
+                self._advance(); self._advance()
+                tokens.append(self._tok(AQLTokenType.REGEX_MATCH, '=~', line, col))
+
+            elif ch == '!' and self._peek(1) == '~':
+                self._advance(); self._advance()
+                tokens.append(self._tok(AQLTokenType.REGEX_NOTMATCH, '!~', line, col))
+
+            elif ch == '=' and self._peek(1) == '=':
+                self._advance(); self._advance()
+                tokens.append(self._tok(AQLTokenType.EQ, '==', line, col))
+
+            elif ch == '!' and self._peek(1) == '=':
+                self._advance(); self._advance()
+                tokens.append(self._tok(AQLTokenType.NEQ, '!=', line, col))
+
+            elif ch == '<' and self._peek(1) == '=':
+                self._advance(); self._advance()
+                tokens.append(self._tok(AQLTokenType.LTE, '<=', line, col))
+
+            elif ch == '>' and self._peek(1) == '=':
+                self._advance(); self._advance()
+                tokens.append(self._tok(AQLTokenType.GTE, '>=', line, col))
+
+            elif ch in '<>=!+-*/%,:()[]{}?':
+                m = {'<': AQLTokenType.LT, '>': AQLTokenType.GT, '=': AQLTokenType.ASSIGN,
+                     '+': AQLTokenType.PLUS, '-': AQLTokenType.MINUS, '*': AQLTokenType.MUL,
+                     '/': AQLTokenType.DIV, '%': AQLTokenType.MOD, ',': AQLTokenType.COMMA,
+                     ':': AQLTokenType.COLON, '(': AQLTokenType.LPAREN, ')': AQLTokenType.RPAREN,
+                     '[': AQLTokenType.LBRACKET, ']': AQLTokenType.RBRACKET,
+                     '{': AQLTokenType.LBRACE, '}': AQLTokenType.RBRACE, '?': AQLTokenType.QUESTION}
+                if ch in m:
+                    self._advance()
+                    tokens.append(self._tok(m[ch], ch, line, col))
+                else:
+                    self._advance()
+            else:
+                self._advance()
+
+        tokens.append(AQLToken(AQLTokenType.EOF, '', self._line, self._col))
+        return tokens
+
+    def _read_ident(self) -> str:
+        start = self._pos
+        while self._pos < len(self._src) and (self._src[self._pos].isalnum() or self._src[self._pos] == '_'):
+            self._advance()
+        return self._src[start:self._pos]
+
+    def _read_number(self, line: int, col: int) -> AQLToken:
+        start = self._pos
+        while self._pos < len(self._src) and self._src[self._pos].isdigit():
+            self._advance()
+        if (self._pos < len(self._src) and self._src[self._pos] == '.' and
+                (self._pos + 1 >= len(self._src) or self._src[self._pos + 1] != '.')):
+            self._advance()
+            while self._pos < len(self._src) and self._src[self._pos].isdigit():
+                self._advance()
+            return AQLToken(AQLTokenType.FLOAT, self._src[start:self._pos], line, col)
+        return AQLToken(AQLTokenType.INT, self._src[start:self._pos], line, col)
+
+    def _read_string(self, line: int, col: int) -> AQLToken:
+        quote = self._advance()
+        chars = []
+        while self._pos < len(self._src):
+            ch = self._src[self._pos]
+            if ch == '\\' and quote != '`':
+                self._advance()
+                esc = self._advance()
+                chars.append({'n': '\n', 't': '\t', 'r': '\r', '\\': '\\',
+                               '"': '"', "'": "'"}.get(esc, esc))
+            elif ch == quote:
+                self._advance(); break
+            else:
+                chars.append(self._advance())
+        return AQLToken(AQLTokenType.STRING, ''.join(chars), line, col)