> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nemo/datadesigner/llms.txt.
> For full documentation content, see https://docs.nvidia.com/nemo/datadesigner/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nemo/datadesigner/_mcp/server.

# data\_designer.engine.resources.seed\_reader

## Module Contents

### Classes

| Name                                                                                                       | Description                                                           |
| ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| [`SeedReaderFileSystemContext`](#data_designerengineresourcesseed_readerseedreaderfilesystemcontext)       | Filesystem and root path available to filesystem seed-reader plugins. |
| [`SeedReaderBatch`](#data_designerengineresourcesseed_readerseedreaderbatch)                               | Batch object returned by seed readers and convertible to a DataFrame. |
| [`SeedReaderBatchReader`](#data_designerengineresourcesseed_readerseedreaderbatchreader)                   | Reader that yields seed batches until exhausted.                      |
| [`PandasSeedReaderBatch`](#data_designerengineresourcesseed_readerpandasseedreaderbatch)                   | Seed-reader batch backed by an in-memory pandas DataFrame.            |
| [`DuckDBSeedReaderBatchReader`](#data_designerengineresourcesseed_readerduckdbseedreaderbatchreader)       | None                                                                  |
| [`HydratingSeedReaderBatchReader`](#data_designerengineresourcesseed_readerhydratingseedreaderbatchreader) | None                                                                  |
| [`SeedReader`](#data_designerengineresourcesseed_readerseedreader)                                         | Base class for reading a seed dataset.                                |
| [`LocalFileSeedReader`](#data_designerengineresourcesseed_readerlocalfileseedreader)                       | Base class for reading a seed dataset.                                |
| [`HuggingFaceSeedReader`](#data_designerengineresourcesseed_readerhuggingfaceseedreader)                   | Base class for reading a seed dataset.                                |
| [`DataFrameSeedReader`](#data_designerengineresourcesseed_readerdataframeseedreader)                       | Base class for reading a seed dataset.                                |
| [`FileSystemSeedReader`](#data_designerengineresourcesseed_readerfilesystemseedreader)                     | Base class for filesystem-derived seed readers.                       |
| [`DirectorySeedReader`](#data_designerengineresourcesseed_readerdirectoryseedreader)                       | Base class for filesystem-derived seed readers.                       |
| [`FileContentsSeedReader`](#data_designerengineresourcesseed_readerfilecontentsseedreader)                 | Base class for filesystem-derived seed readers.                       |
| [`AgentRolloutSeedReader`](#data_designerengineresourcesseed_readeragentrolloutseedreader)                 | Base class for filesystem-derived seed readers.                       |
| [`SeedReaderRegistry`](#data_designerengineresourcesseed_readerseedreaderregistry)                         | None                                                                  |

### Functions

| Name                                                                                                                 | Description                                                                      |
| -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| [`create_seed_reader_output_dataframe`](#data_designerengineresourcesseed_readercreate_seed_reader_output_dataframe) | Create a DataFrame and verify hydrated records match the declared output schema. |
| [`_build_metadata_record`](#data_designerengineresourcesseed_reader_build_metadata_record)                           | None                                                                             |
| [`_normalize_relative_path`](#data_designerengineresourcesseed_reader_normalize_relative_path)                       | None                                                                             |
| [`_normalize_hydrated_row_output`](#data_designerengineresourcesseed_reader_normalize_hydrated_row_output)           | None                                                                             |

### Data

[`logger`](#data_designerengineresourcesseed_readerlogger)
[`SourceT`](#data_designerengineresourcesseed_readersourcet)
[`FileSystemSourceT`](#data_designerengineresourcesseed_readerfilesystemsourcet)

### API

```python
logger = getLogger(...)
```

```python
class data_designer.engine.resources.seed_reader.SeedReaderError
```

**Bases**: `data_designer.errors.DataDesignerError`

```python
class data_designer.engine.resources.seed_reader.SeedReaderFileSystemContext
```

Filesystem and root path available to filesystem seed-reader plugins.

```python
fs: fsspec.spec.AbstractFileSystem
```

```python
root_path: pathlib.Path
```

```python
class data_designer.engine.resources.seed_reader.SeedReaderBatch
```

**Bases**: `typing.Protocol`

Batch object returned by seed readers and convertible to a DataFrame.

```python
to_pandas() -> pandas.DataFrame
```

```python
class data_designer.engine.resources.seed_reader.SeedReaderBatchReader
```

**Bases**: `typing.Protocol`

Reader that yields seed batches until exhausted.

```python
read_next_batch() -> data_designer.engine.resources.seed_reader.SeedReaderBatch
```

```python
class data_designer.engine.resources.seed_reader.PandasSeedReaderBatch
```

Seed-reader batch backed by an in-memory pandas DataFrame.

```python
dataframe: pandas.DataFrame
```

```python
to_pandas() -> pandas.DataFrame
```

Return the batch as a pandas DataFrame.

```python
data_designer.engine.resources.seed_reader.create_seed_reader_output_dataframe(
    *,
    records: list[dict[str, typing.Any]],
    output_columns: list[str]
) -> pandas.DataFrame
```

Create a DataFrame and verify hydrated records match the declared output schema.

```python
class data_designer.engine.resources.seed_reader.DuckDBSeedReaderBatchReader(
    *,
    conn: duckdb.DuckDBPyConnection,
    query_result: typing.Any,
    batch_size: int
)
```

```python
read_next_batch() -> data_designer.engine.resources.seed_reader.SeedReaderBatch
```

```python
class data_designer.engine.resources.seed_reader.HydratingSeedReaderBatchReader(
    *,
    manifest_batch_reader: data_designer.engine.resources.seed_reader.SeedReaderBatchReader,
    hydrate_records: collections.abc.Callable[[list[dict[str, typing.Any]]], list[dict[str, typing.Any]]],
    output_columns: list[str],
    no_rows_error_message: str
)
```

```python
read_next_batch() -> data_designer.engine.resources.seed_reader.SeedReaderBatch
```

```python
SourceT = TypeVar(...)
```

```python
FileSystemSourceT = TypeVar(...)
```

```python
class data_designer.engine.resources.seed_reader.SeedReader
```

**Bases**: `abc.ABC`, `typing.Generic[data_designer.engine.resources.seed_reader.SourceT]`

Base class for reading a seed dataset.

Seeds are read using duckdb. Reader implementations define duckdb connection setup details
and how to get a URI that can be queried with duckdb (i.e. "... FROM \<uri> ...").

The Data Designer engine automatically supplies the appropriate SeedSource
and a SecretResolver to use for any secret fields in the config via
`attach(...)`. Subclasses that need per-attachment setup can override
`on_attach(...)` without needing to call `super()`.

```python
source: data_designer.engine.resources.seed_reader.SourceT
```

```python
secret_resolver: data_designer.engine.secret_resolver.SecretResolver
```

```python
get_dataset_uri() -> str
```

```python
create_duckdb_connection() -> duckdb.DuckDBPyConnection
```

```python
attach(
    source: data_designer.engine.resources.seed_reader.SourceT,
    secret_resolver: data_designer.engine.secret_resolver.SecretResolver
) -> None
```

Attach a source and secret resolver to the instance.

This is called internally by the engine so that these objects do not
need to be provided in the reader's constructor.

```python
on_attach() -> None
```

Hook for subclasses that need per-attachment setup.

```python
_reset_attachment_state() -> None
```

```python
create_dataframe_duckdb_connection(
    *,
    table_name: str,
    dataframe: pandas.DataFrame
) -> duckdb.DuckDBPyConnection
```

```python
get_seed_dataset_size() -> int
```

```python
create_batch_reader(
    *,
    batch_size: int,
    index_range: data_designer.config.seed.IndexRange | None,
    shuffle: bool
) -> data_designer.engine.resources.seed_reader.SeedReaderBatchReader
```

```python
create_filesystem_context(root_path: pathlib.Path | str) -> data_designer.engine.resources.seed_reader.SeedReaderFileSystemContext
```

Create a rooted filesystem context for directory-backed seed readers.

```python
get_matching_relative_paths(
    *,
    context: data_designer.engine.resources.seed_reader.SeedReaderFileSystemContext,
    file_pattern: str,
    recursive: bool
) -> list[str]
```

```python
get_column_names() -> list[str]
```

Returns the seed dataset's column names

```python
_get_duckdb_connection() -> duckdb.DuckDBPyConnection
```

```python
_ensure_attached() -> None
```

```python
build_dataset_read_query(
    *,
    dataset_uri: str,
    index_range: data_designer.config.seed.IndexRange | None,
    shuffle: bool
) -> str
```

```python
get_seed_type() -> str
```

Return the seed\_type of the source class this reader is generic over.

```python
class data_designer.engine.resources.seed_reader.LocalFileSeedReader
```

**Bases**: `data_designer.engine.resources.seed_reader.SeedReader[data_designer.config.seed_source.LocalFileSeedSource]`

```python
create_duckdb_connection() -> duckdb.DuckDBPyConnection
```

```python
get_dataset_uri() -> str
```

```python
class data_designer.engine.resources.seed_reader.HuggingFaceSeedReader
```

**Bases**: `data_designer.engine.resources.seed_reader.SeedReader[data_designer.config.seed_source.HuggingFaceSeedSource]`

```python
create_duckdb_connection() -> duckdb.DuckDBPyConnection
```

```python
get_dataset_uri() -> str
```

```python
class data_designer.engine.resources.seed_reader.DataFrameSeedReader
```

**Bases**: `data_designer.engine.resources.seed_reader.SeedReader[data_designer.config.seed_source_dataframe.DataFrameSeedSource]`

```python
_table_name = df
```

```python
create_duckdb_connection() -> duckdb.DuckDBPyConnection
```

```python
get_dataset_uri() -> str
```

```python
class data_designer.engine.resources.seed_reader.FileSystemSeedReader
```

**Bases**: `data_designer.engine.resources.seed_reader.SeedReader[data_designer.engine.resources.seed_reader.FileSystemSourceT]`, `abc.ABC`

Base class for filesystem-derived seed readers.

Plugin authors implement `build_manifest(...)` to describe the cheap logical
rows available under the configured filesystem root. Readers that need
expensive enrichment can optionally override `hydrate_row(...)` to emit one
record dict or an iterable of record dicts per manifest row. When emitted
records change the manifest schema, `output_columns` must declare the exact
hydrated output schema for each emitted record. The framework owns
attachment-scoped filesystem context reuse, manifest sampling, partitioning,
randomization, batching, and DuckDB registration details.

```python
output_columns: typing.ClassVar[list[str] | None]
```

```python
_reset_attachment_state() -> None
```

```python
create_duckdb_connection() -> duckdb.DuckDBPyConnection
```

```python
get_dataset_uri() -> str
```

```python
get_output_column_names() -> list[str]
```

```python
build_manifest(
    *,
    context: data_designer.engine.resources.seed_reader.SeedReaderFileSystemContext
) -> pandas.DataFrame | list[dict[str, typing.Any]]
```

```python
hydrate_row(
    *,
    manifest_row: dict[str, typing.Any],
    context: data_designer.engine.resources.seed_reader.SeedReaderFileSystemContext
) -> dict[str, typing.Any] | collections.abc.Iterable[dict[str, typing.Any]]
```

```python
get_column_names() -> list[str]
```

```python
get_seed_dataset_size() -> int
```

```python
create_batch_reader(
    *,
    batch_size: int,
    index_range: data_designer.config.seed.IndexRange | None,
    shuffle: bool
) -> data_designer.engine.resources.seed_reader.SeedReaderBatchReader
```

```python
_get_row_manifest_dataframe() -> pandas.DataFrame
```

```python
_get_output_dataframe() -> pandas.DataFrame
```

```python
_get_filesystem_context() -> data_designer.engine.resources.seed_reader.SeedReaderFileSystemContext
```

```python
_get_manifest_dataset_uri() -> str
```

```python
_build_internal_table_name(suffix: str) -> str
```

```python
_get_empty_selected_manifest_rows_error_message() -> str
```

```python
_normalize_rows_to_dataframe(rows: pandas.DataFrame | list[dict[str, typing.Any]]) -> pandas.DataFrame
```

```python
_hydrate_rows(
    *,
    manifest_rows: list[dict[str, typing.Any]],
    context: data_designer.engine.resources.seed_reader.SeedReaderFileSystemContext
) -> list[dict[str, typing.Any]]
```

```python
class data_designer.engine.resources.seed_reader.DirectorySeedReader
```

**Bases**: `data_designer.engine.resources.seed_reader.FileSystemSeedReader[data_designer.config.seed_source.DirectorySeedSource]`

```python
build_manifest(
    *,
    context: data_designer.engine.resources.seed_reader.SeedReaderFileSystemContext
) -> pandas.DataFrame | list[dict[str, typing.Any]]
```

```python
class data_designer.engine.resources.seed_reader.FileContentsSeedReader
```

**Bases**: `data_designer.engine.resources.seed_reader.FileSystemSeedReader[data_designer.config.seed_source.FileContentsSeedSource]`

```python
output_columns = ['source_kind', 'source_path', 'relative_path', 'file_name', 'content']
```

```python
build_manifest(
    *,
    context: data_designer.engine.resources.seed_reader.SeedReaderFileSystemContext
) -> pandas.DataFrame | list[dict[str, typing.Any]]
```

```python
hydrate_row(
    *,
    manifest_row: dict[str, typing.Any],
    context: data_designer.engine.resources.seed_reader.SeedReaderFileSystemContext
) -> dict[str, typing.Any]
```

```python
class data_designer.engine.resources.seed_reader.AgentRolloutSeedReader
```

**Bases**: `data_designer.engine.resources.seed_reader.FileSystemSeedReader[data_designer.config.seed_source.AgentRolloutSeedSource]`

```python
output_columns = get_field_names(...)
```

```python
_PARSE_CONTEXT_UNSET: data_designer.engine.resources.agent_rollout.AgentRolloutParseContext | None = object(...)
```

```python
_reset_attachment_state() -> None
```

```python
build_manifest(
    *,
    context: data_designer.engine.resources.seed_reader.SeedReaderFileSystemContext
) -> list[dict[str, typing.Any]]
```

```python
hydrate_row(
    *,
    manifest_row: dict[str, typing.Any],
    context: data_designer.engine.resources.seed_reader.SeedReaderFileSystemContext
) -> list[dict[str, typing.Any]]
```

```python
get_format_handler() -> data_designer.engine.resources.agent_rollout.AgentRolloutFormatHandler
```

```python
_get_parse_context(context: data_designer.engine.resources.seed_reader.SeedReaderFileSystemContext) -> data_designer.engine.resources.agent_rollout.AgentRolloutParseContext | None
```

```python
class data_designer.engine.resources.seed_reader.SeedReaderRegistry(readers: collections.abc.Sequence[data_designer.engine.resources.seed_reader.SeedReader])
```

```python
add_reader(reader: data_designer.engine.resources.seed_reader.SeedReader) -> typing_extensions.Self
```

```python
get_reader(
    seed_dataset_source: data_designer.config.seed_source.SeedSource,
    secret_resolver: data_designer.engine.secret_resolver.SecretResolver
) -> data_designer.engine.resources.seed_reader.SeedReader
```

```python
_get_reader_for_source(seed_dataset_source: data_designer.config.seed_source.SeedSource) -> data_designer.engine.resources.seed_reader.SeedReader
```

```python
data_designer.engine.resources.seed_reader._build_metadata_record(
    *,
    context: data_designer.engine.resources.seed_reader.SeedReaderFileSystemContext,
    relative_path: str,
    source_kind: str
) -> dict[str, str]
```

```python
data_designer.engine.resources.seed_reader._normalize_relative_path(path: str) -> str
```

```python
data_designer.engine.resources.seed_reader._normalize_hydrated_row_output(
    *,
    hydrated_row_output: dict[str, typing.Any] | collections.abc.Iterable[dict[str, typing.Any]],
    manifest_row_index: int
) -> list[dict[str, typing.Any]]
```