nodekit 0.2.0__py3-none-any.whl

nodekit/_internal/types/sensors/sensors.py

@@ -0,0 +1,156 @@
+from abc import ABC
+from typing import Literal, Annotated, Union, Self, Dict
+
+import pydantic
+
+from nodekit._internal.types.cards import Card
+from nodekit._internal.types.value import (
+    PressableKey,
+    SpatialSize,
+    TimeDurationMsec,
+)
+from nodekit._internal.types.regions import Region
+
+
+# %%
+class BaseSensor(pydantic.BaseModel, ABC):
+    """
+    A Sensor is a listener for Participant behavior.
+    When a Sensor is triggered, it emits an Action and optionally applies an Outcome.
+    """
+
+    sensor_type: str
+
+
+# %%
+class WaitSensor(BaseSensor):
+    """
+    A Sensor that triggers when the specified time has elapsed since the start of the Node.
+    """
+
+    sensor_type: Literal["WaitSensor"] = "WaitSensor"
+    duration_msec: TimeDurationMsec = pydantic.Field(
+        description="The number of milliseconds from the start of the Node when the Sensor triggers.",
+        gt=0,
+    )
+
+
+# %%
+class ClickSensor(BaseSensor):
+    sensor_type: Literal["ClickSensor"] = "ClickSensor"
+    region: Region
+
+
+# %%
+class KeySensor(BaseSensor):
+    sensor_type: Literal["KeySensor"] = "KeySensor"
+    keys: list[PressableKey] = pydantic.Field(
+        description="The keys that triggers the Sensor when pressed down."
+    )
+
+
+# %%
+class SelectSensor(BaseSensor):
+    sensor_type: Literal["SelectSensor"] = "SelectSensor"
+    choices: Dict[str, Card]
+
+
+# %%
+class MultiSelectSensor(BaseSensor):
+    sensor_type: Literal["MultiSelectSensor"] = "MultiSelectSensor"
+    choices: Dict[str, Card]
+
+    min_selections: int = pydantic.Field(
+        ge=0,
+        description="The minimum number of Cards before the Sensor fires.",
+    )
+
+    max_selections: int | None = pydantic.Field(
+        default=None,
+        validate_default=True,
+        ge=0,
+        description="If None, the selection can contain up to the number of available Cards.",
+    )
+
+    confirm_button: Card
+
+    @pydantic.model_validator(mode="after")
+    def validate_selections_vals(self) -> Self:
+        if (
+            self.max_selections is not None
+            and self.max_selections < self.min_selections
+        ):
+            raise pydantic.ValidationError(
+                f"max_selections ({self.max_selections}) must be greater than min_selections ({self.min_selections})",
+            )
+        return self
+
+
+# %%
+class SliderSensor(BaseSensor):
+    sensor_type: Literal["SliderSensor"] = "SliderSensor"
+    num_bins: int = pydantic.Field(gt=1)
+    initial_bin_index: int
+    show_bin_markers: bool = True
+    orientation: Literal["horizontal", "vertical"] = "horizontal"
+    region: Region
+
+
+# %%
+class TextEntrySensor(BaseSensor):
+    sensor_type: Literal["TextEntrySensor"] = "TextEntrySensor"
+
+    prompt: str = pydantic.Field(
+        description="The initial placeholder text shown in the free text response box. It disappears when the user selects the element.",
+        default="",
+    )
+
+    font_size: SpatialSize = pydantic.Field(
+        description="The height of the em-box, in Board units.",
+        default=0.02,
+    )
+
+    min_length: int = pydantic.Field(
+        description="The minimum number of characters the user must enter before the Sensor fires. If None, no limit.",
+        default=1,
+        ge=1,
+        le=10000,
+    )
+
+    max_length: int | None = pydantic.Field(
+        description="The maximum number of characters the user can enter. If None, no limit.",
+        default=None,
+        ge=1,
+        le=10000,
+    )
+
+    region: Region
+
+
+# %%
+class ProductSensor(BaseSensor):
+    sensor_type: Literal["ProductSensor"] = "ProductSensor"
+    children: Dict[str, "Sensor"]
+
+
+# %%
+class SumSensor(BaseSensor):
+    sensor_type: Literal["SumSensor"] = "SumSensor"
+    children: Dict[str, "Sensor"]
+
+
+# %%
+type Sensor = Annotated[
+    Union[
+        WaitSensor,
+        ClickSensor,
+        KeySensor,
+        SelectSensor,
+        MultiSelectSensor,
+        SliderSensor,
+        TextEntrySensor,
+        ProductSensor,
+        SumSensor,
+    ],
+    pydantic.Field(discriminator="sensor_type"),
+]

nodekit/_internal/types/trace.py

@@ -0,0 +1,17 @@
+from typing import Literal
+
+import pydantic
+
+from nodekit import VERSION
+from nodekit._internal.types.events.events import Event
+
+
+class Trace(pydantic.BaseModel):
+    nodekit_version: Literal["0.2.0"] = pydantic.Field(
+        default=VERSION, validate_default=True
+    )
+    events: list[Event]
+
+    @pydantic.field_validator("events")
+    def order_events(cls, events: list[Event]) -> list[Event]:
+        return sorted(events, key=lambda e: e.t)

nodekit/_internal/types/transition.py

@@ -0,0 +1,68 @@
+from typing import Dict, Literal, Annotated
+
+import pydantic
+
+from nodekit._internal.types.expressions.expressions import Expression
+from nodekit._internal.types.value import NodeId, RegisterId, LeafValue
+
+
+# %%
+class BaseTransition(pydantic.BaseModel):
+    transition_type: str
+
+
+class Go(BaseTransition):
+    transition_type: Literal["Go"] = "Go"
+    to: NodeId
+    register_updates: Dict[RegisterId, Expression] = pydantic.Field(
+        default_factory=dict,
+    )
+
+
+class End(BaseTransition):
+    transition_type: Literal["End"] = "End"
+
+
+type LeafTransition = Go | End
+
+
+# %%
+class IfThenElse(BaseTransition):
+    model_config = pydantic.ConfigDict(
+        serialize_by_alias=True,
+        validate_by_alias=False,
+        populate_by_name=True,
+    )  # See https://docs.pydantic.dev/latest/api/config/#pydantic.config.ConfigDict.validate_by_name
+
+    transition_type: Literal["IfThenElse"] = "IfThenElse"
+
+    # Using Annotated to maintain type hints (https://docs.pydantic.dev/latest/concepts/fields/?query=populate_by_name#field-aliases)
+    if_: Annotated[
+        Expression,
+        pydantic.Field(
+            serialization_alias="if",
+            validation_alias="if",
+            description="A boolean-valued Expression.",
+        ),
+    ]
+    then: LeafTransition
+    else_: Annotated[
+        LeafTransition,
+        pydantic.Field(default_factory=End, validate_default=True, alias="else"),
+    ]
+
+
+# %%
+class Switch(BaseTransition):
+    transition_type: Literal["Switch"] = "Switch"
+    on: Expression
+    cases: Dict[LeafValue, LeafTransition]
+    default: LeafTransition = pydantic.Field(
+        default_factory=End,
+        description="The transition to take if no case matches.",
+        validate_default=True,
+    )
+
+
+# %%
+type Transition = Go | End | Switch | IfThenElse

nodekit/_internal/types/value.py

@@ -0,0 +1,145 @@
+from typing import Literal, Annotated
+
+import pydantic
+
+# %% Base Values
+type Boolean = bool
+type Integer = int
+type Float = float
+type String = str
+
+# Containers
+type List = list["Value"]
+type Dict = dict[str, "Value"]
+# Full Value
+type LeafValue = Boolean | Integer | Float | String
+type Value = LeafValue | List | Dict
+
+
+# %% Spatial
+type SpatialSize = Annotated[
+    Float,
+    pydantic.Field(
+        strict=True,
+        ge=0,
+        le=1,
+        description="A spatial size relative to the smaller extent of the board (width or height, whichever is smaller). For example, a value of 0.5 corresponds to half the smaller extent of the board.",
+    ),
+]
+
+type SpatialPoint = Annotated[Float, pydantic.Field(strict=True, ge=-0.5, le=0.5)]
+
+type Mask = Annotated[
+    Literal["ellipse", "rectangle"],
+    pydantic.Field(
+        description='Describes the shape of a region inside of a bounding box. "rectangle" uses the box itself; "ellipse" inscribes a tightly fitted ellipse within the box.'
+    ),
+]
+
+# %% Time
+type TimeElapsedMsec = Annotated[
+    Integer,
+    pydantic.Field(
+        strict=True,
+        description="A time point, relative to some origin.",
+    ),
+]
+
+type TimeDurationMsec = Annotated[
+    Integer,
+    pydantic.Field(
+        strict=True,
+        ge=0,
+        description="A duration of time in milliseconds, relative to the start of the Trace.",
+    ),
+]
+# %% Text
+type MarkdownString = Annotated[
+    str, pydantic.Field(strict=True, description="Markdown-formatted string")
+]
+
+
+def _normalize_hex_code(value: str) -> str:
+    if len(value) == 7:
+        # If the hex code is in the format #RRGGBB, append 'FF' for full opacity
+        value += "FF"
+    return value.lower()  # Lowercase
+
+
+type ColorHexString = Annotated[
+    String,
+    pydantic.BeforeValidator(_normalize_hex_code),
+    pydantic.Field(
+        pattern=r"^#[0-9a-fA-F]{8}$",  # "#RRGGBBAA"
+        min_length=9,
+        max_length=9,
+    ),
+]
+
+# %% Keyboard
+PressableKey = Literal[
+    "Enter",
+    " ",
+    "ArrowDown",
+    "ArrowLeft",
+    "ArrowRight",
+    "ArrowUp",
+    "a",
+    "b",
+    "c",
+    "d",
+    "e",
+    "f",
+    "g",
+    "h",
+    "i",
+    "j",
+    "k",
+    "l",
+    "m",
+    "n",
+    "o",
+    "p",
+    "q",
+    "r",
+    "s",
+    "t",
+    "u",
+    "v",
+    "w",
+    "x",
+    "y",
+    "z",
+    "0",
+    "1",
+    "2",
+    "3",
+    "4",
+    "5",
+    "6",
+    "7",
+    "8",
+    "9",
+]
+
+# %% Assets
+type SHA256 = Annotated[String, pydantic.Field(pattern=r"^[a-f0-9]{64}$")]
+"""A hex string representing a SHA-256 hash.
+"""
+
+type ImageMediaType = Literal["image/png", "image/svg+xml"]
+type VideoMediaType = Literal["video/mp4"]
+type MediaType = ImageMediaType | VideoMediaType
+
+
+# %% Identifiers
+type NodeId = Annotated[
+    String,
+    pydantic.Field(
+        description="An identifier for a Node which is unique within a Graph.",
+    ),
+]
+
+type RegisterId = Annotated[
+    String, pydantic.Field(description="An identifier for a Graph register.")
+]

nodekit/_internal/utils/get_browser_bundle.py

@@ -0,0 +1,35 @@
+import importlib.resources
+from functools import lru_cache
+
+import pydantic
+from nodekit._internal.utils.hashing import hash_string
+from nodekit._internal.types.value import SHA256
+
+
+# %%
+class NodeKitBrowserBundle(pydantic.BaseModel):
+    css: str
+    css_sha256: SHA256
+
+    js: str
+    js_sha256: SHA256
+
+
+@lru_cache(maxsize=1)
+def get_browser_bundle() -> NodeKitBrowserBundle:
+    css_file = importlib.resources.files("nodekit") / "_static" / "nodekit.css"
+    js_file = importlib.resources.files("nodekit") / "_static" / "nodekit.js"
+
+    css_string = css_file.read_text()
+    js_string = js_file.read_text()
+
+    # Compute hashes:
+    css_sha256 = hash_string(css_string)
+    js_sha256 = hash_string(js_string)
+
+    return NodeKitBrowserBundle(
+        css=css_string,
+        css_sha256=css_sha256,
+        js=js_string,
+        js_sha256=js_sha256,
+    )

nodekit/_internal/utils/get_extension_from_media_type.py

@@ -0,0 +1,15 @@
+from nodekit._internal.types.value import MediaType
+
+
+def get_extension_from_media_type(media_type: MediaType) -> str:
+    """
+    Returns the file extension, without the leading dot, for a given media (MIME) type.
+    """
+    mime_to_extension = {
+        "image/png": "png",
+        "image/svg+xml": "svg",
+        "video/mp4": "mp4",
+    }
+    if media_type not in mime_to_extension:
+        raise ValueError(f"Unsupported media type: {media_type}")
+    return mime_to_extension[media_type]

nodekit/_internal/utils/hashing.py

@@ -0,0 +1,46 @@
+from nodekit._internal.types.value import SHA256
+import pydantic
+from pathlib import Path
+from typing import BinaryIO
+import hashlib
+
+
+def hash_file(path: Path) -> SHA256:
+    """
+    Compute the SHA-256 hash of a file at the given path.
+    """
+    with path.open("rb") as f:
+        return hash_byte_stream(f)
+
+
+def hash_byte_stream(byte_stream: BinaryIO) -> SHA256:
+    """
+    Compute the SHA-256 hash of a byte stream.
+    """
+
+    # Reset stream to the beginning
+    initial_position = byte_stream.tell()
+    byte_stream.seek(0)
+    h = hashlib.sha256()
+    for chunk in iter(lambda: byte_stream.read(1024 * 1024), b""):  # 1 MB chunks
+        h.update(chunk)
+    byte_stream.seek(initial_position)  # Reset stream to the beginning again
+
+    sha256_hexdigest = h.hexdigest()
+    type_adapter = pydantic.TypeAdapter(SHA256)
+    validated_sha256 = type_adapter.validate_python(sha256_hexdigest)
+
+    return validated_sha256
+
+
+def hash_string(s: str) -> SHA256:
+    """
+    Compute the SHA-256 hash of a string.
+    """
+    h = hashlib.sha256()
+    h.update(s.encode("utf-8"))
+    sha256_hexdigest = h.hexdigest()
+    type_adapter = pydantic.TypeAdapter(SHA256)
+    validated_sha256 = type_adapter.validate_python(sha256_hexdigest)
+
+    return validated_sha256

nodekit/_internal/utils/iter_assets.py

@@ -0,0 +1,61 @@
+from typing import Iterator, Iterable
+
+from nodekit._internal.types.assets import Image, Video
+from nodekit._internal.types.cards import Card, ImageCard, VideoCard, CompositeCard
+from nodekit._internal.types.graph import Graph
+from nodekit._internal.types.node import Node
+from nodekit._internal.types.sensors.sensors import (
+    SelectSensor,
+    MultiSelectSensor,
+    ProductSensor,
+    SumSensor,
+    Sensor,
+)
+
+
+# %%
+def iter_assets(graph: Graph) -> Iterator[Image | Video]:
+    """
+    Iterates over all assets found in the graph (cards and sensor-attached cards).
+    """
+    for node in graph.nodes.values():
+        if isinstance(node, Graph):
+            yield from iter_assets(node)
+            continue
+        elif isinstance(node, Node):
+            if node.stimulus is not None:
+                yield from _iter_card_assets(node.stimulus)
+
+            # Some sensors carry cards (select/multiselect choices, products/sums).
+
+            yield from _iter_sensor_cards(node.sensor)
+        else:
+            raise TypeError(f"Unexpected graph node type: {type(node)}")
+
+
+def _iter_card_assets(card: Card) -> Iterable[Image | Video]:
+    if isinstance(card, ImageCard):
+        yield card.image
+    elif isinstance(card, VideoCard):
+        yield card.video
+    elif isinstance(card, CompositeCard):
+        for child in card.children.values():
+            yield from _iter_card_assets(child)
+
+
+def _iter_sensor_cards(sensor: Sensor) -> Iterable[Image | Video]:
+    """
+    Helper to walk sensor trees for cards (select/multiselect/product/sum).
+    """
+    if isinstance(sensor, SelectSensor):
+        for choice_card in sensor.choices.values():
+            yield from _iter_card_assets(choice_card)
+    elif isinstance(sensor, MultiSelectSensor):
+        for choice_card in sensor.choices.values():
+            yield from _iter_card_assets(choice_card)
+    elif isinstance(sensor, ProductSensor):
+        for child in sensor.children.values():
+            yield from _iter_sensor_cards(child)
+    elif isinstance(sensor, SumSensor):
+        for child in sensor.children.values():
+            yield from _iter_sensor_cards(child)

nodekit/_internal/version.py

@@ -0,0 +1 @@
+VERSION = "0.2.0"