koi-net 1.0.0b2__py3-none-any.whl → 1.0.0b4__py3-none-any.whl

koi_net/network/graph.py

@@ -14,6 +14,10 @@ logger = logging.getLogger(__name__)
 class NetworkGraph:
     """Graph functions for this node's view of its network."""
     
+    cache: Cache
+    identity: NodeIdentity
+    dg: nx.DiGraph
+    
     def __init__(self, cache: Cache, identity: NodeIdentity):
         self.cache = cache
         self.dg = nx.DiGraph()

koi_net/network/request_handler.py

@@ -12,7 +12,9 @@ from ..protocol.api_models import (
     FetchRids,
     FetchManifests,
     FetchBundles,
-    PollEvents
+    PollEvents,
+    RequestModels,
+    ResponseModels
 )
 from ..protocol.consts import (
     BROADCAST_EVENTS_PATH,
@@ -38,13 +40,19 @@ class RequestHandler:
         self.cache = cache
         self.graph = graph
                 
-    def make_request(self, url, request: BaseModel) -> httpx.Response:
+    def make_request(
+        self, 
+        url: str, 
+        request: RequestModels,
+        response_model: type[ResponseModels] | None = None
+    ) -> ResponseModels | None:
         logger.info(f"Making request to {url}")
         resp = httpx.post(
             url=url,
             data=request.model_dump_json()
         )
-        return resp
+        if response_model:
+            return response_model.model_validate_json(resp.text)
             
     def get_url(self, node_rid: KoiNetNode, url: str) -> str:
         """Retrieves URL of a node, or returns provided URL."""
@@ -64,54 +72,70 @@ class RequestHandler:
             return url
     
     def broadcast_events(
-        self, node: RID = None, url: str = None, **kwargs
+        self, 
+        node: RID = None, 
+        url: str = None, 
+        req: EventsPayload | None = None,
+        **kwargs
     ) -> None:
         """See protocol.api_models.EventsPayload for available kwargs."""
         self.make_request(
             self.get_url(node, url) + BROADCAST_EVENTS_PATH,
-            EventsPayload.model_validate(kwargs)
+            req or EventsPayload.model_validate(kwargs)
         )
         
     def poll_events(
-        self, node: RID = None, url: str = None, **kwargs
+        self, 
+        node: RID = None, 
+        url: str = None, 
+        req: PollEvents | None = None,
+        **kwargs
     ) -> EventsPayload:
         """See protocol.api_models.PollEvents for available kwargs."""
-        resp = self.make_request(
+        return self.make_request(
             self.get_url(node, url) + POLL_EVENTS_PATH,
-            PollEvents.model_validate(kwargs)
+            req or PollEvents.model_validate(kwargs),
+            response_model=EventsPayload
         )
-        
-        return EventsPayload.model_validate_json(resp.text)
-    
+            
     def fetch_rids(
-        self, node: RID = None, url: str = None, **kwargs
+        self, 
+        node: RID = None, 
+        url: str = None, 
+        req: FetchRids | None = None,
+        **kwargs
     ) -> RidsPayload:
         """See protocol.api_models.FetchRids for available kwargs."""
-        resp = self.make_request(
+        return self.make_request(
             self.get_url(node, url) + FETCH_RIDS_PATH,
-            FetchRids.model_validate(kwargs)
+            req or FetchRids.model_validate(kwargs),
+            response_model=RidsPayload
         )
-        
-        return RidsPayload.model_validate_json(resp.text)
-        
+                
     def fetch_manifests(
-        self, node: RID = None, url: str = None, **kwargs
+        self, 
+        node: RID = None, 
+        url: str = None, 
+        req: FetchManifests | None = None,
+        **kwargs
     ) -> ManifestsPayload:
         """See protocol.api_models.FetchManifests for available kwargs."""
-        resp = self.make_request(
+        return self.make_request(
             self.get_url(node, url) + FETCH_MANIFESTS_PATH,
-            FetchManifests.model_validate(kwargs)
+            req or FetchManifests.model_validate(kwargs),
+            response_model=ManifestsPayload
         )
-        
-        return ManifestsPayload.model_validate_json(resp.text)
-        
+                
     def fetch_bundles(
-        self, node: RID = None, url: str = None, **kwargs
+        self, 
+        node: RID = None, 
+        url: str = None, 
+        req: FetchBundles | None = None,
+        **kwargs
     ) -> BundlesPayload:
         """See protocol.api_models.FetchBundles for available kwargs."""
-        resp = self.make_request(
+        return self.make_request(
             self.get_url(node, url) + FETCH_BUNDLES_PATH,
-            FetchBundles.model_validate(kwargs)
-        )
-        
-        return BundlesPayload.model_validate_json(resp.text)
+            req or FetchBundles.model_validate(kwargs),
+            response_model=BundlesPayload
+        )

koi_net/processor/default_handlers.py

@@ -5,7 +5,7 @@ from rid_lib.ext.bundle import Bundle
 from rid_lib.types import KoiNetNode, KoiNetEdge
 from koi_net.protocol.node import NodeType
 from .interface import ProcessorInterface
-from .handler import HandlerType, STOP_CHAIN
+from .handler import KnowledgeHandler, HandlerType, STOP_CHAIN
 from .knowledge_object import KnowledgeObject, KnowledgeSource
 from ..protocol.event import Event, EventType
 from ..protocol.edge import EdgeProfile, EdgeStatus, EdgeType
@@ -14,7 +14,7 @@ logger = logging.getLogger(__name__)
 
 # RID handlers
 
-@ProcessorInterface.as_handler(handler_type=HandlerType.RID)
+@KnowledgeHandler.create(HandlerType.RID)
 def basic_rid_handler(processor: ProcessorInterface, kobj: KnowledgeObject):
     """Default RID handler.
     
@@ -25,7 +25,7 @@ def basic_rid_handler(processor: ProcessorInterface, kobj: KnowledgeObject):
         logger.info("Don't let anyone else tell me who I am!")
         return STOP_CHAIN
     
-    if kobj.event_type == EventType.FORGET:        
+    if kobj.event_type == EventType.FORGET:
         if processor.cache.exists(kobj.rid):
             logger.info("Allowing cache forget")
             kobj.normalized_event_type = EventType.FORGET
@@ -38,7 +38,7 @@ def basic_rid_handler(processor: ProcessorInterface, kobj: KnowledgeObject):
 
 # Manifest handlers
 
-@ProcessorInterface.as_handler(handler_type=HandlerType.Manifest)
+@KnowledgeHandler.create(HandlerType.Manifest)
 def basic_state_handler(processor: ProcessorInterface, kobj: KnowledgeObject):
     """Default manifest handler.
     
@@ -66,7 +66,7 @@ def basic_state_handler(processor: ProcessorInterface, kobj: KnowledgeObject):
 
 # Bundle handlers
 
-@ProcessorInterface.as_handler(HandlerType.Bundle, rid_types=[KoiNetEdge])
+@KnowledgeHandler.create(HandlerType.Bundle, rid_types=[KoiNetEdge])
 def edge_negotiation_handler(processor: ProcessorInterface, kobj: KnowledgeObject):
     """Handles basic edge negotiation process.
     
@@ -131,7 +131,7 @@ def edge_negotiation_handler(processor: ProcessorInterface, kobj: KnowledgeObjec
 
 # Network handlers
 
-@ProcessorInterface.as_handler(HandlerType.Network)
+@KnowledgeHandler.create(HandlerType.Network)
 def basic_network_output_filter(processor: ProcessorInterface, kobj: KnowledgeObject):
     """Default network handler.
     

koi_net/processor/handler.py

@@ -34,4 +34,19 @@ class KnowledgeHandler:
     func: Callable
     handler_type: HandlerType
     rid_types: list[RIDType] | None
+    
+    @classmethod
+    def create(
+        cls,
+        handler_type: HandlerType,
+        rid_types: list[RIDType] | None = None
+    ):
+        """Special decorator that returns a KnowledgeHandler instead of a function.
+        
+        The function symbol will redefined as a `KnowledgeHandler`, which can be passed into the `ProcessorInterface` constructor. This is used to register default handlers.
+        """
+        def decorator(func: Callable) -> KnowledgeHandler:
+            handler = cls(func, handler_type, rid_types)
+            return handler
+        return decorator
 

koi_net/processor/interface.py

@@ -44,21 +44,9 @@ 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.
         
-        The function symbol will redefined as a `KnowledgeHandler`, which can be passed into the `ProcessorInterface` constructor. This is used to register the default handlers.
-        """
-        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,
@@ -68,7 +56,7 @@ class ProcessorInterface:
         """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
             
@@ -114,7 +102,7 @@ class ProcessorInterface:
         return kobj
 
         
-    def handle_kobj(self, kobj: KnowledgeObject) -> None:
+    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:
@@ -211,21 +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):
-        """Queues a knowledge object to be put processed in the pipeline."""
-        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(
@@ -234,23 +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, or event (with an optional event type for non event 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.
+        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/protocol/api_models.py

@@ -38,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-1.0.0b4.dist-info/METADATA

@@ -0,0 +1,510 @@
+Metadata-Version: 2.4
+Name: koi-net
+Version: 1.0.0b4
+Summary: Implementation of KOI-net protocol in Python
+Project-URL: Homepage, https://github.com/BlockScience/koi-net/
+Author-email: Luke Miller <luke@block.science>
+License: MIT License
+        
+        Copyright (c) 2025 BlockScience
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: networkx>=3.4.2
+Requires-Dist: pydantic>=2.10.6
+Requires-Dist: rid-lib>=3.2.1
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: twine>=6.0; extra == 'dev'
+Provides-Extra: examples
+Requires-Dist: fastapi; extra == 'examples'
+Requires-Dist: rich; extra == 'examples'
+Requires-Dist: uvicorn; extra == 'examples'
+Description-Content-Type: text/markdown
+
+# KOI-net
+
+*This specification is the result of several iterations of KOI research, [read more here](https://github.com/BlockScience/koi).*
+
+# Protocol
+## Introduction
+
+*This project builds upon and uses the [RID protocol](https://github.com/BlockScience/rid-lib) to identify and coordinate around knowledge objects.*
+
+This protocol defines the standard communication patterns and coordination norms needed to establish and maintain Knowledge Organization Infrastructure (KOI) networks. KOI-nets are heterogenous compositions of KOI nodes, each of which is capable of autonomously inputting, processing, and outputting knowledge. The behavior of each node and configuration of each network can vary greatly, thus the protocol is designed to be a simple and flexible but interoperable foundation for future projects to build on. The protocol only governs communication between nodes, not how they operate internally. As a result we consider KOI-nets to be fractal-like, in that a network of nodes may act like a single node from an outside perspective.
+
+Generated OpenAPI documentation is provided in this repository, and can be [viewed interactively with Swagger](https://generator.swagger.io/?url=https://raw.githubusercontent.com/BlockScience/koi-net/refs/heads/main/koi-net-protocol-openapi.json).
+
+## Communication Methods
+
+There are two classes of communication methods, event and state communication. 
+- Event communication is one way, a node send an event to another node. 
+- State communication is two way, a node asks another node for RIDs, manifests, or bundles and receives a response containing the requested resource (if available).
+
+There are also two types of nodes, full and partial nodes. 
+- Full nodes are web servers, implementing the endpoints defined in the KOi-net protocol. They are capable of receiving events via webhooks (another node calls their endpoint), and serving state queries. They can also call the endpoints of other full nodes to broadcast events or retrieve state. 
+- Partial nodes are web clients and don't implement any API endpoints. They are capable of receiving events via polling (asking another node for events). They can also call the endpoints of full nodes to broadcast events or retrieve state.
+
+There are five endpoints defined by the API spec. The first two are for event communication with full and partial nodes respectively. The remaining three are for state communication with full nodes. As a result, partial nodes are unable to directly transfer state and may only output events to other nodes.
+- Broadcast events - `/events/broadcast`
+- Poll events - `/events/poll`
+- Fetch bundles - `/bundles/fetch`
+- Fetch manifests - `/manifests/fetch`
+- Fetch RIDs - `/rids/fetch`
+
+All endpoints are called with via POST request with a JSON body, and will receive a response containing a JSON payload (with the exception of broadcast events, which won't return anything). The JSON schemas can be found in the attached OpenAPI specification or the Pydantic models in the "protocol" module.
+
+The request and payload JSON objects are composed of the fundamental "knowledge types" from the RID / KOI-net system: RIDs, manifests, bundles, and events. RIDs, manifests, and bundles are defined by the RID protocol and imported from rid-lib, which you can [read about here](https://github.com/BlockScience/rid-lib). Events are now part of the KOI-net protocol, and are defined as an RID and an event type with an optional manifest and contents. 
+
+```json
+{
+    "rid": "...",
+    "event_type": "NEW | UPDATE | FORGET",
+    "manifest": {
+        "rid": "...",
+        "timestamp": "...",
+        "sha256_hash": "...",
+    },
+    "contents": {}
+}
+```
+
+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:
+- `NEW` - indicates an previously unknown RID was cached
+- `UPDATE` - indicates a previously known RID was cached
+- `FORGET` - indicates a previously known RID was deleted
+
+Nodes may broadcast events to other nodes to indicate their internal state changed. Conversely, nodes may also listen to events from other nodes and as a result decide to change their internal state, take some other action, or do nothing.
+
+
+# Quickstart
+## Setup
+
+The bulk of the code in this repo is taken up by the Python reference implementation, which can be used in other projects to easily set up and configure your own KOI-net node.
+
+This package can be installed with pip:
+```shell
+pip install koi-net
+```
+
+## Creating a Node
+
+*Check out the `examples/` folder to follow along!*
+
+All of the KOI-net functionality comes from the `NodeInterface` class which provides methods to interact with the protocol API, a local RID cache, a view of the network, and an internal processing pipeline. To create a new node, you will need to give it a name and a profile. The name will be used to generate its unique node RID, and the profile stores basic configuration data which will be shared with the other nodes that you communciate with.
+
+Your first decision will be whether to setup a partial or full node:
+- Partial nodes only need to indicate their type, and optionally the RID types of events they provide.
+- Full nodes need to indicate their type, the base URL for their KOI-net API, and optionally the RID types of events and state they provide.
+
+### Partial Node
+```python
+from koi_net import NodeInterface
+from koi_net.protocol.node import NodeProfile, NodeProvides, NodeType
+
+node = NodeInterface(
+    name="mypartialnode",
+    profile=NodeProfile(
+        node_type=NodeType.PARTIAL,
+        provides=NodeProvides(
+            event=[]
+        )
+    )
+)
+```
+### Full Node
+```python
+from koi_net import NodeInterface
+from koi_net.protocol.node import NodeProfile, NodeProvides, NodeType
+
+node = NodeInterface(
+    name="myfullnode",
+    profile=NodeProfile(
+        base_url="http://127.0.0.1:8000",
+        node_type=NodeType.FULL,
+        provides=NodeProvides(
+            event=[],
+            state=[]
+        )
+    )
+)
+```
+
+## Knowledge Processing
+
+Next we'll set up the knowledge processing flow for our node. This is where most of the node's logic and behavior will come into play. For partial nodes this will be an event loop, and for full nodes we will use webhooks. Make sure to call `node.initialize()` and `node.finalize()` at the beginning and end of your node's life cycle.
+
+### Partial Node
+Make sure to set `source=KnowledgeSource.External`, this indicates to the knowledge processing pipeline that the incoming knowledge was received from an external source. Where the knowledge is sourced from will impact decisions in the node's knowledge handlers.
+```python
+import time
+from koi_net.processor.knowledge_object import KnowledgeSource
+
+if __name__ == "__main__":
+    node.initialize()
+
+    try:
+        while True:
+            for event in node.network.poll_neighbors():
+                node.processor.handle(event=event, source=KnowledgeSource.External)
+            node.processor.flush_kobj_queue()
+            
+            time.sleep(5)
+            
+    finally:
+        node.finalize()
+```
+
+### Full Node
+Setting up a full node is slightly more complex as we'll need a webserver. For this example, we'll use FastAPI and uvicorn. First we need to setup the "lifespan" of the server, to initialize and finalize the node before and after execution, as well as the FastAPI app which will be our web server.
+```python
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    node.initialize()
+    yield
+    node.finalize()
+
+
+app = FastAPI(lifespan=lifespan, root_path="/koi-net")
+```
+
+Next we'll add our event handling webhook endpoint, which will allow other nodes to broadcast events to us. You'll notice that we have a similar loop to our partial node, but instead of polling periodicially, we handle events asynchronously as we receive them from other nodes.
+
+```python
+from koi_net.protocol.api_models import *
+from koi_net.protocol.consts import *
+
+@app.post(BROADCAST_EVENTS_PATH)
+def broadcast_events(req: EventsPayload, background: BackgroundTasks):
+    for event in req.events:
+        node.processor.handle(event=event, source=KnowledgeSource.External)
+    
+    background.add_task(node.processor.flush_kobj_queue)
+```
+
+Next we can add the event polling endpoint, this allows partial nodes to receive events from us.
+
+```python
+@app.post(POLL_EVENTS_PATH)
+def poll_events(req: PollEvents) -> EventsPayload:
+    events = node.network.flush_poll_queue(req.rid)
+    return EventsPayload(events=events)
+```
+
+Now for the state transfer "fetch" endpoints:
+```python
+@app.post(FETCH_RIDS_PATH)
+def fetch_rids(req: FetchRids) -> RidsPayload:
+    return node.network.response_handler.fetch_rids(req)
+
+@app.post(FETCH_MANIFESTS_PATH)
+def fetch_manifests(req: FetchManifests) -> ManifestsPayload:
+    return node.network.response_handler.fetch_manifests(req)
+
+@app.post(FETCH_BUNDLES_PATH)
+def fetch_bundles(req: FetchBundles) -> BundlesPayload:
+    return node.network.response_handler.fetch_bundles(req)
+```
+
+Finally we can run the server!
+
+```python
+import uvicorn
+
+if __name__ == "__main__":
+    # update this path to the Python module that defines "app"
+    uvicorn.run("examples.full_node_template:app", port=8000)
+```
+
+*Note: If your node is not the first node in the network, you'll also want to set up a "first contact" in the `NodeInterface`. This is the URL of another full node that can be used to make your first connection and find out about other nodes in the network.*
+
+## Try It Out!
+
+In addition to the partial and full node templates, there's also example implementations that showcase a coordinator + partial node setup. You can run both of them locally after cloning this repository. First, install the koi-net library with the optional examples requirements from the root directory in the repo:
+```shell
+pip install .[examples]
+```
+Then you can start each node in a separate terminal:
+```shell
+python -m examples.basic_coordinator_node
+```
+```shell
+python -m examples.basic_partial_node
+```
+
+# Implementation Reference
+This section provides high level explanations of the Python implementation. More detailed explanations of methods can be found in the docstrings within the codebase itself.
+
+## Node Interface
+The node class mostly acts as a container for other classes with more specialized behavior, with special functions that should be called to start up and shut down a node. We'll take a look at each of these components in turn, but here is the class stub:
+```python
+class NodeInterface:
+    cache: Cache
+    identity: NodeIdentity
+    network: NetworkInterface
+    processor: ProcessorInterface
+    first_contact: str
+
+    def __init__(
+        self, 
+        name: str,
+        profile: NodeProfile,
+        identity_file_path: str = "identity.json",
+        first_contact: str | None = None,
+        handlers: list[KnowledgeHandler] | None = None,
+        cache: Cache | None = None,
+        network: NetworkInterface | None = None,
+        processor: ProcessorInterface | None = None
+    ): ...
+
+    def initialize(self): ...
+    def finalize(self): ...
+```
+As you can see, only a name and profile are required. The other fields allow for additional customization if needed.
+
+## Node Identity
+The `NodeIdentity` class provides easy access to a node's own RID, profile, and bundle. It provides access to the following properties after initialization, accessed with `node.identity`.
+```python
+class NodeIdentity:
+    rid: KoiNetNode # an RID type
+    profile: NodeProfile
+    bundle: Bundle
+```
+This it what is initialized from the required `name` and `profile` fields in the `NodeInterface` constructor. Node RIDs take the form of `orn:koi-net.node:<name>+<uuid>`, and are generated on first use to the identity JSON file along with a the node profile.
+
+## Network Interface
+The `NetworkInterface` class provides access to high level network actions, and contains several other network related classes. It is accessed with `node.network`.
+```python
+class NetworkInterface:
+    graph: NetworkGraph
+    request_handler: RequestHandler
+    response_handler: ResponseHandler
+
+    def __init__(
+        self, 
+        file_path: str,
+        first_contact: str | None,
+        cache: Cache, 
+        identity: NodeIdentity
+    ): ...
+
+    def push_event_to(self, event: Event, node: KoiNetNode, flush=False): ...
+    
+    def flush_poll_queue(self, node: KoiNetNode) -> list[Event]: ...
+    def flush_webhook_queue(self, node: RID): ...
+    def flush_all_webhook_queues(self): ...
+
+    def fetch_remote_bundle(self, rid: RID): ...
+    def fetch_remote_manifest(self, rid: RID): ...
+
+    def get_state_providers(self, rid_type: RIDType): ...
+    def poll_neighbors(self) -> list[Event]: ...
+```
+
+Most of the provided functions are abstractions for KOI-net protocol actions. It also contains three lower level classes: `NetworkGraph`, `RequestHandler`, and `ResponseHandler`.
+
+### Network Graph
+The `NetworkGraph` class provides access to a graph view of the node's KOI network: all of the KOI-net node and edge objects it knows about (stored in local cache). This view allows us to query nodes that we have edges with to make networking decisions.
+```python
+class NetworkGraph:
+    dg: nx.DiGraph
+
+    def __init__(
+        self,
+        cache: Cache,
+        identity: NodeIdentity
+    ): ...
+
+    def generate(self): ...
+
+    def get_edges(
+        self, 
+        direction: Literal["in", "out"] | None = None
+    ) -> list[KoiNetEdge]: ...
+
+    def get_neighbors(
+        self,
+        direction: Literal["in", "out"] | None = None,
+        status: EdgeStatus | None = None,
+        allowed_type: RIDType | None = None
+    ) -> list[KoiNetNode]: ...
+    
+    def get_node_profile(self, rid: KoiNetNode) -> NodeProfile | None: ...
+    def get_edge_profile(
+        self,
+        rid: KoiNetEdge | None = None,
+        source: KoiNetNode | None = None,
+        target: KoiNetNode | None = None
+    ) -> EdgeProfile | None: ...
+```
+
+### Request Handler
+Handles raw API requests to other nodes through the KOI-net protocol. Accepts a node RID or direct URL as the target. Each method requires either a valid request model, or `kwargs` which will be converted to the correct model in `koi_net.protocol.api_models`.
+```python
+class RequestHandler:
+    def __init__(self, cache: Cache, graph: NetworkGraph): ...
+
+    def broadcast_events(
+        self, 
+        node: RID = None, 
+        url: str = None, 
+        req: EventsPayload | None = None,
+        **kwargs
+    ) -> None: ...
+
+    def poll_events(
+        self, 
+        node: RID = None, 
+        url: str = None, 
+        req: PollEvents | None = None,
+        **kwargs
+    ) -> EventsPayload: ...
+
+    def fetch_rids(
+        self, 
+        node: RID = None, 
+        url: str = None, 
+        req: FetchRids | None = None,
+        **kwargs
+    ) -> RidsPayload: ...
+
+    def fetch_manifests(
+        self, 
+        node: RID = None, 
+        url: str = None, 
+        req: FetchManifests | None = None,
+        **kwargs
+    ) -> ManifestsPayload: ...
+
+    def fetch_bundles(
+        self, 
+        node: RID = None, 
+        url: str = None, 
+        req: FetchBundles | None = None,
+        **kwargs
+    ) -> BundlesPayload: ...
+```
+
+### Response Handler
+Handles raw API responses to requests from other nodes through the KOI-net protocol.
+```python
+class ResponseHandler:
+    def __init__(self, cache: Cache): ...
+
+    def fetch_rids(self, req: FetchRids) -> RidsPayload:
+    def fetch_manifests(self, req: FetchManifests) -> ManifestsPayload:
+    def fetch_bundles(self, req: FetchBundles) -> BundlesPayload:
+```
+Only fetch methods are provided right now, event polling and broadcasting can be handled like this:
+```python
+def broadcast_events(req: EventsPayload) -> None:
+    for event in req.events:
+        node.processor.handle(event=event, source=KnowledgeSource.External)
+    node.processor.flush_kobj_queue()
+
+def poll_events(req: PollEvents) -> EventsPayload:
+    events = node.network.flush_poll_queue(req.rid)
+    return EventsPayload(events=events)
+```
+
+## Processor Interface
+The `ProcessorInterface` class provides access to a node's internal knowledge processing pipeline.
+```python
+class ProcessorInterface:
+    def __init__(
+        self, 
+        cache: Cache, 
+        network: NetworkInterface,
+        identity: NodeIdentity,
+        default_handlers: list[KnowledgeHandler] = []
+    ): ...
+
+    def add_handler(self, handler: KnowledgeHandler): ...
+    
+    def register_handler(
+        self,
+        handler_type: HandlerType,
+        rid_types: list[RIDType] | None = None
+    ): ...
+
+    def process_kobj(self, kobj: KnowledgeObject) -> None:
+    def flush_kobj_queue(self): ...
+
+    def handle(
+        self,
+        rid: RID | None = None,
+        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
+    ): ...
+```
+
+The `register_handler` method is a decorator which can wrap a function to create a new `KnowledgeHandler` and add it to the processing pipeline in a single step. The `add_handler` method adds an existing `KnowledgeHandler` to the processining pipeline.
+
+The most commonly used functions in this class are `handle` and `flush_kobj_queue`. The `handle` method can be called on RIDs, manifests, bundles, and events to convert them to normalized to `KnowledgeObject` instances which are then added to the processing queue. The `flush` flag can be set to `True` to immediately start processing, or `flush_kobj_queue` can be called after queueing multiple knowledge objects. When calling the `handle` method, knowledge objects are marked as internally source by default. If you are handling RIDs, manifests, bundles, or events sourced from other nodes, `source` should be set to `KnowledgeSource.External`.
+
+Here is an example of how an event polling loop would be implemented using the knowledge processing pipeline:
+```python
+for event in node.network.poll_neighbors():
+    node.processor.handle(event=event, source=KnowledgeSource.External)
+node.processor.flush_kobj_queue()
+```
+
+# Development
+## Setup
+Clone this repository:
+```console
+git clone https://github.com/BlockScience/koi-net
+```
+Set up and activate virtual environment:
+```shell
+python -m venv venv
+```
+Windows:
+```shell
+.\venv\Scripts\activate
+```
+Linux:
+```shell
+source venv/bin/activate
+```
+Install koi-net with dev dependencies:
+```shell
+pip install -e .[dev]
+```
+## Distribution
+*Be careful! All files not in `.gitignore` will be included in the distribution, even if they aren't tracked by git! Double check the `.tar.gz` after building to make sure you didn't accidently include other files.*
+
+Build package:
+```shell
+python -m build
+```
+Push new package build to PyPI:
+```shell
+python -m twine upload -r pypi dist/*
+```

{koi_net-1.0.0b2.dist-info → koi_net-1.0.0b4.dist-info}/RECORD

@@ -2,23 +2,23 @@ koi_net/__init__.py,sha256=b0Ze0pZmJAuygpWUFHM6Kvqo3DkU_uzmkptv1EpAArw,31
 koi_net/core.py,sha256=ZsBoTay7Z1_7JKzKt-vB3x_zl9GEit-fFkCSifLPoOk,3582
 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=VSvjF2p_EsuJsNPFhK4MEjgXW9oZL0Vg9Tn6X4-c3WY,4710
+koi_net/network/graph.py,sha256=SbA0ATIYaiBnq6PCEN2Mu7dgmfyZW3p5tRhZu23UR4E,4782
 koi_net/network/interface.py,sha256=paBJjQFJC8UkUz-BWeRwvuWD2cv8WFt7PyhoV7VOhWI,10823
-koi_net/network/request_handler.py,sha256=FDS6b3MLjeM_w6josbDtHZZUg0D1kuGDwE1H0si8mus,3870
+koi_net/network/request_handler.py,sha256=fhuCDsxI8fZ4p5TntcTZR4mnLrLQ61zDy7Oca3ooFCE,4402
 koi_net/network/response_handler.py,sha256=mA3FtrN3aTZATcLaHQhJUWrJdIKNv6d24fhvOl-nDKY,1890
 koi_net/processor/__init__.py,sha256=x4fAY0hvQEDcpfdTB3POIzxBQjYAtn0qQazPo1Xm0m4,41
-koi_net/processor/default_handlers.py,sha256=kmXBKBCAs6ygsPWl9IFbjZe1KDC_6M0YgkRF7hfI7kU,7224
-koi_net/processor/handler.py,sha256=9ZHsoPyAwFhtJPmvrLY-7C9dQ7KhLwI3DS5_Ms4HWAY,1640
-koi_net/processor/interface.py,sha256=4oiSWz91WWQywbfRdT2H2-aVh_6BTYE2AHbZSovzd0U,11671
+koi_net/processor/default_handlers.py,sha256=Yc7a9n5sAOYMHzzY59VMXYOxQL-6O9zbMQzd61XbIEs,7184
+koi_net/processor/handler.py,sha256=APCECwU7MFcgP7Vu6UTngs0XIjaXSQ_f8rqy8cH5_rM,2242
+koi_net/processor/interface.py,sha256=4D2M09rfLcjBBfAnA1sXBzKlEjhcd_o7xOgwonSc0zc,11092
 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=Vm2Szp2OZ3EsZrYRwkAiBi_smk4MF1dAt-xPGOLi6ME,919
+koi_net/protocol/api_models.py,sha256=79B5IWQ7gsJ_QIsSRv9424F1frF_DMGkhBbYWkXgtOI,1118
 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.0b2.dist-info/METADATA,sha256=Gry4tH3P7Ed1_d0EiC3oBnLIwHa6BmQaM4gTw6V1cbc,10358
-koi_net-1.0.0b2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-koi_net-1.0.0b2.dist-info/licenses/LICENSE,sha256=XBcvl8yjCAezfuqN1jadQykrX7H2g4nr2WRDmHLW6ik,1090
-koi_net-1.0.0b2.dist-info/RECORD,,
+koi_net-1.0.0b4.dist-info/METADATA,sha256=gDXK_D6NTFeIxcK0XFY5kxHuMyU4b6WKNwU9RnNElgo,21219
+koi_net-1.0.0b4.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+koi_net-1.0.0b4.dist-info/licenses/LICENSE,sha256=XBcvl8yjCAezfuqN1jadQykrX7H2g4nr2WRDmHLW6ik,1090
+koi_net-1.0.0b4.dist-info/RECORD,,

koi_net-1.0.0b2.dist-info/METADATA

@@ -1,209 +0,0 @@
-Metadata-Version: 2.4
-Name: koi-net
-Version: 1.0.0b2
-Summary: Implementation of KOI-net protocol in Python
-Project-URL: Homepage, https://github.com/BlockScience/koi-net/
-Author-email: Luke Miller <luke@block.science>
-License: MIT License
-        
-        Copyright (c) 2025 BlockScience
-        
-        Permission is hereby granted, free of charge, to any person obtaining a copy
-        of this software and associated documentation files (the "Software"), to deal
-        in the Software without restriction, including without limitation the rights
-        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-        copies of the Software, and to permit persons to whom the Software is
-        furnished to do so, subject to the following conditions:
-        
-        The above copyright notice and this permission notice shall be included in all
-        copies or substantial portions of the Software.
-        
-        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-        SOFTWARE.
-License-File: LICENSE
-Requires-Python: >=3.10
-Requires-Dist: httpx>=0.28.1
-Requires-Dist: networkx>=3.4.2
-Requires-Dist: pydantic>=2.10.6
-Requires-Dist: rid-lib>=3.2.1
-Provides-Extra: dev
-Requires-Dist: build; extra == 'dev'
-Requires-Dist: twine>=6.0; extra == 'dev'
-Provides-Extra: examples
-Requires-Dist: fastapi; extra == 'examples'
-Requires-Dist: rich; extra == 'examples'
-Requires-Dist: uvicorn; extra == 'examples'
-Description-Content-Type: text/markdown
-
-# KOI-net
-
-*This specification is the result of several iterations of KOI research, [read more here](https://github.com/BlockScience/koi).*
-
-# Protocol
-## Introduction
-
-*This project builds upon and uses the [RID protocol](https://github.com/BlockScience/rid-lib) to identify and coordinate around knowledge objects.*
-
-This protocol defines the standard communication patterns and coordination norms needed to establish and maintain Knowledge Organization Infrastructure (KOI) networks. KOI-nets are heterogenous compositions of KOI nodes, each of which is capable of autonomously inputting, processing, and outputting knowledge. The behavior of each node and configuration of each network can vary greatly, thus the protocol is designed to be a simple and flexible but interoperable foundation for future projects to build on. The protocol only governs communication between nodes, not how they operate internally. As a result we consider KOI-nets to be fractal-like, in that a network of nodes may act like a single node from an outside perspective.
-
-Generated OpenAPI documentation is provided in this repository, and can be [viewed interactively with Swagger](https://generator.swagger.io/?url=https://raw.githubusercontent.com/BlockScience/koi/refs/heads/main/koi_v3_node_api.yaml).
-
-## Communication Methods
-
-There are two classes of communication methods, event and state communication. 
-- Event communication is one way, a node send an event to another node. 
-- State communication is two way, a node asks another node for RIDs, manifests, or bundles and receives a response containing the requested resource (if available).
-
-There are also two types of nodes, full and partial nodes. 
-- Full nodes are web servers, implementing the endpoints defined in the KOi-net protocol. They are capable of receiving events via webhooks (another node calls their endpoint), and serving state queries. They can also call the endpoints of other full nodes to broadcast events or retrieve state. 
-- Partial nodes are web clients and don't implement any API endpoints. They are capable of receiving events via polling (asking another node for events). They can also call the endpoints of full nodes to broadcast events or retrieve state.
-
-There are five endpoints defined by the API spec. The first two are for event communication with full and partial nodes respectively. The remaining three are for state communication with full nodes. As a result, partial nodes are unable to directly transfer state and may only output events to other nodes.
-- Broadcast events - `/events/broadcast`
-- Poll events - `/events/poll`
-- Fetch bundles - `/bundles/fetch`
-- Fetch manifests - `/manifests/fetch`
-- Fetch RIDs - `/rids/fetch`
-
-All endpoints are called with via POST request with a JSON body, and will receive a response containing a JSON payload (with the exception of broadcast events, which won't return anything). The JSON schemas can be found in the attached OpenAPI specification or the Pydantic models in the "protocol" module.
-
-The request and payload JSON objects are composed of the fundamental "knowledge types" from the RID / KOI-net system: RIDs, manifests, bundles, and events. RIDs, manifests, and bundles are defined by the RID protocol and imported from rid-lib, which you can [read about here](https://github.com/BlockScience/rid-lib). Events are now part of the KOI-net protocol, and are defined as an RID and an event type with an optional manifest and contents. 
-
-```json
-{
-    "rid": "...",
-    "event_type": "NEW | UPDATE | FORGET",
-    "manifest": {
-        "rid": "...",
-        "timestamp": "...",
-        "sha256_hash": "...",
-    },
-    "contents": {}
-}
-```
-
-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:
-- `NEW` - indicates an previously unknown RID was cached
-- `UPDATE` - indicates a previously known RID was cached
-- `FORGET` - indicates a previously known RID was deleted
-
-Nodes may broadcast events to other nodes to indicate its internal state changed. Conversely, nodes may also listen to events from other nodes and decide to change their internal state, take some other action, or do nothing.
-
-
-# Implementation
-## Setup
-
-The bulk of the code in this repo is taken up by the Python reference implementation, which can be used in other projects to easily set up and configure your own KOI node.
-
-This package can be installed with pip:
-```
-pip install koi-net
-```
-
-## Node Interface
-All of the KOI-net functionality comes from the `NodeInterface` class which provides methods to interact with the protocol API, a local RID cache, a view of the network, and an internal processing pipeline. To create a new node, you will need to give it a name and a profile. The name will be used to generate its unique node RID, and the profile stores basic configuration data which will be shared with other nodes you communciate with (it will be stored in the bundle associated with your node's RID). 
-- Partial nodes only need to indicate their type, and optionally the RID types of events they provide.
-- Full nodes need to indicate their type, the base URL for their KOI-net API, and optionally the RID types of events and state they provide.
-
-```python
-from koi_net import NodeInterface
-from koi_net.protocol.node import NodeProfile, NodeProvides, NodeType
-
-# partial node configuration
-
-partial_node = NodeInterface(
-    name="mypartialnode",
-    profile=NodeProfile(
-        node_type=NodeType.PARTIAL,
-        provides=NodeProvides(
-            event=[]
-        )
-    )
-)
-
-# full node configuration
-
-full_node = NodeInterface(
-    name="myfullnode",
-    profile=NodeProfile(
-        base_url="http://127.0.0.1:8000",
-        node_type=NodeType.FULL,
-        provides=NodeProvides(
-            event=[],
-            state=[]
-        )
-    )
-)
-```
-
-The node class mostly acts as a container for other classes with more specialized behavior, with special functions that should be called to start up and shut down a node. We'll take a look at each of these components in turn, but here is the class stub:
-```python
-class NodeInterface:
-    cache: Cache
-    identity: NodeIdentity
-    network: NetworkInterface
-    processor: ProcessorInterface
-    first_contact: str
-
-    def __init__(
-        self, 
-        name: str,
-        profile: NodeProfile,
-        identity_file_path: str = "identity.json",
-        first_contact: str | None = None,
-        handlers: list[KnowledgeHandler] | None = None,
-        cache: Cache | None = None,
-        network: NetworkInterface | None = None,
-        processor: ProcessorInterface | None = None
-    ): ...
-
-    def initialize(self): ...
-    def finalize(self): ...
-```
-As you can see, only a name and profile are required. The other fields allow for additional customization if needed.
-
-## Node Identity
-The `NodeIdentity` class provides easy access to a node's own RID, profile, and bundle. It provides access to the following properties after initialization, accessed with `node.identity`.
-```
-class NodeIdentity:
-    rid: KoiNetNode # an RID type
-    profile: NodeProfile
-    bundle: Bundle
-```
-This it what is initialized from the required `name` and `profile` fields in the `NodeInterface` constructor.
-
-## Network Interface
-The `NetworkInterface` class provides access to high level network actions, and contains several other network related classes. It is accessed with `node.network`.
-```python
-class NetworkInterface:
-    graph: NetworkGraph
-    request_handler: RequestHandler
-    response_handler: ResponseHandler
-
-    def __init__(
-        self, 
-        file_path: str,
-        first_contact: str | None,
-        cache: Cache, 
-        identity: NodeIdentity
-    ): ...
-
-    def push_event_to(self, event: Event, node: KoiNetNode, flush=False): ...
-    
-    def flush_poll_queue(self, node: KoiNetNode) -> list[Event]: ...
-    def flush_webhook_queue(self, node: RID): ...
-    def flush_all_webhook_queues(self): ...
-
-    def get_state_providers(self, rid_type: RIDType): ...
-
-    def fetch_remote_bundle(self, rid: RID): ...
-
-    def fetch_remote_manifest(self, rid: RID): ...
-
-    def poll_neighbors(self) -> list[Event]: ...
-