feat: first draft at kirin kernel debugger that generates HTML

example/README.md

@@ -5,6 +5,7 @@ This folder contains examples of how to use the Kirin library. Each example is a
 ## List of Examples
 
 - `simple.py`: A simple example that demonstrates how to create a simple Kirin dialect group and its kernel.
+- `ir_inspector.py`: Generates an interactive HTML view of a compiled kernel; the same view can be rendered inline in a notebook.
 - `food`: A more sophisticated example but without any domain specifics. It demonstrates how to create a new Kirin dialect and combine it with existing dialects with custom analysis and rewrites.
 - `pauli`: An example that implements a dialect with rewrites that simplifies products of Pauli matrices.
 

example/ir_inspector.py

@@ -0,0 +1,22 @@
+"""Generate an interactive HTML view of a compiled Kirin kernel."""
+
+from pathlib import Path
+
+from kirin.prelude import basic
+
+
+@basic
+def add_one(x: int) -> int:
+    return x + 1
+
+
+if __name__ == "__main__":
+    output = add_one.visualize(Path("add_one.ir.html"))
+    print(f"Wrote interactive IR inspector to {output.resolve()}")
+
+# In a Jupyter notebook, render the same inspector inline instead:
+#
+# from IPython.display import HTML, display
+# from kirin import ir_to_html
+#
+# display(HTML(ir_to_html(add_one)))

src/kirin/__init__.py

@@ -1,5 +1,14 @@
 # re-exports the public API of the kirin package
 from . import ir as ir, types as types, stdlib as stdlib, lowering as lowering
 from .exception import enable_stracetrace, disable_stracetrace
+from .visualize import to_html as ir_to_html, write_html as write_ir_html
 
-__all__ = ["ir", "types", "lowering", "enable_stracetrace", "disable_stracetrace"]
+__all__ = [
+    "ir",
+    "types",
+    "lowering",
+    "enable_stracetrace",
+    "disable_stracetrace",
+    "ir_to_html",
+    "write_ir_html",
+]

src/kirin/ir/method.py

@@ -13,6 +13,11 @@
 from kirin.print.printable import Printable
 
 if typing.TYPE_CHECKING:
+    from collections.abc import Mapping
+    from pathlib import Path
+    from typing import Any
+
+    from kirin.ir.ssa import SSAValue
     from kirin.serialization.base.serializer import Serializer
     from kirin.serialization.base.deserializer import Deserializer
     from kirin.serialization.core.serializationunit import SerializationUnit
@@ -161,6 +166,19 @@ def __repr__(self) -> str:
     def print_impl(self, printer: Printer) -> None:
         return printer.print(self.code)
 
+    def visualize(
+        self,
+        file: str | Path,
+        *,
+        analysis: Mapping[SSAValue, Any] | None = None,
+        title: str | None = None,
+    ) -> Path:
+        """Write an interactive HTML inspector for this method's IR."""
+
+        from kirin.visualize import write_html
+
+        return write_html(self, file, analysis=analysis, title=title)
+
     def similar(self, dialects: typing.Optional["DialectGroup"] = None):
         return Method(
             dialects=dialects or self.dialects,