koi-net 1.0.0b9__py3-none-any.whl → 1.0.0b11__py3-none-any.whl

koi_net/core.py

@@ -50,7 +50,7 @@ class NodeInterface:
         )
         
         # pull all handlers defined in default_handlers module
-        if not handlers:
+        if handlers is None:
             handlers = [
                 obj for obj in vars(default_handlers).values() 
                 if isinstance(obj, KnowledgeHandler)
@@ -84,15 +84,15 @@ class NodeInterface:
             )
         )
         
-        logger.info("Waiting for kobj queue to empty")
+        logger.debug("Waiting for kobj queue to empty")
         if self.use_kobj_processor_thread:
             self.processor.kobj_queue.join()
         else:
             self.processor.flush_kobj_queue()
-        logger.info("Done")
+        logger.debug("Done")
     
         if not self.network.graph.get_neighbors() and self.first_contact:
-            logger.info(f"I don't have any neighbors, reaching out to first contact {self.first_contact}")
+            logger.debug(f"I don't have any neighbors, reaching out to first contact {self.first_contact}")
             
             events = [
                 Event.from_rid(EventType.FORGET, self.identity.rid),
@@ -106,7 +106,7 @@ class NodeInterface:
                 )
                 
             except httpx.ConnectError:
-                logger.info("Failed to reach first contact")
+                logger.warning("Failed to reach first contact")
                 return
             
                         
@@ -118,7 +118,7 @@ class NodeInterface:
         logger.info("Stopping node...")
         
         if self.use_kobj_processor_thread:
-            logger.info("Waiting for kobj queue to empty")
+            logger.info(f"Waiting for kobj queue to empty ({self.processor.kobj_queue.unfinished_tasks} tasks remaining)")
             self.processor.kobj_queue.join()
         else:
             self.processor.flush_kobj_queue()

koi_net/network/graph.py

@@ -25,12 +25,12 @@ class NetworkGraph:
         
     def generate(self):
         """Generates directed graph from cached KOI nodes and edges."""
-        logger.info("Generating network graph")
+        logger.debug("Generating network graph")
         self.dg.clear()
         for rid in self.cache.list_rids():
             if type(rid) == KoiNetNode:                
                 self.dg.add_node(rid)
-                logger.info(f"Added node {rid}")
+                logger.debug(f"Added node {rid}")
                 
             elif type(rid) == KoiNetEdge:
                 edge_profile = self.get_edge_profile(rid)
@@ -38,8 +38,8 @@ class NetworkGraph:
                     logger.warning(f"Failed to load {rid!r}")
                     continue
                 self.dg.add_edge(edge_profile.source, edge_profile.target, rid=rid)
-                logger.info(f"Added edge {rid} ({edge_profile.source} -> {edge_profile.target})")
-        logger.info("Done")
+                logger.debug(f"Added edge {rid} ({edge_profile.source} -> {edge_profile.target})")
+        logger.debug("Done")
         
     def get_node_profile(self, rid: KoiNetNode) -> NodeProfile | None:
         """Returns node profile given its RID."""

koi_net/network/interface.py

@@ -100,7 +100,7 @@ class NetworkInterface:
         
         Event will be sent to webhook or poll queue depending on the node type and edge type of the specified node. If `flush` is set to `True`, the webhook queued will be flushed after pushing the event.
         """
-        logger.info(f"Pushing event {event.event_type} {event.rid} to {node}")
+        logger.debug(f"Pushing event {event.event_type} {event.rid} to {node}")
             
         node_profile = self.graph.get_node_profile(node)
         if not node_profile:
@@ -136,14 +136,14 @@ class NetworkInterface:
         if queue:
             while not queue.empty():
                 event = queue.get()
-                logger.info(f"Dequeued {event.event_type} '{event.rid}'")
+                logger.debug(f"Dequeued {event.event_type} '{event.rid}'")
                 events.append(event)
         
         return events
     
     def flush_poll_queue(self, node: KoiNetNode) -> list[Event]:
         """Flushes a node's poll queue, returning list of events."""
-        logger.info(f"Flushing poll queue for {node}")
+        logger.debug(f"Flushing poll queue for {node}")
         return self._flush_queue(self.poll_event_queue, node)
     
     def flush_webhook_queue(self, node: KoiNetNode):
@@ -152,7 +152,7 @@ class NetworkInterface:
         If node profile is unknown, or node type is not `FULL`, this operation will fail silently. If the remote node cannot be reached, all events will be requeued.
         """
         
-        logger.info(f"Flushing webhook queue for {node}")
+        logger.debug(f"Flushing webhook queue for {node}")
         
         node_profile = self.graph.get_node_profile(node)
         
@@ -167,35 +167,37 @@ class NetworkInterface:
         events = self._flush_queue(self.webhook_event_queue, node)
         if not events: return
         
-        logger.info(f"Broadcasting {len(events)} events")
+        logger.debug(f"Broadcasting {len(events)} events")
         
         try:  
             self.request_handler.broadcast_events(node, events=events)
+            return True
         except httpx.ConnectError:
-            logger.warning("Broadcast failed, requeuing events")
+            logger.warning("Broadcast failed, dropping node")
             for event in events:
                 self.push_event_to(event, node)
+            return False
             
     def get_state_providers(self, rid_type: RIDType) -> list[KoiNetNode]:
         """Returns list of node RIDs which provide state for the specified RID type."""
         
-        logger.info(f"Looking for state providers of '{rid_type}'")
+        logger.debug(f"Looking for state providers of '{rid_type}'")
         provider_nodes = []
         for node_rid in self.cache.list_rids(rid_types=[KoiNetNode]):
             node = self.graph.get_node_profile(node_rid)
                         
             if node.node_type == NodeType.FULL and rid_type in node.provides.state:
-                logger.info(f"Found provider '{node_rid}'")
+                logger.debug(f"Found provider '{node_rid}'")
                 provider_nodes.append(node_rid)
         
         if not provider_nodes:
-            logger.info("Failed to find providers")
+            logger.debug("Failed to find providers")
         return provider_nodes
             
     def fetch_remote_bundle(self, rid: RID):
         """Attempts to fetch a bundle by RID from known peer nodes."""
         
-        logger.info(f"Fetching remote bundle '{rid}'")
+        logger.debug(f"Fetching remote bundle '{rid}'")
         remote_bundle = None
         for node_rid in self.get_state_providers(type(rid)):
             payload = self.request_handler.fetch_bundles(
@@ -203,7 +205,7 @@ class NetworkInterface:
             
             if payload.bundles:
                 remote_bundle = payload.bundles[0]
-                logger.info(f"Got bundle from '{node_rid}'")
+                logger.debug(f"Got bundle from '{node_rid}'")
                 break
         
         if not remote_bundle:
@@ -214,7 +216,7 @@ class NetworkInterface:
     def fetch_remote_manifest(self, rid: RID):
         """Attempts to fetch a manifest by RID from known peer nodes."""
         
-        logger.info(f"Fetching remote manifest '{rid}'")
+        logger.debug(f"Fetching remote manifest '{rid}'")
         remote_manifest = None
         for node_rid in self.get_state_providers(type(rid)):
             payload = self.request_handler.fetch_manifests(
@@ -222,7 +224,7 @@ class NetworkInterface:
             
             if payload.manifests:
                 remote_manifest = payload.manifests[0]
-                logger.info(f"Got bundle from '{node_rid}'")
+                logger.debug(f"Got bundle from '{node_rid}'")
                 break
         
         if not remote_manifest:
@@ -239,17 +241,17 @@ class NetworkInterface:
         neighbors = self.graph.get_neighbors()
         
         if not neighbors and self.first_contact:
-            logger.info("No neighbors found, polling first contact")
+            logger.debug("No neighbors found, polling first contact")
             try:
                 payload = self.request_handler.poll_events(
                     url=self.first_contact, 
                     rid=self.identity.rid
                 )
                 if payload.events:
-                    logger.info(f"Received {len(payload.events)} events from '{self.first_contact}'")
+                    logger.debug(f"Received {len(payload.events)} events from '{self.first_contact}'")
                 return payload.events
             except httpx.ConnectError:
-                logger.info(f"Failed to reach first contact '{self.first_contact}'")
+                logger.debug(f"Failed to reach first contact '{self.first_contact}'")
         
         events = []
         for node_rid in neighbors:
@@ -263,10 +265,10 @@ class NetworkInterface:
                     rid=self.identity.rid
                 )
                 if payload.events:
-                    logger.info(f"Received {len(payload.events)} events from {node_rid!r}")
+                    logger.debug(f"Received {len(payload.events)} events from {node_rid!r}")
                 events.extend(payload.events)
             except httpx.ConnectError:
-                logger.info(f"Failed to reach node '{node_rid}'")
+                logger.debug(f"Failed to reach node '{node_rid}'")
                 continue
             
         return events                

koi_net/network/request_handler.py

@@ -1,6 +1,5 @@
 import logging
 import httpx
-from pydantic import BaseModel
 from rid_lib import RID
 from rid_lib.ext import Cache
 from rid_lib.types.koi_net_node import KoiNetNode
@@ -46,7 +45,7 @@ class RequestHandler:
         request: RequestModels,
         response_model: type[ResponseModels] | None = None
     ) -> ResponseModels | None:
-        logger.info(f"Making request to {url}")
+        logger.debug(f"Making request to {url}")
         resp = httpx.post(
             url=url,
             data=request.model_dump_json()
@@ -66,7 +65,7 @@ class RequestHandler:
                 raise Exception("Node not found")
             if node_profile.node_type != NodeType.FULL:
                 raise Exception("Can't query partial node")
-            logger.info(f"Resolved {node_rid!r} to {node_profile.base_url}")
+            logger.debug(f"Resolved {node_rid!r} to {node_profile.base_url}")
             return node_profile.base_url
         else:
             return url
@@ -79,10 +78,11 @@ class RequestHandler:
         **kwargs
     ) -> None:
         """See protocol.api_models.EventsPayload for available kwargs."""
+        request = req or EventsPayload.model_validate(kwargs)
         self.make_request(
-            self.get_url(node, url) + BROADCAST_EVENTS_PATH,
-            req or EventsPayload.model_validate(kwargs)
+            self.get_url(node, url) + BROADCAST_EVENTS_PATH, request
         )
+        logger.info(f"Broadcasted {len(request.events)} event(s) to {node or url!r}")
         
     def poll_events(
         self, 
@@ -92,12 +92,14 @@ class RequestHandler:
         **kwargs
     ) -> EventsPayload:
         """See protocol.api_models.PollEvents for available kwargs."""
-        return self.make_request(
-            self.get_url(node, url) + POLL_EVENTS_PATH,
-            req or PollEvents.model_validate(kwargs),
+        request = req or PollEvents.model_validate(kwargs)
+        resp = self.make_request(
+            self.get_url(node, url) + POLL_EVENTS_PATH, request,
             response_model=EventsPayload
         )
-            
+        logger.info(f"Polled {len(resp.events)} events from {node or url!r}")
+        return resp
+        
     def fetch_rids(
         self, 
         node: RID = None, 
@@ -106,11 +108,13 @@ class RequestHandler:
         **kwargs
     ) -> RidsPayload:
         """See protocol.api_models.FetchRids for available kwargs."""
-        return self.make_request(
-            self.get_url(node, url) + FETCH_RIDS_PATH,
-            req or FetchRids.model_validate(kwargs),
+        request = req or FetchRids.model_validate(kwargs)
+        resp = self.make_request(
+            self.get_url(node, url) + FETCH_RIDS_PATH, request,
             response_model=RidsPayload
         )
+        logger.info(f"Fetched {len(resp.rids)} RID(s) from {node or url!r}")
+        return resp
                 
     def fetch_manifests(
         self, 
@@ -120,11 +124,13 @@ class RequestHandler:
         **kwargs
     ) -> ManifestsPayload:
         """See protocol.api_models.FetchManifests for available kwargs."""
-        return self.make_request(
-            self.get_url(node, url) + FETCH_MANIFESTS_PATH,
-            req or FetchManifests.model_validate(kwargs),
+        request = req or FetchManifests.model_validate(kwargs)
+        resp = self.make_request(
+            self.get_url(node, url) + FETCH_MANIFESTS_PATH, request,
             response_model=ManifestsPayload
         )
+        logger.info(f"Fetched {len(resp.manifests)} manifest(s) from {node or url!r}")
+        return resp
                 
     def fetch_bundles(
         self, 
@@ -134,8 +140,10 @@ class RequestHandler:
         **kwargs
     ) -> BundlesPayload:
         """See protocol.api_models.FetchBundles for available kwargs."""
-        return self.make_request(
-            self.get_url(node, url) + FETCH_BUNDLES_PATH,
-            req or FetchBundles.model_validate(kwargs),
+        request = req or FetchBundles.model_validate(kwargs)
+        resp = self.make_request(
+            self.get_url(node, url) + FETCH_BUNDLES_PATH, request,
             response_model=BundlesPayload
-        )
+        )
+        logger.info(f"Fetched {len(resp.bundles)} bundle(s) from {node or url!r}")
+        return resp

koi_net/processor/default_handlers.py

@@ -22,7 +22,7 @@ def basic_rid_handler(processor: ProcessorInterface, kobj: KnowledgeObject):
     """
     if (kobj.rid == processor.identity.rid and 
         kobj.source == KnowledgeSource.External):
-        logger.info("Don't let anyone else tell me who I am!")
+        logger.debug("Don't let anyone else tell me who I am!")
         return STOP_CHAIN
     
     if kobj.event_type == EventType.FORGET:
@@ -41,17 +41,17 @@ def basic_manifest_handler(processor: ProcessorInterface, kobj: KnowledgeObject)
 
     if prev_bundle:
         if kobj.manifest.sha256_hash == prev_bundle.manifest.sha256_hash:
-            logger.info("Hash of incoming manifest is same as existing knowledge, ignoring")
+            logger.debug("Hash of incoming manifest is same as existing knowledge, ignoring")
             return STOP_CHAIN
         if kobj.manifest.timestamp <= prev_bundle.manifest.timestamp:
-            logger.info("Timestamp of incoming manifest is the same or older than existing knowledge, ignoring")
+            logger.debug("Timestamp of incoming manifest is the same or older than existing knowledge, ignoring")
             return STOP_CHAIN
         
-        logger.info("RID previously known to me, labeling as 'UPDATE'")
+        logger.debug("RID previously known to me, labeling as 'UPDATE'")
         kobj.normalized_event_type = EventType.UPDATE
 
     else:
-        logger.info("RID previously unknown to me, labeling as 'NEW'")
+        logger.debug("RID previously unknown to me, labeling as 'NEW'")
         kobj.normalized_event_type = EventType.NEW
         
     return kobj
@@ -77,7 +77,7 @@ def edge_negotiation_handler(processor: ProcessorInterface, kobj: KnowledgeObjec
         if edge_profile.status != EdgeStatus.PROPOSED:
             return
         
-        logger.info("Handling edge negotiation")
+        logger.debug("Handling edge negotiation")
         
         peer_rid = edge_profile.target
         peer_profile = processor.network.graph.get_node_profile(peer_rid)
@@ -96,11 +96,11 @@ def edge_negotiation_handler(processor: ProcessorInterface, kobj: KnowledgeObjec
         abort = False
         if (edge_profile.edge_type == EdgeType.WEBHOOK and 
             peer_profile.node_type == NodeType.PARTIAL):
-            logger.info("Partial nodes cannot use webhooks")
+            logger.debug("Partial nodes cannot use webhooks")
             abort = True
         
         if not set(edge_profile.rid_types).issubset(provided_events):
-            logger.info("Requested RID types not provided by this node")
+            logger.debug("Requested RID types not provided by this node")
             abort = True
         
         if abort:
@@ -110,16 +110,16 @@ def edge_negotiation_handler(processor: ProcessorInterface, kobj: KnowledgeObjec
 
         else:
             # approve edge profile
-            logger.info("Approving proposed edge")
+            logger.debug("Approving proposed edge")
             edge_profile.status = EdgeStatus.APPROVED
             updated_bundle = Bundle.generate(kobj.rid, edge_profile.model_dump())
       
-            processor.handle(bundle=updated_bundle)
+            processor.handle(bundle=updated_bundle, event_type=EventType.UPDATE)
             return
               
     elif edge_profile.target == processor.identity.rid:
         if edge_profile.status == EdgeStatus.APPROVED:
-            logger.info("Edge approved by other node!")
+            logger.debug("Edge approved by other node!")
 
 
 # Network handlers
@@ -140,12 +140,12 @@ def basic_network_output_filter(processor: ProcessorInterface, kobj: KnowledgeOb
             edge_profile = kobj.bundle.validate_contents(EdgeProfile)
             
             if edge_profile.source == processor.identity.rid:
-                logger.info(f"Adding edge target '{edge_profile.target!r}' to network targets")
+                logger.debug(f"Adding edge target '{edge_profile.target!r}' to network targets")
                 kobj.network_targets.update([edge_profile.target])
                 involves_me = True
                 
             elif edge_profile.target == processor.identity.rid:
-                logger.info(f"Adding edge source '{edge_profile.source!r}' to network targets")
+                logger.debug(f"Adding edge source '{edge_profile.source!r}' to network targets")
                 kobj.network_targets.update([edge_profile.source])
                 involves_me = True
     
@@ -156,7 +156,7 @@ def basic_network_output_filter(processor: ProcessorInterface, kobj: KnowledgeOb
             allowed_type=type(kobj.rid)
         )
         
-        logger.info(f"Updating network targets with '{type(kobj.rid)}' subscribers: {subscribers}")
+        logger.debug(f"Updating network targets with '{type(kobj.rid)}' subscribers: {subscribers}")
         kobj.network_targets.update(subscribers)
         
     return kobj

koi_net/processor/interface.py

@@ -101,12 +101,12 @@ class ProcessorInterface:
             if handler.event_types and kobj.event_type not in handler.event_types:
                 continue
             
-            logger.info(f"Calling {handler_type} handler '{handler.func.__name__}'")
+            logger.debug(f"Calling {handler_type} handler '{handler.func.__name__}'")
             resp = handler.func(self, kobj.model_copy())
             
             # stops handler chain execution
             if resp is STOP_CHAIN:
-                logger.info(f"Handler chain stopped by {handler.func.__name__}")
+                logger.debug(f"Handler chain stopped by {handler.func.__name__}")
                 return STOP_CHAIN
             # kobj unmodified
             elif resp is None:
@@ -114,7 +114,7 @@ class ProcessorInterface:
             # kobj modified by handler
             elif isinstance(resp, KnowledgeObject):
                 kobj = resp
-                logger.info(f"Knowledge object modified by {handler.func.__name__}")
+                logger.debug(f"Knowledge object modified by {handler.func.__name__}")
             else:
                 raise ValueError(f"Handler {handler.func.__name__} returned invalid response '{resp}'")
                     
@@ -134,34 +134,41 @@ class ProcessorInterface:
         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}")
+        logger.debug(f"Handling {kobj!r}")
         kobj = self.call_handler_chain(HandlerType.RID, kobj)
         if kobj is STOP_CHAIN: return
         
         if kobj.event_type == EventType.FORGET:
             bundle = self.cache.read(kobj.rid)
             if not bundle: 
-                logger.info("Local bundle not found")
+                logger.debug("Local bundle not found")
                 return
             
             # the bundle (to be deleted) attached to kobj for downstream analysis
-            logger.info("Adding local bundle (to be deleted) to knowledge object")
+            logger.debug("Adding local bundle (to be deleted) to knowledge object")
             kobj.manifest = bundle.manifest
             kobj.contents = bundle.contents
             
         else:
             # attempt to retrieve manifest
             if not kobj.manifest:
+                logger.debug("Manifest not found")
                 if kobj.source == KnowledgeSource.External:
-                    logger.info("Manifest not found, attempting to fetch remotely")
+                    logger.debug("Attempting to fetch remote manifest")
                     manifest = self.network.fetch_remote_manifest(kobj.rid)
-                    if not manifest: return
                     
                 elif kobj.source == KnowledgeSource.Internal:
-                    logger.info("Manifest not found, attempting to read cache")
+                    logger.debug("Attempting to read manifest from cache")
                     bundle = self.cache.read(kobj.rid)
-                    if not bundle: return
-                    manifest = bundle.manifest
+                    if bundle: 
+                        manifest = bundle.manifest
+                    else:
+                        manifest = None
+                        return
+                    
+                if not manifest:
+                    logger.debug("Failed to find manifest")
+                    return
                 
                 kobj.manifest = manifest
                 
@@ -170,19 +177,22 @@ class ProcessorInterface:
             
             # attempt to retrieve bundle
             if not kobj.bundle:
+                logger.debug("Bundle not found")
                 if kobj.source == KnowledgeSource.External:
-                    logger.info("Bundle not found, attempting to fetch")
+                    logger.debug("Attempting to fetch remote bundle")
                     bundle = self.network.fetch_remote_bundle(kobj.rid)
-                    # TODO: WARNING MANIFEST MAY BE DIFFERENT
                     
                 elif kobj.source == KnowledgeSource.Internal:
-                    logger.info("Bundle not found, attempting to read cache")
+                    logger.debug("Attempting to read bundle from cache")
                     bundle = self.cache.read(kobj.rid)
                 
+                if not bundle: 
+                    logger.debug("Failed to find bundle")
+                    return
+                
                 if kobj.manifest != bundle.manifest:
                     logger.warning("Retrieved bundle contains a different manifest")
                 
-                if not bundle: return
                 kobj.manifest = bundle.manifest
                 kobj.contents = bundle.contents                
                 
@@ -190,31 +200,34 @@ class ProcessorInterface:
         if kobj is STOP_CHAIN: return
             
         if kobj.normalized_event_type in (EventType.UPDATE, EventType.NEW):
-            logger.info(f"Writing {kobj!r} to cache")
+            logger.info(f"Writing to cache: {kobj!r}")
             self.cache.write(kobj.bundle)
             
         elif kobj.normalized_event_type == EventType.FORGET:
-            logger.info(f"Deleting {kobj!r} from cache")
+            logger.info(f"Deleting from cache: {kobj!r}")
             self.cache.delete(kobj.rid)
             
         else:
-            logger.info("Normalized event type was never set, no cache or network operations will occur")
+            logger.debug("Normalized event type was never set, no cache or network operations will occur")
             return
         
         if type(kobj.rid) in (KoiNetNode, KoiNetEdge):
-            logger.info("Change to node or edge, regenerating network graph")
+            logger.debug("Change to node or edge, regenerating network graph")
             self.network.graph.generate()
         
         kobj = self.call_handler_chain(HandlerType.Network, kobj)
         if kobj is STOP_CHAIN: return
         
         if kobj.network_targets:
-            logger.info(f"Broadcasting event to {len(kobj.network_targets)} network target(s)")
+            logger.debug(f"Broadcasting event to {len(kobj.network_targets)} network target(s)")
         else:
-            logger.info("No network targets set")
+            logger.debug("No network targets set")
         
         for node in kobj.network_targets:
-            self.network.push_event_to(kobj.normalized_event, node, flush=True)
+            self.network.push_event_to(kobj.normalized_event, node)
+            if not self.network.flush_webhook_queue(node):
+                logger.warning("Dropping unresponsive node")
+                self.handle(rid=node, event_type=EventType.FORGET)
         
         kobj = self.call_handler_chain(HandlerType.Final, kobj)
 
@@ -228,18 +241,25 @@ class ProcessorInterface:
         
         while not self.kobj_queue.empty():
             kobj = self.kobj_queue.get()
-            logger.info(f"Dequeued {kobj!r}")
-            self.process_kobj(kobj)
-            self.kobj_queue.task_done()
-            logger.info("Done handling")
+            logger.debug(f"Dequeued {kobj!r}")
+            
+            try:
+                self.process_kobj(kobj)
+            finally:
+                self.kobj_queue.task_done()
+            logger.debug("Done")
     
     def kobj_processor_worker(self, timeout=0.1):
         while True:
             try:
                 kobj = self.kobj_queue.get(timeout=timeout)
-                logger.info(f"Dequeued {kobj!r}")
-                self.process_kobj(kobj)
-                self.kobj_queue.task_done()
+                logger.debug(f"Dequeued {kobj!r}")
+                
+                try:
+                    self.process_kobj(kobj)
+                finally:
+                    self.kobj_queue.task_done()
+                logger.debug("Done")
             
             except queue.Empty:
                 pass
@@ -275,4 +295,4 @@ class ProcessorInterface:
             raise ValueError("One of 'rid', 'manifest', 'bundle', 'event', or 'kobj' must be provided")
         
         self.kobj_queue.put(_kobj)
-        logger.info(f"Queued {_kobj!r}")
+        logger.debug(f"Queued {_kobj!r}")

koi_net/processor/knowledge_object.py

@@ -35,7 +35,7 @@ class KnowledgeObject(BaseModel):
     network_targets: set[KoiNetNode] = set()
     
     def __repr__(self):
-        return f"<Knowledge Object '{self.rid}' ({self.event_type}) -> ({self.normalized_event_type})>"
+        return f"<KObj '{self.rid}' event type: '{self.event_type}' -> '{self.normalized_event_type}', source: '{self.source}'>"
     
     @classmethod
     def from_rid(

koi_net/protocol/event.py

@@ -15,6 +15,9 @@ class Event(BaseModel):
     manifest: Manifest | None = None
     contents: dict | None = None
     
+    def __repr__(self):
+        return f"<Event '{self.rid}' event type: '{self.event_type}'>"
+    
     @classmethod
     def from_bundle(cls, event_type: EventType, bundle: Bundle):
         return cls(

{koi_net-1.0.0b9.dist-info → koi_net-1.0.0b11.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: koi-net
-Version: 1.0.0b9
+Version: 1.0.0b11
 Summary: Implementation of KOI-net protocol in Python
 Project-URL: Homepage, https://github.com/BlockScience/koi-net/
 Author-email: Luke Miller <luke@block.science>
@@ -44,6 +44,37 @@ Description-Content-Type: text/markdown
 
 *This specification is the result of several iterations of KOI research, [read more here](https://github.com/BlockScience/koi).*
 
+### Jump to Sections: 
+- [Protocol](#protocol)
+    - [Introduction](#introduction)
+    - [Communication Methods](#communication-methods)
+- [Quickstart](#quickstart)
+    - [Setup](#setup)
+    - [Creating a Node](#creating-a-node)
+    - [Knowledge Processing](#knowledge-processing)
+    - [Try It Out!](#try-it-out)
+- [Advanced](#advanced)
+    - [Knowledge Processing Pipeline](#knowledge-processing-pipeline)
+    - [Knowledge Handlers](#knowledge-handlers)
+        - [RID Handler](#rid-handler)
+        - [Manifest Handler](#manifest-handler)
+        - [Bundle Handler](#bundle-handler)
+        - [Network Handler](#network-handler)
+        - [Final Handler](#final-handler)
+    - [Registering Handlers](#registering-handlers)
+    - [Default Behavior](#default-behavior)
+- [Implementation Reference](#implementation-reference)
+    - [Node Interface](#node-interface)
+    - [Node Identity](#node-identity)
+    - [Network Interface](#network-interface)
+        - [Network Graph](#network-graph)
+        - [Request Handler](#request-handler)
+        - [Response Handler](#response-handler)
+    - [Processor Interface](#processor-interface)
+- [Development](#development)
+    - [Setup](#setup-1)
+    - [Distribution](#distribution)
+
 # Protocol
 ## Introduction
 
@@ -87,7 +118,9 @@ The request and payload JSON objects are composed of the fundamental "knowledge
 }
 ```
 
-This means that events are essentially just an RID, manifest, or bundle with an event type attached. Event types can be one of `"FORGET"`, `"UPDATE"`, or `"NEW"` forming the "FUN" acronym. While these types roughly correspond to delete, update, and create from CRUD operations, but they are not commands, they are signals. A node emits an event to indicate that its internal state has changed:
+An event is a signalling construct that conveys information about RID objects between networked nodes. Events are composed of an RID, manifest, or bundle with an event type attached. Event types can be one of `"FORGET"`, `"UPDATE"`, or `"NEW"` forming the "FUN" acronym. 
+
+As opposed to CRUD (create, read, update, delete), events are a series of messages, not operations. Each node has its own autonomy in deciding how to react based on the message it receives. For example, a processor node may receive a `"NEW"` event for an RID object its not interested in, and ignore it. Or it may decide that an `"UPDATE"` event should trigger fetching a bundle from another node. A node emits an event to indicate that its internal state has changed:
 - `"NEW"` - indicates an previously unknown RID was cached
 - `"UPDATE"` - indicates a previously known RID was cached
 - `"FORGET"` - indicates a previously known RID was deleted
@@ -653,5 +686,5 @@ python -m build
 ```
 Push new package build to PyPI:
 ```shell
-python -m twine upload dist/*
+python -m twine upload --skip-existing dist/*
 ```

koi_net-1.0.0b11.dist-info/RECORD

@@ -0,0 +1,24 @@
+koi_net/__init__.py,sha256=b0Ze0pZmJAuygpWUFHM6Kvqo3DkU_uzmkptv1EpAArw,31
+koi_net/core.py,sha256=975g-IcEQ72wZCulg34Orh7vJNRWMCh5iC5kppz_18Q,4687
+koi_net/identity.py,sha256=PBgmAx5f3zzQmHASB1TJW2g19n9TLfmSJMXg2eQFg0A,2386
+koi_net/network/__init__.py,sha256=r_RN-q_mDYC-2RAkN-lJoMUX76TXyfEUc_MVKW87z0g,39
+koi_net/network/graph.py,sha256=KyS4Vv94DhHQk12u6rmE8nOIuTxeoJjrnoYEwVMNM74,4837
+koi_net/network/interface.py,sha256=ogVnVufGPv_x83KnGf3AwhCBTF8xETBH3QId6oqpyNs,10708
+koi_net/network/request_handler.py,sha256=dufyJRwKD5w578UM-wzFVT3EU78NMvrh_yNSiI7vgfw,4938
+koi_net/network/response_handler.py,sha256=HaP8Fl0bp_lfMmevhdVY8s9o0Uf8CR1ZaW5g3jsX8gw,1888
+koi_net/processor/__init__.py,sha256=x4fAY0hvQEDcpfdTB3POIzxBQjYAtn0qQazPo1Xm0m4,41
+koi_net/processor/default_handlers.py,sha256=ebFJ_MqvGBAb0SxmreZ9Pvyi0tD7ygDvJKECglw8uAQ,6972
+koi_net/processor/handler.py,sha256=a2wxG3kgux-07YP13HSj_PH5VH_PjbnTS4uZEHjxMw0,2582
+koi_net/processor/interface.py,sha256=IH3rh2lAliqNSKsuH8PwY9N098SnVUBy3Ccel8YgiRM,13188
+koi_net/processor/knowledge_object.py,sha256=xI1K4lIGJrWbb7yStjpU4eqZGI7t4wFklv72V7TRfXY,4212
+koi_net/protocol/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+koi_net/protocol/api_models.py,sha256=RDwVHAahiWzwzUnlj5MIm9et5WVpQOaG-Uscv1B9coU,1116
+koi_net/protocol/consts.py,sha256=zeWJvRpqcERrqJq39heyNHb6f_9QrvoBZJHd70yE914,249
+koi_net/protocol/edge.py,sha256=G3D9Ie0vbTSMJdoTw9g_oBmFCqzJ1gO7U1PVrw7p3j8,447
+koi_net/protocol/event.py,sha256=YHsLD9HPwib-HiCWv9ep0sPqL2VHQqx_egDmbriChXM,1378
+koi_net/protocol/helpers.py,sha256=9E9PaoIuSNrTBATGCLJ_kSBMZ2z-KIMnLJzGOTqQDC0,719
+koi_net/protocol/node.py,sha256=Ntrx01dbm39ViKGtr4gLmztcMwKpTIweS6rRL-zoU_Y,391
+koi_net-1.0.0b11.dist-info/METADATA,sha256=CAQb9AH_yDb2FO1XT9FzmDrrfUsCYTDUUo3mCPq8VQ4,34131
+koi_net-1.0.0b11.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+koi_net-1.0.0b11.dist-info/licenses/LICENSE,sha256=XBcvl8yjCAezfuqN1jadQykrX7H2g4nr2WRDmHLW6ik,1090
+koi_net-1.0.0b11.dist-info/RECORD,,

koi_net-1.0.0b9.dist-info/RECORD

@@ -1,24 +0,0 @@
-koi_net/__init__.py,sha256=b0Ze0pZmJAuygpWUFHM6Kvqo3DkU_uzmkptv1EpAArw,31
-koi_net/core.py,sha256=dE4sE2qsoIRUU1zsnrjx7aqYtYdHyCx-Dv4cwbkRjy4,4613
-koi_net/identity.py,sha256=PBgmAx5f3zzQmHASB1TJW2g19n9TLfmSJMXg2eQFg0A,2386
-koi_net/network/__init__.py,sha256=r_RN-q_mDYC-2RAkN-lJoMUX76TXyfEUc_MVKW87z0g,39
-koi_net/network/graph.py,sha256=KMUCU3AweRvivwy7GuWgX2zX74FPgHeVMO5ydvhVyvA,4833
-koi_net/network/interface.py,sha256=4JTeg8Eah0z5YKhcVKJbCVZw_Ghl_6xfG8aa1I5PCWI,10643
-koi_net/network/request_handler.py,sha256=fhuCDsxI8fZ4p5TntcTZR4mnLrLQ61zDy7Oca3ooFCE,4402
-koi_net/network/response_handler.py,sha256=HaP8Fl0bp_lfMmevhdVY8s9o0Uf8CR1ZaW5g3jsX8gw,1888
-koi_net/processor/__init__.py,sha256=x4fAY0hvQEDcpfdTB3POIzxBQjYAtn0qQazPo1Xm0m4,41
-koi_net/processor/default_handlers.py,sha256=cdGDFb4z1vnDmAXQO5XeDjhbUHbB8TndC-E6AFJzp2M,6930
-koi_net/processor/handler.py,sha256=a2wxG3kgux-07YP13HSj_PH5VH_PjbnTS4uZEHjxMw0,2582
-koi_net/processor/interface.py,sha256=5zYxaD_ATjjp1xFunRomCrrzjyspi8zZzeY2Rca7bVU,12522
-koi_net/processor/knowledge_object.py,sha256=cGv33fwNZQMylkhlTaQTbk96FVIVbdOUaBsG06u0m4k,4187
-koi_net/protocol/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-koi_net/protocol/api_models.py,sha256=RDwVHAahiWzwzUnlj5MIm9et5WVpQOaG-Uscv1B9coU,1116
-koi_net/protocol/consts.py,sha256=zeWJvRpqcERrqJq39heyNHb6f_9QrvoBZJHd70yE914,249
-koi_net/protocol/edge.py,sha256=G3D9Ie0vbTSMJdoTw9g_oBmFCqzJ1gO7U1PVrw7p3j8,447
-koi_net/protocol/event.py,sha256=dzJmcHbimo7p5NwH2drccF0vMcAj9oQRj3iZ9Bjf7kg,1275
-koi_net/protocol/helpers.py,sha256=9E9PaoIuSNrTBATGCLJ_kSBMZ2z-KIMnLJzGOTqQDC0,719
-koi_net/protocol/node.py,sha256=Ntrx01dbm39ViKGtr4gLmztcMwKpTIweS6rRL-zoU_Y,391
-koi_net-1.0.0b9.dist-info/METADATA,sha256=GZbTzNd_k5uVlvaik7_YXdYd17Ya6XtVTf6NXrxbRes,32539
-koi_net-1.0.0b9.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-koi_net-1.0.0b9.dist-info/licenses/LICENSE,sha256=XBcvl8yjCAezfuqN1jadQykrX7H2g4nr2WRDmHLW6ik,1090
-koi_net-1.0.0b9.dist-info/RECORD,,