# 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:

```python file="bindr_create.py"
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.

```python file="nested.py"
# 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

| | Folder | Episode | Bindr |
| --- | --- | --- | --- |
| Stores data? | No (tree node) | No (tree node) | No (just refs) |
| Has a fixed location? | Yes — under one parent | Yes — under one project | No — references anywhere |
| Members can be from different episodes? | No | N/A | Yes |
| Moves with the data? | Yes (rename folder = rename path) | Yes | No (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

- [Download Files](/examples-download.md) — direct download by path or node ID
- [Upload an Episode](/examples-upload-episode.md) — get data into the tree to bindr in the first place
