koi-net 1.0.0b1__tar.gz

koi_net-1.0.0b1/.gitignore

@@ -0,0 +1,6 @@
+rid-lib
+__pycache__
+*.json
+venv
+prototypes
+.vscode

koi_net-1.0.0b1/LICENSE

@@ -0,0 +1,21 @@
+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.

koi_net-1.0.0b1/PKG-INFO

@@ -0,0 +1,43 @@
+Metadata-Version: 2.4
+Name: koi-net
+Version: 1.0.0b1
+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

koi_net-1.0.0b1/README.md

@@ -0,0 +1 @@
+# koi-net

koi_net-1.0.0b1/examples/full_node.py

@@ -0,0 +1,134 @@
+import json
+import logging
+import uvicorn
+from contextlib import asynccontextmanager
+from rich.logging import RichHandler
+from fastapi import FastAPI, BackgroundTasks
+from rid_lib.types import KoiNetNode, KoiNetEdge
+from koi_net import NodeInterface
+from koi_net.processor.handler import HandlerType
+from koi_net.processor.knowledge_object import KnowledgeObject, KnowledgeSource
+from koi_net.protocol.edge import EdgeType
+from koi_net.protocol.event import Event, EventType
+from koi_net.protocol.helpers import generate_edge_bundle
+from koi_net.protocol.node import NodeProfile, NodeType, NodeProvides
+from koi_net.processor import ProcessorInterface
+from koi_net.protocol.api_models import (
+    PollEvents,
+    FetchRids,
+    FetchManifests,
+    FetchBundles,
+    EventsPayload,
+    RidsPayload,
+    ManifestsPayload,
+    BundlesPayload
+)
+from koi_net.protocol.consts import (
+    BROADCAST_EVENTS_PATH,
+    POLL_EVENTS_PATH,
+    FETCH_RIDS_PATH,
+    FETCH_MANIFESTS_PATH,
+    FETCH_BUNDLES_PATH
+)
+
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+    datefmt="%Y-%m-%d %H:%M:%S",
+    handlers=[RichHandler()]
+)
+
+logging.getLogger("koi_net").setLevel(logging.DEBUG)
+
+port = 8000
+
+node = NodeInterface(
+    name="coordinator",
+    profile=NodeProfile(
+        base_url=f"http://127.0.0.1:{port}/koi-net",
+        node_type=NodeType.FULL,
+        provides=NodeProvides(
+            event=[KoiNetNode, KoiNetEdge],
+            state=[KoiNetNode, KoiNetEdge]
+        )
+    ),
+    identity_file_path="coordinator_identity.json"
+)
+
+
+logger = logging.getLogger(__name__)
+
+
+@node.processor.register_handler(HandlerType.Network, rid_types=[KoiNetNode])
+def handshake_handler(proc: ProcessorInterface, kobj: KnowledgeObject):    
+    logger.info("Handling node handshake")
+
+    # only respond if node declares itself as NEW
+    if kobj.event_type != EventType.NEW:
+        return
+        
+    logger.info("Sharing this node's bundle with peer")
+    proc.network.push_event_to(
+        event=Event.from_bundle(EventType.NEW, proc.identity.bundle),
+        node=kobj.rid,
+        flush=True
+    )
+    
+    logger.info("Proposing new edge")    
+    # defer handling of proposed edge
+    proc.handle(bundle=generate_edge_bundle(
+        source=kobj.rid,
+        target=proc.identity.rid,
+        edge_type=EdgeType.WEBHOOK,
+        rid_types=[KoiNetNode, KoiNetEdge]
+    ))
+
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    node.initialize()
+    yield
+    node.finalize()
+
+app = FastAPI(
+    lifespan=lifespan, 
+    root_path="/koi-net",
+    title="KOI-net Protocol API",
+    version="1.0.0"
+)
+
+@app.post(BROADCAST_EVENTS_PATH)
+def broadcast_events(req: EventsPayload, background: BackgroundTasks):
+    logger.info(f"Request to {BROADCAST_EVENTS_PATH}, received {len(req.events)} event(s)")
+    for event in req.events:
+        node.processor.handle(event=event, source=KnowledgeSource.External)
+    
+    background.add_task(node.processor.flush_kobj_queue)
+
+@app.post(POLL_EVENTS_PATH)
+def poll_events(req: PollEvents) -> EventsPayload:
+    logger.info(f"Request to {POLL_EVENTS_PATH}")
+    events = node.network.flush_poll_queue(req.rid)
+    return EventsPayload(events=events)
+
+@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)
+
+openapi_spec = app.openapi()
+
+with open("koi-net-protocol-openapi.json", "w") as f:
+    json.dump(openapi_spec, f, indent=2)
+    
+if __name__ == "__main__":
+    uvicorn.run("examples.full_node:app", port=port)

koi_net-1.0.0b1/examples/partial_node.py

@@ -0,0 +1,82 @@
+import time
+import logging
+from rich.logging import RichHandler
+from koi_net import NodeInterface
+from koi_net.processor.handler import HandlerType
+from koi_net.processor.knowledge_object import KnowledgeSource, KnowledgeObject
+from koi_net.processor.interface import ProcessorInterface
+from koi_net.protocol.event import EventType
+from koi_net.protocol.edge import EdgeType
+from koi_net.protocol.node import NodeProfile, NodeType
+from koi_net.protocol.helpers import generate_edge_bundle
+from rid_lib.types import KoiNetNode
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+    datefmt="%Y-%m-%d %H:%M:%S",
+    handlers=[RichHandler()]
+)
+
+logging.getLogger("koi_net").setLevel(logging.DEBUG)
+logger = logging.getLogger(__name__)
+
+
+node = NodeInterface(
+    name="partial",
+    profile=NodeProfile(
+        node_type=NodeType.PARTIAL
+    ),
+    identity_file_path="partial_identity.json",
+    first_contact="http://127.0.0.1:8000/koi-net"
+)
+
+@node.processor.register_handler(HandlerType.Network, rid_types=[KoiNetNode])
+def coordinator_contact(processor: ProcessorInterface, kobj: KnowledgeObject):
+    # when I found out about a new node
+    if kobj.normalized_event_type != EventType.NEW: 
+        return
+    
+    node_profile = kobj.bundle.validate_contents(NodeProfile)
+    
+    # looking for event provider of nodes
+    if KoiNetNode not in node_profile.provides.event:
+        return
+    
+    logger.info("Identified a coordinator!")
+    logger.info("Proposing new edge")
+    
+    # queued for processing
+    processor.handle(bundle=generate_edge_bundle(
+        source=kobj.rid,
+        target=node.identity.rid,
+        edge_type=EdgeType.POLL,
+        rid_types=[KoiNetNode]
+    ))
+    
+    logger.info("Catching up on network state")
+    
+    payload = processor.network.request_handler.fetch_rids(kobj.rid, rid_types=[KoiNetNode])
+    for rid in payload.rids:
+        if rid == processor.identity.rid:
+            logger.info("Skipping myself")
+            continue
+        if processor.cache.exists(rid):
+            logger.info(f"Skipping known RID '{rid}'")
+            continue
+        
+        # marked as external since we are handling RIDs from another node
+        # will fetch remotely instead of checking local cache
+        processor.handle(rid=rid, source=KnowledgeSource.External)
+    logger.info("Done")
+    
+
+
+node.initialize()
+
+while True:
+    for event in node.network.poll_neighbors():
+        node.processor.handle(event=event, source=KnowledgeSource.External)
+    node.processor.flush_kobj_queue()
+    
+    time.sleep(1)

koi_net-1.0.0b1/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "koi-net"
+version = "1.0.0-beta.1"
+description = "Implementation of KOI-net protocol in Python"
+authors = [
+    {name = "Luke Miller", email = "luke@block.science"}
+]
+readme = "README.md"
+requires-python = ">=3.10"
+license = {file = "LICENSE"}
+dependencies = [
+    "rid-lib>=3.2.1",
+    "networkx>=3.4.2",
+    "httpx>=0.28.1",
+    "pydantic>=2.10.6"
+]
+
+[project.optional-dependencies]
+dev = ["twine>=6.0", "build"]
+examples = [
+    "rich",
+    "fastapi",
+    "uvicorn"
+]
+
+[project.urls]
+Homepage = "https://github.com/BlockScience/koi-net/"

koi_net-1.0.0b1/requirements.txt

@@ -0,0 +1,9 @@
+networkx>=3.4.2
+rid-lib>=3.2.1
+httpx>=0.28.1
+pydantic>=2.10.6
+
+# requirements for examples/
+rich
+fastapi
+uvicorn

koi_net-1.0.0b1/src/koi_net/__init__.py

@@ -0,0 +1 @@
+from .core import NodeInterface

koi_net-1.0.0b1/src/koi_net/core.py

@@ -0,0 +1,86 @@
+import logging
+import httpx
+from rid_lib.ext import Cache, Bundle
+from .network import NetworkInterface
+from .processor import ProcessorInterface
+from .processor import default_handlers as _default_handlers
+from .processor.handler import KnowledgeHandler
+from .identity import NodeIdentity
+from .protocol.node import NodeProfile
+from .protocol.event import Event, EventType
+
+logger = logging.getLogger(__name__)
+
+class NodeInterface:
+    def __init__(
+        self, 
+        name: str,
+        profile: NodeProfile,
+        identity_file_path: str = "identity.json",
+        first_contact: str | None = None,
+        default_handlers: list[KnowledgeHandler] | None = None,
+        cache: Cache | None = None,
+        network: NetworkInterface | None = None,
+        processor: ProcessorInterface | None = None
+    ):
+        self.cache = cache or Cache(directory_path=f"{name}_cache")
+        self.identity = NodeIdentity(
+            name=name,
+            profile=profile,
+            cache=self.cache,
+            file_path=identity_file_path
+        )
+        self.first_contact = first_contact
+        self.network = network or NetworkInterface(
+            file_path=f"{self.identity.rid.name}_event_queues.json", 
+            first_contact=self.first_contact,
+            cache=self.cache, 
+            identity=self.identity
+        )
+        
+        # pull all handlers defined in default_handlers module
+        if not default_handlers:
+            default_handlers = [
+                obj for obj in vars(_default_handlers).values() 
+                if isinstance(obj, KnowledgeHandler)
+            ]
+        
+        self.processor = processor or ProcessorInterface(
+            cache=self.cache, 
+            network=self.network, 
+            identity=self.identity, 
+            default_handlers=default_handlers
+        )
+    
+    def initialize(self):
+        self.network.graph.generate()
+        
+        self.processor.handle(
+            bundle=Bundle.generate(
+                rid=self.identity.rid, 
+                contents=self.identity.profile.model_dump()
+            ),
+            flush=True
+        )
+    
+        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}")
+            
+            events = [
+                Event.from_rid(EventType.FORGET, self.identity.rid),
+                Event.from_bundle(EventType.NEW, self.identity.bundle)
+            ]
+            
+            try:
+                self.network.request_handler.broadcast_events(
+                    url=self.first_contact,
+                    events=events
+                )
+                
+            except httpx.ConnectError:
+                logger.info("Failed to reach first contact")
+                return
+            
+                        
+    def finalize(self):
+        self.network.save_event_queues()

koi_net-1.0.0b1/src/koi_net/identity.py

@@ -0,0 +1,62 @@
+import logging
+from pydantic import BaseModel
+from rid_lib.ext.bundle import Bundle
+from rid_lib.ext.cache import Cache
+from rid_lib.types.koi_net_node import KoiNetNode
+from .protocol.node import NodeProfile
+
+logger = logging.getLogger(__name__)
+
+
+class NodeIdentityModel(BaseModel):
+    rid: KoiNetNode
+    profile: NodeProfile
+    
+class NodeIdentity:
+    _identity: NodeIdentityModel
+    file_path: str
+    cache: Cache
+    
+    def __init__(
+        self,  
+        name: str,
+        profile: NodeProfile,
+        cache: Cache,
+        file_path: str = "identity.json"
+    ):
+        self.cache = cache
+        self.file_path = file_path
+        
+        self._identity = None
+        try:
+            with open(file_path, "r") as f:
+                self._identity = NodeIdentityModel.model_validate_json(f.read())
+                    
+        except FileNotFoundError:
+            pass
+        
+        if self._identity:
+            if self._identity.rid.name != name:
+                logger.warning("Node name changed which will change this node's RID, if you really want to do this manually delete the identity JSON file")
+            if self._identity.profile != profile:
+                self._identity.profile = profile
+        else:
+            self._identity = NodeIdentityModel( 
+                rid=KoiNetNode.generate(name), 
+                profile=profile,
+            )
+                    
+        with open(file_path, "w") as f:
+            f.write(self._identity.model_dump_json(indent=2))
+        
+    @property
+    def rid(self) -> KoiNetNode:
+        return self._identity.rid
+    
+    @property
+    def profile(self) -> NodeProfile:
+        return self._identity.profile    
+    
+    @property
+    def bundle(self) -> Bundle:
+        return self.cache.read(self.rid)

koi_net-1.0.0b1/src/koi_net/network/__init__.py

@@ -0,0 +1 @@
+from .interface import NetworkInterface

koi_net-1.0.0b1/src/koi_net/network/graph.py

@@ -0,0 +1,112 @@
+import logging
+from typing import Literal
+import networkx as nx
+from rid_lib import RIDType
+from rid_lib.ext import Cache
+from rid_lib.types import KoiNetEdge, KoiNetNode
+from ..identity import NodeIdentity
+from ..protocol.edge import EdgeProfile, EdgeStatus
+from ..protocol.node import NodeProfile
+
+logger = logging.getLogger(__name__)
+
+
+class NetworkGraph:
+    def __init__(self, cache: Cache, identity: NodeIdentity):
+        self.cache = cache
+        self.dg = nx.DiGraph()
+        self.identity = identity
+        
+    def generate(self):
+        logger.info("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}")
+                
+            elif type(rid) == KoiNetEdge:
+                edge_profile = self.get_edge_profile(rid)
+                if not edge_profile:
+                    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")
+        
+    def get_node_profile(self, rid: KoiNetNode) -> NodeProfile | None:
+        bundle = self.cache.read(rid)
+        if bundle:
+            return bundle.validate_contents(NodeProfile)
+        
+    def get_edge_profile(
+        self, 
+        rid: KoiNetEdge | None = None,
+        source: KoiNetNode | None = None, 
+        target: KoiNetNode | None = None,
+    ) -> EdgeProfile | None:
+        if source and target:
+            if (source, target) not in self.dg.edges: return
+            edge_data = self.dg.get_edge_data(source, target)
+            if not edge_data: return
+            rid = edge_data.get("rid")
+            if not rid: return
+        elif not rid:
+            raise ValueError("Either 'rid' or 'source' and 'target' must be provided")
+        
+        bundle = self.cache.read(rid)
+        if bundle:
+            return bundle.validate_contents(EdgeProfile)
+        
+    def get_edges(
+        self,
+        direction: Literal["in", "out"] | None = None,
+    ) -> list[KoiNetEdge]:
+        
+        edges = []
+        if direction != "in":
+            out_edges = self.dg.out_edges(self.identity.rid)
+            edges.extend([e for e in out_edges])
+                
+        if direction != "out":
+            in_edges = self.dg.in_edges(self.identity.rid)
+            edges.extend([e for e in in_edges])
+                    
+        edge_rids = []
+        for edge in edges:
+            edge_data = self.dg.get_edge_data(*edge)
+            if not edge_data: continue
+            edge_rid = edge_data.get("rid")
+            if not edge_rid: continue
+            edge_rids.append(edge_rid)
+       
+        return edge_rids
+    
+    def get_neighbors(
+        self,
+        direction: Literal["in", "out"] | None = None,
+        status: EdgeStatus | None = None,
+        allowed_type: RIDType | None = None
+    ) -> list[KoiNetNode]:
+        
+        neighbors = []
+        for edge_rid in self.get_edges(direction):
+            edge_profile = self.get_edge_profile(edge_rid)
+            
+            if not edge_profile: 
+                logger.warning(f"Failed to find edge {edge_rid!r} in cache")
+                continue
+                        
+            if status and edge_profile.status != status:
+                continue
+            
+            if allowed_type and allowed_type not in edge_profile.rid_types:
+                continue
+            
+            if edge_profile.target == self.identity.rid:
+                neighbors.append(edge_profile.source)
+            elif edge_profile.source == self.identity.rid:
+                neighbors.append(edge_profile.target)
+                
+        return list(neighbors)
+