DreamLake

Bindrs

A bindr is a named collection of node references. It doesn't copy data — it points at paths or whole folders elsewhere in the tree. Use them for:

  • Assembling a training set out of scattered episodes
  • Sharing a curated slice of a project with a teammate
  • Defining "everything I need for experiment X" as a single name

Create a bindr from paths

Inside a Prefix context, members are paths relative to the current episode:

bindr_create.pypython
import dreamlake as dl

with dl.Prefix(project="robotics@alice", prefix="/session-100"):
    dl.bindr(
        "training-set",
        members=[
            "camera/front",        # whole folder
            "labels/yolo",         # whole folder
            "meta.json",           # single file
        ],
        description="Inputs + labels for the front-camera classifier",
        tags=["training", "classifier-v3"],
    )

The SDK resolves each path string to a node ID via /nodes/lookup. Folders are kept as folder references, files as file references. The bindr stores only the IDs — moving or renaming the source files breaks the reference (intentional — bindrs aren't symlinks).

Cross-episode bindrs

Step out of the Prefix context and use absolute paths to mix multiple episodes:

python
dl.bindr(
    "all-camera-front",
    project="robotics@alice",
    members=[
        "/session-100/camera/front",
        "/session-101/camera/front",
        "/session-102/camera/front",
    ],
)

Download a bindr as one tree

dl.download_bindr resolves every member, walks any folder members recursively, and writes each file under to= preserving its relative path:

python
dl.download_bindr("training-set", project="robotics@alice", to="./train/")

Result on disk:

./train/
├── camera/front/clip.mp4
├── labels/yolo/detections.jsonl
└── meta.json

Folder members keep their internal structure under to=. File members land at to=/<filename>.

Add more members later

Calling dl.bindr with an existing name adds to it (rather than replacing). Useful for incrementally building up a set:

python
with dl.Prefix(project="robotics@alice", prefix="/run-100"):
    # Initial set
    dl.bindr("training-set", members=["camera/front"])

    # Later — add another folder. Existing members are kept.
    dl.bindr("training-set", members=["camera/rear"])

If you want to replace members, delete and recreate the bindr (preview UI has a delete button, or use the lower-level client).

Nested bindrs

A bindr can contain other bindrs. Useful for rolling up smaller, focused bindrs into a larger curated set without copying members around.

nested.pypython
# Per-episode media bindrs
for ep in ["run-100", "run-101", "run-102"]:
    with dl.Prefix(project="robotics@alice", prefix=f"/{ep}"):
        dl.bindr(f"{ep}-media", members=["camera", "audio"])

# Roll them up into a single training set
dl.bindr(
    "training-set-v1",
    project="robotics@alice",
    bindrs=["run-100-media", "run-101-media", "run-102-media"],
    description="V1 training set — every run's media",
)

# Download walks the parent into the children and pulls everything
dl.download_bindr("training-set-v1", project="robotics@alice", to="./train/")

The new kwarg is bindrs= — distinct from members= (paths). You can pass both:

python
dl.bindr(
    "experiment-X",
    project="robotics@alice",
    members=["/run-100/meta.json"],     # specific file
    bindrs=["run-100-media"],            # plus a whole nested bindr
)

Cycles are rejected

The server runs a reachability check on every add. Trying to put a bindr inside one of its own descendants is rejected with 400 cycle detected:

python
# Suppose A contains B. This fails:
dl.bindr("B", project="robotics@alice", bindrs=["A"])
# → httpx.HTTPStatusError: 400 cycle detected

download_bindr also tracks visited bindr IDs at download time — even if a cycle somehow slipped through, the recursion terminates.

Bindrs vs folders vs episodes

FolderEpisodeBindr
Stores data?No (tree node)No (tree node)No (just refs)
Has a fixed location?Yes — under one parentYes — under one projectNo — references anywhere
Members can be from different episodes?NoN/AYes
Moves with the data?Yes (rename folder = rename path)YesNo (paths frozen at creation)

Use folders to organize. Use episodes to demarcate experiment runs. Use bindrs to assemble curated views that cut across the structural hierarchy.

What you can do next