iris-vector-graph 4.1.1__tar.gz → 4.2.0__tar.gz

{iris_vector_graph-4.1.1 → iris_vector_graph-4.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: iris-vector-graph
-Version: 4.1.1
+Version: 4.2.0
 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

iris_vector_graph-4.2.0/iris_src/src/Graph/KG/AlgoCache.cls

@@ -0,0 +1,68 @@
+/// Graph.KG.AlgoCache - the shared result cache for graph-wide algorithms (spec 236).
+///
+///   ^IVG.AlgoCache(graphKey, algorithm, paramHash) = $ListBuild(token, payload)
+///
+/// `token` is ^KG("__version") as read BEFORE the answer was computed, so a write that
+/// lands during the computation leaves the entry stale and never wrongly fresh. Every
+/// read compares it with the current value; a mismatch is a miss. The graph key comes
+/// from Graph.KG.GraphKey.ForIndex (ADR-0003), the same subscript ^KG uses, never the
+/// ledger's form.
+///
+/// Kept out of ^KG so that Kill ^KG cannot take it along: the token comparison would
+/// still catch the stale entry, but a cache that outlives its graph is a cache that can
+/// be read by mistake (ADR-0004). Erase paths kill it too (Graph.KG.Eraser).
+Class Graph.KG.AlgoCache Extends %RegisteredObject
+{
+
+/// The current graph-version token. 0 when nothing has ever written the graph.
+ClassMethod Token() As %Integer
+{
+	Quit +$Get(^KG("__version"), 0)
+}
+
+/// One round trip for both outcomes: "H<token>|<payload>" when the stored token equals
+/// the current one, otherwise "M<token>". The token is the one the caller hands back to
+/// Put after it has computed the answer (on a miss), or validates a front copy against
+/// (on a hit).
+ClassMethod Lookup(pGraph As %String = "", pAlgorithm As %String, pParamHash As %String) As %String
+{
+	Set tToken = ..Token()
+	Set tKey = ##class(Graph.KG.GraphKey).ForIndex(pGraph)
+	Set tEntry = $Get(^IVG.AlgoCache(tKey, pAlgorithm, pParamHash))
+	If (tEntry '= "") && ($ListGet(tEntry, 1) = tToken) {
+		Quit "H" _ tToken _ "|" _ $ListGet(tEntry, 2)
+	}
+	Quit "M" _ tToken
+}
+
+/// The payload when the entry is current, otherwise "".
+ClassMethod Get(pGraph As %String = "", pAlgorithm As %String, pParamHash As %String) As %String
+{
+	Set tOut = ..Lookup(pGraph, pAlgorithm, pParamHash)
+	Quit $Select($Extract(tOut) = "H": $Extract(tOut, $Find(tOut, "|"), *), 1: "")
+}
+
+/// Store an answer under the token read before it was computed.
+ClassMethod Put(pGraph As %String = "", pAlgorithm As %String, pParamHash As %String, pToken As %Integer, pPayload As %String) As %Integer
+{
+	Set tKey = ##class(Graph.KG.GraphKey).ForIndex(pGraph)
+	Set ^IVG.AlgoCache(tKey, pAlgorithm, pParamHash) = $ListBuild(+pToken, pPayload)
+	Quit 1
+}
+
+/// Drop every entry of one graph.
+ClassMethod InvalidateGraph(pGraph As %String = "") As %Integer
+{
+	Set tKey = ##class(Graph.KG.GraphKey).ForIndex(pGraph)
+	Kill ^IVG.AlgoCache(tKey)
+	Quit 1
+}
+
+/// Drop every entry of every graph.
+ClassMethod InvalidateAll() As %Integer
+{
+	Kill ^IVG.AlgoCache
+	Quit 1
+}
+
+}

{iris_vector_graph-4.1.1 → iris_vector_graph-4.2.0}/iris_src/src/Graph/KG/ArnoAccel.cls

@@ -8,6 +8,9 @@ Class Graph.KG.ArnoAccel Extends %RegisteredObject
 
 ClassMethod Load(libPath As %String = "/tmp/libarno_callout.so") As %Boolean
 {
+	// The library's init entry moves the process to USER. Put it back: every step after
+	// a Load would otherwise run against USER (spec 236 R3).
+	Set tNs = $NAMESPACE
 	Try {
 		Set dllid = $ZF(-4, 1, libPath)
 		If dllid = 0 Return 0
@@ -19,8 +22,10 @@ ClassMethod Load(libPath As %String = "/tmp/libarno_callout.so") As %Boolean
 		}
 		Set initfid = ^ArnoAccel("fid", "init")
 		Do $ZF(-5, dllid, initfid)
+		Set $NAMESPACE = tNs
 		Return 1
 	} Catch {
+		Set $NAMESPACE = tNs
 		Return 0
 	}
 }
@@ -56,11 +61,92 @@ ClassMethod CallFn(fn As %String, a1 As %String = "", a2 As %String = "", a3 As
 	Return $ZF(-5, dllid, fid, a1, a2, a3, a4)
 }
 
+/// Reader revisions of the loaded callout build, as a JSON object {"<reader>": <int>}.
+/// "{}" when no library is loaded in this process, the build predates the
+/// `capabilities` entry (1.0.x: the lookup throws <ILLEGAL VALUE>, not 0), or the report
+/// is not JSON. Never throws. Reuses the handle Load recorded; loads nothing itself.
+ClassMethod ReaderRevisions() As %String
+{
+	Set tOut = "{}"
+	Try {
+		Set tId = $Get(^ArnoAccel("dllid"), 0)
+		If tId '= 0 {
+			Set tFn = $ZF(-4, 3, tId, "capabilities")
+			If tFn '= 0 {
+				Set tObj = {}.%FromJSON($ZF(-5, tId, tFn))
+				If $IsObject(tObj.readers) Set tOut = tObj.readers.%ToJSON()
+			}
+		}
+	} Catch tEx {
+		Set tOut = "{}"
+	}
+	Quit tOut
+}
+
+/// The loaded build's version string ("arno-callout X.Y.Z+<sha>"), "" when none is loaded.
+/// For logs and the proof file; routing never reads it.
+ClassMethod LibraryVersion() As %String
+{
+	Set tOut = ""
+	Try {
+		Set tId = $Get(^ArnoAccel("dllid"), 0)
+		If tId '= 0 Set tOut = $ZF(-5, tId, $ZF(-4, 3, tId, "version"))
+	} Catch tEx {
+		Set tOut = ""
+	}
+	Quit tOut
+}
+
+/// Calls a Rust kg_*_global reader; an "ERROR..." answer is thrown so the caller falls
+/// back to its Owner.
+ClassMethod NativeResult(fn As %String, a1 As %String = "", a2 As %String = "", a3 As %String = "", a4 As %String = "") As %String [ Private ]
+{
+	// The readers walk USER's ^KG whatever namespace the caller is in, and leave the
+	// process in USER. Answering from them elsewhere would return another namespace's
+	// graph, so refuse and let the Owner answer.
+	If $NAMESPACE '= "USER" $$$ThrowStatus($$$ERROR($$$GeneralError, "arno "_fn_" reads USER only, not "_$NAMESPACE))
+	Set tResult = ..CallFn(fn, a1, a2, a3, a4)
+	If $Extract(tResult, 1, 5) = "ERROR" $$$ThrowStatus($$$ERROR($$$GeneralError, "arno "_fn_": "_tResult))
+	Quit tResult
+}
+
+/// The Rust readers. Routed to only when the proof file accepts the loaded revision
+/// (iris_vector_graph.arno_readers.route); the Owner-delegating *Json methods above
+/// are unchanged.
+ClassMethod PageRankNativeJson(damping As %Double = 0.85, maxIter As %Integer = 20) As %String
+{
+	Quit ..NativeResult("kg_pagerank_global", "^KG", damping, maxIter)
+}
+
+ClassMethod PPRNativeJson(seedJson As %String, damping As %Double = 0.85, maxIter As %Integer = 20) As %String
+{
+	Quit ..NativeResult("kg_ppr_global", "^KG", seedJson, damping, maxIter)
+}
+
+ClassMethod WCCNativeJson() As %String
+{
+	Quit ..NativeResult("kg_wcc_global", "^KG")
+}
+
+ClassMethod CDLPNativeJson(maxIter As %Integer = 10) As %String
+{
+	Quit ..NativeResult("kg_cdlp_global", "^KG", maxIter)
+}
+
+ClassMethod SubgraphNativeJson(seedJson As %String, hops As %Integer = 2, maxNodes As %Integer = 10000) As %String
+{
+	Quit ..NativeResult("kg_subgraph_global", "^KG", seedJson, hops, maxNodes)
+}
+
 /// Build and cache graph JSON in ^||ArnoKG.JSON.<gname>.graph_json.
 /// Called automatically before each algorithm invocation.
+///
+/// $Increment, not Set: it is atomic, so two writers never take the same value, and a
+/// rolled-back transaction does not undo it, so a value a reader has seen is never
+/// handed out again (spec 236, research-token-audit section 4.1).
 ClassMethod BumpVersion()
 {
-	Set ^KG("__version") = $Get(^KG("__version"), 0) + 1
+	Set tmp = $Increment(^KG("__version"))
 	Set tmp = $Increment(^NKG("$meta", "version"))
 }