nodekit 0.2.0__py3-none-any.whl

nodekit/_internal/types/assets/__init__.py

@@ -0,0 +1,151 @@
+import enum
+import mimetypes
+from abc import ABC
+from pathlib import Path
+from typing import Literal, Annotated, Union, Self, cast
+
+import pydantic
+
+from nodekit._internal.utils.hashing import (
+    hash_file,
+)
+from nodekit._internal.types.value import (
+    SHA256,
+    MediaType,
+    ImageMediaType,
+    VideoMediaType,
+)
+
+
+# %%
+class LocatorTypeEnum(str, enum.Enum):
+    FileSystemPath = "FileSystemPath"
+    ZipArchiveInnerPath = "ZipArchiveInnerPath"
+    RelativePath = "RelativePath"
+    URL = "URL"
+
+
+class BaseLocator(pydantic.BaseModel, ABC):
+    locator_type: LocatorTypeEnum
+
+
+class FileSystemPath(BaseLocator):
+    """
+    A locator which points to an absolute filepath on the viewer's local file system.
+    """
+
+    locator_type: Literal[LocatorTypeEnum.FileSystemPath] = (
+        LocatorTypeEnum.FileSystemPath
+    )
+    path: pydantic.FilePath = pydantic.Field(
+        description="The absolute path to the asset file in the local filesystem."
+    )
+
+    @pydantic.field_validator("path", mode="after")
+    def ensure_path_absolute(cls, path: Path) -> Path:
+        return path.resolve()
+
+
+class ZipArchiveInnerPath(BaseLocator):
+    locator_type: Literal[LocatorTypeEnum.ZipArchiveInnerPath] = (
+        LocatorTypeEnum.ZipArchiveInnerPath
+    )
+    zip_archive_path: pydantic.FilePath = pydantic.Field(
+        description="The path to the zip archive file on the local filesystem"
+    )
+    inner_path: Path = pydantic.Field(
+        description="The internal path within the zip archive to the asset file."
+    )
+
+    @pydantic.field_validator("zip_archive_path", mode="after")
+    def ensure_zip_path_absolute(cls, path: Path) -> Path:
+        return path.resolve()
+
+
+class RelativePath(BaseLocator):
+    """
+    A locator which points to a relative path on the viewer's local file system.
+    This is useful for assets that are bundled alongside a graph file, e.g., in a zip archive.
+    The viewer must resolve the relative path against a known base path.
+    """
+
+    locator_type: Literal[LocatorTypeEnum.RelativePath] = LocatorTypeEnum.RelativePath
+    relative_path: Path = pydantic.Field(
+        description="The relative path to the asset file in the local filesystem."
+    )
+
+    @pydantic.field_validator("relative_path", mode="after")
+    def ensure_path_not_absolute(cls, path: Path) -> Path:
+        if path.is_absolute():
+            raise ValueError("RelativePath must be a relative path, got absolute path.")
+        return path
+
+
+class URL(BaseLocator):
+    locator_type: Literal[LocatorTypeEnum.URL] = LocatorTypeEnum.URL
+    url: str = pydantic.Field(
+        description="The URL to the asset file. May be a relative or absolute URL."
+    )
+
+
+type AssetLocator = Annotated[
+    Union[FileSystemPath, ZipArchiveInnerPath, RelativePath, URL],
+    pydantic.Field(discriminator="locator_type"),
+]
+
+
+# %%
+class BaseAsset(pydantic.BaseModel):
+    """
+    An Asset is:
+    - An identifier for an asset file (its SHA-256 hash and media type)
+    - A locator of bytes that are claimed to hash to the identifier.
+    """
+
+    sha256: SHA256 = pydantic.Field(
+        description="The SHA-256 hash of the asset file, as a hex string."
+    )
+    media_type: MediaType = pydantic.Field(
+        description="The IANA media (MIME) type of the asset."
+    )
+    locator: AssetLocator = pydantic.Field(
+        description="A location which is a claimed source of valid bytes for this Asset.",
+    )
+
+    @classmethod
+    def from_path(cls, path: Path | str) -> Self:
+        """
+        A public convenience method to create an Asset from a file path on the user's local file system.
+        This is I/O bound, as it computes the SHA-256 hash of the file.
+        """
+        path = Path(path)
+        sha256 = hash_file(path)
+        guessed_media_type, _ = mimetypes.guess_type(path, strict=True)
+        if not guessed_media_type:
+            raise ValueError(
+                f"Could not determine MIME type for file at {path}\n Does it have a valid file extension?"
+            )
+
+        return cls(
+            sha256=sha256,
+            media_type=cast(MediaType, guessed_media_type),
+            locator=FileSystemPath(path=path),
+        )
+
+
+class Image(BaseAsset):
+    media_type: ImageMediaType = pydantic.Field(
+        description="The IANA media (MIME) type of the image file."
+    )
+
+
+class Video(BaseAsset):
+    media_type: VideoMediaType = pydantic.Field(
+        description="The IANA media (MIME) type of the video file."
+    )
+
+
+type Asset = Annotated[
+    Union[Image, Video],
+    pydantic.Field(discriminator="media_type"),
+]

nodekit/_internal/types/cards/__init__.py

@@ -0,0 +1,85 @@
+from abc import ABC
+from typing import Literal, Annotated, Union, Dict
+
+import pydantic
+
+from nodekit._internal.types.assets import Image, Video
+from nodekit._internal.types.value import (
+    ColorHexString,
+    MarkdownString,
+    SpatialSize,
+)
+from nodekit._internal.types.regions import Region
+
+
+# %%
+class BaseCard(pydantic.BaseModel, ABC):
+    """
+    Cards are visual elements which are placed on the Board.
+    They are defined by their type, position, size, and the time range during which they are visible.
+    """
+
+    # Identifiers
+    card_type: str
+
+
+# %%
+class BaseLeafCard(BaseCard):
+    region: Region = pydantic.Field(
+        description="The Board region where the card is rendered.",
+        default=Region(x=0, y=0, w=0.5, h=0.5),
+    )
+
+
+# %%
+class ImageCard(BaseLeafCard):
+    card_type: Literal["ImageCard"] = "ImageCard"
+    image: Image
+
+
+# %%
+class VideoCard(BaseLeafCard):
+    """Video stimulus placed on the Board.
+
+    Attributes:
+        video: The video asset to render.
+        loop: Whether to loop the video when it ends.
+        region: The Board region where the video is rendered.
+    """
+
+    card_type: Literal["VideoCard"] = "VideoCard"
+    video: Video
+    loop: bool = pydantic.Field(
+        description="Whether to loop the video when it ends.", default=False
+    )
+
+
+# %%
+class TextCard(BaseLeafCard):
+    card_type: Literal["TextCard"] = "TextCard"
+    text: MarkdownString
+    font_size: SpatialSize = pydantic.Field(
+        default=0.02, description="The height of the em-box, in Board units."
+    )
+    justification_horizontal: Literal["left", "center", "right"] = "center"
+    justification_vertical: Literal["top", "center", "bottom"] = "center"
+    text_color: ColorHexString = pydantic.Field(
+        default="#000000", validate_default=True
+    )
+    background_color: ColorHexString = pydantic.Field(
+        default="#E6E6E600",  # Transparent by default
+        description="The background color of the TextCard in hexadecimal format.",
+    )
+
+
+# %%
+class CompositeCard(BaseCard):
+    card_type: Literal["CompositeCard"] = "CompositeCard"
+    children: Dict[str, "Card"]
+
+
+# %%
+type Card = Annotated[
+    Union[ImageCard, VideoCard, TextCard, CompositeCard],
+    pydantic.Field(discriminator="card_type"),
+]

nodekit/_internal/types/events/events.py

@@ -0,0 +1,145 @@
+# %%
+import enum
+from typing import Literal, Annotated, Union
+
+import pydantic
+
+from nodekit._internal.types.value import (
+    TimeElapsedMsec,
+    NodeId,
+    SpatialPoint,
+)
+from nodekit._internal.types.actions.actions import Action
+
+
+# %%
+class EventTypeEnum(str, enum.Enum):
+    TraceStartedEvent = "TraceStartedEvent"
+    TraceEndedEvent = "TraceEndedEvent"
+
+    NodeStartedEvent = "NodeStartedEvent"
+    ActionTakenEvent = "ActionTakenEvent"
+    NodeEndedEvent = "NodeEndedEvent"
+
+    PointerSampledEvent = "PointerSampledEvent"
+    KeySampledEvent = "KeySampledEvent"
+
+    BrowserContextSampledEvent = "BrowserContextSampledEvent"
+    PageSuspendedEvent = "PageSuspendedEvent"
+    PageResumedEvent = "PageResumedEvent"
+
+
+# %%
+class BaseEvent(pydantic.BaseModel):
+    event_type: EventTypeEnum
+    t: TimeElapsedMsec = pydantic.Field(
+        description="The number of elapsed milliseconds since StartedEvent."
+    )
+
+
+# %% System events
+class TraceStartedEvent(BaseEvent):
+    event_type: Literal[EventTypeEnum.TraceStartedEvent] = (
+        EventTypeEnum.TraceStartedEvent
+    )
+
+
+class TraceEndedEvent(BaseEvent):
+    event_type: Literal[EventTypeEnum.TraceEndedEvent] = EventTypeEnum.TraceEndedEvent
+
+
+class PageSuspendedEvent(BaseEvent):
+    """
+    Emitted when a Participant suspends the page (e.g., closes the tab or navigates away).
+    """
+
+    event_type: Literal[EventTypeEnum.PageSuspendedEvent] = (
+        EventTypeEnum.PageSuspendedEvent
+    )
+
+
+class PageResumedEvent(BaseEvent):
+    """
+    Emitted when a Participant returns to the page (e.g., reopens the tab or navigates back).
+    """
+
+    event_type: Literal[EventTypeEnum.PageResumedEvent] = EventTypeEnum.PageResumedEvent
+
+
+class RegionSizePx(pydantic.BaseModel):
+    width_px: int
+    height_px: int
+
+
+class BrowserContextSampledEvent(BaseEvent):
+    event_type: Literal[EventTypeEnum.BrowserContextSampledEvent] = (
+        EventTypeEnum.BrowserContextSampledEvent
+    )
+    user_agent: str = pydantic.Field(
+        description="The user agent string of the browser."
+    )
+    timestamp_client: str = pydantic.Field(
+        description="The ISO8601-formatted timestamp that the Participant's browser disclosed at the time of this event."
+    )
+    device_pixel_ratio: float = pydantic.Field(
+        description="The ratio between physical pixels and logical CSS pixels on the device."
+    )
+    display: RegionSizePx = pydantic.Field(
+        description="The size of the Participant's display in physical pixels."
+    )
+    viewport: RegionSizePx
+
+
+# %%
+class PointerSampledEvent(BaseEvent):
+    event_type: Literal[EventTypeEnum.PointerSampledEvent] = (
+        EventTypeEnum.PointerSampledEvent
+    )
+    x: SpatialPoint
+    y: SpatialPoint
+    kind: Literal["move", "down", "up"]
+
+
+class KeySampledEvent(BaseEvent):
+    event_type: Literal[EventTypeEnum.KeySampledEvent] = EventTypeEnum.KeySampledEvent
+    key: str
+    kind: Literal["down", "up"]
+
+
+# %%
+class BaseNodeEvent(BaseEvent):
+    node_id: NodeId
+
+
+class NodeStartedEvent(BaseNodeEvent):
+    event_type: Literal[EventTypeEnum.NodeStartedEvent] = EventTypeEnum.NodeStartedEvent
+
+
+class ActionTakenEvent(BaseNodeEvent):
+    event_type: Literal[EventTypeEnum.ActionTakenEvent] = EventTypeEnum.ActionTakenEvent
+    action: Action
+
+
+class NodeEndedEvent(BaseNodeEvent):
+    event_type: Literal[EventTypeEnum.NodeEndedEvent] = EventTypeEnum.NodeEndedEvent
+
+
+# %%
+type Event = Annotated[
+    Union[
+        # System events flow:
+        TraceStartedEvent,
+        TraceEndedEvent,
+        PageSuspendedEvent,
+        PageResumedEvent,
+        BrowserContextSampledEvent,
+        # Node events:
+        NodeStartedEvent,
+        ActionTakenEvent,
+        NodeEndedEvent,
+        # Agent inputs:
+        PointerSampledEvent,
+        KeySampledEvent,
+    ],
+    pydantic.Field(discriminator="event_type"),
+]

nodekit/_internal/types/expressions/expressions.py

@@ -0,0 +1,242 @@
+from abc import ABC
+from typing import Annotated, Literal, Optional
+
+import pydantic
+
+from nodekit._internal.types.value import Value, RegisterId
+
+# %% Expression
+type LocalVariableName = str
+
+
+class BaseExpression(pydantic.BaseModel, ABC):
+    op: str
+
+
+class Reg(BaseExpression):
+    op: Literal["reg"] = "reg"
+    id: RegisterId
+
+
+class Local(BaseExpression):
+    op: Literal["local"] = "local"
+    name: LocalVariableName
+
+
+class LastAction(BaseExpression):
+    """
+    Evaluates to the last completed Node's Action.
+    """
+
+    op: Literal["la"] = "la"
+
+
+class GetListItem(BaseExpression):
+    """
+    Get an element from a container (Array or Struct).
+    `container` must evaluate to an array- or struct-valued result.
+    """
+
+    op: Literal["gli"] = "gli"
+    list: "Expression"
+    index: "Expression"
+
+
+class GetDictValue(BaseExpression):
+    """
+    Get a value from a dictionary by key.
+    `dict` must evaluate to a dict-valued result.
+    """
+
+    op: Literal["gdv"] = "gdv"
+    d: "Expression" = pydantic.Field(description="Evaluates to a Dict.")
+    key: "Expression"
+
+
+class Lit(BaseExpression):
+    """
+    Literal value.
+    """
+
+    op: Literal["lit"] = "lit"
+    value: Value
+
+
+# %% Conditional
+class If(BaseExpression):
+    op: Literal["if"] = "if"
+    cond: "Expression"
+    then: "Expression"
+    otherwise: "Expression"
+
+
+# %% Boolean logic
+class Not(BaseExpression):
+    op: Literal["not"] = "not"
+    operand: "Expression"
+
+
+class Or(BaseExpression):
+    op: Literal["or"] = "or"
+    # variadic
+    args: list["Expression"]
+
+
+class And(BaseExpression):
+    op: Literal["and"] = "and"
+    # variadic
+    args: list["Expression"]
+
+
+# %% Binary comparators
+class BaseCmp(BaseExpression, ABC):
+    lhs: "Expression"
+    rhs: "Expression"
+
+
+class Eq(BaseCmp):
+    op: Literal["eq"] = "eq"
+
+
+class Ne(BaseCmp):
+    op: Literal["ne"] = "ne"
+
+
+class Gt(BaseCmp):
+    op: Literal["gt"] = "gt"
+
+
+class Ge(BaseCmp):
+    op: Literal["ge"] = "ge"
+
+
+class Lt(BaseCmp):
+    op: Literal["lt"] = "lt"
+
+
+class Le(BaseCmp):
+    op: Literal["le"] = "le"
+
+
+# %% Arithmetic
+class BaseArithmeticOperation(BaseExpression, ABC):
+    lhs: "Expression"
+    rhs: "Expression"
+
+
+class Add(BaseArithmeticOperation):
+    op: Literal["add"] = "add"
+
+
+class Sub(BaseArithmeticOperation):
+    op: Literal["sub"] = "sub"
+
+
+class Mul(BaseArithmeticOperation):
+    op: Literal["mul"] = "mul"
+
+
+class Div(BaseArithmeticOperation):
+    op: Literal["div"] = "div"
+
+
+# %% Array operations
+class ListOp(BaseExpression, ABC):
+    # Expression must be array-valued at runtime
+    array: "Expression"
+
+
+class Slice(ListOp):
+    op: Literal["slice"] = "slice"
+    start: "Expression"
+    end: Optional["Expression"] = None
+
+
+class Map(ListOp):
+    op: Literal["map"] = "map"
+    # The variable name of the current array element.
+    cur: LocalVariableName
+    # Expression that will be applied to each element of the array.
+    func: "Expression"
+
+
+class Filter(ListOp):
+    op: Literal["filter"] = "filter"
+    # The variable name of the current array element.
+    cur: LocalVariableName
+    # Expression that will be applied to each element of the array
+    # and interpreted as a predicate.
+    predicate: "Expression"
+
+
+class Fold(ListOp):
+    op: Literal["fold"] = "fold"
+    init: "Expression"
+    # The ID of the current cumulant.
+    acc: LocalVariableName
+    # The variable name of the current array element.
+    cur: LocalVariableName
+    func: "Expression"
+
+
+# =====================
+# Discriminated union
+# =====================
+
+type Expression = Annotated[
+    Reg
+    | Local
+    | LastAction
+    | GetListItem
+    | GetDictValue
+    | Lit
+    | If
+    | Not
+    | Or
+    | And
+    | Eq
+    | Ne
+    | Gt
+    | Ge
+    | Lt
+    | Le
+    | Add
+    | Sub
+    | Mul
+    | Div
+    | Slice
+    | Map
+    | Filter
+    | Fold,
+    pydantic.Field(discriminator="op"),
+]
+
+
+# Ensure forward refs are resolved (Pydantic v2)
+for _model in (
+    Reg,
+    Local,
+    LastAction,
+    GetListItem,
+    GetDictValue,
+    Lit,
+    If,
+    Not,
+    Or,
+    And,
+    Eq,
+    Ne,
+    Gt,
+    Ge,
+    Lt,
+    Le,
+    Add,
+    Sub,
+    Mul,
+    Div,
+    Slice,
+    Map,
+    Filter,
+    Fold,
+):
+    _model.model_rebuild()

nodekit/_internal/types/graph.py

@@ -0,0 +1,42 @@
+from typing import Dict, Literal, Self, Union
+
+import pydantic
+
+from nodekit import VERSION, Node
+from nodekit._internal.types.transition import Transition
+from nodekit._internal.types.value import NodeId, RegisterId, Value
+
+
+# %%
+class Graph(pydantic.BaseModel):
+    type: Literal["Graph"] = "Graph"
+    nodekit_version: Literal["0.2.0"] = pydantic.Field(
+        default=VERSION, validate_default=True
+    )
+    nodes: Dict[NodeId, Union[Node, "Graph"]]
+    transitions: Dict[NodeId, Transition]
+    start: NodeId
+    registers: Dict[RegisterId, Value] = pydantic.Field(default_factory=dict)
+
+    @pydantic.model_validator(mode="after")
+    def check_graph_is_valid(
+        self,
+    ) -> Self:
+        if self.start not in self.nodes:
+            raise ValueError(f"Graph start node {self.start} not in nodes.")
+
+        num_nodes = len(self.nodes)
+        if num_nodes == 0:
+            raise ValueError("Graph must have at least one node.")
+
+        # Check the start Node exists:
+        if self.start not in self.nodes:
+            raise ValueError(f"Start Node {self.start} does not exist in nodes.")
+
+        # Todo: Each Node must be reachable from the start Node (i.e., no disconnected components)
+
+        # Todo: Each Go transition must point to an existing Node
+
+        # Todo: check each Nodes has a path to an End transition
+
+        return self

nodekit/_internal/types/node.py

@@ -0,0 +1,21 @@
+from typing import Literal
+
+import pydantic
+
+from nodekit._internal.types.cards import Card
+from nodekit._internal.types.sensors.sensors import Sensor
+from nodekit._internal.types.value import ColorHexString
+
+
+# %%
+class Node(pydantic.BaseModel):
+    type: Literal["Node"] = "Node"
+    stimulus: Card | None
+    sensor: Sensor
+
+    board_color: ColorHexString = pydantic.Field(
+        description='The color of the Board during this Node (the "background color").',
+        default="#808080ff",
+        validate_default=True,
+    )
+    hide_pointer: bool = False

nodekit/_internal/types/regions/__init__.py

@@ -0,0 +1,13 @@
+import pydantic
+
+from nodekit._internal.types.value import SpatialPoint, SpatialSize, Mask
+
+
+# %%
+class Region(pydantic.BaseModel):
+    x: SpatialPoint
+    y: SpatialPoint
+    w: SpatialSize
+    h: SpatialSize
+    z_index: int | None = None
+    mask: Mask = "rectangle"