koi-net 1.0.0b1__py3-none-any.whl → 1.0.0b3__py3-none-any.whl

koi_net/processor/interface.py

@@ -11,7 +11,8 @@ from ..protocol.event import Event, EventType
 from .handler import (
     KnowledgeHandler, 
     HandlerType, 
-    STOP_CHAIN
+    STOP_CHAIN,
+    StopChain
 )
 from .knowledge_object import (
     KnowledgeObject,
@@ -23,6 +24,8 @@ logger = logging.getLogger(__name__)
 
 
 class ProcessorInterface:
+    """Provides access to this node's knowledge processing pipeline."""
+    
     cache: Cache
     network: NetworkInterface
     identity: NodeIdentity
@@ -41,28 +44,19 @@ class ProcessorInterface:
         self.identity = identity
         self.handlers: list[KnowledgeHandler] = default_handlers
         self.kobj_queue = Queue()
-    
-    @classmethod
-    def as_handler(
-        cls,
-        handler_type: HandlerType,
-        rid_types: list[RIDType] | None = None
-    ):
-        """Special decorator that returns a Handler instead of a function."""
-        def decorator(func: Callable) -> KnowledgeHandler:
-            handler = KnowledgeHandler(func, handler_type, rid_types, )
-            return handler
-        return decorator
+        
+    def add_handler(self, handler: KnowledgeHandler):
+        self.handlers.append(handler)
             
     def register_handler(
         self,
         handler_type: HandlerType,
         rid_types: list[RIDType] | None = None
     ):
-        """Assigns decorated function as handler for this Processor."""
+        """Assigns decorated function as handler for this processor."""
         def decorator(func: Callable) -> Callable:
             handler = KnowledgeHandler(func, handler_type, rid_types)
-            self.handlers.append(handler)
+            self.add_handler(handler)
             return func
         return decorator
             
@@ -70,7 +64,17 @@ class ProcessorInterface:
         self, 
         handler_type: HandlerType,
         kobj: KnowledgeObject
-    ):
+    ) -> KnowledgeObject | StopChain:
+        """Calls handlers of provided type, chaining their inputs and outputs together.
+        
+        The knowledge object provided when this function is called will be passed to the first handler. A handler may return one of three types: 
+        - `KnowledgeObject` - to modify the knowledge object for the next handler in the chain
+        - `None` - to keep the same knowledge object for the next handler in the chain
+        - `STOP_CHAIN` - to stop the handler chain and immediately exit the processing pipeline
+        
+        Handlers will only be called in the chain if their handler and RID type match that of the inputted knowledge object. 
+        """
+        
         for handler in self.handlers:
             if handler_type != handler.handler_type: 
                 continue
@@ -98,7 +102,19 @@ class ProcessorInterface:
         return kobj
 
         
-    def handle_kobj(self, kobj: KnowledgeObject):
+    def process_kobj(self, kobj: KnowledgeObject) -> None:
+        """Sends provided knowledge obejct through knowledge processing pipeline.
+        
+        Handler chains are called in between major events in the pipeline, indicated by their handler type. Each handler type is guaranteed to have access to certain knowledge, and may affect a subsequent action in the pipeline. The five handler types are as follows:
+        - RID - provided RID; if event type is `FORGET`, this handler decides whether to delete the knowledge from the cache by setting the normalized event type to `FORGET`, otherwise this handler decides whether to validate the manifest (and fetch it if not provided).
+        - Manifest - provided RID, manifest; decides whether to validate the bundle (and fetch it if not provided).
+        - Bundle - provided RID, manifest, contents (bundle); decides whether to write knowledge to the cache by setting the normalized event type to `NEW` or `UPDATE`.
+        - Network - provided RID, manifest, contents (bundle); decides which nodes (if any) to broadcast an event about this knowledge to. (Note, if event type is `FORGET`, the manifest and contents will be retrieved from the local cache, and indicate the last state of the knowledge before it was deleted.)
+        - Final - provided RID, manifests, contents (bundle); final action taken after network broadcast.
+        
+        The pipeline may be stopped by any point by a single handler returning the `STOP_CHAIN` sentinel. In that case, the process will exit immediately. Further handlers of that type and later handler chains will not be called.
+        """
+        
         logger.info(f"Handling {kobj!r}")
         kobj = self.call_handler_chain(HandlerType.RID, kobj)
         if kobj is STOP_CHAIN: return
@@ -183,19 +199,13 @@ class ProcessorInterface:
         self.network.flush_all_webhook_queues()
         
         kobj = self.call_handler_chain(HandlerType.Final, kobj)
-            
-    def queue_kobj(self, kobj: KnowledgeObject, flush: bool = False):
-        self.kobj_queue.put(kobj)
-        logger.info(f"Queued {kobj!r}")
-        
-        if flush:
-            self.flush_kobj_queue()
                 
     def flush_kobj_queue(self):
+        """Flushes all knowledge objects from queue and processes them."""
         while not self.kobj_queue.empty():
             kobj = self.kobj_queue.get()
             logger.info(f"Dequeued {kobj!r}")
-            self.handle_kobj(kobj)
+            self.process_kobj(kobj)
             logger.info("Done handling")
         
     def handle(
@@ -204,19 +214,30 @@ class ProcessorInterface:
         manifest: Manifest | None = None,
         bundle: Bundle | None = None,
         event: Event | None = None,
+        kobj: KnowledgeObject | None = None,
         event_type: KnowledgeEventType = None,
         source: KnowledgeSource = KnowledgeSource.Internal,
         flush: bool = False
     ):
+        """Queues provided knowledge to be handled by processing pipeline.
+        
+        Knowledge may take the form of an RID, manifest, bundle, event, or knowledge object (with an optional event type for RID, manifest, or bundle objects). All objects will be normalized into knowledge objects and queued. If `flush` is `True`, the queue will be flushed immediately after adding the new knowledge.
+        """
         if rid:
-            kobj = KnowledgeObject.from_rid(rid, event_type, source)
+            _kobj = KnowledgeObject.from_rid(rid, event_type, source)
         elif manifest:
-            kobj = KnowledgeObject.from_manifest(manifest, event_type, source)
+            _kobj = KnowledgeObject.from_manifest(manifest, event_type, source)
         elif bundle:
-            kobj = KnowledgeObject.from_bundle(bundle, event_type, source)
+            _kobj = KnowledgeObject.from_bundle(bundle, event_type, source)
         elif event:
-            kobj = KnowledgeObject.from_event(event, source)
+            _kobj = KnowledgeObject.from_event(event, source)
+        elif _kobj:
+            _kobj = kobj
         else:
-            raise ValueError("One of 'rid', 'manifest', 'bundle', or 'event' must be provided")
-          
-        self.queue_kobj(kobj, flush)
+            raise ValueError("One of 'rid', 'manifest', 'bundle', 'event', or 'kobj' must be provided")
+        
+        self.kobj_queue.put(kobj)
+        logger.info(f"Queued {kobj!r}")
+        
+        if flush:
+            self.flush_kobj_queue()

koi_net/processor/knowledge_object.py

@@ -14,6 +14,18 @@ class KnowledgeSource(StrEnum):
     External = "EXTERNAL"
 
 class KnowledgeObject(BaseModel):
+    """A normalized knowledge representation for internal processing.
+    
+    Capable of representing an RID, manifest, bundle, or event. Contains three additional fields use for decision making in the knowledge processing pipeline. 
+    
+    The source indicates whether this object was generated by this node, or sourced from another node in the network. 
+    
+    The normalized event type indicates how the knowledge object is viewed from the perspective of this node, and what cache actions will take place. `NEW`, `UPDATE` -> cache write, `FORGET` -> cache delete, `None` -> no cache action.
+    
+    The network targets indicate other nodes in the network this knowledge object will be sent to. The event sent to them will be constructed from this knowledge object's RID, manifest, contents, and normalized event type.
+    
+    Constructors are provided to create a knowledge object from an RID, manifest, bundle, or event.
+    """
     rid: RID
     manifest: Manifest | None = None
     contents: dict | None = None
@@ -93,12 +105,19 @@ class KnowledgeObject(BaseModel):
     
     @property
     def normalized_event(self):
-        if not self.normalized_event_type:
+        if self.normalized_event_type is None:
             raise ValueError("Internal event's normalized event type is None, cannot convert to Event")
         
-        return Event(
-            rid=self.rid,
-            event_type=self.normalized_event_type,
-            manifest=self.manifest,
-            contents=self.contents
-        )
+        elif self.normalized_event_type == EventType.FORGET:
+            return Event(
+                rid=self.rid,
+                event_type=EventType.FORGET
+            )
+        
+        else:    
+            return Event(
+                rid=self.rid,
+                event_type=self.normalized_event_type,
+                manifest=self.manifest,
+                contents=self.contents
+            )

koi_net/protocol/api_models.py

@@ -1,3 +1,5 @@
+"""Pydantic models for request and response/payload objects in the KOI-net API."""
+
 from pydantic import BaseModel
 from rid_lib import RID, RIDType
 from rid_lib.ext import Bundle, Manifest
@@ -36,4 +38,10 @@ class BundlesPayload(BaseModel):
     deferred: list[RID] = []
     
 class EventsPayload(BaseModel):
-    events: list[Event]
+    events: list[Event]
+    
+
+# TYPES
+
+type RequestModels = EventsPayload | PollEvents | FetchRids | FetchManifests | FetchBundles
+type ResponseModels = RidsPayload | ManifestsPayload | BundlesPayload | EventsPayload

koi_net/protocol/consts.py

@@ -1,3 +1,5 @@
+"""API paths for KOI-net protocol."""
+
 BROADCAST_EVENTS_PATH = "/events/broadcast"
 POLL_EVENTS_PATH      = "/events/poll"
 FETCH_RIDS_PATH       = "/rids/fetch"