nodekit 0.0.1a1__py3-none-any.whl

nodekit/_internal/models/node_engine/node_graph.py

@@ -0,0 +1,118 @@
+from typing import List, Self
+from uuid import uuid4
+
+import pydantic
+
+from nodekit._internal.models.fields import (
+    PayableMonetaryAmountUsd, DatetimeUTC
+)
+from nodekit._internal.models.node_engine.board import Board
+from nodekit._internal.models.node_engine.bonus_policy import BonusRule
+from nodekit._internal.models.node_engine.cards.cards import Card
+from nodekit._internal.models.node_engine.effects.base import Effect
+from nodekit._internal.models.node_engine.fields import NodeId
+from nodekit._internal.models.node_engine.reinforcer_maps.reinforcer_maps import ReinforcerMap
+from nodekit._internal.models.node_engine.runtime_metrics import RuntimeMetrics
+from nodekit._internal.models.node_engine.sensors.actions.actions import Action
+from nodekit._internal.models.node_engine.sensors.sensors import Sensor
+
+
+# %% Node
+class Node(pydantic.BaseModel):
+    node_id: NodeId = pydantic.Field(default_factory=uuid4)
+
+    board: Board = pydantic.Field(
+        default_factory=Board
+    )
+
+    cards: List[Card] = pydantic.Field(
+        description="List of Cards that will be placed on the Board, in back-to-front order (i.e. the first Card is at the bottom of the Board, in the z-direction)",
+        min_length=1,
+    )
+
+    sensors: List[Sensor] = pydantic.Field(min_length=1)
+    reinforcer_maps: List[ReinforcerMap] = pydantic.Field(default_factory=list)
+    effects: List[Effect] = pydantic.Field(default_factory=list)
+
+    @pydantic.model_validator(mode='after')
+    def check_node_is_well_formed(self) -> Self:
+
+        # Run basic checks
+        # Check Cards have unique IDs
+        card_id_to_card = {card.card_id: card for card in self.cards}
+        if len(card_id_to_card) != len(self.cards):
+            raise ValueError("Cards must have unique IDs.")
+
+        # Check Sensors:
+        sensor_id_to_sensor = {sensor.sensor_id: sensor for sensor in self.sensors}
+        if len(sensor_id_to_sensor) != len(self.sensors):
+            raise ValueError("Sensors must have unique IDs.")
+        for sensor in self.sensors:
+
+            # Ensure Sensor references a valid target
+            if sensor.card_id and sensor.card_id not in card_id_to_card:
+                raise ValueError(f"Sensor {sensor.sensor_id} is not attached to a valid Card or the Board.")
+
+            # Todo: check that the Sensor and Target type are compatible:
+            ...
+
+        # Check Reinforcer Maps
+        for rmap in self.reinforcer_maps:
+            if rmap.sensor_id not in sensor_id_to_sensor:
+                raise ValueError(f"ReinforcerMap {rmap.reinforcer_map_id} is not attached to a valid Sensor.")
+
+            # Todo: apply rules for ReinforcerMap-Sensor compatibility
+            ...
+
+        return self
+
+
+# %% NodeGraph
+class NodeGraph(pydantic.BaseModel):
+    nodes: List[Node]
+
+    # Payment information
+    base_payment_usd: PayableMonetaryAmountUsd = pydantic.Field(
+        description="The base payment (in USD) that a Participant receives upon successfully completing a TaskRun. Explicitly disclosed to the Participant ahead of time.",
+    )
+    bonus_rules: List[BonusRule] = pydantic.Field(
+        default_factory=list,
+        description='A list of bonus rules that apply to the TaskRun. These rules determine additional payments based on Participant behavior during the TaskRun.'
+                    'These are not disclosed to the Participant by default, but might be described elsewhere, like the description or in a Node.'
+    )
+
+    # Duration
+    max_duration_sec: int = pydantic.Field(
+        gt=0,
+        description="The maximum of time in seconds a Participant has to complete a TaskRun, before it is marked as failed."
+    )
+
+    # Metadata that is disclosed to the Participant:
+    title: str = pydantic.Field(
+        min_length=1,
+        description='The title of the Recruitment Platform posting for the task.'
+    )
+    description: str = pydantic.Field(
+        min_length=1,
+        description='A detailed description of the task in the Recruitment Platform posting.'
+    )
+    keywords: List[str] = pydantic.Field(
+        description='Keywords that Participants may use to discover this task on the Recruitment Platform.'
+    )
+
+
+
+# %%
+class NodeResult(pydantic.BaseModel):
+    """
+    Describes the result of a NodePlay.
+    """
+
+    node_id: str = pydantic.Field(description='The ID of the Node from which this NodeResult was produced.')
+    node_execution_index: int = pydantic.Field(description='The index of the Node execution in the NodeGraph. This is used to identify the order of Node executions in a TaskRun.')
+
+    timestamp_start: DatetimeUTC
+    timestamp_end: DatetimeUTC
+
+    action: Action
+    runtime_metrics: RuntimeMetrics

nodekit/_internal/models/node_engine/reinforcer_maps/base.py

@@ -0,0 +1,14 @@
+from abc import ABC
+from typing import Any
+
+from nodekit._internal.models.node_engine.base import DslModel
+from nodekit._internal.models.node_engine.fields import SensorId
+
+
+class BaseReinforcerMap(DslModel, ABC):
+    """
+    Represents a map from a fully qualified Action emitted by a particular Sensor to an Outcome.
+    """
+    reinforcer_map_type: str
+    reinforcer_map_parameters: Any
+    sensor_id: SensorId

nodekit/_internal/models/node_engine/reinforcer_maps/reinforcer/reinforcer.py

@@ -0,0 +1,14 @@
+
+from typing import List
+
+import pydantic
+
+from nodekit._internal.models.node_engine.base import DslModel
+from nodekit._internal.models.node_engine.cards.cards import Card
+
+
+class Reinforcer(DslModel):
+
+    reinforcer_cards: List[Card] = pydantic.Field(
+        description='Cards which configure the (noninteractive) Reinforcer delivery phase.'
+    )

nodekit/_internal/models/node_engine/reinforcer_maps/reinforcer_maps.py

@@ -0,0 +1,43 @@
+from typing import Literal
+
+from nodekit._internal.models.node_engine.base import DslModel, NullParameters
+from nodekit._internal.models.node_engine.reinforcer_maps.base import BaseReinforcerMap
+from nodekit._internal.models.node_engine.reinforcer_maps.reinforcer.reinforcer import Reinforcer
+
+from typing import Annotated, Union
+
+import pydantic
+
+
+# %%
+class ConstantReinforcerMap(BaseReinforcerMap):
+    class Parameters(DslModel):
+        reinforcer: Reinforcer = pydantic.Field(description='The Outcome to return for any Action emitted by the Sensor it is attached to.')
+
+    """
+    An OutcomeMap which always returns the same Outcome for any Action emitted by the Sensor it is attached to.
+    """
+    reinforcer_map_type: Literal['ConstantReinforcerMap'] = 'ConstantReinforcerMap'
+    reinforcer_map_parameters: Parameters
+
+
+# %%
+class NullReinforcerMap(BaseReinforcerMap):
+    """
+    A convenience class which represents an ReinforcerMap which yields a NullReinforcer.
+    """
+    reinforcer_map_type: Literal['NullReinforcerMap'] = 'NullReinforcerMap'
+    reinforcer_map_parameters: NullParameters = pydantic.Field(
+        default_factory=NullParameters, frozen=True
+    )
+
+
+# %%
+ReinforcerMap = Annotated[
+    Union[
+        NullReinforcerMap,
+        ConstantReinforcerMap,
+        # Add other OutcomeMap types here as needed
+    ],
+    pydantic.Field(discriminator='reinforcer_map_type')
+]

nodekit/_internal/models/node_engine/runtime_metrics.py

@@ -0,0 +1,24 @@
+import pydantic
+
+from nodekit._internal.models.node_engine.base import DslModel
+
+
+# %% Measurements
+class PixelArea(DslModel):
+    width_px: int = pydantic.Field(description="Width of the area in pixels.", ge=0)
+    height_px: int = pydantic.Field(description="Height of the area in pixels.", ge=0)
+
+
+class RuntimeMetrics(DslModel):
+    model_config = pydantic.ConfigDict(
+        extra='allow',
+        frozen=True,
+    )
+
+    # Board
+    display_area: PixelArea = pydantic.Field(description="Metrics of the display area in which the board is rendered.")
+    viewport_area: PixelArea = pydantic.Field(description="Metrics of the viewport in which the board is rendered.")
+    board_area: PixelArea = pydantic.Field(description="Metrics of the board area in which the cards are rendered.")
+
+    # User agent string
+    user_agent: str = pydantic.Field(description="User agent string of the browser or application rendering the board.")

nodekit/_internal/models/node_engine/sensors/actions/actions.py

@@ -0,0 +1,48 @@
+from typing import Literal, Union, Annotated
+
+import pydantic
+
+from nodekit._internal.models.node_engine.base import DslModel, NullValue
+from nodekit._internal.models.node_engine.sensors.actions.base import BaseAction
+
+
+# %%
+
+class ClickAction(BaseAction):
+    """
+    A fully-qualified description of a Sensor emission.
+    """
+
+    class Value(DslModel):
+        """
+        A fully-qualified description of a Sensor emission.
+        """
+        click_x: float = pydantic.Field(description='The x-coordinate of the click, in Board units.')
+        click_y: float = pydantic.Field(description='The y-coordinate of the click, in Board units.')
+
+    action_type: Literal['ClickAction'] = 'ClickAction'
+    action_value: Value
+
+
+# %%
+class DoneAction(BaseAction):
+    action_type: Literal['DoneAction'] = 'DoneAction'
+    action_value: NullValue = pydantic.Field(default_factory=NullValue, frozen=True)
+
+
+# %%
+class TimeoutAction(BaseAction):
+    action_type: Literal['TimeoutAction'] = 'TimeoutAction'
+    action_value: NullValue = pydantic.Field(default_factory=NullValue, frozen=True)
+
+
+# %%
+Action = Annotated[
+    Union[
+        ClickAction,
+        DoneAction,
+        TimeoutAction,
+        # Add other Action types here as needed
+    ],
+    pydantic.Field(discriminator='action_type')
+]

nodekit/_internal/models/node_engine/sensors/actions/base.py

@@ -0,0 +1,18 @@
+from abc import ABC
+from typing import Any
+
+import pydantic
+
+from nodekit._internal.models.node_engine.base import DslModel
+from nodekit._internal.models.node_engine.fields import TimePointMsec, SensorId
+
+
+class BaseAction(DslModel, ABC):
+    sensor_id: SensorId = pydantic.Field(
+        description='Identifier of the Sensor that emitted this Action.'
+    )
+    action_type: str
+    action_value: Any
+    reaction_time_msec: TimePointMsec = pydantic.Field(
+        description='Measured from the onset of the earliest possible time the Action could be emitted.'
+    )

nodekit/_internal/models/node_engine/sensors/base.py

@@ -0,0 +1,25 @@
+from abc import ABC
+from typing import Any
+
+import pydantic
+
+from nodekit._internal.models.node_engine.base import DslModel
+from nodekit._internal.models.node_engine.fields import Timespan, SensorId, CardId
+from uuid import uuid4
+
+
+class BaseSensor(DslModel, ABC):
+    """
+    A Sensor represents a listener for Participant behavior. Sensors are bound to a specific Card, or to the Board.
+    When a Sensor is triggered, it emits a fully qualified Action.
+    """
+
+    # Sensor
+    sensor_id: SensorId = pydantic.Field(default_factory=uuid4)
+    sensor_type: str
+    sensor_parameters: Any
+    # Temporal
+    sensor_timespan: Timespan
+
+    # Sensor target
+    card_id: CardId | None = pydantic.Field(description='Identifier of the Entity (Card or Board) that this Sensor is attached to.')

nodekit/_internal/models/node_engine/sensors/sensors.py

@@ -0,0 +1,49 @@
+from typing import Literal, Union, Annotated
+
+import pydantic
+
+from nodekit._internal.models.node_engine.base import DslModel, NullParameters
+from nodekit._internal.models.node_engine.fields import TimeDurationMsec
+from nodekit._internal.models.node_engine.sensors.base import BaseSensor
+
+from nodekit._internal.models.node_engine.fields import CardId
+
+
+# %%
+class TimeoutSensor(BaseSensor):
+    """
+    Attaches to the Board and triggers an Action after a specified timeout period.
+    """
+
+    class TimeoutSensorParameters(DslModel):
+        timeout_msec: TimeDurationMsec
+
+    sensor_type: Literal['TimeoutSensor'] = 'TimeoutSensor'
+    sensor_parameters: TimeoutSensorParameters
+    card_id: None = pydantic.Field(default=None, frozen=True)  # Only binds to Board
+
+
+# %%
+class DoneSensor(BaseSensor):
+    sensor_type: Literal['DoneSensor'] = 'DoneSensor'
+    sensor_parameters: NullParameters = pydantic.Field(default_factory=NullParameters, frozen=True)
+    card_id: CardId = pydantic.Field(default=None, frozen=True)  # Only binds to Card
+
+
+# %%
+class ClickSensor(BaseSensor):
+    sensor_type: Literal['ClickSensor'] = pydantic.Field(default='ClickSensor', frozen=True)
+    sensor_parameters: NullParameters = pydantic.Field(default_factory=NullParameters, frozen=True)
+    card_id: CardId = pydantic.Field(default=None, frozen=True)  # Only binds to Card
+
+
+# %%
+Sensor = Annotated[
+    Union[
+        TimeoutSensor,
+        DoneSensor,
+        ClickSensor,
+        # Add other Sensor types here as needed
+    ],
+    pydantic.Field(discriminator='sensor_type')
+]

nodekit/_internal/rule_engine/compute_bonus.py

@@ -0,0 +1,32 @@
+from decimal import Decimal
+from typing import List
+
+from nodekit._internal.models.node_engine.bonus_policy import BonusRule, ConstantBonusRule
+from nodekit._internal.models.node_engine.node_graph import NodeResult
+
+
+# %% BonusPolicy Rule Engine
+def compute_bonus(
+        bonus_rules: List[BonusRule],
+        node_results: List[NodeResult]
+) -> Decimal:
+
+    calculated_amount = Decimal('0')
+
+    for node_result in node_results:
+        action = node_result.action
+
+        # Perform scan through rules
+        for rule in bonus_rules:
+            # Dynamic dispatch
+            if isinstance(rule, ConstantBonusRule):
+                rule: ConstantBonusRule
+                if action.sensor_id == rule.bonus_rule_parameters.sensor_id:
+                    # Check currency match
+                    calculated_amount += Decimal(rule.bonus_rule_parameters.bonus_amount_usd)
+
+    # Clip at minimum of 0:
+    if calculated_amount < Decimal('0'):
+        calculated_amount = Decimal('0.00')
+
+    return calculated_amount

nodekit/actions/__init__.py

@@ -0,0 +1,13 @@
+__all__ = [
+    "Action",
+    "ClickAction",
+    "DoneAction",
+    "TimeoutAction",
+]
+
+from nodekit._internal.models.node_engine.sensors.actions.actions import (
+    Action,
+    ClickAction,
+    DoneAction,
+    TimeoutAction,
+)

nodekit/assets/__init__.py

@@ -0,0 +1,9 @@
+__all__ = [
+    "AssetLink",
+    "ImageLink",
+]
+
+from nodekit._internal.models.assets.base import (
+    AssetLink,
+    ImageLink,
+)

nodekit/bonus_rules/__init__.py

@@ -0,0 +1,10 @@
+__all__ = [
+    'ConstantBonusRule',
+    'compute_bonus',
+]
+
+from nodekit._internal.models.node_engine.bonus_policy import (
+    ConstantBonusRule,
+)
+
+from nodekit._internal.rule_engine.compute_bonus import compute_bonus

nodekit/cards/__init__.py

@@ -0,0 +1,13 @@
+__all__ = [
+    'FixationPointCard',
+    'MarkdownPagesCard',
+    'ImageCard',
+    'TextCard',
+]
+
+from nodekit._internal.models.node_engine.cards.cards import (
+    FixationPointCard,
+    MarkdownPagesCard,
+    ImageCard,
+    TextCard,
+)

nodekit/compile/__init__.py

@@ -0,0 +1,10 @@
+__all__ = [
+    'html',
+    'CompileHtmlOptions',
+]
+
+from nodekit._internal.compilers.html_rendering import (
+    html,
+    CompileHtmlOptions,
+)
+

nodekit/effects/__init__.py

@@ -0,0 +1,7 @@
+__all__ = [
+    'HidePointerEffect',
+]
+
+from nodekit._internal.models.node_engine.effects.base import (
+    HidePointerEffect
+)

nodekit/events/__init__.py

@@ -0,0 +1,23 @@
+__all__ = [
+    "EventTypeEnum",
+    "Event",
+
+    # Concrete classes:
+    "StartEvent",
+    "EndEvent",
+    "NodeResultEvent",
+
+    # Client-server models:
+    "SubmitEventRequest",
+    "SubmitEventResponse",
+]
+
+from nodekit._internal.compilers.events import (
+    Event,
+    StartEvent,
+    EndEvent,
+    NodeResultEvent,
+    SubmitEventRequest,
+    SubmitEventResponse,
+    EventTypeEnum,
+)

nodekit/reinforcer_maps/__init__.py

@@ -0,0 +1,10 @@
+__all__ = [
+    'ConstantReinforcerMap',
+    'Reinforcer',
+]
+
+from nodekit._internal.models.node_engine.reinforcer_maps.reinforcer_maps import (
+    ConstantReinforcerMap,
+    Reinforcer,
+)
+

nodekit/sensors/__init__.py

@@ -0,0 +1,12 @@
+__all__ = [
+    'TimeoutSensor',
+    'DoneSensor',
+    'ClickSensor',
+]
+
+from nodekit._internal.models.node_engine.sensors.sensors import (
+    TimeoutSensor,
+    DoneSensor,
+    ClickSensor,
+)
+

nodekit/types/__init__.py

@@ -0,0 +1,27 @@
+__all__ = [
+    # Reusable structural types used as field values in models:
+    'TextContent',
+    'Board',
+    'BoardRectangle',
+    'BoardLocation',
+    'Timespan',
+
+    'RuntimeMetrics',
+    'PixelArea',
+]
+
+from nodekit._internal.models.node_engine.fields import (
+    TextContent,
+    BoardRectangle,
+    BoardLocation,
+    Timespan,
+)
+
+from nodekit._internal.models.node_engine.runtime_metrics import (
+    PixelArea,
+    RuntimeMetrics,
+)
+
+from nodekit._internal.models.node_engine.board import Board
+
+