trustgraph-base 2.2.20__tar.gz → 2.2.22__tar.gz

{trustgraph_base-2.2.20 → trustgraph_base-2.2.22}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trustgraph-base
-Version: 2.2.20
+Version: 2.2.22
 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.2.20 → trustgraph_base-2.2.22}/trustgraph/api/socket_client.py

@@ -366,19 +366,13 @@ class SocketClient:
         # Handle GraphRAG/DocRAG message format with message_type
         if message_type == "explain":
             if include_provenance:
-                return ProvenanceEvent(
-                    explain_id=resp.get("explain_id", ""),
-                    explain_graph=resp.get("explain_graph", "")
-                )
+                return self._build_provenance_event(resp)
             return None
 
         # Handle Agent message format with chunk_type="explain"
         if chunk_type == "explain":
             if include_provenance:
-                return ProvenanceEvent(
-                    explain_id=resp.get("explain_id", ""),
-                    explain_graph=resp.get("explain_graph", "")
-                )
+                return self._build_provenance_event(resp)
             return None
 
         if chunk_type == "thought":
@@ -413,6 +407,42 @@ class SocketClient:
                 error=None
             )
 
+    def _build_provenance_event(self, resp: Dict[str, Any]) -> ProvenanceEvent:
+        """Build a ProvenanceEvent from a response dict, parsing inline triples
+        into an ExplainEntity if available."""
+        explain_id = resp.get("explain_id", "")
+        explain_graph = resp.get("explain_graph", "")
+        raw_triples = resp.get("explain_triples", [])
+
+        entity = None
+        if raw_triples:
+            try:
+                from .explainability import ExplainEntity
+                # Convert wire-format triple dicts to (s, p, o) tuples
+                parsed = []
+                for t in raw_triples:
+                    s = t.get("s", {}).get("i", "") if t.get("s") else ""
+                    p = t.get("p", {}).get("i", "") if t.get("p") else ""
+                    o_term = t.get("o", {})
+                    if o_term:
+                        if o_term.get("t") == "i":
+                            o = o_term.get("i", "")
+                        else:
+                            o = o_term.get("v", "")
+                    else:
+                        o = ""
+                    parsed.append((s, p, o))
+                entity = ExplainEntity.from_triples(explain_id, parsed)
+            except Exception:
+                pass
+
+        return ProvenanceEvent(
+            explain_id=explain_id,
+            explain_graph=explain_graph,
+            entity=entity,
+            triples=raw_triples,
+        )
+
     def close(self) -> None:
         """Close the persistent WebSocket connection."""
         if self._loop and not self._loop.is_closed():

{trustgraph_base-2.2.20 → trustgraph_base-2.2.22}/trustgraph/api/types.py

@@ -213,25 +213,47 @@ class ProvenanceEvent:
     """
     Provenance event for explainability.
 
-    Emitted during GraphRAG queries when explainable mode is enabled.
+    Emitted during retrieval queries when explainable mode is enabled.
     Each event represents a provenance node created during query processing.
 
     Attributes:
         explain_id: URI of the provenance node (e.g., urn:trustgraph:question:abc123)
         explain_graph: Named graph where provenance triples are stored (e.g., urn:graph:retrieval)
-        event_type: Type of provenance event (question, exploration, focus, synthesis)
+        event_type: Type of provenance event (question, exploration, focus, synthesis, etc.)
+        entity: Parsed ExplainEntity from inline triples (if available)
+        triples: Raw triples from the response (wire format dicts)
     """
     explain_id: str
     explain_graph: str = ""
     event_type: str = ""  # Derived from explain_id
+    entity: object = None  # ExplainEntity (parsed from triples)
+    triples: list = dataclasses.field(default_factory=list)  # Raw wire-format triple dicts
 
     def __post_init__(self):
         # Extract event type from explain_id
         if "question" in self.explain_id:
             self.event_type = "question"
+        elif "grounding" in self.explain_id:
+            self.event_type = "grounding"
         elif "exploration" in self.explain_id:
             self.event_type = "exploration"
         elif "focus" in self.explain_id:
             self.event_type = "focus"
         elif "synthesis" in self.explain_id:
             self.event_type = "synthesis"
+        elif "iteration" in self.explain_id:
+            self.event_type = "iteration"
+        elif "observation" in self.explain_id:
+            self.event_type = "observation"
+        elif "conclusion" in self.explain_id:
+            self.event_type = "conclusion"
+        elif "decomposition" in self.explain_id:
+            self.event_type = "decomposition"
+        elif "finding" in self.explain_id:
+            self.event_type = "finding"
+        elif "plan" in self.explain_id:
+            self.event_type = "plan"
+        elif "step-result" in self.explain_id:
+            self.event_type = "step-result"
+        elif "session" in self.explain_id:
+            self.event_type = "session"

{trustgraph_base-2.2.20 → trustgraph_base-2.2.22}/trustgraph/base/async_processor.py

@@ -94,7 +94,6 @@ class AsyncProcessor:
             metrics = config_consumer_metrics,
 
             start_of_messages = False,
-            consumer_type = 'exclusive',
         )
 
         self.running = True
@@ -172,7 +171,8 @@ class AsyncProcessor:
 
             except Exception as e:
                 logger.warning(
-                    f"Config fetch failed: {e}, retrying in 2s..."
+                    f"Config fetch failed: {e}, retrying in 2s...",
+                    exc_info=True
                 )
                 await asyncio.sleep(2)
 

{trustgraph_base-2.2.20 → trustgraph_base-2.2.22}/trustgraph/base/consumer.py

@@ -12,6 +12,7 @@
 import asyncio
 import time
 import logging
+from concurrent.futures import ThreadPoolExecutor
 
 from .. exceptions import TooManyRequests
 
@@ -110,29 +111,37 @@ class Consumer:
                 logger.info(f"Starting {self.concurrency} receiver threads")
 
                 # Create one backend consumer per concurrent task.
-                # Each gets its own connection — required for backends
-                # like RabbitMQ where connections are not thread-safe.
+                # Each gets its own connection and dedicated thread —
+                # required for backends like RabbitMQ where connections
+                # are not thread-safe (pika BlockingConnection must be
+                # used from a single thread).
                 consumers = []
+                executors = []
                 for i in range(self.concurrency):
                     try:
                         logger.info(f"Subscribing to topic: {self.topic} (worker {i})")
-                        c = await asyncio.to_thread(
-                            self.backend.create_consumer,
-                            topic = self.topic,
-                            subscription = self.subscriber,
-                            schema = self.schema,
-                            initial_position = initial_pos,
-                            consumer_type = self.consumer_type,
+                        executor = ThreadPoolExecutor(max_workers=1)
+                        loop = asyncio.get_event_loop()
+                        c = await loop.run_in_executor(
+                            executor,
+                            lambda: self.backend.create_consumer(
+                                topic = self.topic,
+                                subscription = self.subscriber,
+                                schema = self.schema,
+                                initial_position = initial_pos,
+                                consumer_type = self.consumer_type,
+                            ),
                         )
                         consumers.append(c)
+                        executors.append(executor)
                         logger.info(f"Successfully subscribed to topic: {self.topic} (worker {i})")
                     except Exception as e:
                         logger.error(f"Consumer subscription exception (worker {i}): {e}", exc_info=True)
                         raise
 
                 async with asyncio.TaskGroup() as tg:
-                    for c in consumers:
-                        tg.create_task(self.consume_from_queue(c))
+                    for c, ex in zip(consumers, executors):
+                        tg.create_task(self.consume_from_queue(c, ex))
 
                 if self.metrics:
                     self.metrics.state("stopped")
@@ -146,7 +155,10 @@ class Consumer:
                         c.close()
                     except Exception:
                         pass
+                for ex in executors:
+                    ex.shutdown(wait=False)
                 consumers = []
+                executors = []
                 await asyncio.sleep(self.reconnect_time)
                 continue
 
@@ -157,15 +169,18 @@ class Consumer:
                         c.close()
                     except Exception:
                         pass
+                for ex in executors:
+                    ex.shutdown(wait=False)
 
-    async def consume_from_queue(self, consumer):
+    async def consume_from_queue(self, consumer, executor=None):
 
+        loop = asyncio.get_event_loop()
         while self.running:
 
             try:
-                msg = await asyncio.to_thread(
-                    consumer.receive,
-                    timeout_millis=2000
+                msg = await loop.run_in_executor(
+                    executor,
+                    lambda: consumer.receive(timeout_millis=100),
                 )
             except Exception as e:
                 # Handle timeout from any backend
@@ -173,10 +188,11 @@ class Consumer:
                     continue
                 raise e
 
-            await self.handle_one_from_queue(msg, consumer)
+            await self.handle_one_from_queue(msg, consumer, executor)
 
-    async def handle_one_from_queue(self, msg, consumer):
+    async def handle_one_from_queue(self, msg, consumer, executor=None):
 
+        loop = asyncio.get_event_loop()
         expiry = time.time() + self.rate_limit_timeout
 
         # This loop is for retry on rate-limit / resource limits
@@ -187,8 +203,11 @@ class Consumer:
                 logger.warning("Gave up waiting for rate-limit retry")
 
                 # Message failed to be processed, this causes it to
-                # be retried
-                consumer.negative_acknowledge(msg)
+                # be retried.  Ack on the consumer's dedicated thread
+                # (pika is not thread-safe).
+                await loop.run_in_executor(
+                    executor, lambda: consumer.negative_acknowledge(msg)
+                )
 
                 if self.metrics:
                     self.metrics.process("error")
@@ -210,8 +229,11 @@ class Consumer:
 
                 logger.debug("Message processed successfully")
 
-                # Acknowledge successful processing of the message
-                consumer.acknowledge(msg)
+                # Acknowledge on the consumer's dedicated thread
+                # (pika is not thread-safe)
+                await loop.run_in_executor(
+                    executor, lambda: consumer.acknowledge(msg)
+                )
 
                 if self.metrics:
                     self.metrics.process("success")
@@ -237,8 +259,10 @@ class Consumer:
                 logger.error(f"Message processing exception: {e}", exc_info=True)
 
                 # Message failed to be processed, this causes it to
-                # be retried
-                consumer.negative_acknowledge(msg)
+                # be retried.  Ack on the consumer's dedicated thread.
+                await loop.run_in_executor(
+                    executor, lambda: consumer.negative_acknowledge(msg)
+                )
 
                 if self.metrics:
                     self.metrics.process("error")

{trustgraph_base-2.2.20 → trustgraph_base-2.2.22}/trustgraph/base/rabbitmq_backend.py

@@ -288,6 +288,7 @@ class RabbitMQBackend:
             port=port,
             virtual_host=vhost,
             credentials=pika.PlainCredentials(username, password),
+            heartbeat=0,
         )
         logger.info(f"RabbitMQ backend: {host}:{port} vhost={vhost}")
 

{trustgraph_base-2.2.20 → trustgraph_base-2.2.22}/trustgraph/base/subscriber.py

@@ -7,6 +7,7 @@ import asyncio
 import time
 import logging
 import uuid
+from concurrent.futures import ThreadPoolExecutor
 
 # Module logger
 logger = logging.getLogger(__name__)
@@ -38,6 +39,7 @@ class Subscriber:
         self.pending_acks = {}  # Track messages awaiting delivery
 
         self.consumer = None
+        self.executor = None
 
     def __del__(self):
 
@@ -45,15 +47,6 @@ class Subscriber:
 
     async def start(self):
 
-        # Create consumer via backend
-        self.consumer = await asyncio.to_thread(
-            self.backend.create_consumer,
-            topic=self.topic,
-            subscription=self.subscription,
-            schema=self.schema,
-            consumer_type='exclusive',
-        )
-
         self.task = asyncio.create_task(self.run())
 
     async def stop(self):
@@ -80,6 +73,21 @@ class Subscriber:
 
             try:
 
+                # Create consumer and dedicated thread if needed
+                # (first run or after failure)
+                if self.consumer is None:
+                    self.executor = ThreadPoolExecutor(max_workers=1)
+                    loop = asyncio.get_event_loop()
+                    self.consumer = await loop.run_in_executor(
+                        self.executor,
+                        lambda: self.backend.create_consumer(
+                            topic=self.topic,
+                            subscription=self.subscription,
+                            schema=self.schema,
+                            consumer_type='exclusive',
+                        ),
+                    )
+
                 if self.metrics:
                     self.metrics.state("running")
 
@@ -128,9 +136,12 @@ class Subscriber:
                     # Process messages only if not draining
                     if not self.draining:
                         try:
-                            msg = await asyncio.to_thread(
-                                self.consumer.receive,
-                                timeout_millis=250
+                            loop = asyncio.get_event_loop()
+                            msg = await loop.run_in_executor(
+                                self.executor,
+                                lambda: self.consumer.receive(
+                                    timeout_millis=250
+                                ),
                             )
                         except Exception as e:
                             # Handle timeout from any backend
@@ -172,15 +183,18 @@ class Subscriber:
                     except Exception:
                         pass  # Already closed or error
                     self.consumer = None
-                
-         
+
+                if self.executor:
+                    self.executor.shutdown(wait=False)
+                    self.executor = None
+
             if self.metrics:
                 self.metrics.state("stopped")
 
             if not self.running and not self.draining:
                 return
-            
-            # If handler drops out, sleep a retry
+
+            # Sleep before retry
             await asyncio.sleep(1)
 
     async def subscribe(self, id):

trustgraph_base-2.2.22/trustgraph/base_version.py

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

{trustgraph_base-2.2.20 → trustgraph_base-2.2.22}/trustgraph/messaging/translators/agent.py

@@ -1,6 +1,7 @@
 from typing import Dict, Any, Tuple
 from ...schema import AgentRequest, AgentResponse
 from .base import MessageTranslator
+from .primitives import TripleTranslator
 
 
 class AgentRequestTranslator(MessageTranslator):
@@ -49,10 +50,13 @@ class AgentRequestTranslator(MessageTranslator):
 
 class AgentResponseTranslator(MessageTranslator):
     """Translator for AgentResponse schema objects"""
-    
+
+    def __init__(self):
+        self.triple_translator = TripleTranslator()
+
     def decode(self, data: Dict[str, Any]) -> AgentResponse:
         raise NotImplementedError("Response translation to Pulsar not typically needed")
-    
+
     def encode(self, obj: AgentResponse) -> Dict[str, Any]:
         result = {}
 
@@ -75,6 +79,13 @@ class AgentResponseTranslator(MessageTranslator):
         if explain_graph is not None:
             result["explain_graph"] = explain_graph
 
+        # Include explain_triples for explain messages
+        explain_triples = getattr(obj, "explain_triples", [])
+        if explain_triples:
+            result["explain_triples"] = [
+                self.triple_translator.encode(t) for t in explain_triples
+            ]
+
         # Always include error if present
         if hasattr(obj, 'error') and obj.error and obj.error.message:
             result["error"] = {"message": obj.error.message, "code": obj.error.code}

{trustgraph_base-2.2.20 → trustgraph_base-2.2.22}/trustgraph/messaging/translators/collection.py

@@ -79,7 +79,6 @@ class CollectionManagementResponseTranslator(MessageTranslator):
     def encode(self, obj: CollectionManagementResponse) -> Dict[str, Any]:
         result = {}
 
-        print("COLLECTIONMGMT", obj, flush=True)
 
         if obj.error is not None:
             result["error"] = {
@@ -99,6 +98,4 @@ class CollectionManagementResponseTranslator(MessageTranslator):
                     "tags": list(coll.tags) if coll.tags else []
                 })
 
-        print("RESULT IS", result, flush=True)
-
         return result

{trustgraph_base-2.2.20 → trustgraph_base-2.2.22}/trustgraph/messaging/translators/retrieval.py

@@ -1,6 +1,7 @@
 from typing import Dict, Any, Tuple
 from ...schema import DocumentRagQuery, DocumentRagResponse, GraphRagQuery, GraphRagResponse
 from .base import MessageTranslator
+from .primitives import TripleTranslator
 
 
 class DocumentRagRequestTranslator(MessageTranslator):
@@ -28,6 +29,9 @@ class DocumentRagRequestTranslator(MessageTranslator):
 class DocumentRagResponseTranslator(MessageTranslator):
     """Translator for DocumentRagResponse schema objects"""
 
+    def __init__(self):
+        self.triple_translator = TripleTranslator()
+
     def decode(self, data: Dict[str, Any]) -> DocumentRagResponse:
         raise NotImplementedError("Response translation to Pulsar not typically needed")
 
@@ -53,6 +57,13 @@ class DocumentRagResponseTranslator(MessageTranslator):
         if explain_graph is not None:
             result["explain_graph"] = explain_graph
 
+        # Include explain_triples for explain messages
+        explain_triples = getattr(obj, "explain_triples", [])
+        if explain_triples:
+            result["explain_triples"] = [
+                self.triple_translator.encode(t) for t in explain_triples
+            ]
+
         # Include end_of_stream flag (LLM stream complete)
         result["end_of_stream"] = getattr(obj, "end_of_stream", False)
 
@@ -107,6 +118,9 @@ class GraphRagRequestTranslator(MessageTranslator):
 class GraphRagResponseTranslator(MessageTranslator):
     """Translator for GraphRagResponse schema objects"""
 
+    def __init__(self):
+        self.triple_translator = TripleTranslator()
+
     def decode(self, data: Dict[str, Any]) -> GraphRagResponse:
         raise NotImplementedError("Response translation to Pulsar not typically needed")
 
@@ -132,6 +146,13 @@ class GraphRagResponseTranslator(MessageTranslator):
         if explain_graph is not None:
             result["explain_graph"] = explain_graph
 
+        # Include explain_triples for explain messages
+        explain_triples = getattr(obj, "explain_triples", [])
+        if explain_triples:
+            result["explain_triples"] = [
+                self.triple_translator.encode(t) for t in explain_triples
+            ]
+
         # Include end_of_stream flag (LLM stream complete)
         result["end_of_stream"] = getattr(obj, "end_of_stream", False)
 

{trustgraph_base-2.2.20 → trustgraph_base-2.2.22}/trustgraph/schema/services/agent.py

@@ -2,7 +2,7 @@
 from dataclasses import dataclass, field
 from typing import Optional
 
-from ..core.primitives import Error
+from ..core.primitives import Error, Triple
 
 ############################################################################
 
@@ -57,8 +57,9 @@ class AgentResponse:
     end_of_dialog: bool = False    # Entire agent dialog is complete
 
     # Explainability fields
-    explain_id: str | None = None     # Provenance URI (announced as created)
-    explain_graph: str | None = None  # Named graph where explain was stored
+    explain_id: str | None = None     # Root URI for this explain step
+    explain_graph: str | None = None  # Named graph (e.g., urn:graph:retrieval)
+    explain_triples: list[Triple] = field(default_factory=list)  # Provenance triples for this step
 
     # Orchestration fields
     message_id: str = ""              # Unique ID for this response message

{trustgraph_base-2.2.20 → trustgraph_base-2.2.22}/trustgraph/schema/services/retrieval.py

@@ -1,5 +1,5 @@
-from dataclasses import dataclass
-from ..core.primitives import Error, Term
+from dataclasses import dataclass, field
+from ..core.primitives import Error, Term, Triple
 
 ############################################################################
 
@@ -24,8 +24,9 @@ class GraphRagResponse:
     error: Error | None = None
     response: str = ""
     end_of_stream: bool = False       # LLM response stream complete
-    explain_id: str | None = None     # Single explain URI (announced as created)
-    explain_graph: str | None = None  # Named graph where explain was stored (e.g., urn:graph:retrieval)
+    explain_id: str | None = None     # Root URI for this explain step
+    explain_graph: str | None = None  # Named graph (e.g., urn:graph:retrieval)
+    explain_triples: list[Triple] = field(default_factory=list)  # Provenance triples for this step
     message_type: str = ""            # "chunk" or "explain"
     end_of_session: bool = False      # Entire session complete
 
@@ -46,7 +47,8 @@ class DocumentRagResponse:
     error: Error | None = None
     response: str | None = ""
     end_of_stream: bool = False       # LLM response stream complete
-    explain_id: str | None = None     # Single explain URI (announced as created)
-    explain_graph: str | None = None  # Named graph where explain was stored (e.g., urn:graph:retrieval)
+    explain_id: str | None = None     # Root URI for this explain step
+    explain_graph: str | None = None  # Named graph (e.g., urn:graph:retrieval)
+    explain_triples: list[Triple] = field(default_factory=list)  # Provenance triples for this step
     message_type: str = ""            # "chunk" or "explain"
     end_of_session: bool = False      # Entire session complete

{trustgraph_base-2.2.20 → trustgraph_base-2.2.22}/trustgraph_base.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trustgraph-base
-Version: 2.2.20
+Version: 2.2.22
 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.2.20/trustgraph/base_version.py

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