Merge pull request #168 from biggraph/darabos-ws-docs

examples/ODE-GNN.lynxkite.json

@@ -1,12 +1,5 @@
 {
   "edges": [
-    {
-      "id": "Input: embedding 1 Graph conv 1",
-      "source": "Input: embedding 1",
-      "sourceHandle": "x",
-      "target": "Graph conv 1",
-      "targetHandle": "x"
-    },
     {
       "id": "Input: graph edges 1 Graph conv 1",
       "source": "Input: graph edges 1",
@@ -21,13 +14,6 @@
       "target": "Activation 1",
       "targetHandle": "x"
     },
-    {
-      "id": "Activation 1 Repeat 1",
-      "source": "Activation 1",
-      "sourceHandle": "x",
-      "target": "Repeat 1",
-      "targetHandle": "input"
-    },
     {
       "id": "Repeat 1 Graph conv 1",
       "source": "Repeat 1",
@@ -43,86 +29,84 @@
       "targetHandle": "x"
     },
     {
-      "id": "Input: zeros 1 LSTM 1",
-      "source": "Input: zeros 1",
+      "id": "Neural ODE 2 MSE loss 1",
+      "source": "Neural ODE 2",
       "sourceHandle": "x",
-      "target": "LSTM 1",
-      "targetHandle": "h"
+      "target": "MSE loss 1",
+      "targetHandle": "x"
     },
     {
-      "id": "Recurrent chain 1 LSTM 1",
-      "source": "Recurrent chain 1",
+      "id": "Input: tensor 1 Graph conv 1",
+      "source": "Input: tensor 1",
       "sourceHandle": "output",
-      "target": "LSTM 1",
-      "targetHandle": "h"
+      "target": "Graph conv 1",
+      "targetHandle": "x"
     },
     {
-      "id": "LSTM 1 Recurrent chain 1",
-      "source": "LSTM 1",
-      "sourceHandle": "h",
-      "target": "Recurrent chain 1",
+      "id": "Input: tensor 2 MSE loss 1",
+      "source": "Input: tensor 2",
+      "sourceHandle": "output",
+      "target": "MSE loss 1",
+      "targetHandle": "y"
+    },
+    {
+      "id": "MSE loss 1 Optimizer 1",
+      "source": "MSE loss 1",
+      "sourceHandle": "output",
+      "target": "Optimizer 1",
+      "targetHandle": "loss"
+    },
+    {
+      "id": "Activation 1 output Repeat 1 input",
+      "source": "Activation 1",
+      "sourceHandle": "output",
+      "target": "Repeat 1",
       "targetHandle": "input"
     },
     {
-      "id": "Activation 1 Concatenate 1",
+      "id": "Activation 1 output Concatenate 1 a",
       "source": "Activation 1",
-      "sourceHandle": "x",
+      "sourceHandle": "output",
       "target": "Concatenate 1",
       "targetHandle": "a"
     },
     {
-      "id": "LSTM 1 Concatenate 1",
+      "id": "LSTM 1 output Concatenate 1 b",
       "source": "LSTM 1",
-      "sourceHandle": "x",
+      "sourceHandle": "output",
       "target": "Concatenate 1",
       "targetHandle": "b"
     },
     {
-      "id": "Input: label 1 MSE loss 1",
-      "source": "Input: label 1",
-      "sourceHandle": "y",
-      "target": "MSE loss 1",
-      "targetHandle": "y"
-    },
-    {
-      "id": "MSE loss 1 Optimizer 1",
-      "source": "MSE loss 1",
-      "sourceHandle": "loss",
-      "target": "Optimizer 1",
-      "targetHandle": "loss"
-    },
-    {
-      "id": "Concatenate 1 Neural ODE 2",
+      "id": "Concatenate 1 output Neural ODE 2 x",
       "source": "Concatenate 1",
-      "sourceHandle": "x",
+      "sourceHandle": "output",
       "target": "Neural ODE 2",
       "targetHandle": "x"
-    },
-    {
-      "id": "Neural ODE 2 MSE loss 1",
-      "source": "Neural ODE 2",
-      "sourceHandle": "x",
-      "target": "MSE loss 1",
-      "targetHandle": "x"
     }
   ],
   "env": "PyTorch model",
   "nodes": [
     {
       "data": {
+        "__execution_delay": 0.0,
+        "collapsed": null,
         "display": null,
         "error": null,
+        "input_metadata": null,
         "meta": {
+          "color": "blue",
+          "doc": null,
           "inputs": [
             {
-              "name": "edges",
+              "name": "x",
               "position": "bottom",
               "type": {
                 "type": "tensor"
               }
             },
             {
-              "name": "x",
+              "name": "edges",
               "position": "bottom",
               "type": {
                 "type": "tensor"
@@ -141,7 +125,7 @@
           ],
           "params": [
             {
-              "default": "1",
+              "default": "GCNConv",
               "name": "type",
               "type": {
                 "enum": [
@@ -156,17 +140,17 @@
           "type": "basic"
         },
         "params": {
-          "type": 1.0
+          "type": "SAGEConv"
         },
-        "status": "planned",
+        "status": "done",
         "title": "Graph conv"
       },
       "dragHandle": ".bg-primary",
       "height": 200.0,
       "id": "Graph conv 1",
       "position": {
-        "x": 350.98078368755864,
-        "y": 195.0
+        "x": 353.5291731060978,
+        "y": 191.17741587219126
       },
       "type": "basic",
       "width": 200.0
@@ -177,7 +161,10 @@
         "collapsed": null,
         "display": null,
         "error": null,
+        "input_metadata": null,
         "meta": {
+          "color": "orange",
+          "doc": null,
           "inputs": [
             {
               "name": "input",
@@ -204,6 +191,13 @@
               "type": {
                 "type": "<class 'int'>"
               }
+            },
+            {
+              "default": false,
+              "name": "same_weights",
+              "type": {
+                "type": "<class 'bool'>"
+              }
             }
           ],
           "type": "basic"
@@ -211,15 +205,15 @@
         "params": {
           "times": "5"
         },
-        "status": "planned",
+        "status": "done",
         "title": "Repeat"
       },
       "dragHandle": ".bg-primary",
       "height": 200.0,
       "id": "Repeat 1",
       "position": {
-        "x": -94.15168677219138,
-        "y": 14.525356969883305
+        "x": 55.8483132278086,
+        "y": 54.525356969883305
       },
       "type": "basic",
       "width": 200.0
@@ -230,30 +224,33 @@
         "collapsed": true,
         "display": null,
         "error": null,
+        "input_metadata": null,
         "meta": {
+          "color": "orange",
+          "doc": null,
           "inputs": [
             {
               "name": "a",
               "position": "bottom",
               "type": {
-                "type": "tensor"
+                "type": "<class 'inspect._empty'>"
               }
             },
             {
               "name": "b",
               "position": "bottom",
               "type": {
-                "type": "tensor"
+                "type": "<class 'inspect._empty'>"
               }
             }
           ],
           "name": "Concatenate",
           "outputs": [
             {
-              "name": "x",
+              "name": "output",
               "position": "top",
               "type": {
-                "type": "tensor"
+                "type": "None"
               }
             }
           ],
@@ -261,7 +258,7 @@
           "type": "basic"
         },
         "params": {},
-        "status": "planned",
+        "status": "done",
         "title": "Concatenate"
       },
       "dragHandle": ".bg-primary",
@@ -280,7 +277,10 @@
         "collapsed": true,
         "display": null,
         "error": null,
+        "input_metadata": null,
         "meta": {
+          "color": "orange",
+          "doc": null,
           "inputs": [],
           "name": "Input: graph edges",
           "outputs": [
@@ -296,50 +296,15 @@
           "type": "basic"
         },
         "params": {},
-        "status": "planned",
+        "status": "done",
         "title": "Input: graph edges"
       },
       "dragHandle": ".bg-primary",
       "height": 200.0,
       "id": "Input: graph edges 1",
       "position": {
-        "x": 515.6535517374441,
-        "y": 545.4709559884296
-      },
-      "type": "basic",
-      "width": 200.0
-    },
-    {
-      "data": {
-        "__execution_delay": null,
-        "collapsed": true,
-        "display": null,
-        "error": null,
-        "meta": {
-          "inputs": [],
-          "name": "Input: embedding",
-          "outputs": [
-            {
-              "name": "x",
-              "position": "top",
-              "type": {
-                "type": "tensor"
-              }
-            }
-          ],
-          "params": [],
-          "type": "basic"
-        },
-        "params": {},
-        "status": "planned",
-        "title": "Input: embedding"
-      },
-      "dragHandle": ".bg-primary",
-      "height": 200.0,
-      "id": "Input: embedding 1",
-      "position": {
-        "x": 246.6527948448857,
-        "y": 551.6313504198322
+        "x": 457.3761886867096,
+        "y": 530.2733532051268
       },
       "type": "basic",
       "width": 200.0
@@ -348,34 +313,37 @@
       "data": {
         "display": null,
         "error": null,
+        "input_metadata": null,
         "meta": {
+          "color": "orange",
+          "doc": null,
           "inputs": [
             {
               "name": "x",
               "position": "bottom",
               "type": {
-                "type": "tensor"
+                "type": "<class 'inspect._empty'>"
               }
             }
           ],
           "name": "Activation",
           "outputs": [
             {
-              "name": "x",
+              "name": "output",
               "position": "top",
               "type": {
-                "type": "tensor"
+                "type": "None"
               }
             }
           ],
           "params": [
             {
-              "default": "1",
+              "default": "ReLU",
               "name": "type",
               "type": {
                 "enum": [
                   "ReLU",
-                  "LeakyReLU",
+                  "Leaky_ReLU",
                   "Tanh",
                   "Mish"
                 ]
@@ -387,7 +355,7 @@
         "params": {
           "type": 1.0
         },
-        "status": "planned",
+        "status": "done",
         "title": "Activation"
       },
       "dragHandle": ".bg-primary",
@@ -402,68 +370,86 @@
     },
     {
       "data": {
-        "__execution_delay": null,
-        "collapsed": true,
+        "__execution_delay": 0.0,
+        "collapsed": false,
         "display": null,
         "error": null,
+        "input_metadata": null,
         "meta": {
+          "color": "blue",
+          "doc": null,
           "inputs": [
-            {
-              "name": "h",
-              "position": "bottom",
-              "type": {
-                "type": "tensor"
-              }
-            },
             {
               "name": "x",
               "position": "bottom",
               "type": {
-                "type": "tensor"
+                "type": "<class 'inspect._empty'>"
               }
             }
           ],
           "name": "LSTM",
           "outputs": [
             {
-              "name": "h",
+              "name": "output",
               "position": "top",
               "type": {
-                "type": "tensor"
+                "type": "None"
+              }
+            }
+          ],
+          "params": [
+            {
+              "default": 1024.0,
+              "name": "input_size",
+              "type": {
+                "type": "<class 'int'>"
               }
             },
             {
-              "name": "x",
-              "position": "top",
+              "default": 1024.0,
+              "name": "hidden_size",
               "type": {
-                "type": "tensor"
+                "type": "<class 'int'>"
+              }
+            },
+            {
+              "default": 0.0,
+              "name": "dropout",
+              "type": {
+                "type": "<class 'float'>"
               }
             }
           ],
-          "params": [],
           "type": "basic"
         },
-        "params": {},
-        "status": "planned",
+        "params": {
+          "dropout": "0.2",
+          "hidden_size": "128",
+          "input_size": "128"
+        },
+        "status": "done",
         "title": "LSTM"
       },
       "dragHandle": ".bg-primary",
-      "height": 200.0,
+      "height": 312.0,
       "id": "LSTM 1",
       "position": {
         "x": 960.0,
         "y": 135.0
       },
       "type": "basic",
-      "width": 200.0
+      "width": 204.0
     },
     {
       "data": {
-        "__execution_delay": null,
-        "collapsed": true,
+        "__execution_delay": 0.0,
+        "collapsed": false,
         "display": null,
         "error": null,
+        "input_metadata": null,
         "meta": {
+          "color": "orange",
+          "doc": null,
           "inputs": [],
           "name": "Input: sequential",
           "outputs": [
@@ -475,97 +461,29 @@
               }
             }
           ],
-          "params": [],
-          "type": "basic"
-        },
-        "params": {},
-        "status": "planned",
-        "title": "Input: sequential"
-      },
-      "dragHandle": ".bg-primary",
-      "height": 200.0,
-      "id": "Input: sequential 1",
-      "position": {
-        "x": 1005.0,
-        "y": 510.0
-      },
-      "type": "basic",
-      "width": 200.0
-    },
-    {
-      "data": {
-        "__execution_delay": null,
-        "collapsed": true,
-        "display": null,
-        "error": null,
-        "meta": {
-          "inputs": [],
-          "name": "Input: zeros",
-          "outputs": [
+          "params": [
             {
-              "name": "x",
-              "position": "top",
+              "default": null,
+              "name": "name",
               "type": {
-                "type": "tensor"
+                "type": "None"
               }
             }
           ],
-          "params": [],
           "type": "basic"
         },
-        "params": {},
-        "status": "planned",
-        "title": "Input: zeros"
-      },
-      "dragHandle": ".bg-primary",
-      "height": 200.0,
-      "id": "Input: zeros 1",
-      "position": {
-        "x": 1290.0,
-        "y": 405.0
-      },
-      "type": "basic",
-      "width": 200.0
-    },
-    {
-      "data": {
-        "__execution_delay": null,
-        "collapsed": true,
-        "display": null,
-        "error": null,
-        "meta": {
-          "inputs": [
-            {
-              "name": "input",
-              "position": "top",
-              "type": {
-                "type": "tensor"
-              }
-            }
-          ],
-          "name": "Recurrent chain",
-          "outputs": [
-            {
-              "name": "output",
-              "position": "bottom",
-              "type": {
-                "type": "tensor"
-              }
-            }
-          ],
-          "params": [],
-          "type": "basic"
+        "params": {
+          "name": "time series"
         },
-        "params": {},
-        "status": "planned",
-        "title": "Recurrent chain"
+        "status": "done",
+        "title": "Input: sequential"
       },
       "dragHandle": ".bg-primary",
       "height": 200.0,
-      "id": "Recurrent chain 1",
+      "id": "Input: sequential 1",
       "position": {
-        "x": 1224.6603040746108,
-        "y": 135.44839862151363
+        "x": 961.5476403063019,
+        "y": 511.8105149872374
       },
       "type": "basic",
       "width": 200.0
@@ -576,30 +494,33 @@
         "collapsed": true,
         "display": null,
         "error": null,
+        "input_metadata": null,
         "meta": {
+          "color": "orange",
+          "doc": null,
           "inputs": [
             {
               "name": "x",
               "position": "bottom",
               "type": {
-                "type": "tensor"
+                "type": "<class 'inspect._empty'>"
               }
             },
             {
               "name": "y",
               "position": "bottom",
               "type": {
-                "type": "tensor"
+                "type": "<class 'inspect._empty'>"
               }
             }
           ],
           "name": "MSE loss",
           "outputs": [
             {
-              "name": "loss",
+              "name": "output",
               "position": "top",
               "type": {
-                "type": "tensor"
+                "type": "None"
               }
             }
           ],
@@ -607,50 +528,15 @@
           "type": "basic"
         },
         "params": {},
-        "status": "planned",
+        "status": "done",
         "title": "MSE loss"
       },
       "dragHandle": ".bg-primary",
       "height": 200.0,
       "id": "MSE loss 1",
       "position": {
-        "x": 915.0,
-        "y": -900.0
-      },
-      "type": "basic",
-      "width": 200.0
-    },
-    {
-      "data": {
-        "__execution_delay": null,
-        "collapsed": true,
-        "display": null,
-        "error": null,
-        "meta": {
-          "inputs": [],
-          "name": "Input: label",
-          "outputs": [
-            {
-              "name": "y",
-              "position": "top",
-              "type": {
-                "type": "tensor"
-              }
-            }
-          ],
-          "params": [],
-          "type": "basic"
-        },
-        "params": {},
-        "status": "planned",
-        "title": "Input: label"
-      },
-      "dragHandle": ".bg-primary",
-      "height": 200.0,
-      "id": "Input: label 1",
-      "position": {
-        "x": 1095.0,
-        "y": -450.0
+        "x": 627.1281170292506,
+        "y": -957.9364795915974
       },
       "type": "basic",
       "width": 200.0
@@ -659,7 +545,10 @@
       "data": {
         "display": null,
         "error": null,
+        "input_metadata": null,
         "meta": {
+          "color": "green",
+          "doc": null,
           "inputs": [
             {
               "name": "loss",
@@ -673,14 +562,7 @@
           "outputs": [],
           "params": [
             {
-              "default": 0.001,
-              "name": "lr",
-              "type": {
-                "type": "<class 'float'>"
-              }
-            },
-            {
-              "default": "1",
+              "default": "AdamW",
               "name": "type",
               "type": {
                 "enum": [
@@ -693,6 +575,13 @@
                   "Galore AdamW"
                 ]
               }
+            },
+            {
+              "default": 0.001,
+              "name": "lr",
+              "type": {
+                "type": "<class 'float'>"
+              }
             }
           ],
           "type": "basic"
@@ -701,24 +590,29 @@
           "lr": 0.001,
           "type": 1.0
         },
-        "status": "planned",
+        "status": "done",
         "title": "Optimizer"
       },
       "dragHandle": ".bg-primary",
       "height": 247.0,
       "id": "Optimizer 1",
       "position": {
-        "x": 915.3430278730226,
-        "y": -1268.0577550022126
+        "x": 632.9026898639854,
+        "y": -1321.9205758725257
       },
       "type": "basic",
       "width": 190.0
     },
     {
       "data": {
+        "__execution_delay": 0.0,
+        "collapsed": null,
         "display": null,
         "error": null,
+        "input_metadata": null,
         "meta": {
+          "color": "blue",
+          "doc": null,
           "inputs": [
             {
               "name": "x",
@@ -739,6 +633,13 @@
             }
           ],
           "params": [
+            {
+              "default": null,
+              "name": "relative_tolerance",
+              "type": {
+                "type": "None"
+              }
+            },
             {
               "default": null,
               "name": "absolute_tolerance",
@@ -747,7 +648,7 @@
               }
             },
             {
-              "default": "1",
+              "default": "dopri8",
               "name": "method",
               "type": {
                 "enum": [
@@ -763,10 +664,53 @@
                   "implicit_adams"
                 ]
               }
-            },
+            }
+          ],
+          "type": "basic"
+        },
+        "params": {
+          "absolute_tolerance": "",
+          "method": 1.0,
+          "relative_tolerance": null
+        },
+        "status": "done",
+        "title": "Neural ODE"
+      },
+      "dragHandle": ".bg-primary",
+      "height": 309.0,
+      "id": "Neural ODE 2",
+      "position": {
+        "x": 424.3358615871781,
+        "y": -784.0744992448747
+      },
+      "type": "basic",
+      "width": 308.0
+    },
+    {
+      "data": {
+        "__execution_delay": 0.0,
+        "collapsed": false,
+        "display": null,
+        "error": null,
+        "input_metadata": null,
+        "meta": {
+          "color": "orange",
+          "doc": null,
+          "inputs": [],
+          "name": "Input: tensor",
+          "outputs": [
+            {
+              "name": "output",
+              "position": "top",
+              "type": {
+                "type": "tensor"
+              }
+            }
+          ],
+          "params": [
             {
               "default": null,
-              "name": "relative_tolerance",
+              "name": "name",
               "type": {
                 "type": "None"
               }
@@ -775,19 +719,65 @@
           "type": "basic"
         },
         "params": {
-          "absolute_tolerance": null,
-          "method": 1.0,
-          "relative_tolerance": null
+          "name": "embedding"
         },
-        "status": "planned",
-        "title": "Neural ODE"
+        "status": "done",
+        "title": "Input: tensor"
       },
       "dragHandle": ".bg-primary",
       "height": 200.0,
-      "id": "Neural ODE 2",
+      "id": "Input: tensor 1",
+      "position": {
+        "x": 231.36175845539515,
+        "y": 526.043774935379
+      },
+      "type": "basic",
+      "width": 200.0
+    },
+    {
+      "data": {
+        "__execution_delay": 0.0,
+        "collapsed": false,
+        "display": null,
+        "error": null,
+        "input_metadata": null,
+        "meta": {
+          "color": "orange",
+          "doc": null,
+          "inputs": [],
+          "name": "Input: tensor",
+          "outputs": [
+            {
+              "name": "output",
+              "position": "top",
+              "type": {
+                "type": "tensor"
+              }
+            }
+          ],
+          "params": [
+            {
+              "default": null,
+              "name": "name",
+              "type": {
+                "type": "None"
+              }
+            }
+          ],
+          "type": "basic"
+        },
+        "params": {
+          "name": "label"
+        },
+        "status": "done",
+        "title": "Input: tensor"
+      },
+      "dragHandle": ".bg-primary",
+      "height": 200.0,
+      "id": "Input: tensor 2",
       "position": {
-        "x": 342.3226409443945,
-        "y": -687.1882072175634
+        "x": 787.538183263333,
+        "y": -801.4448540205135
       },
       "type": "basic",
       "width": 200.0

examples/fake_data.py

@@ -7,6 +7,11 @@ faker = Faker()
 
 @op("LynxKite Graph Analytics", "Fake data")
 def fake(*, n=10):
+    """Creates a DataFrame with random-generated names and postal addresses.
+
+    Parameters:
+        n: Number of rows to create.
+    """
     df = pd.DataFrame(
         {
             "name": [faker.name() for _ in range(n)],

lynxkite-app/pyproject.toml

@@ -10,6 +10,7 @@ dependencies = [
     "orjson>=3.10.13",
     "pycrdt-websocket>=0.15.3",
     "sse-starlette>=2.2.1",
+    "griffe>=1.7.3",
 ]
 
 [project.optional-dependencies]

lynxkite-app/web/package-lock.json

@@ -30,6 +30,7 @@
         "react-error-boundary": "^5.0.0",
         "react-markdown": "^9.0.1",
         "react-router-dom": "^7.5.2",
+        "react-tooltip": "^5.28.1",
         "swr": "^2.2.5",
         "unplugin-icons": "^0.21.0",
         "y-monaco": "^0.1.6",
@@ -940,6 +941,31 @@
         "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
       }
     },
+    "node_modules/@floating-ui/core": {
+      "version": "1.6.9",
+      "resolved": "https://registry.npmjs.org/@floating-ui/core/-/core-1.6.9.tgz",
+      "integrity": "sha512-uMXCuQ3BItDUbAMhIXw7UPXRfAlOAvZzdK9BWpE60MCn+Svt3aLn9jsPTi/WNGlRUu2uI0v5S7JiIUsbsvh3fw==",
+      "license": "MIT",
+      "dependencies": {
+        "@floating-ui/utils": "^0.2.9"
+      }
+    },
+    "node_modules/@floating-ui/dom": {
+      "version": "1.6.13",
+      "resolved": "https://registry.npmjs.org/@floating-ui/dom/-/dom-1.6.13.tgz",
+      "integrity": "sha512-umqzocjDgNRGTuO7Q8CU32dkHkECqI8ZdMZ5Swb6QAM0t5rnlrN3lGo1hdpscRd3WS8T6DKYK4ephgIH9iRh3w==",
+      "license": "MIT",
+      "dependencies": {
+        "@floating-ui/core": "^1.6.0",
+        "@floating-ui/utils": "^0.2.9"
+      }
+    },
+    "node_modules/@floating-ui/utils": {
+      "version": "0.2.9",
+      "resolved": "https://registry.npmjs.org/@floating-ui/utils/-/utils-0.2.9.tgz",
+      "integrity": "sha512-MDWhGtE+eHw5JW7lq4qhc5yRLS11ERl1c7Z6Xd0a58DozHES6EnNNwUWbMiG4J9Cgj053Bhk8zvlhFYKVhULwg==",
+      "license": "MIT"
+    },
     "node_modules/@humanfs/core": {
       "version": "0.19.1",
       "resolved": "https://registry.npmjs.org/@humanfs/core/-/core-0.19.1.tgz",
@@ -2879,6 +2905,12 @@
       "integrity": "sha512-JhZUT7JFcQy/EzW605k/ktHtncoo9vnyW/2GspNYwFlN1C/WmjuV/xtS04e9SOkL2sTdw0VAZ2UGCcQ9lR6p6w==",
       "license": "MIT"
     },
+    "node_modules/classnames": {
+      "version": "2.5.1",
+      "resolved": "https://registry.npmjs.org/classnames/-/classnames-2.5.1.tgz",
+      "integrity": "sha512-saHYOzhIQs6wy2sVxTM6bUDsQO4F50V9RQ22qBpEdCW+I+/Wmke2HOl6lS6dTpdxVhb88/I6+Hs+438c3lfUow==",
+      "license": "MIT"
+    },
     "node_modules/client-only": {
       "version": "0.0.1",
       "resolved": "https://registry.npmjs.org/client-only/-/client-only-0.0.1.tgz",
@@ -6239,6 +6271,20 @@
         "react-dom": ">=18"
       }
     },
+    "node_modules/react-tooltip": {
+      "version": "5.28.1",
+      "resolved": "https://registry.npmjs.org/react-tooltip/-/react-tooltip-5.28.1.tgz",
+      "integrity": "sha512-ZA4oHwoIIK09TS7PvSLFcRlje1wGZaxw6xHvfrzn6T82UcMEfEmHVCad16Gnr4NDNDh93HyN037VK4HDi5odfQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@floating-ui/dom": "^1.6.1",
+        "classnames": "^2.3.0"
+      },
+      "peerDependencies": {
+        "react": ">=16.14.0",
+        "react-dom": ">=16.14.0"
+      }
+    },
     "node_modules/read-cache": {
       "version": "1.0.0",
       "resolved": "https://registry.npmjs.org/read-cache/-/read-cache-1.0.0.tgz",

lynxkite-app/web/package.json

@@ -33,6 +33,7 @@
     "react-error-boundary": "^5.0.0",
     "react-markdown": "^9.0.1",
     "react-router-dom": "^7.5.2",
+    "react-tooltip": "^5.28.1",
     "swr": "^2.2.5",
     "unplugin-icons": "^0.21.0",
     "y-monaco": "^0.1.6",

lynxkite-app/web/src/Tooltip.tsx

@@ -0,0 +1,21 @@
+import { useId } from "react";
+import Markdown from "react-markdown";
+import { Tooltip as ReactTooltip } from "react-tooltip";
+
+export default function Tooltip(props: any) {
+  const id = useId();
+  if (!props.doc) return null;
+  return (
+    <>
+      <a data-tooltip-id={id} tabIndex={0}>
+        {props.children}
+      </a>
+      <ReactTooltip id={id} className="tooltip" place="top-end">
+        {props.doc.map?.(
+          (section: any, i: number) =>
+            section.kind === "text" && <Markdown key={i}>{section.value}</Markdown>,
+        ) ?? <Markdown>{props.doc}</Markdown>}
+      </ReactTooltip>
+    </>
+  );
+}

lynxkite-app/web/src/index.css

@@ -68,11 +68,6 @@ body {
     font-size: 12px;
   }
 
-  .title-icon {
-    margin-left: 5px;
-    float: right;
-  }
-
   .node-container {
     padding: 8px;
     position: relative;
@@ -93,8 +88,21 @@ body {
     }
   }
 
+  .tooltip {
+    padding: 8px;
+    border-radius: 4px;
+    opacity: 1;
+    text-align: left;
+    background: #fffa;
+    color: black;
+    box-shadow: 0px 5px 50px 0px rgba(0, 0, 0, 0.1);
+    backdrop-filter: blur(10px);
+    font-size: 16px;
+    font-weight: initial;
+    max-width: 300px;
+  }
+
   .expanded .lynxkite-node {
-    overflow-y: auto;
     height: 100%;
   }
 
@@ -114,6 +122,13 @@ body {
     --status-color-2: #0000;
     --status-color-3: #0000;
     transition: --status-color-1 0.3s, --status-color-2 0.3s, --status-color-3 0.3s;
+    display: flex;
+    flex-direction: row;
+    gap: 10px;
+
+    .title-title {
+      flex: 1;
+    }
   }
 
   .lynxkite-node .title.active {
@@ -143,24 +158,40 @@ body {
     visibility: hidden;
   }
 
-  .react-flow__handle-left .handle-name {
-    right: 20px;
+  .react-flow__handle-left {
+    left: -5px;
+
+    .handle-name {
+      right: 30px;
+    }
   }
 
-  .react-flow__handle-right .handle-name {
-    left: 20px;
+  .react-flow__handle-right {
+    right: -5px;
+
+    .handle-name {
+      left: 30px;
+    }
   }
 
-  .react-flow__handle-top .handle-name {
-    top: -20px;
-    left: 5px;
-    backdrop-filter: none;
+  .react-flow__handle-top {
+    top: -5px;
+
+    .handle-name {
+      top: -3px;
+      left: 13px;
+      backdrop-filter: none;
+    }
   }
 
-  .react-flow__handle-bottom .handle-name {
-    top: 0px;
-    left: 5px;
-    backdrop-filter: none;
+  .react-flow__handle-bottom {
+    bottom: -5px;
+
+    .handle-name {
+      top: 0px;
+      left: 13px;
+      backdrop-filter: none;
+    }
   }
 
   .node-container:hover .handle-name {
@@ -180,6 +211,13 @@ body {
       display: block;
     }
 
+    .param-name-row {
+      display: flex;
+      flex-direction: row;
+      justify-content: space-between;
+      align-items: end;
+    }
+
     .param-name {
       display: block;
       font-size: 10px;
@@ -453,8 +491,9 @@ body {
 .react-flow__handle {
   border-color: black;
   background: white;
-  width: 10px;
-  height: 10px;
+  width: 20px;
+  height: 20px;
+  border-width: 2px;
 }
 
 .react-flow__arrowhead * {

lynxkite-app/web/src/workspace/LynxKiteEdge.tsx

@@ -0,0 +1,30 @@
+import { BaseEdge, Position } from "@xyflow/react";
+
+function addOffset(x: number, y: number, p: Position, offset: number) {
+  if (p === Position.Top) return `${x},${y - offset}`;
+  if (p === Position.Bottom) return `${x},${y + offset}`;
+  if (p === Position.Left) return `${x - offset},${y}`;
+  return `${x + offset},${y}`;
+}
+
+export default function LynxKiteEdge(props: any) {
+  const offset = 0.3 * Math.hypot(props.targetX - props.sourceX, props.targetY - props.sourceY);
+  const s = addOffset(props.sourceX, props.sourceY, props.sourcePosition, 0);
+  const sc = addOffset(props.sourceX, props.sourceY, props.sourcePosition, offset);
+  const tc = addOffset(props.targetX, props.targetY, props.targetPosition, offset);
+  const t = addOffset(props.targetX, props.targetY, props.targetPosition, 0);
+  const path = `M${s} C${sc} ${tc} ${t}`;
+  return (
+    <>
+      <BaseEdge
+        id={props.id}
+        path={path}
+        {...props}
+        style={{
+          strokeWidth: 2,
+          stroke: "black",
+        }}
+      />
+    </>
+  );
+}

lynxkite-app/web/src/workspace/Workspace.tsx

@@ -34,6 +34,7 @@ import favicon from "../assets/favicon.ico";
 import { usePath } from "../common.ts";
 // import NodeWithTableView from './NodeWithTableView';
 import EnvironmentSelector from "./EnvironmentSelector";
+import LynxKiteEdge from "./LynxKiteEdge.tsx";
 import { LynxKiteState } from "./LynxKiteState";
 import NodeSearch, { type OpsOp, type Catalog, type Catalogs } from "./NodeSearch.tsx";
 import NodeWithGraphCreationView from "./nodes/GraphCreationNode.tsx";
@@ -186,6 +187,12 @@ function LynxKiteFlow() {
     }),
     [],
   );
+  const edgeTypes = useMemo(
+    () => ({
+      default: LynxKiteEdge,
+    }),
+    [],
+  );
 
   // Global keyboard shortcuts.
   useEffect(() => {
@@ -280,7 +287,7 @@ function LynxKiteFlow() {
     (connection: Connection) => {
       setSuppressSearchUntil(Date.now() + 200);
       const edge = {
-        id: `${connection.source} ${connection.target}`,
+        id: `${connection.source} ${connection.sourceHandle} ${connection.target} ${connection.targetHandle}`,
         source: connection.source,
         sourceHandle: connection.sourceHandle!,
         target: connection.target,
@@ -374,6 +381,7 @@ function LynxKiteFlow() {
             nodes={nodes}
             edges={edges}
             nodeTypes={nodeTypes}
+            edgeTypes={edgeTypes}
             fitView
             onNodesChange={onNodesChange}
             onEdgesChange={onEdgesChange}

lynxkite-app/web/src/workspace/nodes/LynxKiteNode.tsx

@@ -1,9 +1,17 @@
 import { Handle, NodeResizeControl, type Position, useReactFlow } from "@xyflow/react";
+import type React from "react";
 import { ErrorBoundary } from "react-error-boundary";
 // @ts-ignore
+import AlertTriangle from "~icons/tabler/alert-triangle-filled.jsx";
+// @ts-ignore
 import ChevronDownRight from "~icons/tabler/chevron-down-right.jsx";
 // @ts-ignore
+import Dots from "~icons/tabler/dots.jsx";
+// @ts-ignore
+import Help from "~icons/tabler/question-mark.jsx";
+// @ts-ignore
 import Skull from "~icons/tabler/skull.jsx";
+import Tooltip from "../../Tooltip";
 
 interface LynxKiteNodeProps {
   id: string;
@@ -44,9 +52,11 @@ function getHandles(inputs: any[], outputs: any[]) {
 }
 
 const OP_COLORS: { [key: string]: string } = {
+  pink: "oklch(75% 0.2 0)",
   orange: "oklch(75% 0.2 55)",
+  green: "oklch(75% 0.2 150)",
   blue: "oklch(75% 0.2 230)",
-  green: "oklch(75% 0.2 130)",
+  purple: "oklch(75% 0.2 290)",
 };
 
 function LynxKiteNodeComponent(props: LynxKiteNodeProps) {
@@ -81,9 +91,20 @@ function LynxKiteNodeComponent(props: LynxKiteNodeProps) {
           style={titleStyle}
           onClick={titleClicked}
         >
-          {data.title}
-          {data.error && <span className="title-icon">⚠️</span>}
-          {expanded || <span className="title-icon">⋯</span>}
+          <span className="title-title">{data.title}</span>
+          {data.error && (
+            <Tooltip doc={`Error: ${data.error}`}>
+              <AlertTriangle />
+            </Tooltip>
+          )}
+          {expanded || (
+            <Tooltip doc="Click to expand node">
+              <Dots />
+            </Tooltip>
+          )}
+          <Tooltip doc={data.meta?.value?.doc}>
+            <Help />
+          </Tooltip>
         </div>
         {expanded && (
           <>

lynxkite-app/web/src/workspace/nodes/NodeParameter.tsx

@@ -1,6 +1,9 @@
 import { useRef } from "react";
 // @ts-ignore
 import ArrowsHorizontal from "~icons/tabler/arrows-horizontal.jsx";
+// @ts-ignore
+import Help from "~icons/tabler/question-mark.jsx";
+import Tooltip from "../../Tooltip";
 import NodeGroupParameter from "./NodeGroupParameter";
 
 const BOOLEAN = "<class 'bool'>";
@@ -9,8 +12,19 @@ const MODEL_TRAINING_INPUT_MAPPING =
 const MODEL_INFERENCE_INPUT_MAPPING =
   "<class 'lynxkite_graph_analytics.ml_ops.ModelInferenceInputMapping'>";
 const MODEL_OUTPUT_MAPPING = "<class 'lynxkite_graph_analytics.ml_ops.ModelOutputMapping'>";
-function ParamName({ name }: { name: string }) {
-  return <span className="param-name bg-base-200">{name.replace(/_/g, " ")}</span>;
+
+function ParamName({ name, doc }: { name: string; doc: string }) {
+  const help = doc && (
+    <Tooltip doc={doc} width={200}>
+      <Help />
+    </Tooltip>
+  );
+  return (
+    <div className="param-name-row">
+      <span className="param-name bg-base-200">{name.replace(/_/g, " ")}</span>
+      {help}
+    </div>
+  );
 }
 
 function Input({
@@ -195,18 +209,31 @@ interface NodeParameterProps {
 
 export type UpdateOptions = { delay?: number };
 
+function findDocs(docs: any, parameter: string) {
+  for (const sec of docs) {
+    if (sec.kind === "parameters") {
+      for (const p of sec.value) {
+        if (p.name === parameter) {
+          return p.description;
+        }
+      }
+    }
+  }
+}
+
 export default function NodeParameter({ name, value, meta, data, setParam }: NodeParameterProps) {
+  const doc = findDocs(data.meta?.value?.doc ?? [], name);
   function onChange(value: any, opts?: UpdateOptions) {
     setParam(meta.name, value, opts || {});
   }
   return meta?.type?.format === "collapsed" ? (
     <label className="param">
-      <ParamName name={name} />
+      <ParamName name={name} doc={doc} />
       <button className="collapsed-param">⋯</button>
     </label>
   ) : meta?.type?.format === "textarea" ? (
     <label className="param">
-      <ParamName name={name} />
+      <ParamName name={name} doc={doc} />
       <textarea
         className="textarea textarea-bordered w-full"
         rows={6}
@@ -219,7 +246,7 @@ export default function NodeParameter({ name, value, meta, data, setParam }: Nod
     <NodeGroupParameter meta={meta} data={data} setParam={setParam} />
   ) : meta?.type?.enum ? (
     <label className="param">
-      <ParamName name={name} />
+      <ParamName name={name} doc={doc} />
       <select
         className="select select-bordered w-full"
         value={value || meta.type.enum[0]}
@@ -246,22 +273,22 @@ export default function NodeParameter({ name, value, meta, data, setParam }: Nod
     </div>
   ) : meta?.type?.type === MODEL_TRAINING_INPUT_MAPPING ? (
     <label className="param">
-      <ParamName name={name} />
+      <ParamName name={name} doc={doc} />
       <ModelMapping value={value} data={data} variant="training input" onChange={onChange} />
     </label>
   ) : meta?.type?.type === MODEL_INFERENCE_INPUT_MAPPING ? (
     <label className="param">
-      <ParamName name={name} />
+      <ParamName name={name} doc={doc} />
       <ModelMapping value={value} data={data} variant="inference input" onChange={onChange} />
     </label>
   ) : meta?.type?.type === MODEL_OUTPUT_MAPPING ? (
     <label className="param">
-      <ParamName name={name} />
+      <ParamName name={name} doc={doc} />
       <ModelMapping value={value} data={data} variant="output" onChange={onChange} />
     </label>
   ) : (
     <label className="param">
-      <ParamName name={name} />
+      <ParamName name={name} doc={doc} />
       <Input value={value} onChange={onChange} />
     </label>
   );

lynxkite-core/pyproject.toml

@@ -5,6 +5,7 @@ description = "A lightweight dependency for authoring LynxKite operations and ex
 readme = "README.md"
 requires-python = ">=3.11"
 dependencies = [
+    "griffe>=1.7.3",
 ]
 
 [project.optional-dependencies]

lynxkite-core/src/lynxkite/core/ops.py

@@ -1,19 +1,22 @@
 """API for implementing LynxKite operations."""
 
 from __future__ import annotations
+
 import asyncio
 import enum
 import functools
+import json
 import importlib
 import inspect
 import pathlib
 import subprocess
 import traceback
-import joblib
 import types
-import pydantic
 import typing
 from dataclasses import dataclass
+
+import joblib
+import pydantic
 from typing_extensions import Annotated
 
 if typing.TYPE_CHECKING:
@@ -180,6 +183,7 @@ class Op(BaseConfig):
     # TODO: Make type an enum with the possible values.
     type: str = "basic"  # The UI to use for this operation.
     color: str = "orange"  # The color of the operation in the UI.
+    doc: object = None
 
     def __call__(self, *inputs, **params):
         # Convert parameters.
@@ -236,6 +240,7 @@ def op(
     """Decorator for defining an operation."""
 
     def decorator(func):
+        doc = get_doc(func)
         sig = inspect.signature(func)
         _view = view
         if view == "matplotlib":
@@ -262,6 +267,7 @@ def op(
             _outputs = [Output(name="output", type=None)] if view == "basic" else []
         op = Op(
             func=func,
+            doc=doc,
             name=name,
             params=_params,
             inputs=inputs,
@@ -279,10 +285,11 @@ def op(
 
 def matplotlib_to_image(func):
     """Decorator for converting a matplotlib figure to an image."""
-    import matplotlib.pyplot as plt
     import base64
     import io
 
+    import matplotlib.pyplot as plt
+
     @functools.wraps(func)
     def wrapper(*args, **kwargs):
         func(*args, **kwargs)
@@ -423,3 +430,15 @@ def run_user_script(script_path: pathlib.Path):
     spec = importlib.util.spec_from_file_location(script_path.stem, str(script_path))
     module = importlib.util.module_from_spec(spec)
     spec.loader.exec_module(module)
+
+
+def get_doc(func):
+    """Griffe is an optional dependency. When available, we returned the parsed docstring."""
+    try:
+        import griffe
+    except ImportError:
+        return func.__doc__
+    if func.__doc__ is None:
+        return None
+    doc = griffe.Docstring(func.__doc__).parse("google")
+    return json.loads(json.dumps(doc, cls=griffe.JSONEncoder))

lynxkite-graph-analytics/src/lynxkite_graph_analytics/lynxkite_ops.py

@@ -8,7 +8,6 @@ from collections import deque
 
 from . import core
 import grandcypher
-import joblib
 import matplotlib
 import networkx as nx
 import pandas as pd
@@ -16,7 +15,6 @@ import polars as pl
 import json
 
 
-mem = joblib.Memory(".joblib-cache")
 op = ops.op_registration(core.ENV)
 
 
@@ -82,8 +80,7 @@ def import_parquet(*, filename: str):
     return pd.read_parquet(filename)
 
 
-@op("Import CSV")
-@mem.cache
+@op("Import CSV", slow=True)
 def import_csv(*, filename: str, columns: str = "<from file>", separator: str = "<auto>"):
     """Imports a CSV file."""
     return pd.read_csv(
@@ -93,8 +90,7 @@ def import_csv(*, filename: str, columns: str = "<from file>", separator: str =
     )
 
 
-@op("Import GraphML")
-@mem.cache
+@op("Import GraphML", slow=True)
 def import_graphml(*, filename: str):
     """Imports a GraphML file."""
     files = fsspec.open_files(filename, compression="infer")
@@ -105,8 +101,7 @@ def import_graphml(*, filename: str):
     raise ValueError(f"No .graphml file found at {filename}")
 
 
-@op("Graph from OSM")
-@mem.cache
+@op("Graph from OSM", slow=True)
 def import_osm(*, location: str):
     import osmnx as ox
 

lynxkite-graph-analytics/src/lynxkite_graph_analytics/pytorch/pytorch_ops.py

@@ -8,7 +8,7 @@ from .pytorch_core import op, reg, ENV
 
 reg("Input: tensor", outputs=["output"], params=[P.basic("name")])
 reg("Input: graph edges", outputs=["edges"])
-reg("Input: sequential", outputs=["y"])
+reg("Input: sequential", outputs=["y"], params=[P.basic("name")])
 reg("Output", inputs=["x"], outputs=["x"], params=[P.basic("name")])
 
 
@@ -19,6 +19,7 @@ def lstm(x, *, input_size=1024, hidden_size=1024, dropout=0.0):
 
 reg(
     "Neural ODE",
+    color="blue",
     inputs=["x"],
     params=[
         P.basic("relative_tolerance"),
@@ -99,6 +100,7 @@ def concatenate(a, b):
 
 reg(
     "Graph conv",
+    color="blue",
     inputs=["x", "edges"],
     outputs=["x"],
     params=[P.options("type", ["GCNConv", "GATConv", "GATv2Conv", "SAGEConv"])],