koi-net 1.1.0__tar.gz → 1.2.0b9__tar.gz

{koi_net-1.1.0 → koi_net-1.2.0b9}/.gitignore

@@ -1,10 +1,13 @@
 rid-lib
 __pycache__
-*.json
 *.pem
 *.yaml
+*.ndjson*
 venv
 .env
 prototypes
 .vscode
-dist/
+dist/
+docs/
+tests/
+.rid_cache/

{koi_net-1.1.0 → koi_net-1.2.0b9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: koi-net
-Version: 1.1.0
+Version: 1.2.0b9
 Summary: Implementation of KOI-net protocol in Python
 Project-URL: Homepage, https://github.com/BlockScience/koi-net/
 Author-email: Luke Miller <luke@block.science>
@@ -33,14 +33,19 @@ Requires-Dist: httpx>=0.28.1
 Requires-Dist: networkx>=3.4.2
 Requires-Dist: pydantic>=2.10.6
 Requires-Dist: python-dotenv>=1.1.0
+Requires-Dist: rich>=14.1.0
 Requires-Dist: rid-lib>=3.2.7
 Requires-Dist: ruamel-yaml>=0.18.10
+Requires-Dist: structlog>=25.4.0
 Requires-Dist: uvicorn>=0.34.2
 Provides-Extra: dev
 Requires-Dist: build; extra == 'dev'
 Requires-Dist: twine>=6.0; extra == 'dev'
-Provides-Extra: examples
-Requires-Dist: rich; extra == 'examples'
+Provides-Extra: docs
+Requires-Dist: sphinx; extra == 'docs'
+Requires-Dist: sphinx-autoapi>=3.6.0; extra == 'docs'
+Requires-Dist: sphinx-autodoc-typehints>=3.0.1; extra == 'docs'
+Requires-Dist: sphinx-rtd-theme>=3.0.2; extra == 'docs'
 Description-Content-Type: text/markdown
 
 # KOI-net

koi_net-1.2.0b9/examples/coordinator.py

@@ -0,0 +1,68 @@
+from rid_lib.types import KoiNetNode, KoiNetEdge
+import structlog
+from koi_net.config.full_node import (
+    FullNodeConfig, 
+    ServerConfig, 
+    KoiNetConfig, 
+    NodeProfile, 
+    NodeProvides
+)
+from koi_net.core import FullNode
+from koi_net.processor.context import HandlerContext
+from koi_net.processor.handler import HandlerType, KnowledgeHandler
+from koi_net.processor.knowledge_object import KnowledgeObject
+from koi_net.protocol.event import Event, EventType
+from koi_net.protocol.edge import EdgeType, generate_edge_bundle
+
+log = structlog.stdlib.get_logger()
+
+
+class CoordinatorConfig(FullNodeConfig):
+    server: ServerConfig = ServerConfig(port=8080)
+    koi_net: KoiNetConfig = KoiNetConfig(
+        node_name="coordinator",
+        node_profile=NodeProfile(
+            provides=NodeProvides(
+                event=[KoiNetNode, KoiNetEdge],
+                state=[KoiNetNode, KoiNetEdge]
+            )
+        ),
+        rid_types_of_interest=[KoiNetNode, KoiNetEdge]
+    )
+
+@KnowledgeHandler.create(
+    HandlerType.Network, 
+    rid_types=[KoiNetNode])
+def handshake_handler(ctx: HandlerContext, kobj: KnowledgeObject):
+    log.info("Handling node handshake")
+
+    # only respond if node declares itself as NEW
+    if kobj.event_type != EventType.NEW:
+        return
+        
+    log.info("Sharing this node's bundle with peer")
+    identity_bundle = ctx.cache.read(ctx.identity.rid)
+    ctx.event_queue.push(
+        event=Event.from_bundle(EventType.NEW, identity_bundle),
+        target=kobj.rid
+    )
+    
+    log.info("Proposing new edge")    
+    # defer handling of proposed edge
+    
+    edge_bundle = generate_edge_bundle(
+        source=kobj.rid,
+        target=ctx.identity.rid,
+        edge_type=EdgeType.WEBHOOK,
+        rid_types=[KoiNetNode, KoiNetEdge]
+    )
+        
+    ctx.kobj_queue.push(rid=edge_bundle.rid, event_type=EventType.FORGET)
+    ctx.kobj_queue.push(bundle=edge_bundle)
+
+class CoordinatorNode(FullNode):
+    config_schema = CoordinatorConfig
+    knowledge_handlers = FullNode.knowledge_handlers + [handshake_handler]
+
+if __name__ == "__main__":
+    CoordinatorNode().run()

koi_net-1.2.0b9/examples/partial.py

@@ -0,0 +1,15 @@
+from koi_net.config.partial_node import PartialNodeConfig, KoiNetConfig, NodeProfile
+from koi_net.core import PartialNode
+
+
+class MyPartialNodeConfig(PartialNodeConfig):
+    koi_net: KoiNetConfig = KoiNetConfig(
+        node_name="partial",
+        node_profile=NodeProfile()
+    )
+
+class MyPartialNode(PartialNode):
+    config_schema = MyPartialNodeConfig
+
+if __name__ == "__main__":
+    MyPartialNode().run()

koi_net-1.2.0b9/koi-net-protocol-openapi.json

@@ -0,0 +1,522 @@
+{
+  "openapi": "3.1.0",
+  "info": {
+    "title": "KOI-net Protocol API",
+    "version": "1.0.0"
+  },
+  "paths": {
+    "/events/broadcast": {
+      "post": {
+        "summary": "Broadcast Events",
+        "operationId": "broadcast_events_events_broadcast_post",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/EventsPayload-Input"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {}
+              }
+            }
+          },
+          "422": {
+            "description": "Validation Error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/events/poll": {
+      "post": {
+        "summary": "Poll Events",
+        "operationId": "poll_events_events_poll_post",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PollEvents"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/EventsPayload-Output"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Validation Error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/rids/fetch": {
+      "post": {
+        "summary": "Fetch Rids",
+        "operationId": "fetch_rids_rids_fetch_post",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/FetchRids"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/RidsPayload"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Validation Error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/manifests/fetch": {
+      "post": {
+        "summary": "Fetch Manifests",
+        "operationId": "fetch_manifests_manifests_fetch_post",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/FetchManifests"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ManifestsPayload"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Validation Error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/bundles/fetch": {
+      "post": {
+        "summary": "Fetch Bundles",
+        "operationId": "fetch_bundles_bundles_fetch_post",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/FetchBundles"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/BundlesPayload"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Validation Error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "Bundle": {
+        "properties": {
+          "manifest": {
+            "$ref": "#/components/schemas/Manifest"
+          },
+          "contents": {
+            "type": "object",
+            "title": "Contents"
+          }
+        },
+        "type": "object",
+        "required": [
+          "manifest",
+          "contents"
+        ],
+        "title": "Bundle",
+        "description": "A knowledge bundle composed of a manifest and contents associated with an RIDed object.\n\nActs as a container for the data associated with an RID. It is written to and read from the cache."
+      },
+      "BundlesPayload": {
+        "properties": {
+          "bundles": {
+            "items": {
+              "$ref": "#/components/schemas/Bundle"
+            },
+            "type": "array",
+            "title": "Bundles"
+          },
+          "not_found": {
+            "items": {
+              "type": "string",
+              "format": "rid"
+            },
+            "type": "array",
+            "title": "Not Found",
+            "default": []
+          },
+          "deferred": {
+            "items": {
+              "type": "string",
+              "format": "rid"
+            },
+            "type": "array",
+            "title": "Deferred",
+            "default": []
+          }
+        },
+        "type": "object",
+        "required": [
+          "bundles"
+        ],
+        "title": "BundlesPayload"
+      },
+      "Event": {
+        "properties": {
+          "rid": {
+            "type": "string",
+            "format": "rid",
+            "title": "Rid"
+          },
+          "event_type": {
+            "$ref": "#/components/schemas/EventType"
+          },
+          "manifest": {
+            "anyOf": [
+              {
+                "$ref": "#/components/schemas/Manifest"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "contents": {
+            "anyOf": [
+              {
+                "type": "object"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Contents"
+          }
+        },
+        "type": "object",
+        "required": [
+          "rid",
+          "event_type"
+        ],
+        "title": "Event"
+      },
+      "EventType": {
+        "type": "string",
+        "enum": [
+          "NEW",
+          "UPDATE",
+          "FORGET"
+        ],
+        "title": "EventType"
+      },
+      "EventsPayload-Input": {
+        "properties": {
+          "events": {
+            "items": {
+              "$ref": "#/components/schemas/Event"
+            },
+            "type": "array",
+            "title": "Events"
+          }
+        },
+        "type": "object",
+        "required": [
+          "events"
+        ],
+        "title": "EventsPayload"
+      },
+      "EventsPayload-Output": {
+        "properties": {
+          "events": {
+            "items": {
+              "$ref": "#/components/schemas/Event"
+            },
+            "type": "array",
+            "title": "Events"
+          }
+        },
+        "type": "object",
+        "required": [
+          "events"
+        ],
+        "title": "EventsPayload"
+      },
+      "FetchBundles": {
+        "properties": {
+          "rids": {
+            "items": {
+              "type": "string",
+              "format": "rid"
+            },
+            "type": "array",
+            "title": "Rids"
+          }
+        },
+        "type": "object",
+        "required": [
+          "rids"
+        ],
+        "title": "FetchBundles"
+      },
+      "FetchManifests": {
+        "properties": {
+          "rid_types": {
+            "items": {
+              "type": "string",
+              "format": "rid-type"
+            },
+            "type": "array",
+            "title": "Rid Types",
+            "default": []
+          },
+          "rids": {
+            "items": {
+              "type": "string",
+              "format": "rid"
+            },
+            "type": "array",
+            "title": "Rids",
+            "default": []
+          }
+        },
+        "type": "object",
+        "title": "FetchManifests"
+      },
+      "FetchRids": {
+        "properties": {
+          "rid_types": {
+            "items": {
+              "type": "string",
+              "format": "rid-type"
+            },
+            "type": "array",
+            "title": "Rid Types",
+            "default": []
+          }
+        },
+        "type": "object",
+        "title": "FetchRids"
+      },
+      "HTTPValidationError": {
+        "properties": {
+          "detail": {
+            "items": {
+              "$ref": "#/components/schemas/ValidationError"
+            },
+            "type": "array",
+            "title": "Detail"
+          }
+        },
+        "type": "object",
+        "title": "HTTPValidationError"
+      },
+      "Manifest": {
+        "properties": {
+          "rid": {
+            "type": "string",
+            "format": "rid",
+            "title": "Rid"
+          },
+          "timestamp": {
+            "type": "string",
+            "format": "date-time",
+            "title": "Timestamp"
+          },
+          "sha256_hash": {
+            "type": "string",
+            "title": "Sha256 Hash"
+          }
+        },
+        "type": "object",
+        "required": [
+          "rid",
+          "timestamp",
+          "sha256_hash"
+        ],
+        "title": "Manifest",
+        "description": "A portable descriptor of a data object associated with an RID.\n\nComposed of an RID, timestamp, and sha256 hash of the data object."
+      },
+      "ManifestsPayload": {
+        "properties": {
+          "manifests": {
+            "items": {
+              "$ref": "#/components/schemas/Manifest"
+            },
+            "type": "array",
+            "title": "Manifests"
+          },
+          "not_found": {
+            "items": {
+              "type": "string",
+              "format": "rid"
+            },
+            "type": "array",
+            "title": "Not Found",
+            "default": []
+          }
+        },
+        "type": "object",
+        "required": [
+          "manifests"
+        ],
+        "title": "ManifestsPayload"
+      },
+      "PollEvents": {
+        "properties": {
+          "rid": {
+            "type": "string",
+            "format": "rid",
+            "title": "Rid"
+          },
+          "limit": {
+            "type": "integer",
+            "title": "Limit",
+            "default": 0
+          }
+        },
+        "type": "object",
+        "required": [
+          "rid"
+        ],
+        "title": "PollEvents"
+      },
+      "RidsPayload": {
+        "properties": {
+          "rids": {
+            "items": {
+              "type": "string",
+              "format": "rid"
+            },
+            "type": "array",
+            "title": "Rids"
+          }
+        },
+        "type": "object",
+        "required": [
+          "rids"
+        ],
+        "title": "RidsPayload"
+      },
+      "ValidationError": {
+        "properties": {
+          "loc": {
+            "items": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "integer"
+                }
+              ]
+            },
+            "type": "array",
+            "title": "Location"
+          },
+          "msg": {
+            "type": "string",
+            "title": "Message"
+          },
+          "type": {
+            "type": "string",
+            "title": "Error Type"
+          }
+        },
+        "type": "object",
+        "required": [
+          "loc",
+          "msg",
+          "type"
+        ],
+        "title": "ValidationError"
+      }
+    }
+  }
+}