# Builders

## timenet.builders

Builder discovery: how the SDK finds something able to build a dataset the registry lacks.

The SDK cannot import a connectors package (the dependency runs the other way), so a build
backend registers itself under the `timenet.builders` entry-point group instead. This keeps the
SDK's whole knowledge of building to one protocol and one lookup, and lets a third-party connector
package plug in the same way the first-party one does.

### ENTRY\_POINT\_GROUP `module-attribute`

```
ENTRY_POINT_GROUP = 'timenet.builders'
```

### BuilderBackend

Bases: `Protocol`

Something that can build a dataset from its connector.

#### build

```
build(
    dataset_id: str, root: Path, *, force: bool = False
) -> Path
```

Build the dataset into a registry directory.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `dataset_id` | `str` | The dataset id. | *required* |
| `root` | `Path` | The output registry directory. | *required* |
| `force` | `bool` | Rebuild even if the version is already built. | `False` |

Returns:

| Type | Description |
| --- | --- |
| `Path` | The committed version directory. |

#### declared\_version

```
declared_version(dataset_id: str) -> str | None
```

Return the version the connector declares, without importing or building it.

A caller checks a version pin against this before the build runs, so a pin the connector
cannot satisfy fails fast instead of after a full build. Answer without importing the
connector, like :meth:`knows`.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `dataset_id` | `str` | The dataset id. | *required* |

Returns:

| Type | Description |
| --- | --- |
| `str | None` | The declared version string, or `None` if it cannot be read. |

#### knows

```
knows(dataset_id: str) -> bool
```

Report whether this backend has a connector for the id.

Implementations must answer without importing the connector: this runs before any
connector environment exists.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `dataset_id` | `str` | The dataset id. | *required* |

Returns:

| Type | Description |
| --- | --- |
| `bool` | Whether the backend can build it. |

### find\_builder

```
find_builder(dataset_id: str) -> BuilderBackend | None
```

Return the first registered backend that claims this dataset id.

Parameters:

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `dataset_id` | `str` | The dataset id. | *required* |

Returns:

| Type | Description |
| --- | --- |
| `BuilderBackend | None` | The backend, or `None` when no installed package claims the id. |