nodekit 0.2.0__py3-none-any.whl

nodekit/_internal/ops/play/local_runner/main.py

@@ -0,0 +1,234 @@
+import atexit
+import hashlib
+import threading
+import time
+from pathlib import Path
+from typing import List, Dict
+
+import fastapi
+import fastapi.responses
+import fastapi.templating
+import pydantic
+import uvicorn
+
+from nodekit import Graph
+from nodekit._internal.utils.get_browser_bundle import get_browser_bundle
+from nodekit._internal.utils.iter_assets import iter_assets
+from nodekit._internal.types.assets import URL, Asset
+from nodekit._internal.types.value import SHA256
+from nodekit._internal.types.events.events import Event, EventTypeEnum
+from nodekit._internal.types.trace import Trace
+from nodekit._internal.ops.open_asset_save_asset import open_asset
+
+
+# %%
+class LocalRunner:
+    def __init__(
+        self,
+        port: int = 7651,
+        host: str = "127.0.0.1",
+    ):
+        self._lock = threading.RLock()
+        self._thread: threading.Thread | None = None
+        self._server: uvicorn.Server | None = None
+        self._running = False
+
+        self.port = port
+        self.host = host
+
+        # In-memory state of the runner:
+        self._graph: Graph | None = None
+        self._events: List[Event] = []
+
+        self.asset_id_to_asset: Dict[SHA256, Asset] = {}
+
+        # Initialize FastAPI app
+        self.app = self._build_app()
+        atexit.register(self.shutdown)
+
+    def ensure_running(self):
+        with self._lock:
+            if self._running:
+                return
+
+            config = uvicorn.Config(
+                app=self.app,
+                host=self.host,
+                port=self.port,
+                log_level="warning",
+            )
+            self._server = uvicorn.Server(config=config)
+            self._thread = threading.Thread(target=self._server.run, daemon=True)
+            self._thread.start()
+            self._running = True
+
+    def shutdown(self):
+        with self._lock:
+            if not self._running:
+                return
+
+            if self._server is not None:
+                self._server.should_exit = True
+            if self._thread is not None:
+                self._thread.join(timeout=5.0)
+
+            self._running = False
+            self._server = None
+            self._thread = None
+
+    def set_graph(self, graph: Graph):
+        with self._lock:
+            graph = graph.model_copy(deep=True)
+            # Reset Graph and Events
+            self._graph = graph
+            self._events = []
+
+            # Mount the Graph's assets:
+            for asset in iter_assets(graph=graph):
+                if not isinstance(asset.locator, URL):
+                    # Save a copy of the original Asset:
+                    self.asset_id_to_asset[asset.sha256] = asset.model_copy(deep=True)
+
+                    # Mutate the Graph's Asset to have a URL locator:
+                    asset.locator = URL(url=f"assets/{asset.sha256}")
+
+    def _build_app(self) -> fastapi.FastAPI:
+        app = fastapi.FastAPI()
+
+        # Mount the static JS and CSS files
+        bundle = get_browser_bundle()
+
+        def _sha(text: str) -> str:
+            return hashlib.sha256(text.encode("utf-8")).hexdigest()[:12]
+
+        NODEKIT_JS_HASH = _sha(bundle.js)
+        NODEKIT_CSS_HASH = _sha(bundle.css)
+
+        # Mount the jinja2 template at ./site-template.j2:
+        templates = fastapi.templating.Jinja2Templates(directory=Path(__file__).parent)
+
+        # Cache-busted asset endpoints
+        @app.get("/static/nodekit.{js_hash}.js", name="get_nodekit_javascript")
+        def get_nodekit_javascript(js_hash: str) -> fastapi.responses.PlainTextResponse:
+            if not js_hash == NODEKIT_JS_HASH:
+                raise fastapi.HTTPException(status_code=404, detail="JS not found")
+            return fastapi.responses.PlainTextResponse(
+                bundle.js, media_type="application/javascript"
+            )
+
+        @app.get("/static/nodekit.{css_hash}.css", name="get_nodekit_css")
+        def get_nodekit_css(css_hash: str) -> fastapi.responses.PlainTextResponse:
+            if not css_hash == NODEKIT_CSS_HASH:
+                raise fastapi.HTTPException(status_code=404, detail="CSS not found")
+            return fastapi.responses.PlainTextResponse(
+                bundle.css, media_type="text/css"
+            )
+
+        @app.get("/health")
+        def health():
+            return fastapi.Response(status_code=fastapi.status.HTTP_204_NO_CONTENT)
+
+        @app.get("/assets/{asset_id}")
+        async def get_asset(asset_id: str):
+            try:
+                asset = self.asset_id_to_asset[asset_id]
+            except KeyError:
+                raise fastapi.HTTPException(
+                    status_code=404, detail=f"Asset with ID {asset_id} not found."
+                )
+
+            # Hardcode
+            with open_asset(asset) as f:
+                savepath = Path(f"/tmp/{asset_id}")
+                if not savepath.exists():
+                    with open(savepath, "wb") as out:
+                        out.write(f.read())
+                    print(f"Saved asset to {savepath}")
+            return fastapi.responses.FileResponse(
+                path=savepath,
+                media_type=asset.media_type,
+            )
+
+        @app.get("/")
+        def site(
+            request: fastapi.Request,
+        ) -> fastapi.responses.HTMLResponse:
+            if self._graph is None:
+                raise fastapi.HTTPException(
+                    status_code=404,
+                    detail="No Graph is currently being served. Call `nodekit.play` first.",
+                )
+
+            return templates.TemplateResponse(
+                request=request,
+                name="site-template.j2",
+                context={
+                    "graph": self._graph.model_dump(mode="json"),
+                    "nodekit_javascript_link": request.url_for(
+                        "get_nodekit_javascript",
+                        js_hash=NODEKIT_JS_HASH,
+                    ),
+                    "nodekit_css_link": request.url_for(
+                        "get_nodekit_css",
+                        css_hash=NODEKIT_CSS_HASH,
+                    ),
+                    "submit_event_url": request.url_for(
+                        "submit_event",
+                    ),
+                },
+            )
+
+        @app.post("/submit")
+        def submit_event(
+            event: dict,
+        ) -> fastapi.Response:
+            # Event is a type alias which is a Union of multiple concrete event types.
+            # Need a TypeAdapter for this.
+            typeadapter = pydantic.TypeAdapter(Event)
+            event = typeadapter.validate_python(event)
+            print(f"Received {event.event_type.value}")
+            self._events.append(event)
+            return fastapi.Response(status_code=fastapi.status.HTTP_204_NO_CONTENT)
+
+        return app
+
+    @property
+    def url(self) -> str:
+        return f"http://{self.host}:{self.port}"
+
+    def list_events(self) -> List[Event]:
+        with self._lock:
+            return list(self._events)
+
+
+# %%
+def play(
+    graph: Graph,
+) -> Trace:
+    """
+    Play the given Graph locally, then return the Trace.
+
+    Args:
+        graph: x
+
+    Returns:
+        The Trace of Events observed during execution.
+
+    """
+    runner = LocalRunner()
+    runner.ensure_running()
+    runner.set_graph(graph)
+
+    print("Play the Graph at:\n", runner.url)
+
+    # Wait until the End Event is observed:
+    while True:
+        events = runner.list_events()
+        if any([e.event_type == EventTypeEnum.TraceEndedEvent for e in events]):
+            break
+        time.sleep(1)
+
+    # Shut down the server:
+    runner.shutdown()
+
+    return Trace(events=events)

nodekit/_internal/ops/play/local_runner/site-template.j2

@@ -0,0 +1,38 @@
+<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <title>NodeKit Preview Page</title>
+    <link rel="shortcut icon" href="">
+
+    <!-- NodeKit -->
+    <script src="{{ nodekit_javascript_link }}"></script>
+    <link href="{{ nodekit_css_link }}" rel="stylesheet">
+
+    <script>
+        const graph = {{ graph | tojson(indent=4) | indent(8, first=False) }};
+        const eventSubmitUrl = "{{ submit_event_url }}";
+
+        async function sendEvent(ev) {
+            console.log(ev)
+            try {
+                await fetch(eventSubmitUrl, {
+                    method: "POST",
+                    headers: { "Content-Type": "application/json" },
+                    body: JSON.stringify(ev),
+                });
+            } catch (err) {
+                console.error("Failed to send event", err);
+            }
+        }
+
+        window.onload = async () => {
+            await NodeKit.play(
+                graph,
+                sendEvent
+            );
+        };
+    </script>
+</head>
+<body></body>
+</html>

nodekit/_internal/ops/save_graph_load_graph.py

@@ -0,0 +1,131 @@
+import os
+import shutil
+import zipfile
+from pathlib import Path
+from typing import Tuple, Dict
+
+from nodekit._internal.utils.get_extension_from_media_type import (
+    get_extension_from_media_type,
+)
+from nodekit._internal.utils.iter_assets import iter_assets
+from nodekit._internal.ops.open_asset_save_asset import open_asset
+from nodekit._internal.types.assets import (
+    ZipArchiveInnerPath,
+    RelativePath,
+    Asset,
+)
+from nodekit._internal.types.value import MediaType, SHA256
+from nodekit._internal.types.graph import Graph
+
+
+# %%
+def _get_archive_relative_path(media_type: MediaType, sha256: SHA256) -> Path:
+    """
+    Returns the relative path within the .nkg archive for a given asset.
+    """
+    extension = get_extension_from_media_type(media_type)
+    return Path("assets") / media_type / f"{sha256}.{extension}"
+
+
+# %%
+def save_graph(
+    graph: Graph,
+    path: str | os.PathLike,
+) -> Path:
+    """
+    Packs the Graph model into a .nkg file, which is the canonical representation of a Graph.
+    A .nkg file is a .zip archive with the following structure:
+
+    graph.json
+    assets/
+        {mime-type-1}/{mime-type-2}/{sha256}.{ext}
+    """
+    # Ensure the given path ends with .nkg or has no extension:
+    path = Path(path)
+    if not str(path).endswith(".nkg"):
+        raise ValueError(f"Path must end with .nkg: {path}")
+
+    if not path.parent.exists():
+        raise ValueError(f"Parent directory does not exist: {path.parent}")
+
+    # Deep copy the Graph, as we will be modifying it so that all AssetLocators are RelativePathAssetLocators:
+    graph = graph.model_copy(deep=True)
+
+    # Mutate all AssetLocators in the Graph to be RelativePathAssetLocators:
+    supplied_assets: Dict[Tuple[MediaType, SHA256], Asset] = {}
+    relative_asset_locators: Dict[Tuple[MediaType, SHA256], RelativePath] = {}
+    for asset in iter_assets(graph=graph):
+        # Log the asset locator if we haven't seen it before:
+        asset_key = (asset.media_type, asset.sha256)
+        if asset_key not in supplied_assets:
+            supplied_assets[asset_key] = asset.model_copy()
+            relative_asset_locators[asset_key] = RelativePath(
+                relative_path=_get_archive_relative_path(
+                    media_type=asset.media_type, sha256=asset.sha256
+                )
+            )
+
+        # Mutate the AssetLocator to be a RelativePathAssetLocator:
+        asset.locator = relative_asset_locators[asset_key]
+
+    # Open a temporary zip file for writing:
+    temp_path = path.with_suffix(".nkg.tmp")
+    if temp_path.exists():
+        raise ValueError(f"Temporary path already exists: {temp_path}")
+
+    try:
+        with zipfile.ZipFile(temp_path, "w", zipfile.ZIP_DEFLATED) as myzip:
+            # Write all asset files to the archive:
+            for asset_key, asset_locator in supplied_assets.items():
+                with open_asset(asset_locator) as src_file:
+                    media_type, sha256 = asset_key
+                    archive_relative_path = _get_archive_relative_path(
+                        media_type, sha256
+                    )
+                    with myzip.open(str(archive_relative_path), "w") as dst_file:
+                        shutil.copyfileobj(src_file, dst_file)
+
+            # Write the graph.json file:
+            myzip.writestr("graph.json", graph.model_dump_json(indent=2))
+
+        # Rename the temporary file to the final path:
+        temp_path.rename(path)
+    finally:
+        if temp_path.exists():
+            temp_path.unlink()
+    return Path(path)
+
+
+# %%
+def load_graph(
+    path: str | os.PathLike,
+) -> Graph:
+    """
+    Unpacks a .nkg file from disk and returns the corresponding Graph object.
+    All AssetFiles in the Graph are backed by the asset files in the .nkg archive.
+    The user is responsible for ensuring the .nkg file is not moved or edited while the Graph is in use.
+    """
+
+    if not str(path).endswith(".nkg"):
+        raise ValueError(f"Invalid path given; must end with .nkg: {path}")
+
+    # Open the zip file for reading:
+    with zipfile.ZipFile(path, "r") as zf:
+        # Read graph.json
+        with zf.open("graph.json") as f:
+            graph = Graph.model_validate_json(f.read().decode("utf-8"))
+
+        # Mutate all AssetLocators in the Graph from RelativePath to ZipArchiveInnerPath:
+        for asset in iter_assets(graph=graph):
+            # Raise a ValueError if the asset locator is not a RelativePath:
+            if not isinstance(asset.locator, RelativePath):
+                raise ValueError(
+                    f".nkg encoding error: Asset's locator is not a RelativePath: {asset}"
+                )
+
+            # Mutate the asset locator
+            asset.locator = ZipArchiveInnerPath(
+                zip_archive_path=Path(path), inner_path=asset.locator.relative_path
+            )
+
+    return graph

nodekit/_internal/ops/topological_sorting.py

@@ -0,0 +1,122 @@
+from collections import defaultdict, deque
+from typing import List, Tuple
+
+from nodekit import Graph
+from nodekit._internal.types.transition import IfThenElse, Switch, End, Go, Transition
+from nodekit._internal.types.value import NodeId
+
+
+# %%
+def topological_sort(
+    graph: Graph,
+) -> List[NodeId]:
+    """
+    Perform a topological sort over a directed graph of nodes and transitions.
+
+    Each Transition defines zero or more outgoing edges from a node. Nodes are ranked
+    according to topological order; ties within the same rank are deterministically
+    broken lexicographically. Nested Graphs (if present in nodes) are treated as leaves.
+
+    Args:
+        graph: The nk.Graph object containing nodes and transitions.
+    Returns:
+        List[NodeId]: A list of node identifiers in topologically sorted order
+    """
+
+    nodes, transitions = graph.nodes, graph.transitions
+
+    edges: list[tuple[NodeId, NodeId]] = []
+    for in_node, transition in transitions.items():
+        if in_node not in nodes:
+            raise KeyError(f"Transition refers to non-existent node '{in_node}'")
+
+        for out_node in _outgoing_targets(transition):
+            if out_node not in nodes:
+                raise KeyError(
+                    f"Transition from '{in_node}' points to unknown node '{out_node}'"
+                )
+            edges.append((in_node, out_node))
+
+    rank_order = _topo_sort_core(list(nodes.keys()), edges)
+
+    # Group by rank and apply lexical tie-breaker:
+    rank_groups = defaultdict(list)
+    for key, rank in zip(nodes.keys(), rank_order):
+        rank_groups[rank].append(key)
+
+    ordered: list[NodeId] = []
+    for rank in sorted(rank_groups.keys()):
+        group = rank_groups[rank]
+        group.sort()
+        ordered.extend(group)
+
+    return ordered
+
+
+def _topo_sort_core(
+    node_keys: List[NodeId], edges: List[Tuple[NodeId, NodeId]]
+) -> List[int]:
+    """
+    Perform topological sorting and return a list of ranks for each node key.
+
+    Args:
+        node_keys: List of unique node identifiers (strings).
+        edges: List of (src, dst) edges representing dependencies.
+
+    Returns:
+        List[int]: Ranks corresponding to each node in node_keys order.
+    """
+    # Build adjacency list and indegree count:
+    adjacency = defaultdict(list)
+    indegree = {key: 0 for key in node_keys}
+
+    for src, dst in edges:
+        adjacency[src].append(dst)
+        indegree[dst] += 1
+
+    # Initialize queue with nodes of indegree 0:
+    queue = deque([key for key, deg in indegree.items() if deg == 0])
+
+    rank_map = {}
+    current_rank = 0
+
+    # Core sorting algorithm:
+    while queue:
+        for _ in range(len(queue)):
+            node = queue.popleft()
+            rank_map[node] = current_rank
+            for neighbor in adjacency[node]:
+                indegree[neighbor] -= 1
+                if indegree[neighbor] == 0:
+                    queue.append(neighbor)
+        current_rank += 1
+
+    # Check for cycles:
+    if len(rank_map) != len(node_keys):
+        raise ValueError("Loop present in Graph, please reconfigure the structure")
+
+    # Return ranks in the same order as node_keys:
+    return [rank_map[key] for key in node_keys]
+
+
+def _outgoing_targets(tr: Transition) -> list[NodeId]:
+    if isinstance(tr, Go):
+        return [tr.to]
+    if isinstance(tr, End):
+        return []
+    if isinstance(tr, Switch):
+        targets: list[NodeId] = []
+        for _value, transition in tr.cases.items():
+            if isinstance(transition, Go):
+                targets.append(transition.to)
+        if isinstance(tr.default, Go):
+            targets.append(tr.default.to)
+        return targets
+    if isinstance(tr, IfThenElse):
+        targets: list[NodeId] = []
+        if isinstance(tr.then, Go):
+            targets.append(tr.then.to)
+        if isinstance(tr.else_, Go):
+            targets.append(tr.else_.to)
+        return targets
+    raise TypeError(f"Unsupported transition type: {tr}")

nodekit/_internal/types/actions/actions.py

@@ -0,0 +1,89 @@
+from abc import ABC
+from typing import Literal, Union, Annotated, Dict
+
+import pydantic
+
+from nodekit._internal.types.value import PressableKey, SpatialPoint
+
+
+# %%
+class BaseAction(pydantic.BaseModel, ABC):
+    action_type: str
+
+
+# %%
+class ClickAction(BaseAction):
+    action_type: Literal["ClickAction"] = "ClickAction"
+    x: SpatialPoint = pydantic.Field(
+        description="The x-coordinate of the click, in Board units."
+    )
+    y: SpatialPoint = pydantic.Field(
+        description="The y-coordinate of the click, in Board units."
+    )
+
+
+# %%
+class KeyAction(BaseAction):
+    action_type: Literal["KeyAction"] = "KeyAction"
+    key: PressableKey = pydantic.Field(description="The key that was pressed.")
+
+
+# %%
+class SliderAction(BaseAction):
+    action_type: Literal["SliderAction"] = "SliderAction"
+    bin_index: int = pydantic.Field(
+        description="The index of the bin that was selected.", ge=0
+    )
+
+
+# %%
+class TextEntryAction(BaseAction):
+    action_type: Literal["TextEntryAction"] = "TextEntryAction"
+    text: str
+
+
+# %%
+class WaitAction(BaseAction):
+    action_type: Literal["WaitAction"] = "WaitAction"
+
+
+# %%
+class SelectAction(BaseAction):
+    action_type: Literal["SelectAction"] = "SelectAction"
+    selection: str
+
+
+# %%
+class MultiSelectAction(BaseAction):
+    action_type: Literal["MultiSelectAction"] = "MultiSelectAction"
+    selections: list[str]
+
+
+# %%
+class ProductAction(BaseAction):
+    action_type: Literal["ProductAction"] = "ProductAction"
+    child_actions: Dict[str, "Action"]
+
+
+# %%
+class SumAction(BaseAction):
+    action_type: Literal["SumAction"] = "SumAction"
+    child_id: str
+    child_action: "Action"
+
+
+# %%
+Action = Annotated[
+    Union[
+        ClickAction,
+        KeyAction,
+        SliderAction,
+        TextEntryAction,
+        WaitAction,
+        SelectAction,
+        MultiSelectAction,
+        ProductAction,
+        SumAction,
+    ],
+    pydantic.Field(discriminator="action_type"),
+]