trustgraph-base 2.10.0__tar.gz → 2.10.2__tar.gz

{trustgraph_base-2.10.0 → trustgraph_base-2.10.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trustgraph-base
-Version: 2.10.0
+Version: 2.10.2
 Summary: TrustGraph provides a means to run a pipeline of flexible AI processing components in a flexible means to achieve a processing pipeline.
 Author-email: "trustgraph.ai" <security@trustgraph.ai>
 Project-URL: Homepage, https://github.com/trustgraph-ai/trustgraph

{trustgraph_base-2.10.0 → trustgraph_base-2.10.2}/trustgraph/api/async_bulk_client.py

@@ -4,7 +4,7 @@ import websockets
 from typing import Optional, AsyncIterator, Dict, Any, Iterator
 
 from . types import Triple
-from . bulk_client import _string_to_term
+from . bulk_client import _value_to_term
 
 
 class AsyncBulkClient:
@@ -46,13 +46,9 @@ class AsyncBulkClient:
         async with websockets.connect(ws_url, ping_interval=20, ping_timeout=self.timeout) as websocket:
             async for triple in triples:
                 t = {
-                    "s": _string_to_term(triple.s),
-                    "p": _string_to_term(triple.p),
-                    "o": _string_to_term(
-                        triple.o,
-                        datatype=triple.o_datatype,
-                        language=triple.o_language,
-                    ),
+                    "s": _value_to_term(triple.s),
+                    "p": _value_to_term(triple.p),
+                    "o": _value_to_term(triple.o),
                 }
                 if triple.g:
                     t["g"] = triple.g

{trustgraph_base-2.10.0 → trustgraph_base-2.10.2}/trustgraph/api/async_flow.py

@@ -16,8 +16,8 @@ import base64
 from typing import Optional, Dict, Any, List
 
 from . types import TextCompletionResult, ImageToTextResult
-
 from . exceptions import ProtocolException, ApplicationException
+from .. base.serialization import dataclass_to_dict
 
 
 def check_error(response):
@@ -529,7 +529,8 @@ class AsyncFlowInstance:
 
     async def graph_rag(self, query: str, collection: str,
                         max_subgraph_size: int = 1000, max_subgraph_count: int = 5,
-                        max_entity_distance: int = 3, **kwargs: Any) -> str:
+                        max_entity_distance: int = 3,
+                        user_context=None, **kwargs: Any) -> str:
         """
         Execute graph-based RAG query (non-streaming).
 
@@ -572,6 +573,8 @@ class AsyncFlowInstance:
             "max-entity-distance": max_entity_distance,
             "streaming": False
         }
+        if user_context is not None:
+            request_data["user-context"] = dataclass_to_dict(user_context)
         request_data.update(kwargs)
 
         result = await self.request("graph-rag", request_data)
@@ -721,7 +724,8 @@ class AsyncFlowInstance:
 
         return await self.request("reranker", request_data)
 
-    async def triples_query(self, s=None, p=None, o=None, collection=None, limit=100, **kwargs: Any):
+    async def triples_query(self, s=None, p=None, o=None, collection=None, limit=100,
+                            user_context=None, **kwargs: Any):
         """
         Query RDF triples using pattern matching.
 
@@ -763,10 +767,43 @@ class AsyncFlowInstance:
             request_data["o"] = str(o)
         if collection is not None:
             request_data["collection"] = collection
+        if user_context is not None:
+            request_data["user-context"] = dataclass_to_dict(user_context)
         request_data.update(kwargs)
 
         return await self.request("triples", request_data)
 
+    async def sparql_query(self, query: str, collection: str = "default",
+                           limit: int = 10000, user_context=None,
+                           **kwargs: Any):
+        """
+        Execute a SPARQL query against the knowledge graph.
+
+        Args:
+            query: SPARQL 1.1 query string
+            collection: Collection identifier (default: "default")
+            limit: Safety limit on results (default: 10000)
+            user_context: Optional UserContext for policy-based filtering
+            **kwargs: Additional service-specific parameters
+
+        Returns:
+            dict: Query results depending on query type (SELECT, ASK,
+                CONSTRUCT, DESCRIBE)
+
+        Raises:
+            ApplicationException: If an error occurs
+        """
+        request_data = {
+            "query": query,
+            "collection": collection,
+            "limit": limit,
+        }
+        if user_context is not None:
+            request_data["user-context"] = dataclass_to_dict(user_context)
+        request_data.update(kwargs)
+
+        return await self.request("sparql", request_data)
+
     async def rows_query(self, query: str, collection: str, variables: Optional[Dict] = None,
                          operation_name: Optional[str] = None, **kwargs: Any):
         """

{trustgraph_base-2.10.0 → trustgraph_base-2.10.2}/trustgraph/api/bulk_client.py

@@ -11,23 +11,24 @@ import asyncio
 import websockets
 from typing import Optional, Iterator, Dict, Any, Coroutine
 
-from . types import Triple
+from . types import Triple, Uri, Literal
 from . exceptions import ProtocolException
 
 
-def _string_to_term(
-    value: str, datatype: str = "", language: str = ""
-) -> Dict[str, Any]:
-    """Convert a string value to Term format for the gateway."""
+def _value_to_term(value) -> Dict[str, Any]:
+    """Convert a Uri, Literal, or plain string to wire Term format."""
+    if isinstance(value, Uri):
+        return {"t": "i", "i": str(value)}
+    if isinstance(value, Literal):
+        result: Dict[str, Any] = {"t": "l", "v": str(value)}
+        if value.datatype:
+            result["dt"] = value.datatype
+        if value.language:
+            result["ln"] = value.language
+        return result
     if value.startswith("http://") or value.startswith("https://") or "://" in value:
         return {"t": "i", "i": value}
-    else:
-        result: Dict[str, Any] = {"t": "l", "v": value}
-        if datatype:
-            result["dt"] = datatype
-        if language:
-            result["ln"] = language
-        return result
+    return {"t": "l", "v": value}
 
 
 class BulkClient:
@@ -145,13 +146,9 @@ class BulkClient:
             batch = []
             for triple in triples:
                 t = {
-                    "s": _string_to_term(triple.s),
-                    "p": _string_to_term(triple.p),
-                    "o": _string_to_term(
-                        triple.o,
-                        datatype=triple.o_datatype,
-                        language=triple.o_language,
-                    ),
+                    "s": _value_to_term(triple.s),
+                    "p": _value_to_term(triple.p),
+                    "o": _value_to_term(triple.o),
                 }
                 if triple.g:
                     t["g"] = triple.g

{trustgraph_base-2.10.0 → trustgraph_base-2.10.2}/trustgraph/api/flow.py

@@ -11,6 +11,7 @@ import base64
 
 from .. knowledge import hash, Uri, Literal, QuotedTriple
 from .. schema import IRI, LITERAL, TRIPLE
+from .. base.serialization import dataclass_to_dict
 from . types import Triple, TextCompletionResult, ImageToTextResult
 from . exceptions import ProtocolException
 
@@ -406,6 +407,7 @@ class FlowInstance:
             entity_limit=50, triple_limit=30, max_subgraph_size=150,
             max_path_length=2, edge_score_limit=30, edge_limit=25,
             max_reranker_input=350,
+            user_context=None,
     ):
         """
         Execute graph-based Retrieval-Augmented Generation (RAG) query.
@@ -452,6 +454,9 @@ class FlowInstance:
             "max-reranker-input": max_reranker_input,
         }
 
+        if user_context is not None:
+            input["user-context"] = dataclass_to_dict(user_context)
+
         result = self.request(
             "service/graph-rag",
             input
@@ -772,7 +777,8 @@ class FlowInstance:
 
     def triples_query(
             self, s=None, p=None, o=None, g=None,
-            collection=None, limit=10000
+            collection=None, limit=10000,
+            user_context=None,
     ):
         """
         Query knowledge graph triples using pattern matching.
@@ -848,6 +854,9 @@ class FlowInstance:
         if g is not None:
             input["g"] = g
 
+        if user_context is not None:
+            input["user-context"] = dataclass_to_dict(user_context)
+
         object = self.request(
             "service/triples",
             input
@@ -1103,7 +1112,8 @@ class FlowInstance:
 
     def sparql_query(
             self, query,collection="default",
-            limit=10000
+            limit=10000,
+            user_context=None,
     ):
         """
         Execute a SPARQL query against the knowledge graph.
@@ -1129,6 +1139,9 @@ class FlowInstance:
             "limit": limit,
         }
 
+        if user_context is not None:
+            input["user-context"] = dataclass_to_dict(user_context)
+
         response = self.request("service/sparql", input)
 
         if "error" in response and response["error"]:

{trustgraph_base-2.10.0 → trustgraph_base-2.10.2}/trustgraph/api/types.py

@@ -8,7 +8,23 @@ graph elements, metadata structures, and streaming response chunks.
 import dataclasses
 import datetime
 from typing import List, Optional, Dict, Any
-from .. knowledge import hash, Uri, Literal
+
+class Literal(str):
+    def __new__(cls, value, datatype=None, language=None):
+        return str.__new__(cls, value)
+    def __init__(self, value, datatype=None, language=None):
+        self.datatype = datatype
+        self.language = language
+    def is_uri(self): return False
+    def is_literal(self): return True
+    def is_triple(self): return False
+
+class Uri(str):
+    def __init__(self, value):
+        str(value)
+    def is_uri(self): return True
+    def is_literal(self): return False
+    def is_triple(self): return False
 
 @dataclasses.dataclass
 class Triple:
@@ -19,17 +35,17 @@ class Triple:
         s: Subject (entity URI or value)
         p: Predicate (relationship URI)
         o: Object (entity URI, literal value, or typed value)
-        o_datatype: XSD datatype URI for literal objects (e.g. "xsd:string")
-        o_language: Language tag for literal objects (e.g. "en", "lt")
         g: Named graph URI (e.g. "urn:graph:catalog")
     """
-    s : str
-    p : str
-    o : str
-    o_datatype : str = ""
-    o_language : str = ""
+    s : Uri | str
+    p : Uri | str
+    o : Uri | Literal | str
     g : str = ""
 
+    def is_uri(self): return False
+    def is_literal(self): return False
+    def is_triple(self): return True
+
 @dataclasses.dataclass
 class ConfigKey:
     """

{trustgraph_base-2.10.0 → trustgraph_base-2.10.2}/trustgraph/base/__init__.py

@@ -46,6 +46,7 @@ from . keyword_index_client import KeywordIndexClientSpec, KeywordIndexClient
 from . row_embeddings_query_client import RowEmbeddingsQueryClientSpec
 from . collection_config_handler import CollectionConfigHandler
 from . audit_publisher import AuditPublisher
+from . policy_event_publisher import PolicyEventPublisher
 from . schema_compatibility import is_strict_mode_compatible
 from . async_backend import (
     AsyncPubSubBackend, AsyncBackendConsumer, AsyncBackendProducer, Message,

trustgraph_base-2.10.2/trustgraph/base/policy_event_publisher.py

@@ -0,0 +1,169 @@
+
+import json
+import logging
+from datetime import datetime, timezone
+from uuid import uuid4
+from collections import defaultdict
+
+from trustgraph.schema import PolicyEvent, policy_events_queue
+
+logger = logging.getLogger(__name__)
+
+NODE_IRI_CAP = 100
+
+
+class PolicyEventPublisher:
+
+    def __init__(self, component_name, async_backend=None):
+        self.component_name = component_name
+        self._handle = None
+        self._async_producer = None
+        self._async_backend = async_backend
+
+    async def start(self, sender_pool=None):
+        if sender_pool is not None:
+            self._handle = await sender_pool.add_producer(
+                topic=policy_events_queue,
+                schema=PolicyEvent,
+            )
+        elif self._async_backend is not None:
+            self._async_producer = (
+                await self._async_backend.create_producer(
+                    topic=policy_events_queue,
+                    schema=PolicyEvent,
+                )
+            )
+
+    async def stop(self):
+        if self._async_producer:
+            try:
+                await self._async_producer.close()
+            except BaseException:
+                pass
+            self._async_producer = None
+        if self._handle:
+            await self._handle.unregister()
+
+    async def emit(self, event_type, payload):
+        event = PolicyEvent(
+            schema_version=1,
+            event_id=str(uuid4()),
+            event_type=event_type,
+            timestamp=datetime.now(timezone.utc).isoformat(),
+            producer=self.component_name,
+            payload_json=json.dumps(payload),
+        )
+
+        try:
+            if self._handle:
+                await self._handle.send(event)
+            elif self._async_producer:
+                await self._async_producer.send(event)
+        except Exception as e:
+            logger.warning(f"Failed to emit policy event: {e}")
+
+    async def emit_evaluations(
+        self,
+        evaluations,
+        user_context,
+        request_id="",
+        query_s=None,
+        query_p=None,
+        query_o=None,
+        collection="",
+        graph="",
+        workspace="",
+    ):
+        """Batch evaluations by policy and emit one event per policy.
+
+        Evaluations with the same (policy_uri, determination, blocks)
+        are grouped into a single event. The node_iris list is capped
+        at NODE_IRI_CAP per event; node_count reflects the true total.
+        """
+
+        by_policy = defaultdict(list)
+        for ev in evaluations:
+            by_policy[(ev.policy_uri, ev.policy_label,
+                       ev.determination, ev.blocks)].append(ev)
+
+        for (policy_uri, policy_label, determination, blocks), group in (
+            by_policy.items()
+        ):
+            node_iris = [ev.node_iri for ev in group]
+            node_count = len(node_iris)
+
+            reason = group[0].reason if group else ""
+
+            payload = {
+                "request_id": request_id,
+                "policy_uri": policy_uri,
+                "policy_label": policy_label,
+                "determination": determination,
+                "blocks": blocks,
+                "reason": reason,
+                "user_context": self._serialise_user_context(
+                    user_context
+                ),
+                "node_iris": node_iris[:NODE_IRI_CAP],
+                "node_count": node_count,
+                "query_s": query_s,
+                "query_p": query_p,
+                "query_o": query_o,
+                "collection": collection,
+                "graph": graph,
+                "workspace": workspace,
+            }
+
+            await self.emit("policy.evaluation", payload)
+
+    def _serialise_user_context(self, user_context):
+        if user_context is None:
+            return None
+
+        result = {
+            "user_id": user_context.user_id,
+            "roles": user_context.roles,
+            "organisational_units": user_context.organisational_units,
+            "purpose": user_context.purpose,
+        }
+
+        if user_context.assignments:
+            result["assignments"] = [
+                {
+                    "resource": a.resource,
+                    "scope": a.scope,
+                    "status": a.status,
+                    "valid_from": a.valid_from,
+                    "valid_to": a.valid_to,
+                    "qualifiers": a.qualifiers,
+                }
+                for a in user_context.assignments
+            ]
+
+        if user_context.entitlements:
+            result["entitlements"] = [
+                {
+                    "resource_scope": e.resource_scope,
+                    "access_level": e.access_level,
+                    "valid_from": e.valid_from,
+                    "valid_to": e.valid_to,
+                }
+                for e in user_context.entitlements
+            ]
+
+        if user_context.override_authorities:
+            result["override_authorities"] = [
+                {
+                    "policy_area": oa.policy_area,
+                    "condition": oa.condition,
+                }
+                for oa in user_context.override_authorities
+            ]
+
+        if user_context.delegation:
+            result["delegation"] = {
+                "delegator_id": user_context.delegation.delegator_id,
+                "scope": user_context.delegation.scope,
+            }
+
+        return result

{trustgraph_base-2.10.0 → trustgraph_base-2.10.2}/trustgraph/base/triples_client.py

@@ -48,7 +48,8 @@ class TriplesClient:
 
     async def query_gen(self, s=None, p=None, o=None, limit=20,
                         collection="default",
-                        batch_size=20, timeout=30, g=None):
+                        batch_size=20, timeout=30, g=None,
+                        user_context=None):
         """Async generator yielding Triple objects as batches arrive."""
         queue = asyncio.Queue()
         done = False
@@ -79,6 +80,7 @@ class TriplesClient:
                 streaming=True,
                 batch_size=batch_size,
                 g=g,
+                user_context=user_context,
             ),
             timeout=timeout,
             recipient=recipient,
@@ -101,7 +103,8 @@ class TriplesClient:
 
     async def query(self, s=None, p=None, o=None, limit=20,
                     collection="default",
-                    timeout=30, g=None):
+                    timeout=30, g=None,
+                    user_context=None):
 
         resp = await self.request(
             TriplesQueryRequest(
@@ -111,6 +114,7 @@ class TriplesClient:
                 limit = limit,
                 collection = collection,
                 g = g,
+                user_context = user_context,
             ),
             timeout=timeout
         )
@@ -128,7 +132,8 @@ class TriplesClient:
     async def query_stream(self, s=None, p=None, o=None, limit=20,
                            collection="default",
                            batch_size=20, timeout=30,
-                           batch_callback=None, g=None):
+                           batch_callback=None, g=None,
+                           user_context=None):
         """
         Streaming triple query - calls callback for each batch as it arrives.
 
@@ -173,6 +178,7 @@ class TriplesClient:
                 streaming=True,
                 batch_size=batch_size,
                 g=g,
+                user_context=user_context,
             ),
             timeout=timeout,
             recipient=recipient,

trustgraph_base-2.10.2/trustgraph/base_version.py

@@ -0,0 +1 @@
+__version__ = "2.10.2"

{trustgraph_base-2.10.0 → trustgraph_base-2.10.2}/trustgraph/messaging/translators/retrieval.py

@@ -1,5 +1,7 @@
 from typing import Dict, Any, Tuple
 from ...schema import DocumentRagQuery, DocumentRagResponse, GraphRagQuery, GraphRagResponse
+from ...schema import UserContext
+from ...base.serialization import dict_to_dataclass, dataclass_to_dict
 from .base import MessageTranslator
 from .primitives import TripleTranslator
 
@@ -94,6 +96,7 @@ class GraphRagRequestTranslator(MessageTranslator):
     """Translator for GraphRagQuery schema objects"""
 
     def decode(self, data: Dict[str, Any]) -> GraphRagQuery:
+        uc = data.get("user-context")
         return GraphRagQuery(
             query=data["query"],
             collection=data.get("collection", "default"),
@@ -104,11 +107,12 @@ class GraphRagRequestTranslator(MessageTranslator):
             edge_score_limit=int(data.get("edge-score-limit", 30)),
             edge_limit=int(data.get("edge-limit", 25)),
             max_reranker_input=int(data.get("max-reranker-input", 350)),
-            streaming=data.get("streaming", False)
+            streaming=data.get("streaming", False),
+            user_context=dict_to_dataclass(uc, UserContext) if uc else None,
         )
 
     def encode(self, obj: GraphRagQuery) -> Dict[str, Any]:
-        return {
+        result = {
             "query": obj.query,
             "collection": obj.collection,
             "entity-limit": obj.entity_limit,
@@ -118,8 +122,11 @@ class GraphRagRequestTranslator(MessageTranslator):
             "edge-score-limit": obj.edge_score_limit,
             "edge-limit": obj.edge_limit,
             "max-reranker-input": obj.max_reranker_input,
-            "streaming": getattr(obj, "streaming", False)
+            "streaming": getattr(obj, "streaming", False),
         }
+        if obj.user_context is not None:
+            result["user-context"] = dataclass_to_dict(obj.user_context)
+        return result
 
 
 class GraphRagResponseTranslator(MessageTranslator):

{trustgraph_base-2.10.0 → trustgraph_base-2.10.2}/trustgraph/messaging/translators/sparql_query.py

@@ -2,7 +2,9 @@ from typing import Dict, Any, Tuple
 from ...schema import (
     SparqlQueryRequest, SparqlQueryResponse, SparqlBinding,
     Error, Term, Triple, IRI, LITERAL, BLANK,
+    UserContext,
 )
+from ...base.serialization import dict_to_dataclass, dataclass_to_dict
 from .base import MessageTranslator
 from .primitives import TermTranslator, TripleTranslator
 
@@ -11,22 +13,27 @@ class SparqlQueryRequestTranslator(MessageTranslator):
     """Translator for SparqlQueryRequest schema objects."""
 
     def decode(self, data: Dict[str, Any]) -> SparqlQueryRequest:
+        uc = data.get("user-context")
         return SparqlQueryRequest(
             collection=data.get("collection", "default"),
             query=data.get("query", ""),
             limit=int(data.get("limit", 10000)),
             streaming=data.get("streaming", False),
             batch_size=int(data.get("batch-size", 20)),
+            user_context=dict_to_dataclass(uc, UserContext) if uc else None,
         )
 
     def encode(self, obj: SparqlQueryRequest) -> Dict[str, Any]:
-        return {
+        result = {
             "collection": obj.collection,
             "query": obj.query,
             "limit": obj.limit,
             "streaming": obj.streaming,
             "batch-size": obj.batch_size,
         }
+        if obj.user_context is not None:
+            result["user-context"] = dataclass_to_dict(obj.user_context)
+        return result
 
 
 class SparqlQueryResponseTranslator(MessageTranslator):

{trustgraph_base-2.10.0 → trustgraph_base-2.10.2}/trustgraph/messaging/translators/triples.py

@@ -1,5 +1,6 @@
 from typing import Dict, Any, Tuple, Optional
-from ...schema import TriplesQueryRequest, TriplesQueryResponse
+from ...schema import TriplesQueryRequest, TriplesQueryResponse, UserContext
+from ...base.serialization import dict_to_dataclass, dataclass_to_dict
 from .base import MessageTranslator
 from .primitives import ValueTranslator, SubgraphTranslator
 
@@ -15,6 +16,7 @@ class TriplesQueryRequestTranslator(MessageTranslator):
         p = self.value_translator.decode(data["p"]) if "p" in data else None
         o = self.value_translator.decode(data["o"]) if "o" in data else None
         g = data.get("g")  # None=default graph, "*"=all graphs
+        uc = data.get("user-context")
 
         return TriplesQueryRequest(
             s=s,
@@ -25,6 +27,7 @@ class TriplesQueryRequestTranslator(MessageTranslator):
             collection=data.get("collection", "default"),
             streaming=data.get("streaming", False),
             batch_size=int(data.get("batch-size", 20)),
+            user_context=dict_to_dataclass(uc, UserContext) if uc else None,
         )
 
     def encode(self, obj: TriplesQueryRequest) -> Dict[str, Any]:
@@ -43,6 +46,8 @@ class TriplesQueryRequestTranslator(MessageTranslator):
             result["o"] = self.value_translator.encode(obj.o)
         if obj.g is not None:
             result["g"] = obj.g
+        if obj.user_context is not None:
+            result["user-context"] = dataclass_to_dict(obj.user_context)
 
         return result
 

{trustgraph_base-2.10.0 → trustgraph_base-2.10.2}/trustgraph/schema/__init__.py

@@ -13,3 +13,5 @@ from .agent import *
 from .config import *
 from .iam import *
 from .audit import *
+from .policy_event import *
+from .user_context import *

trustgraph_base-2.10.2/trustgraph/schema/policy_event.py

@@ -0,0 +1,22 @@
+
+from dataclasses import dataclass, field
+
+from .core.topic import queue
+
+############################################################################
+
+# Policy events — see docs/tech-specs/policy-audit-events.md for spec.
+
+@dataclass
+class PolicyEvent:
+    schema_version: int = 1
+    event_id: str = ""
+    event_type: str = ""
+    timestamp: str = ""
+    producer: str = ""
+    payload_json: str = ""
+
+
+policy_events_queue = queue('policy-events', cls='notify')
+
+############################################################################