NodeKit

https://intelligence-observatory.github.io/nodekit
Admin
NodeKit is a Python library for writing behavioral tasks that can be run in the browser for humans...
Tokens:12,021
Snippets:184
Trust Score:9.7
Update:2 months ago
Show doc for...
Tokens:
Raw
### Verify NodeKit installation

Source: https://intelligence-observatory.github.io/nodekit/tutorial/1-installation

Launch an interactive Python session and import the library to confirm it is installed correctly.

```bash
uv run python
```

```python
import nodekit as nk
```

--------------------------------

### Verify uv installation

Source: https://intelligence-observatory.github.io/nodekit/tutorial/1-installation

Check that uv is installed and view its version.

```bash
uv --version
```

```text
uv 0.8.12 (36151df0e 2025-08-18)
```

--------------------------------

### Install NodeKit via pip

Source: https://intelligence-observatory.github.io/nodekit/tutorial/1-installation

Use this command if you prefer managing dependencies with pip.

```bash
pip install nodekit
```

--------------------------------

### Install NodeKit via uv

Source: https://intelligence-observatory.github.io/nodekit/tutorial/1-installation

Use this command to add NodeKit to an existing Python project managed by uv.

```bash
uv add nodekit
```

--------------------------------

### Line Break Formatting

Source: https://intelligence-observatory.github.io/nodekit/guides/styling-text

Examples showing how to correctly trigger line breaks versus how they are ignored.

```markdown
This is the first line.\n\n
This is the second line. 
```

```markdown
This is the first line.\n
This is also the first. 
```

--------------------------------

### Markdown TextCard Example

Source: https://intelligence-observatory.github.io/nodekit/guides/styling-text

Demonstrates basic formatting including headers, bold/italic text, nested lists, and color spans.

```markdown
# Heading

This is a paragraph with **bold** and _italic_ text.

- First item
    - Nested item
- Second item

* Same list, different marker

Here is <span style="color:#ff00ff">magenta text</span>.
```

--------------------------------

### StepRecord Start Timestamp Field

Source: https://intelligence-observatory.github.io/nodekit/reference/trace

Represents the timestamp of the NodeStartedEvent.

```python
t_start: TimeElapsedMsec
```

--------------------------------

### Define Graph start field

Source: https://intelligence-observatory.github.io/nodekit/reference/graph

The start Node of the Graph.

```python
start: NodeId
```

--------------------------------

### Define WaitSensor duration

Source: https://intelligence-observatory.github.io/nodekit/reference/sensors

Sets the time in milliseconds from the start of the node for the sensor to trigger.

```python
duration_msec: TimeDurationMsec
```

--------------------------------

### Initialize a new project with uv

Source: https://intelligence-observatory.github.io/nodekit/tutorial/1-installation

Create a new directory and project structure for the tutorial.

```bash
uv init nodekit-tutorial
```

--------------------------------

### Prepare the site URL

Source: https://intelligence-observatory.github.io/nodekit/guides/mechanical-turk-and-prolific

Use nk.prepare_site_url to correctly append the nodekitSubmitTo query parameter to the entrypoint URL.

```python
import nodekit as nk

entrypoint_url = "https://site.com/graphs/568...7f6a.html"
submit_url = "https://my-endpoint.com"

prepared_url = nk.prepare_site_url(
    site_url=entrypoint_url,
    nodekit_submit_to=submit_url,
)
```

--------------------------------

### Build a site from a Graph

Source: https://intelligence-observatory.github.io/nodekit/guides/mechanical-turk-and-prolific

Use nk.build_site to convert a Graph into a static website folder.

```python
import nodekit as nk
...
graph = nk.Graph(...)  # put your Graph here
result = nk.build_site(graph=graph, savedir="my-site")
```

--------------------------------

### Sync site to S3

Source: https://intelligence-observatory.github.io/nodekit/guides/mechanical-turk-and-prolific

Use the AWS CLI to sync the generated site folder to an S3 bucket.

```bash
aws s3 sync build/my-site s3://your-bucket/task --delete
```

--------------------------------

### Build a static site

Source: https://intelligence-observatory.github.io/nodekit/reference/site

Generates a static website from a Graph object and saves it to the specified directory.

```python
build_site(
    graph: Graph,
    savedir: PathLike | str,
    slug: str | None = None,
) -> BuildSiteResult
```

--------------------------------

### nodekit.build_site

Source: https://intelligence-observatory.github.io/nodekit/reference/site

Builds a static website for a given Graph and saves it to the specified directory.

```APIDOC
## nodekit.build_site

### Description
Builds a static website for a Graph and saves it to disk.

### Signature
`build_site(graph: Graph, savedir: PathLike | str, slug: str | None = None) -> BuildSiteResult`

### Parameters
- **graph** (Graph) - Required - Graph to serialize and render into a site.
- **savedir** (PathLike | str) - Required - Directory to write the site into.
- **slug** (str | None) - Optional - Optional human-readable URL slug for the entrypoint HTML file.

### Returns
- **BuildSiteResult** - BuildSiteResult with the site root, entrypoint, and dependency list.

### Raises
- **ValueError** - If savedir is not a directory.
- **ValueError** - If slug is invalid or collides with a different built Graph.
```

--------------------------------

### Execute the Graph

Source: https://intelligence-observatory.github.io/nodekit/tutorial/2-first-graph

Launches the graph in a local web server and captures the resulting behavioral trace.

```python
import nodekit as nk

node = nk.Node(
    card=nk.cards.TextCard(text="Hello world! Press f or j to continue."),
    sensor=nk.sensors.KeySensor(keys=['f', 'j'])
)

graph = nk.Graph(
    start='my-first-node',
    nodes={'my-first-node': node},
    transitions={'my-first-node': nk.transitions.End()},
)

trace = nk.play(graph)  # launch a local server
```

--------------------------------

### Open an Asset

Source: https://intelligence-observatory.github.io/nodekit/reference/ops

Provides a context manager to stream the binary data of an Asset.

```python
open_asset(asset: Asset) -> ContextManager[IO[bytes]]
```

--------------------------------

### Define the first instruction node

Source: https://intelligence-observatory.github.io/nodekit/tutorial/2b-afc-graph

Creates a single instruction node with a TextCard and a KeySensor for navigation.

```python
import nodekit as nk 

instructions_page_1 = nk.Node(
    card=nk.cards.TextCard(
        text=("# Welcome!"
              "\n\n"
              "This is the first page of the instructions. "
              "Press the right arrow key to continue."),
        justification_horizontal='left',
    ), 
    sensor=nk.sensors.KeySensor(
        keys=['ArrowRight']
    ),
    board_color='#ffffffff', # white background
)
```

--------------------------------

### Play a graph locally

Source: https://intelligence-observatory.github.io/nodekit/tutorial/3-deploy-graph

Launch a graph in the local browser to collect behavioral traces from human participants.

```python
import nodekit as nk
graph = nk.Graph(...) # Insert your Graph here
trace = nk.play(graph) # Launch Graph on your local machine
```

--------------------------------

### Project Trace to StepRecords

Source: https://intelligence-observatory.github.io/nodekit/reference/trace

Projects a Trace into a list of StepRecord objects, pairing lifecycle events for each completed node.

```python
list_steps() -> list[StepRecord]
```

--------------------------------

### nodekit.prepare_site_url

Source: https://intelligence-observatory.github.io/nodekit/reference/site

Prepares a Site URL for NodeKit submission behavior, including platform-specific configurations.

```APIDOC
## nodekit.prepare_site_url

### Description
Prepare a Site URL for NodeKit submission behavior.

### Signature
`prepare_site_url(site_url: str, platform: Platform = "none", nodekit_submit_to: str | None = None, prolific_completion_code: str | None = None) -> str`

### Parameters
- **site_url** (str) - Required - The participant-facing Site URL to prepare.
- **platform** (Platform) - Optional - The recruitment platform (e.g., "none", "prolific", "mturk").
- **nodekit_submit_to** (str | None) - Optional - An optional side-channel URL where NodeKit should POST the completed SiteSubmission.
- **prolific_completion_code** (str | None) - Optional - The Prolific completion code to include when platform is "prolific".

### Returns
- **str** - The prepared Site URL.

### Raises
- **ValueError** - If platform is unsupported, if Prolific is selected without a completion code or submission URL, or if a Prolific completion code is supplied for another platform.
```

--------------------------------

### Image Asset Creation

Source: https://intelligence-observatory.github.io/nodekit/reference/assets

Method to instantiate an Image asset from a local file path.

```python
from_path(path: Path | str) -> Self
```

--------------------------------

### Define a Node

Source: https://intelligence-observatory.github.io/nodekit/tutorial/2-first-graph

Creates a node with a text display and keyboard input sensor.

```python
import nodekit as nk

node = nk.Node(
    card=nk.cards.TextCard(text="Hello world! Press f or j to continue."),
    sensor=nk.sensors.KeySensor(keys=['f', 'j'])
)
```

--------------------------------

### nodekit.assets.Video.from_path

Source: https://intelligence-observatory.github.io/nodekit/reference/assets

Creates a Video asset instance from a file path on the local file system. This method performs I/O to compute the SHA-256 hash of the file.

```APIDOC
## nodekit.assets.Video.from_path(path: Path | str) -> Self

### Description
A public convenience method to create a Video 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.

### Parameters
- **path** (Path | str) - Required - The file path to the video on the local file system.
```

--------------------------------

### RandomGuesser agent initialization

Source: https://intelligence-observatory.github.io/nodekit/reference/agent

Initializes a RandomGuesser agent which selects the first available action in a node randomly.

```python
RandomGuesser(seed: int | None = None)
```

--------------------------------

### list_steps

Source: https://intelligence-observatory.github.io/nodekit/reference/trace

Projects the Trace into a list of StepRecord objects, each representing a completed node visit with associated action and timing data.

```APIDOC
## list_steps()

### Description
Projects the Trace to one StepRecord per completed Node. Each record pairs one NodeStartedEvent, one ActionTakenEvent, and one NodeEndedEvent with the same NodeAddress.

### Signature
`list_steps() -> list[StepRecord]`

### Returns
- **list[StepRecord]** - A list of StepRecords in Trace order.

### Raises
- **ValueError** - If Node lifecycle Events do not appear in strict NodeStartedEvent, ActionTakenEvent, NodeEndedEvent order, or if paired lifecycle Events have different Node addresses.
```

--------------------------------

### Site layout structure

Source: https://intelligence-observatory.github.io/nodekit/reference/site

The directory structure generated by the build_site function.

```text
assets/
    {mime-type-1}/{mime-type-2}/{sha256}.{ext}
runtime/
    nodekit.{js-digest}.js
    nodekit.{css-digest}.css
graphs/
    {graph_digest}.html (if slug is None)
    {slug}.html (if slug is provided)
```

--------------------------------

### Retrieve the entrypoint location

Source: https://intelligence-observatory.github.io/nodekit/guides/mechanical-turk-and-prolific

Access the .entrypoint property of the build result to find the relative location of the HTML file.

```python
import nodekit as nk
...
graph = nk.Graph(...)  # put your Graph here
result = nk.build_site(graph=graph, savedir="my-site")
print("Entrypoint:", result.entrypoint)      # graphs/<hash>.html
```

--------------------------------

### nodekit.simulate

Source: https://intelligence-observatory.github.io/nodekit/reference/ops

Deterministically simulates a Graph using an optional Agent.

```APIDOC
## nodekit.simulate(graph: Graph, agent: BaseAgent | None = None) -> Trace

### Description
Performs a deterministic simulation of a Graph. If no agent is provided, a DummyAgent is used to randomly select actions.

### Parameters
- **graph** (Graph) - Required - The graph to simulate.
- **agent** (BaseAgent | None) - Optional - The agent used for simulation.
```

--------------------------------

### Define a simple NodeKit graph

Source: https://intelligence-observatory.github.io/nodekit/tutorial/3-deploy-graph

Create a basic graph structure with a text card and a key sensor to serve as a foundation for testing.

```python
import nodekit as nk

node = nk.Node(
    card=nk.cards.TextCard(text="Hello world! Press f or j to continue."),
    sensor=nk.sensors.KeySensor(keys=['f', 'j'])
)

graph = nk.Graph(
    start='my-first-node',
    nodes={'my-first-node': node},
    transitions={'my-first-node': nk.transitions.End()},
)
```

--------------------------------

### Prepare Prolific Study URL

Source: https://intelligence-observatory.github.io/nodekit/guides/mechanical-turk-and-prolific

Use nk.prepare_site_url to generate a URL with the required Prolific query parameters.

```python
study_url = nk.prepare_site_url(
    site_url=entrypoint_url,
    platform="prolific",
    nodekit_submit_to=submit_url,
    prolific_completion_code="YOUR_COMPLETION_CODE",
)
```

--------------------------------

### Configure VideoCard loop behavior

Source: https://intelligence-observatory.github.io/nodekit/reference/cards

Determines whether the video asset should loop upon reaching the end.

```python
loop: bool = False
```

--------------------------------

### Access platform context

Source: https://intelligence-observatory.github.io/nodekit/reference/site

Retrieves information about the platform where the Graph site was hosted.

```python
platform_context: PlatformContext
```

--------------------------------

### nodekit.play

Source: https://intelligence-observatory.github.io/nodekit/reference/ops

Executes a Graph or Node locally and returns the resulting Trace.

```APIDOC
## nodekit.play(graph: Graph | Node, port: int | None = None) -> Trace

### Description
Plays the given Graph or Node locally and returns the Trace of events observed during execution.

### Parameters
- **graph** (Graph | Node) - Required - The Graph or Node to execute.
- **port** (int | None) - Optional - The port to connect to.
```

--------------------------------

### Define multiple instruction nodes

Source: https://intelligence-observatory.github.io/nodekit/tutorial/2b-afc-graph

Defines two sequential instruction nodes with customized text and font settings.

```python
import nodekit as nk

instructions_page_1 = nk.Node(
    card=nk.cards.TextCard(
        text=("# Welcome!"
              "\n\n"
              "This is the first page of the instructions. "
              "Press the right arrow key to continue."),
        justification_horizontal='left',
    ),
    sensor=nk.sensors.KeySensor(
        keys=['ArrowRight']
    ), 
    board_color='#ffffffff', # white
)

instructions_page_2 = nk.Node(
    card=nk.cards.TextCard(
        text=("This is the **second** page. "
              "Press the right arrow key to continue."),
        font_size=20, 
        justification_horizontal='left',
    ), 
    sensor=nk.sensors.KeySensor(
        keys=['ArrowRight']
    ),
    board_color='#ffffffff', # white background
)
```

--------------------------------

### nodekit.assets.Image.from_path

Source: https://intelligence-observatory.github.io/nodekit/reference/assets

Creates an Image asset instance from a file path on the local file system. This method performs I/O to compute the SHA-256 hash of the file.

```APIDOC
## nodekit.assets.Image.from_path(path: Path | str) -> Self

### Description
A public convenience method to create an Image 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.

### Parameters
- **path** (Path | str) - Required - The file path to the image on the local file system.
```

--------------------------------

### Simulate a graph with an agent

Source: https://intelligence-observatory.github.io/nodekit/tutorial/3-deploy-graph

Run a graph using an automated agent, such as the RandomGuesser, to generate behavioral data without human input.

```python
import nodekit as nk
graph = nk.Graph(...) # Insert your Graph here
agent = nk.agents.RandomGuesser(seed=0) # Instantiate agent
trace = nk.simulate(graph, agent) # Run Graph on agent and get its behavioral trace
```

--------------------------------

### Define AFC Trial Parameters

Source: https://intelligence-observatory.github.io/nodekit/tutorial/2b-afc-graph

Set the initial dimensions and timing durations for the trial components.

```python
import nodekit as nk

fixation_size = 60
stimulus_size = 350
choice_size = 250
stimulus_duration_msec = 500
feedback_duration_msec = 600
```

--------------------------------

### ProductAction

Source: https://intelligence-observatory.github.io/nodekit/reference/actions

Represents a product action containing child actions.

```APIDOC
## nodekit.actions.ProductAction

### Description
Represents a product action mapping child IDs to actions.

### Fields
- **action_type** (Literal['ProductAction']) - The type of action.
- **action_value** (dict[str, Action]) - A dictionary mapping child IDs to their corresponding Actions.
```

--------------------------------

### Play a Graph

Source: https://intelligence-observatory.github.io/nodekit/reference/ops

Executes a Graph or Node locally and returns the resulting Trace.

```python
play(graph: Graph | Node, port: int | None = None) -> Trace
```

--------------------------------

### nodekit.transitions.Go

Source: https://intelligence-observatory.github.io/nodekit/reference/transitions

A transition model that directs the flow to a specific node and updates registers.

```APIDOC
## nodekit.transitions.Go

### Description
Represents a transition that moves the execution flow to a specified node.

### Fields
- **transition_type** (Literal['Go']) - Required - The type identifier for the transition.
- **to** (NodeId) - Required - The identifier of the target node.
- **register_updates** (dict[RegisterId, Expression]) - Optional - A mapping of register identifiers to expressions for state updates.
```

--------------------------------

### Prepare site URL for submission

Source: https://intelligence-observatory.github.io/nodekit/reference/site

Configures a URL for participant-facing submission, supporting platforms like Prolific and Mechanical Turk.

```python
prepare_site_url(
    site_url: str,
    platform: Platform = "none",
    nodekit_submit_to: str | None = None,
    prolific_completion_code: str | None = None,
) -> str
```

--------------------------------

### Configure Node board color

Source: https://intelligence-observatory.github.io/nodekit/reference/node

Sets the background color of the board during the node execution.

```python
board_color: ColorHexString = '#808080ff'
```

--------------------------------

### KeyAction

Source: https://intelligence-observatory.github.io/nodekit/reference/actions

Represents a key press action.

```APIDOC
## nodekit.actions.KeyAction

### Description
Represents a key press action within the system.

### Fields
- **action_type** (Literal['KeyAction']) - The type of action.
- **action_value** (str) - The key that was pressed.
```

--------------------------------

### Access platform property

Source: https://intelligence-observatory.github.io/nodekit/reference/site

Retrieves the recruiter platform associated with a SiteSubmission.

```python
platform: Platform
```

--------------------------------

### Wire nodes into an instruction Graph

Source: https://intelligence-observatory.github.io/nodekit/tutorial/2b-afc-graph

Combines defined nodes into a Graph structure with transitions to manage flow.

```python
import nodekit as nk

instructions_page_1 = nk.Node(
    card=nk.cards.TextCard(
        text=("# Welcome!"
              "\n\n"
              "This is the first page of the instructions. "
              "Press the right arrow key to continue."),
        justification_horizontal='left',
    ),
    sensor=nk.sensors.KeySensor(
        keys=['ArrowRight']
    ),
    board_color='#ffffffff', # white background
)

instructions_page_2 = nk.Node(
    card=nk.cards.TextCard(
        text=("This is the **second** page. "
              "Press the right arrow key to continue."),
        font_size=20, 
        justification_horizontal='left',
    ), 
    sensor=nk.sensors.KeySensor(
        keys=['ArrowRight']
    ),
    board_color='#ffffffff', # white background
)

instructions_graph = nk.Graph(
    start='page1',
    nodes={
        'page1': instructions_page_1, 
        'page2': instructions_page_2,
    },
    transitions={
        'page1': nk.transitions.Go(to='page2'),
        'page2': nk.transitions.End()
    }
)
```

--------------------------------

### Prepare a Mechanical Turk HIT URL

Source: https://intelligence-observatory.github.io/nodekit/guides/mechanical-turk-and-prolific

Use nk.prepare_site_url with the platform argument set to mturk to generate a HIT URL.

```python
hit_url = nk.prepare_site_url(
    site_url=entrypoint_url,
    platform="mturk",
    nodekit_submit_to=submit_url,
)
```

--------------------------------

### Configure MultiSelectSensor selection limits

Source: https://intelligence-observatory.github.io/nodekit/reference/sensors

Defines the minimum and maximum number of cards required for selection.

```python
max_selections: int | None = None
```

```python
min_selections: int
```

--------------------------------

### Video Asset Fields

Source: https://intelligence-observatory.github.io/nodekit/reference/assets

Definitions for the locator, media_type, and sha256 fields within the Video model.

```python
locator: AssetLocator
```

```python
media_type: VideoMediaType
```

```python
sha256: SHA256
```

--------------------------------

### nodekit.load_graph

Source: https://intelligence-observatory.github.io/nodekit/reference/ops

Unpacks a .nkg file and returns a Graph object.

```APIDOC
## nodekit.load_graph(path: str | PathLike) -> Graph

### Description
Loads a Graph from a .nkg file on disk.

### Parameters
- **path** (str | PathLike) - Required - The path to the .nkg file.
```

--------------------------------

### Save a Graph to a .nkg file

Source: https://intelligence-observatory.github.io/nodekit/guides/saving-and-sharing

Serializes a Graph and its associated assets into a single .nkg file. The destination path must end in .nkg and the parent directory must exist.

```python
import nodekit as nk

graph = nk.Graph(...)  # your Graph here
nk.save_graph(graph, "my-task.nkg")
```

--------------------------------

### SelectAction

Source: https://intelligence-observatory.github.io/nodekit/reference/actions

Represents a selection action.

```APIDOC
## nodekit.actions.SelectAction

### Description
Represents a selection made by an agent.

### Fields
- **action_type** (Literal['SelectAction']) - The type of action.
- **action_value** (str) - The selection made by the agent.
```

--------------------------------

### Import NodeKit

Source: https://intelligence-observatory.github.io/nodekit/tutorial/2-first-graph

The standard import statement required to access NodeKit functionality.

```python
import nodekit as nk
```

--------------------------------

### WaitAction

Source: https://intelligence-observatory.github.io/nodekit/reference/actions

Represents a wait action.

```APIDOC
## nodekit.actions.WaitAction

### Description
Represents a wait action.

### Fields
- **action_type** (Literal['WaitAction']) - The type of action.
- **action_value** (None) - No value associated.
```

--------------------------------

### nodekit.transitions.IfThenElse

Source: https://intelligence-observatory.github.io/nodekit/reference/transitions

A conditional transition model that branches flow based on an expression.

```APIDOC
## nodekit.transitions.IfThenElse

### Description
Represents a conditional branch in the transition flow.

### Fields
- **transition_type** (Literal['IfThenElse']) - Required - The type identifier for the transition.
- **if** (Expression) - Required - A boolean-valued expression used to determine the branch.
- **then** (Transition) - Required - The transition to execute if the condition is true.
- **else** (Transition) - Optional - The transition to execute if the condition is false (defaults to End).
```

--------------------------------

### ProductAction action_value

Source: https://intelligence-observatory.github.io/nodekit/reference/actions

Represents a dictionary mapping child IDs to their corresponding Actions.

```python
action_value: dict[str, Action]
```

--------------------------------

### Load a Graph from a .nkg file

Source: https://intelligence-observatory.github.io/nodekit/guides/saving-and-sharing

Restores a Graph from a previously saved .nkg archive. The archive must remain accessible while the Graph is in use as it reads assets directly from the file.

```python
import nodekit as nk

graph = nk.load_graph("my-task.nkg")
```

--------------------------------

### nodekit.BaseAgent.__call__

Source: https://intelligence-observatory.github.io/nodekit/reference/agent

An abstract method that must be implemented to return an Action based on a given Node.

```APIDOC
## __call__(node: Node) -> Action

### Description
Abstract method to select an action for a given node.

### Parameters
- **node** (Node) - Required - The node context for the action selection.

### Returns
- **Action** (Action) - The selected Action.
```

--------------------------------

### Image Asset Fields

Source: https://intelligence-observatory.github.io/nodekit/reference/assets

Definitions for the locator, media_type, and sha256 fields within the Image model.

```python
locator: AssetLocator
```

```python
media_type: ImageMediaType
```

```python
sha256: SHA256
```

--------------------------------

### Configure Node timeout with KeySensor

Source: https://intelligence-observatory.github.io/nodekit/guides/adding-time-limits

Sets a 5000 millisecond time limit on a KeySensor, causing it to time out with a WaitAction if no input is received.

```python
import nodekit as nk

# The Node's KeySensor will time out with a WaitAction after 5000 msec:
node = nk.Node(
    card=nk.cards.TextCard(text='Hello, world!'),
    sensor=nk.sensors.KeySensor(
        keys=['f', 'j'],
        duration_msec=5000 
    )
)
```

--------------------------------

### Configure TextCard background color

Source: https://intelligence-observatory.github.io/nodekit/reference/cards

Sets the background color for a TextCard using a hexadecimal string.

```python
background_color: ColorHexString = '#E6E6E600'
```

--------------------------------

### Load a Graph

Source: https://intelligence-observatory.github.io/nodekit/reference/ops

Deserializes a .nkg archive file into a Graph object.

```python
load_graph(path: str | PathLike) -> Graph
```

--------------------------------

### nodekit.transitions.End

Source: https://intelligence-observatory.github.io/nodekit/reference/transitions

A transition model that terminates the current flow.

```APIDOC
## nodekit.transitions.End

### Description
Represents a transition that ends the current execution path.

### Fields
- **transition_type** (Literal['End']) - Required - The type identifier for the transition.
- **register_updates** (dict[RegisterId, Expression]) - Optional - A mapping of register identifiers to expressions for state updates.
```

--------------------------------

### Simulate a Graph

Source: https://intelligence-observatory.github.io/nodekit/reference/ops

Performs a deterministic simulation of a Graph using an optional Agent.

```python
simulate(
    graph: Graph, agent: BaseAgent | None = None
) -> Trace
```

--------------------------------

### nodekit.open_asset

Source: https://intelligence-observatory.github.io/nodekit/reference/ops

Streams the bytes of a given Asset.

```APIDOC
## nodekit.open_asset(asset: Asset) -> ContextManager[IO[bytes]]

### Description
Provides a context manager to stream the raw bytes of an asset.

### Parameters
- **asset** (Asset) - Required - The asset to stream.
```

--------------------------------

### Access trace property

Source: https://intelligence-observatory.github.io/nodekit/reference/site

Decompresses and decodes the gzipped base64 Trace from a submission.

```python
trace: Trace
```

--------------------------------

### Configure TextEntrySensor properties

Source: https://intelligence-observatory.github.io/nodekit/reference/sensors

Defines the visual and input constraints for text entry fields.

```python
font_size: PixelSize = 20
```

```python
max_length: int | None = None
```

```python
min_length: int = 1
```

```python
prompt: str = ''
```

--------------------------------

### KeyAction action_value

Source: https://intelligence-observatory.github.io/nodekit/reference/actions

Represents the key pressed by the agent.

```python
action_value: str
```

--------------------------------

### SumAction

Source: https://intelligence-observatory.github.io/nodekit/reference/actions

Represents a sum action.

```APIDOC
## nodekit.actions.SumAction

### Description
Represents a sum action taken by a child node.

### Fields
- **action_type** (Literal['SumAction']) - The type of action.
- **action_value** (tuple[str, Action]) - A tuple of (winner_id, Action) taken by the child node.
```

--------------------------------

### Define Node and Graph address types

Source: https://intelligence-observatory.github.io/nodekit/reference/values

Identifiers and address structures for nodes and graphs.

```python
NodeId = Annotated[
    str,
    Field(
        description="An identifier for a Node which is unique within a Graph."
    ),
]
```

```python
NodeAddress = Annotated[
    list[NodeId],
    Field(
        description="The address of a Node within a Graph."
    ),
]
```

```python
GraphAddress = NodeAddress
```

```python
RegisterId = Annotated[
    str,
    Field(
        description="An identifier for a Graph register."
    ),
]
```

--------------------------------

### MultiSelectAction

Source: https://intelligence-observatory.github.io/nodekit/reference/actions

Represents a multi-selection action.

```APIDOC
## nodekit.actions.MultiSelectAction

### Description
Represents multiple selections made by an agent.

### Fields
- **action_type** (Literal['MultiSelectAction']) - The type of action.
- **action_value** (list[str]) - The selections made by the agent.
```

--------------------------------

### Define PixelSize and PixelPoint types

Source: https://intelligence-observatory.github.io/nodekit/reference/values

Spatial types using W3C reference pixels.

```python
PixelSize = Annotated[
    int,
    Field(
        strict=True,
        ge=0,
        description="A spatial size in units of W3C reference pixels. ",
    ),
]
```

```python
PixelPoint = Annotated[
    int,
    Field(
        strict=True,
        description="A spatial location relative to some origin, in units of W3C reference pixels.",
    ),
]
```

--------------------------------

### nodekit.agents.RandomGuesser

Source: https://intelligence-observatory.github.io/nodekit/reference/agent

An implementation of BaseAgent that randomly selects the first available action in a node.

```APIDOC
## RandomGuesser(seed: int | None = None)

### Description
An Agent that randomly selects the first available Action in a Node.

### Parameters
- **seed** (int | None) - Optional - Seed for the random number generator.
```

--------------------------------

### Concatenate Graphs Linearly

Source: https://intelligence-observatory.github.io/nodekit/tutorial/2b-afc-graph

Use nk.concat to automatically generate transitions for a linear sequence of graphs, reducing boilerplate code.

```python
import nodekit as nk

... # definitions of child graphs go here

graph = nk.concat(
    sequence=[instructions_graph, afc_graph1, afc_graph2, afc_graph3], 
    ids = ['instructions', 'trial1', 'trial2', 'trial3']
)
```

--------------------------------

### StepRecord Action Field

Source: https://intelligence-observatory.github.io/nodekit/reference/trace

Represents the action taken at a specific node.

```python
action: Action
```

--------------------------------

### nodekit.save_graph

Source: https://intelligence-observatory.github.io/nodekit/reference/ops

Packs a Graph model into a .nkg file.

```APIDOC
## nodekit.save_graph(graph: Graph, path: str | PathLike) -> Path

### Description
Saves the Graph model as a .nkg zip archive containing the graph JSON and associated assets.

### Parameters
- **graph** (Graph) - Required - The graph object to save.
- **path** (str | PathLike) - Required - The destination file path.
```

--------------------------------

### Define MediaType types

Source: https://intelligence-observatory.github.io/nodekit/reference/values

Literal types for image and video media formats.

```python
ImageMediaType = Literal[
    "image/png", "image/svg+xml", "image/jpeg"
]
```

```python
VideoMediaType = Literal['video/mp4']
```

```python
MediaType = ImageMediaType | VideoMediaType
```

--------------------------------

### Define MarkdownString type

Source: https://intelligence-observatory.github.io/nodekit/reference/values

Annotated string for Markdown content.

```python
MarkdownString = Annotated[
    str,
    Field(
        strict=True, description="Markdown-formatted string"
    ),
]
```

--------------------------------

### Configure TextCard font size

Source: https://intelligence-observatory.github.io/nodekit/reference/cards

Defines the height of the em-box for text in Board units.

```python
font_size: PixelSize = 20
```

--------------------------------

### Define KeySensor keys

Source: https://intelligence-observatory.github.io/nodekit/reference/sensors

Specifies the keys that trigger the sensor when pressed.

```python
keys: list[PressableKey]
```

--------------------------------

### SliderAction action_value

Source: https://intelligence-observatory.github.io/nodekit/reference/actions

Represents the index of the selected bin.

```python
action_value: int
```

--------------------------------

### Define Graph registers field

Source: https://intelligence-observatory.github.io/nodekit/reference/graph

The initial register values.

```python
registers: dict[RegisterId, LeafValue]
```

--------------------------------

### Define AFC Trial Nodes

Source: https://intelligence-observatory.github.io/nodekit/tutorial/2b-afc-graph

Construct the fixation, stimulus, choice, and feedback nodes using image and text cards with specific sensors.

```python
import nodekit as nk

fixation_size = 60
stimulus_size = 350
choice_size = 250
stimulus_duration_msec = 500
feedback_duration_msec = 600

fixation_card = nk.cards.ImageCard(
    image=nk.assets.Image.from_path("fixation.png"),
    region=nk.Region(x=0, y=0, w=fixation_size, h=fixation_size),
)

fixation_node = nk.Node(
    sensor=nk.sensors.SelectSensor(choices={"fixation": fixation_card}),
)

stimulus_node = nk.Node(
    card=nk.cards.ImageCard(
        image=nk.assets.Image.from_path("stimulus.png"),
        region=nk.Region(x=0, y=0, w=stimulus_size, h=stimulus_size),
    ),
    sensor=nk.sensors.WaitSensor(duration_msec=stimulus_duration_msec),
    hide_pointer=True,
)

choice_cards = {
    "left": nk.cards.ImageCard(
        image=nk.assets.Image.from_path("choice-correct.png"),
        region=nk.Region(x=-200, y=0, w=choice_size, h=choice_size),
    ),
    "right": nk.cards.ImageCard(
        image=nk.assets.Image.from_path("choice-incorrect.png"),
        region=nk.Region(x=200, y=0, w=choice_size, h=choice_size),
    ),
}

choice_node = nk.Node(
    sensor=nk.sensors.SelectSensor(choices=choice_cards),
)

reward_node = nk.Node(
    card=nk.cards.TextCard(
        text="Correct!",
        font_size=48,
    ),
    sensor=nk.sensors.WaitSensor(duration_msec=feedback_duration_msec),
)

punish_node = nk.Node(
    card=nk.cards.TextCard(
        text="Incorrect.",
        font_size=48,
    ),
    sensor=nk.sensors.WaitSensor(duration_msec=feedback_duration_msec),
)
```

--------------------------------

### Load a Trace from JSON

Source: https://intelligence-observatory.github.io/nodekit/guides/saving-and-sharing

Validates and reconstructs a Trace object from a saved JSON file using model_validate_json.

```python
import nodekit as nk
from pathlib import Path

trace = nk.Trace.model_validate_json(Path("my-trace.json").read_text())
```

--------------------------------

### Define Node card

Source: https://intelligence-observatory.github.io/nodekit/reference/node

Specifies the visual context for the agent; defaults to a blank board if set to None.

```python
card: Card | None = None
```

--------------------------------

### TextEntryAction

Source: https://intelligence-observatory.github.io/nodekit/reference/actions

Represents a text entry action.

```APIDOC
## nodekit.actions.TextEntryAction

### Description
Represents a text entry action performed by an agent.

### Fields
- **action_type** (Literal['TextEntryAction']) - The type of action.
- **action_value** (str) - The text that was entered by the agent.
```

--------------------------------

### SliderAction

Source: https://intelligence-observatory.github.io/nodekit/reference/actions

Represents a slider selection action.

```APIDOC
## nodekit.actions.SliderAction

### Description
Represents a slider selection action.

### Fields
- **action_type** (Literal['SliderAction']) - The type of action.
- **action_value** (int) - The index of the bin that was selected.
```

--------------------------------

### Wire Nodes into an AFC Graph

Source: https://intelligence-observatory.github.io/nodekit/tutorial/2b-afc-graph

Defines a graph structure using transitions to manage flow, including conditional branching with IfThenElse based on user actions.

```python
import nodekit as nk
... # old code hidden
afc_graph = nk.Graph(
    start='fixation',
    nodes={
        'fixation': fixation_node,
        'stimulus': stimulus_node,
        'choice': choice_node,
        'reward': reward_node,
        'punish': punish_node,
    },
    transitions={
        'fixation': nk.transitions.Go(to='stimulus'),
        'stimulus': nk.transitions.Go(to='choice'),
        'choice': nk.transitions.IfThenElse(
            if_=nk.expressions.Eq(
                lhs=nk.expressions.LastAction(), 
                rhs=nk.expressions.Lit(value='left')
            ), 
            then=nk.transitions.Go(to='reward'), 
            else_ = nk.transitions.Go(to='punish')
        ),
        'reward': nk.transitions.End(),
        'punish': nk.transitions.End(),
    },
)
```

--------------------------------

### StepRecord Action Timestamp Field

Source: https://intelligence-observatory.github.io/nodekit/reference/trace

Represents the timestamp of the ActionTakenEvent.

```python
t_action: TimeElapsedMsec
```

--------------------------------

### nodekit.concat

Source: https://intelligence-observatory.github.io/nodekit/reference/ops

Returns a Graph which executes the given sequence of Node or Graph objects. It allows for prepending IDs to the sequence items.

```APIDOC
## nodekit.concat(sequence: list[Graph | Node], ids: list[str] | None = None) -> Graph

### Description
Returns a new Graph that executes the provided sequence of Nodes or Graphs. If `ids` are provided, they are used for the sequence items; otherwise, they are prepended with '0', '1', etc.

### Parameters
- **sequence** (list[Graph | Node]) - Required - The sequence of nodes or graphs to concatenate.
- **ids** (list[str] | None) - Optional - Custom identifiers for the sequence items.
```

--------------------------------

### BaseAgent __call__ method definition

Source: https://intelligence-observatory.github.io/nodekit/reference/agent

Abstract method that must be implemented to return an Action based on a provided Node.

```python
__call__(node: Node) -> Action
```

--------------------------------

### StepRecord Node Address Field

Source: https://intelligence-observatory.github.io/nodekit/reference/trace

Represents the address of the completed node.

```python
node_address: NodeAddress
```

--------------------------------

### MultiSelectAction action_value

Source: https://intelligence-observatory.github.io/nodekit/reference/actions

Represents the list of selections made by the agent.

```python
action_value: list[str]
```

--------------------------------

### Configure SliderSensor confirmation

Source: https://intelligence-observatory.github.io/nodekit/reference/sensors

Optional button that requires user interaction to confirm a slider selection.

```python
confirm_button: Card | None = None
```

--------------------------------

### Concatenate Graphs or Nodes

Source: https://intelligence-observatory.github.io/nodekit/reference/ops

Creates a new Graph by executing a sequence of Nodes or Graphs in order.

```python
concat(
    sequence: list[Graph | Node],
    ids: list[str] | None = None,
) -> Graph
```

--------------------------------

### BrowserContextSampledEvent Fields

Source: https://intelligence-observatory.github.io/nodekit/reference/events

Individual field definitions for the BrowserContextSampledEvent model.

```python
device_pixel_ratio: float
```

```python
display: RegionSizePx
```

```python
timestamp_client: str
```

```python
user_agent: str
```

--------------------------------

### Retrieve node at address

Source: https://intelligence-observatory.github.io/nodekit/reference/graph

Return the Node or nested Graph at a NodeAddress. Raises ValueError if the address is invalid or KeyError if a NodeId is missing.

```python
get_node_at(node_address: NodeAddress) -> Node | Graph
```

--------------------------------

### Define a Nested Graph

Source: https://intelligence-observatory.github.io/nodekit/tutorial/2b-afc-graph

Construct a parent graph by mapping child graphs to nodes and defining transitions between them.

```python
import nodekit as nk 

... # definitions of child graphs go here

graph = nk.Graph(
    start='instructions',
    nodes={
        'instructions': instructions_graph,
        'trial1': afc_graph1,
        'trial2': afc_graph2,
        'trial3': afc_graph3,
    }, 
    transitions={
        'instructions': nk.transitions.Go(to='trial1'),
        'trial1': nk.transitions.Go(to='trial2'),
        'trial2': nk.transitions.Go(to='trial3'),
        'trial3': nk.transitions.End(), 
    }
)
```

--------------------------------

### Define Graph transitions field

Source: https://intelligence-observatory.github.io/nodekit/reference/graph

The set of Transitions in the Graph, by NodeId.

```python
transitions: dict[NodeId, Transition]
```

--------------------------------

### Define Node sensor

Source: https://intelligence-observatory.github.io/nodekit/reference/node

Specifies the Action Set required for the agent to complete the node.

```python
sensor: Sensor
```

--------------------------------

### Define an AFC Graph Factory Function

Source: https://intelligence-observatory.github.io/nodekit/tutorial/2b-afc-graph

Template for a factory function that generates an AFC graph, allowing for dynamic stimulus configuration.

```python
from pathlib import Path 
import nodekit as nk 

def generate_afc_graph(
        fixation_image_path: Path,
        stimulus_image_path: Path,
        correct_image_path: Path,
        incorrect_image_path: Path, 
        correct_on_left: bool,
) -> nk.Graph:
    # Code not shown here. 
    # Sorry, I'll add it in later!
    # But hopefully you get the idea I'm driving at here.
    # - @himjl
    ...
```

--------------------------------

### StepRecord Index Field

Source: https://intelligence-observatory.github.io/nodekit/reference/trace

Represents the zero-based index of the step record within the trace.

```python
step_index: int
```

--------------------------------

### Define List and Dict types

Source: https://intelligence-observatory.github.io/nodekit/reference/values

Type aliases for recursive data structures.

```python
List = list[Value]
```

```python
Dict = dict[str, Value]
```

--------------------------------

### Define TimeElapsedMsec and TimeDurationMsec types

Source: https://intelligence-observatory.github.io/nodekit/reference/values

Temporal types measured in milliseconds.

```python
TimeElapsedMsec = Annotated[
    int,
    Field(
        strict=True,
        description="A time point, relative to some origin.",
    ),
]
```

```python
TimeDurationMsec = Annotated[
    int,
    Field(
        strict=True,
        ge=0,
        description="A duration of time in milliseconds, relative to the start of the Trace.",
    ),
]
```

--------------------------------

### Define PressableKey type

Source: https://intelligence-observatory.github.io/nodekit/reference/values

Literal set of supported keyboard inputs.

```python
PressableKey = Literal[
    "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",
    "Enter",
    " ",
    "ArrowDown",
    "ArrowLeft",
    "ArrowRight",
    "ArrowUp",
]
```

--------------------------------

### SumAction action_value

Source: https://intelligence-observatory.github.io/nodekit/reference/actions

Represents a tuple containing the winner ID and the Action taken by the child node.

```python
action_value: tuple[str, Action]
```

--------------------------------

### Toggle Node pointer visibility

Source: https://intelligence-observatory.github.io/nodekit/reference/node

Determines whether the mouse pointer is hidden during the node.

```python
hide_pointer: bool = False
```

--------------------------------

### Access trace gzipped base64 field

Source: https://intelligence-observatory.github.io/nodekit/reference/site

Retrieves the raw base64-encoded gzipped JSON bytes of the submitted Trace.

```python
trace_gzipped_base64: str
```

--------------------------------

### Define LeafValue and Value types

Source: https://intelligence-observatory.github.io/nodekit/reference/values

Base types for primitive and composite data.

```python
LeafValue = bool | int | float | str
```

```python
Value = LeafValue | List | Dict | None
```

--------------------------------

### StepRecord End Timestamp Field

Source: https://intelligence-observatory.github.io/nodekit/reference/trace

Represents the timestamp of the NodeEndedEvent.

```python
t_end: TimeElapsedMsec
```

--------------------------------

### Save a Trace to JSON

Source: https://intelligence-observatory.github.io/nodekit/guides/saving-and-sharing

Serializes a Trace object to a JSON file using Pydantic's model_dump_json method. The resulting file contains both the task structure and the behavioral record.

```python
import nodekit as nk
from pathlib import Path

graph = nk.Graph(...)
trace = nk.play(graph)

Path("my-trace.json").write_text(trace.model_dump_json(indent=2))
```

--------------------------------

### Define SHA256 type

Source: https://intelligence-observatory.github.io/nodekit/reference/values

Annotated string for SHA-256 hash validation.

```python
SHA256 = Annotated[str, Field(pattern='^[a-f0-9]{64}$')]
```

--------------------------------

### get_node_at

Source: https://intelligence-observatory.github.io/nodekit/reference/graph

Retrieves a Node or nested Graph located at a specific NodeAddress within the current Graph.

```APIDOC
## get_node_at(node_address: NodeAddress)

### Description
Returns the Node or nested Graph at a specified NodeAddress.

### Parameters
- **node_address** (NodeAddress) - Required - The address to resolve from this Graph.

### Returns
- **Node | Graph** - The Node or nested Graph at the given address.

### Raises
- **ValueError** - If the NodeAddress is empty, or if the NodeAddress tries to descend through a Node instead of a nested Graph.
- **KeyError** - If any NodeId in the NodeAddress does not exist.
```

--------------------------------

### Validate Submission Data

Source: https://intelligence-observatory.github.io/nodekit/guides/mechanical-turk-and-prolific

Load and validate a JSON submission payload using the NodeKit SiteSubmission model.

```python
import nodekit as nk
from pathlib import Path
import json

data = json.loads(Path('the-data.json').read_text())
site_submission = nk.SiteSubmission.model_validate_json(data)
print(site_submission.platform_context)
print(site_submission.trace)
```

--------------------------------

### Define ColorHexString type

Source: https://intelligence-observatory.github.io/nodekit/reference/values

Hex string validated for 8-character color codes.

```python
ColorHexString = Annotated[
    str,
    BeforeValidator(_normalize_hex_code),
    Field(
        pattern="^#[0-9a-fA-F]{8}$",
        min_length=9,
        max_length=9,
    ),
]
```

--------------------------------

### Define GetDictValue expression field

Source: https://intelligence-observatory.github.io/nodekit/reference/expressions

Specifies the dictionary expression field for the GetDictValue model.

```python
d: Expression
```

--------------------------------

### Define Graph annotation field

Source: https://intelligence-observatory.github.io/nodekit/reference/graph

An optional, user-defined annotation for the Graph that may be useful for debugging or analysis purposes.

```python
annotation: JsonValue = None
```

--------------------------------

### Define Graph nodes field

Source: https://intelligence-observatory.github.io/nodekit/reference/graph

The set of Nodes in the Graph, by NodeId. Note that a Graph can contain other Graphs as Nodes.

```python
nodes: dict[
    NodeId,
    Annotated[Node | Graph, Field(discriminator="type")],
]
```
Tokens:
Raw