nodekit 0.2.0__py3-none-any.whl

nodekit/__init__.py

@@ -0,0 +1,53 @@
+__all__ = [
+    "VERSION",
+    # Top-level types:
+    "Node",
+    "Graph",
+    "Trace",
+    # One-off top-level types:
+    "Region",
+    # Namespaced types:
+    "assets",
+    "cards",
+    "sensors",
+    "actions",
+    "events",
+    "transitions",
+    "expressions",
+    "values",
+    # Ops:
+    "play",
+    "concat",
+    "save_graph",
+    "load_graph",
+    "open_asset",
+    "build_site",
+]
+
+# Version
+from nodekit._internal.version import VERSION
+
+# Incoming models:
+from nodekit._internal.types.node import Node
+from nodekit._internal.types.trace import Trace
+from nodekit._internal.types.graph import Graph
+
+# Random
+from nodekit._internal.types.regions import Region
+
+# Namespaced types:
+import nodekit.cards as cards
+import nodekit.assets as assets
+import nodekit.sensors as sensors
+import nodekit.actions as actions
+import nodekit.events as events
+import nodekit.transitions as transitions
+import nodekit.expressions as expressions
+import nodekit.values as values
+
+# Ops:
+from nodekit._internal.ops.play import play
+from nodekit._internal.ops.concat import concat
+from nodekit._internal.ops.save_graph_load_graph import save_graph, load_graph
+from nodekit._internal.ops.open_asset_save_asset import open_asset
+from nodekit._internal.ops.build_site import build_site

nodekit/_internal/ops/build_site/__init__.py

@@ -0,0 +1,117 @@
+from pathlib import Path
+import os
+
+import jinja2
+import pydantic
+
+from nodekit._internal.ops.open_asset_save_asset import save_asset
+from nodekit._internal.types.assets import RelativePath
+from nodekit._internal.types.graph import Graph
+from nodekit._internal.utils.get_browser_bundle import get_browser_bundle
+from nodekit._internal.utils.get_extension_from_media_type import (
+    get_extension_from_media_type,
+)
+from nodekit._internal.utils.hashing import hash_string
+from nodekit._internal.utils.iter_assets import iter_assets
+
+
+# %%
+class BuildSiteResult(pydantic.BaseModel):
+    site_root: Path = pydantic.Field(
+        description="The absolute path to the folder containing the site."
+    )
+    entrypoint: Path = pydantic.Field(
+        description="The path of the index html (relative to the root)."
+    )
+    dependencies: list[Path] = pydantic.Field(
+        description="List of paths to all files needed by the index html, relative to the root."
+    )
+
+
+def build_site(
+    graph: Graph,
+    savedir: os.PathLike | str,
+) -> BuildSiteResult:
+    """
+    Builds a static website for the given Graph, saving all assets and the HTML file to the given directory.
+    Returns a path to the entrypoint HTML file of the site ({graph-id}.html).
+
+    assets/
+        {mime-type-1}/{mime-type-2}/{sha256}.{ext}
+    runtime/
+        nodekit.{js-digest}.js
+        nodekit.{css-digest}.css
+    graphs/
+        {graph_digest}/
+            index.html
+            graph.json
+    """
+    savedir = Path(savedir)
+    if not savedir.exists():
+        savedir.mkdir(parents=True, exist_ok=True)
+
+    if not savedir.is_dir():
+        raise ValueError(f"Savedir must be a directory: {savedir}")
+
+    dependencies = []
+
+    # Ensure the browser runtime is saved to the appropriate location:
+    browser_bundle = get_browser_bundle()
+    css_relative_path = Path("runtime") / f"nodekit.{browser_bundle.css_sha256}.css"
+    js_relative_path = Path("runtime") / f"nodekit.{browser_bundle.js_sha256}.js"
+    css_abs_path = savedir / css_relative_path
+    js_abs_path = savedir / js_relative_path
+    dependencies.append(css_relative_path)
+    dependencies.append(js_relative_path)
+    if not css_abs_path.exists():
+        css_abs_path.parent.mkdir(parents=True, exist_ok=True)
+        css_abs_path.write_text(browser_bundle.css)
+    if not js_abs_path.exists():
+        js_abs_path.parent.mkdir(parents=True, exist_ok=True)
+        js_abs_path.write_text(browser_bundle.js)
+
+    # Ensure all assets saved to the appropriate location:
+    graph = graph.model_copy(deep=True)
+    for asset in iter_assets(graph=graph):
+        asset_relative_path = (
+            Path("assets")
+            / asset.media_type
+            / f"{asset.sha256}.{get_extension_from_media_type(asset.media_type)}"
+        )
+        asset_abs_path = savedir / asset_relative_path
+        dependencies.append(asset_relative_path)
+        if not asset_abs_path.exists():
+            # Copy the asset to the savepath:
+            asset_abs_path.parent.mkdir(parents=True, exist_ok=True)
+            save_asset(
+                asset=asset,
+                path=asset_abs_path,
+            )
+
+        # Mutate the asset locator in the graph to be a RelativePath - relative to the graph!:
+        asset.locator = RelativePath(relative_path=Path("../..") / asset_relative_path)
+
+    # Render the HTML site using the Jinja2 template:
+    jinja2_location = Path(__file__).parent / "harness.j2"
+    jinja2_loader = jinja2.FileSystemLoader(searchpath=jinja2_location.parent)
+    jinja2_env = jinja2.Environment(loader=jinja2_loader)
+    template = jinja2_env.get_template(jinja2_location.name)
+    rendered_html = template.render(
+        graph=graph.model_dump(mode="json"),
+        css_path=Path("../..") / css_relative_path,
+        js_path=Path("../..") / js_relative_path,
+    )
+
+    # Save the graph site:
+    graph_serialized = graph.model_dump_json()
+    graph_digest = hash_string(s=graph_serialized)
+    graph_dir = savedir / "graphs" / graph_digest
+    graph_dir.mkdir(parents=True, exist_ok=True)
+    graph_html_path = graph_dir / "index.html"
+    graph_html_path.write_text(rendered_html)
+
+    return BuildSiteResult(
+        site_root=savedir.resolve(),
+        entrypoint=graph_html_path.relative_to(savedir),
+        dependencies=dependencies,
+    )

nodekit/_internal/ops/build_site/harness.j2

@@ -0,0 +1,158 @@
+<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <title>NodeKit</title>
+    <link rel="shortcut icon" href="">
+
+    <!-- NodeKit -->
+    <script src="{{ js_path }}"></script>
+    <link href="{{ css_path }}" rel="stylesheet">
+
+
+    <script>
+        function tryInferTurkContext() {
+            if (typeof window === "undefined" || !window.location) {
+                return null
+            }
+
+            const params = new URLSearchParams(window.location.search);
+
+            // MTurk-style query params
+            const assignmentId = params.get("assignmentId");
+            const hitId = params.get("hitId");
+            const workerId = params.get("workerId");
+            const turkSubmitTo = params.get("turkSubmitTo");
+
+            const looksLikeMTurk =
+                assignmentId !== null ||
+                hitId !== null ||
+                workerId !== null ||
+                turkSubmitTo !== null;
+
+            if (!looksLikeMTurk) {
+                return null
+            }
+
+            // Preview mode per MTurk docs: assignmentId is present and equals this sentinel.
+            const PREVIEW_SENTINEL = "ASSIGNMENT_ID_NOT_AVAILABLE";
+            const preview_mode = assignmentId === PREVIEW_SENTINEL;
+
+            if (preview_mode) {
+                return {
+                    previewMode: true,
+                    context: null,
+                };
+            }
+
+            // Not previewing → require all fields
+            if (!turkSubmitTo || !hitId || !assignmentId || !workerId) {
+                const e = new Error("Missing required parameters in the query for MTurk platform.");
+                e.name = "BadPlatformContextError";
+                throw e;
+            }
+
+            return {
+                previewMode: false,
+                context: {
+                    assignmentId: assignmentId,
+                    turkSubmitTo: turkSubmitTo,
+                    workerId: workerId,
+                },
+            };
+        }
+    </script>
+    <script>
+        function addPreviewSplash(){
+            if (typeof window === "undefined" || !window.location) {
+                return null
+            }
+            const div = document.createElement('div');
+            div.textContent = 'Preview Mode. Accept the HIT to continue.';
+            Object.assign(div.style, {
+                position: 'fixed',
+                top: '50%',
+                left: '50%',
+                transform: 'translate(-50%, -50%)',
+                padding: '1.5rem 2rem',
+                background: 'white',
+                border: '2px solid #ccc',
+                borderRadius: '8px',
+                fontFamily: 'sans-serif',
+                fontSize: '1.2rem',
+                textAlign: 'center',
+                boxShadow: '0 0 2px rgba(0,0,0,0.2)',
+            });
+            document.body.appendChild(div);
+        }
+    </script>
+
+    <script>
+        function submitToTurk(
+            trace,
+            assignmentId,
+            turkSubmitTo,
+        ){
+            // Submission procedure for Mechanical Turk. See: https://docs.aws.amazon.com/AWSMechTurk/latest/AWSMechanicalTurkRequester/mturk-hits-defining-questions-html-javascript.html
+            // Note the following undocumented gotcha: the form must have at least one input element other than assignmentId, otherwise
+            // Mechanical Turk will not accept the submission. Here, we have the input element `sessionId`, which satisfies this requirement.
+
+            // Get context variables:
+
+            // create the form element and point it to the correct endpoint
+            const form = document.createElement('form')
+            form.action = (new URL('mturk/externalSubmit', turkSubmitTo)).href
+            form.method = 'post'
+
+            // attach the assignmentId
+            const inputAssignmentId = document.createElement('input')
+            inputAssignmentId.name = 'assignmentId'
+            inputAssignmentId.value = assignmentId
+            inputAssignmentId.hidden = true
+            form.appendChild(inputAssignmentId)
+
+            // attach a runId to allow for Experimenters to map HITs to Sessions
+            const inputRunId = document.createElement('input')
+            inputRunId.name = 'trace';
+            inputRunId.value = JSON.stringify(trace);
+            inputRunId.hidden = true;
+            form.appendChild(inputRunId)
+
+            // attach the form to the HTML document and trigger submission
+            document.body.appendChild(form)
+
+            // Submit the form
+            form.submit()
+        }
+    </script>
+
+    <script>
+        const graph = {{ graph | tojson(indent=4) | indent(8, first=False) }};
+
+        window.onload = async () => {
+            // Infer the context:
+            const turkContext = tryInferTurkContext()
+
+            // Guard execution if in preview mode
+            if (turkContext && turkContext.previewMode === true){
+                // Add a simple, centered div in the middle of the page stating: "Preview Mode. Accept the HIT to continue."
+                addPreviewSplash()
+                return
+            }
+
+            // Play the Graph:
+            const trace = await NodeKit.play(graph);
+
+            // Handle close down procedures, based on the inferred context:
+            if(turkContext && turkContext.previewMode === false){
+                submitToTurk(
+                    trace,
+                    turkContext.context.assignmentId,
+                    turkContext.context.turkSubmitTo,
+                )
+            }
+        };
+    </script>
+</head>
+<body></body>
+</html>

nodekit/_internal/ops/concat.py

@@ -0,0 +1,51 @@
+import collections
+from typing import Dict
+
+from nodekit._internal.types.graph import Graph
+from nodekit._internal.types.node import Node
+from nodekit._internal.types.transition import End, Go, Transition
+from nodekit._internal.types.value import NodeId
+
+
+# %%
+def concat(
+    sequence: list[Graph | Node],
+    ids: list[str] | None = None,
+) -> Graph:
+    """
+    Returns a Graph which executes the given sequence of Node | Graph.
+    In the new Graph, the sequence items' RegisterIds and NodeIds are prepended ids '0', '1', ..., unless `ids` is given.
+    """
+
+    if len(sequence) == 0:
+        raise ValueError("Sequence must have at least one item.")
+
+    # Generate new IDs:
+    if ids and len(ids) != len(sequence):
+        raise ValueError("If ids are given, must be the same length as sequence.")
+    if ids is None:
+        ids: list[NodeId] = [f"{i}" for i in range(len(sequence))]
+    if len(set(ids)) != len(ids):
+        counts = collections.Counter(ids)
+        duplicates = [id_ for id_, count in counts.items() if count > 1]
+        raise ValueError(
+            f"If ids are given, they must be unique. Duplicates:\n{'\n'.join(duplicates)}"
+        )
+
+    # Assemble:
+    nodes: Dict[NodeId, Node | Graph] = {}
+    transitions: Dict[NodeId, Transition] = {}
+
+    for i, (node_id, node) in enumerate(zip(ids, sequence)):
+        nodes[node_id] = node
+
+        if i + 1 < len(ids):
+            transitions[node_id] = Go(to=ids[i + 1])
+        else:
+            transitions[node_id] = End()
+
+    return Graph(
+        nodes=nodes,
+        transitions=transitions,
+        start=ids[0],
+    )

nodekit/_internal/ops/open_asset_save_asset.py

@@ -0,0 +1,125 @@
+import contextlib
+import zipfile
+from typing import ContextManager, IO
+
+from nodekit._internal.types.assets import (
+    AssetLocator,
+    URL,
+    RelativePath,
+    ZipArchiveInnerPath,
+    FileSystemPath,
+    Asset,
+)
+import urllib.request
+import urllib.error
+from pathlib import Path
+
+import os
+import shutil
+import tempfile
+
+
+# %%
+def open_asset(
+    asset: Asset,
+) -> ContextManager[IO[bytes]]:
+    """
+    Streams the bytes of the given Asset.
+    """
+
+    locator: AssetLocator = asset.locator
+
+    if isinstance(locator, FileSystemPath):
+        return open(locator.path, "rb")
+    elif isinstance(locator, URL):
+
+        @contextlib.contextmanager
+        def open_url_stream():
+            req = urllib.request.Request(locator.url)
+            try:
+                # Add a timeout to avoid hanging forever:
+                with urllib.request.urlopen(req, timeout=30) as resp:
+                    # Raise on non-2xx if you want stricter behavior:
+                    status = getattr(resp, "status", 200)
+                    if not (200 <= status < 300):
+                        raise urllib.error.HTTPError(
+                            locator.url, status, "Bad HTTP status", resp.headers, None
+                        )
+                    yield resp  # file-like, binary
+            except urllib.error.URLError as e:
+                raise RuntimeError(
+                    f"Failed to stream Asset from URL: {locator.url}"
+                ) from e
+
+        return open_url_stream()
+
+    elif isinstance(locator, ZipArchiveInnerPath):
+
+        @contextlib.contextmanager
+        def open_stream():
+            with zipfile.ZipFile(locator.zip_archive_path, "r") as zf:
+                with zf.open(str(locator.inner_path), "r") as fh:
+                    yield fh
+
+        return open_stream()
+    elif isinstance(locator, RelativePath):
+        # Try to open relative to current working directory:
+        return open(locator.relative_path, "rb")
+    else:
+        raise ValueError(f"Unsupported locator type: {locator.locator_type}")
+
+
+# %%
+def save_asset(
+    asset: Asset,
+    path: Path,
+) -> None:
+    """
+    Persist `asset` bytes to `path` atomically.
+    Raises:
+      - FileExistsError if target exists and `overwrite=False`
+      - ValueError for mismatched extension when `add_extension=True`
+    """
+    buffer_size: int = 1024 * 1024  # 1MB buffer for streaming copy
+
+    # --- ensure parent exists ---
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    # --- exists check ---
+    if path.exists():
+        raise FileExistsError(f"Refusing to overwrite existing file: {path}")
+
+    # Fast path: hardlink local file if possible
+    loc = asset.locator
+    if isinstance(loc, FileSystemPath):
+        src = Path(loc.path)
+        try:
+            # Hardlink avoids IO; falls back to copy path if cross-device
+            os.link(src, path)
+        except OSError:
+            # Cross-device or FS limitation: fall through to streamed copy
+            pass
+        return
+
+    # Slow path: stream
+    tmp_file_descriptor, tmp_path_str = tempfile.mkstemp(
+        prefix=path.name + ".", dir=path.parent
+    )
+    tmp_path = Path(tmp_path_str)
+    try:
+        with os.fdopen(tmp_file_descriptor, "wb", closefd=True) as out_f:
+            # Stream from source to temp file
+            with open_asset(asset) as in_f:
+                shutil.copyfileobj(in_f, out_f, length=buffer_size)
+            out_f.flush()
+            os.fsync(out_f.fileno())
+
+        # Atomic move into place (overwrites if exists)
+        os.replace(tmp_path, path)
+    finally:
+        # If something failed before replace, cleanup temp
+        if tmp_path.exists():
+            try:
+                tmp_path.unlink()
+            except OSError:
+                pass

nodekit/_internal/ops/play/__init__.py

@@ -0,0 +1,4 @@
+__all__ = [
+    "play",
+]
+from nodekit._internal.ops.play.local_runner.main import play