> ## Documentation Index
> Fetch the complete documentation index at: https://wiki.latch.bio/llms.txt
> Use this file to discover all available pages before exploring further.

# UI Definition

> Define and customize the Latch workflow interface.

## Overview

The Latch platform uses metadata objects to define and customize workflow interfaces. If you are using the Python SDK, you can define the metadata object in your workflow code. If you are using Nextflow or Snakemake, the metadata object is auto-generated from the `nextflow_json.schema` or `config.yaml` file using the `latch generate-metadata` command.

This document provides a comprehensive reference for all metadata types available in the Latch SDK.

## Examples

Visit a few examples that our engineers have curated below:

<Card title="nf-core/atacseq" icon="https://files.svgcdn.io/vscode-icons/file-type-nextflow.png" horizontal>
  ATAC-seq peak-calling and QC analysis pipeline, uploaded using the Nextflow SDK.
  [Workflow UI](https://console.latch.bio/workflows/110336/parameters)
  [Source Code](https://github.com/latchbio-nfcore/atacseq/blob/master/latch_metadata/__init__.py)
</Card>

<Card title="Boltz-2" icon="python" horizontal>
  A biomolecular foundation model that jointly predicts structure and binding affinity, uploaded using the Python SDK.
  [Workflow UI](https://console.latch.bio/workflows/111064/parameters)
  [Source Code](https://github.com/latchbio-workflows/wf-latchbio-boltz2/blob/main/wf/__init__.py#L155)
</Card>

## Core Metadata Classes

### `LatchMetadata`

The primary metadata class for Python SDK workflows.

```python theme={null}
from latch.types.metadata import LatchMetadata, LatchParameter, LatchAuthor

metadata = LatchMetadata(
    display_name="Workflow Name",
    author=LatchAuthor(
        name="Your Name",
        email="your.email@example.com",
        github="https://github.com/username"
    ),
    documentation="https://github.com/author/my_workflow/README.md",
    repository="https://github.com/author/my_workflow",
    license="MIT",
    parameters={
        'param_name': LatchParameter(
            display_name="Parameter Display Name",
            description="Parameter description",
            hidden=False,
            section_title="Section Title"
        )
    },
    tags=["NGS", "MAG"],
    flow=[...],
    no_standard_bulk_execution=False,
    about_page_path=Path("about.md")
)
```

#### Parameters

* **`display_name`** (str): The human-readable name of the workflow
* **`author`** (LatchAuthor): Author information for the workflow
* **`documentation`** (str, optional): Link to workflow documentation
* **`repository`** (str, optional): Link to source code repository
* **`license`** (str): SPDX license identifier (default: "MIT")
* **`parameters`** (Dict\[str, LatchParameter]): Parameter definitions
* **`wiki_url`** (str, optional): Link to wiki documentation
* **`video_tutorial`** (str, optional): Link to video tutorial
* **`tags`** (List\[str]): Tags for workflow discovery
* **`flow`** (List\[FlowBase]): Custom parameter layouts
* **`no_standard_bulk_execution`** (bool): Disable standard CSV bulk execution
* **`about_page_path`** (Path, optional): Path to about page markdown file

### `NextflowMetadata`

Metadata class for Nextflow workflows.

```python theme={null}
from latch.types.metadata import NextflowMetadata, NextflowParameter, LatchAuthor
from latch.types.metadata import NextflowRuntimeResources

metadata = NextflowMetadata(
    display_name="Nextflow Workflow",
    author=LatchAuthor(name="Your Name"),
    parameters={
        'input_file': NextflowParameter(
            type=LatchFile,
            display_name="Input File",
            description="Input file description"
        )
    },
    runtime_resources=NextflowRuntimeResources(
        cpus=8,
        memory=16,
        storage_gib=200
    ),
    execution_profiles=["docker", "test"],
    log_dir=LatchDir("latch:///log_directory"),
    upload_command_logs=True
)
```

#### Parameters

* **`display_name`** (str): Workflow display name
* **`author`** (LatchAuthor): Author information
* **`parameters`** (Dict\[str, NextflowParameter]): Parameter definitions
* **`runtime_resources`** (NextflowRuntimeResources): Resource configuration
* **`execution_profiles`** (List\[str]): Available execution profiles
* **`log_dir`** (LatchDir, optional): Directory for workflow logs
* **`upload_command_logs`** (bool): Upload command logs to Latch Data

### `SnakemakeMetadata`

Metadata class for Snakemake workflows.

```python theme={null}
from latch.types.metadata import SnakemakeMetadata, SnakemakeParameter, LatchAuthor
from latch.types.metadata import DockerMetadata, EnvironmentConfig

metadata = SnakemakeMetadata(
    display_name="Snakemake Workflow",
    author=LatchAuthor(name="Your Name"),
    parameters={
        'samples': SnakemakeParameter(
            type=List[Sample],
            display_name="Samples",
            samplesheet=True
        )
    },
    file_metadata={
        'samples': SnakemakeFileMetadata(
            path=Path('data/samples/'),
            config=True,
            download=False
        )
    },
    output_dir=LatchDir("latch:///output_directory"),
    docker_metadata=DockerMetadata(
        username="username",
        secret_name="docker_secret"
    ),
    env_config=EnvironmentConfig(
        use_conda=True,
        use_container=False
    ),
    cores=8,
    about_page_content=Path("about.md")
)
```

#### Parameters

* **`display_name`** (str): Workflow display name
* **`author`** (LatchAuthor): Author information
* **`parameters`** (Dict\[str, SnakemakeParameter]): Parameter definitions
* **`file_metadata`** (FileMetadata): File-specific metadata
* **`output_dir`** (LatchDir, optional): Output directory location
* **`docker_metadata`** (DockerMetadata, optional): Docker credentials
* **`env_config`** (EnvironmentConfig): Environment configuration
* **`cores`** (int): Number of cores for Snakemake tasks
* **`about_page_content`** (Path, optional): Path to about page content

## Parameter Classes

### `LatchParameter`

Base parameter class for Python SDK workflows.

```python theme={null}
LatchParameter(
    display_name="Parameter Name",
    description="Parameter description",
    hidden=False,
    section_title="Section Title",
    placeholder="Enter value...",
    comment="Additional comment",
    output=False,
    batch_table_column=False,
    allow_dir=True,
    allow_file=True,
    appearance_type=LatchAppearanceEnum.line,
    rules=[LatchRule(...)],
    detail="Additional detail text",
    samplesheet=False,
    allowed_tables=[1, 2, 3]
)
```

#### Parameters

* **`display_name`** (str, optional): Human-readable parameter name
* **`description`** (str, optional): Parameter description/tooltip
* **`hidden`** (bool): Whether parameter is hidden by default
* **`section_title`** (str, optional): Section grouping title
* **`placeholder`** (str, optional): Placeholder text for input
* **`comment`** (str, optional): Additional comment text
* **`output`** (bool): Whether parameter is an output
* **`batch_table_column`** (bool): Show in batch mode table
* **`allow_dir`** (bool): Accept directories in UI
* **`allow_file`** (bool): Accept files in UI
* **`appearance_type`** (LatchAppearance): UI appearance type
* **`rules`** (List\[LatchRule]): Validation rules
* **`detail`** (str, optional): Secondary label text
* **`samplesheet`** (bool, optional): Enable samplesheet input
* **`allowed_tables`** (List\[int], optional): Allowed registry tables

### `NextflowParameter`

Parameter class for Nextflow workflows.

```python theme={null}
NextflowParameter(
    type=typing.Any,  # Required for Nextflow
    display_name="Parameter Name",
    description="Description",
    default=None,
    samplesheet=False,
    samplesheet_type='csv',
    samplesheet_constructor=custom_constructor,
    results_paths=[Path("output1"), Path("output2")]
)
```

#### Parameters

* **`type`** (Type\[T], optional): Expected parameter type
* **`display_name`** (str, optional): Parameter display name
* **`description`** (str, optional): Parameter description
* **`default`** (T, optional): Default parameter value
* **`samplesheet`** (bool, optional): Enable samplesheet input
* **`samplesheet_type`** (Literal\["csv", "tsv", None]): Samplesheet format
* **`samplesheet_constructor`** (Callable\[\[T], Path], optional): Custom constructor
* **`results_paths`** (List\[Path], optional): Output sub-paths for UI

### `SnakemakeParameter`

Parameter class for Snakemake workflows.

```python theme={null}
SnakemakeParameter(
    type=typing.Any,  # Required for Snakemake
    display_name="Parameter Name",
    description="Description",
    default=None
)
```

#### Parameters

* **`type`** (Type\[T], optional): Expected parameter type
* **`display_name`** (str, optional): Parameter display name
* **`description`** (str, optional): Parameter description
* **`default`** (T, optional): Default parameter value

## Organization of Parameters into Sections

By default, all parameters are rendered from top to bottom on the workflow UI, in the order they are defined in the metadata object. This can be overwhelming for end users if workflows have dozens or hundreds of parameters.

To make the UI more user-friendly, you can organize parameters into `Section`s and take advantage of elements like `Spoiler` or `Fork` to collapse advanced parameters.

### Custom Flows

Define custom parameter layouts using flow elements:

```python theme={null}
flow=[
    Section(
        "Input Section",
        Text("Configure your input data"),
        Params("input_file", "output_dir")
    ),
    Section(
        "Processing Options",
        Text("Configure processing parameters"),
        Params("threads", "memory")
    ),
    Spoiler(
        "Advanced Options",
        Text("Advanced configuration options"),
        Params("advanced_param1", "advanced_param2")
    )
]
```

### Appearance Customization

Customize parameter appearance:

```python theme={null}
appearance_type=LatchAppearance(
    type=LatchAppearanceEnum.paragraph,
    placeholder="Enter detailed description...",
    comment="This field supports markdown formatting",
    detail="Additional context information"
)
```

## Flow Elements

### `Section`

Flow element that displays child flow in a titled card.

```python theme={null}
Section(
    "Section Title",
    Text("Description text"),
    Params("param1", "param2"),
    Fork(...)
)
```

### `Text`

Flow element that displays markdown text.

```python theme={null}
Text("This is markdown text with **bold** and *italic* formatting")
```

### `Title`

Flow element that displays a markdown title.

```python theme={null}
Title("# Main Title")
```

### `Params`

Flow element that displays parameter widgets.

```python theme={null}
Params("param1", "param2", "param3")
```

### `Spoiler`

Flow element that displays a collapsible card.

```python theme={null}
Spoiler(
    "Advanced Options",
    Text("These are advanced configuration options"),
    Params("advanced_param1", "advanced_param2")
)
```

### `Fork`

Flow element that displays mutually exclusive alternatives.

```python theme={null}
Fork(
    "sample_fork",
    "Choose read type",
    paired_end=ForkBranch("Paired-end", Params("paired_end")),
    single_end=ForkBranch("Single-end", Params("single_end"))
)
```

## Supporting Classes

### `LatchAuthor`

Author information for workflows.

```python theme={null}
LatchAuthor(
    name="Author Name",
    email="author@example.com",
    github="https://github.com/username"
)
```

### `LatchRule`

Validation rule for parameter inputs.

```python theme={null}
LatchRule(
    regex=r"\.(fastq|fq)$",
    message="Only .fastq or .fq files are allowed"
)
```

### `LatchAppearance`

Parameter appearance configuration.

```python theme={null}
# Line input
appearance_type=LatchAppearanceEnum.line

# Paragraph input
appearance_type=LatchAppearanceEnum.paragraph

# Multiselect with custom options
appearance_type=Multiselect(
    options=[
        MultiselectOption("Option 1", "value1"),
        MultiselectOption("Option 2", "value2")
    ],
    allow_custom=True
)
```

### `SnakemakeFileMetadata`

File-specific metadata for Snakemake workflows.

```python theme={null}
SnakemakeFileMetadata(
    path=Path('local/path/'),
    config=True,
    download=False
)
```

### `NextflowRuntimeResources`

Resource configuration for Nextflow runtime tasks.

```python theme={null}
NextflowRuntimeResources(
    cpus=8,
    memory=16,
    storage_gib=200,
    storage_expiration_hours=168  # 7 days
)
```

### `DockerMetadata`

Credentials for private Docker repositories.

```python theme={null}
DockerMetadata(
    username="docker_username",
    secret_name="docker_password_secret"
)
```

### `EnvironmentConfig`

Environment configuration for Snakemake tasks.

```python theme={null}
EnvironmentConfig(
    use_conda=True,
    use_container=False,
    container_args=["--gpus", "all"]
)
```

## Type System

### Supported Parameter Types

```python theme={null}
ParameterType = Union[
    None,
    int,
    float,
    str,
    bool,
    LatchFile,
    LatchDir,
    Enum,
    _IsDataclass,  # Any dataclass
    Collection["ParameterType"],  # Lists, Dicts, etc.
]
```

### Type Validation

The SDK automatically validates parameter types based on:

* Function signature type annotations
* Metadata parameter definitions
* Runtime value validation
* Custom validation rules via `LatchRule`

## Samplesheet Support

### Basic Samplesheet

```python theme={null}
'samples': NextflowParameter(
    type=List[Sample],
    samplesheet=True,
    samplesheet_type='csv'
)
```

### Custom Samplesheet Constructor

```python theme={null}
def custom_constructor(samples: List[Sample]) -> Path:
    # Custom logic to create samplesheet
    return Path("custom_samplesheet.txt")

'samples': NextflowParameter(
    type=List[Sample],
    samplesheet=True,
    samplesheet_constructor=custom_constructor
)
```

### `SamplesheetItem`s

Often when populating a samplesheet parameter using rows from Registry, it is useful to have access to the originating record that created the row. Wrapping a samplesheet type with the `SamplesheetItem` marker allows downstream code to easily access this underlying record.

```python theme={null}
from latch.types.samplesheet_item import SamplesheetItem

@dataclass
class Sample:
    fastq_1: LatchFile
    fastq_2: Optional[LatchFile]

@task
def example(input: list[SamplesheetItem[Sample]]):
    for row in input:
        print(row.data) # `Sample` object, contains the underlying data of the row
        print(row.record) # `Record` object, None if the row wasn't imported from registry

```

## Validation and Rules

### Regex Validation

```python theme={null}
'filename': LatchParameter(
    display_name="Filename",
    rules=[
        LatchRule(
            regex=r"^[a-zA-Z0-9_-]+$",
            message="Filename must contain only letters, numbers, underscores, and hyphens"
        )
    ]
)
```

### Multiple Rules

```python theme={null}
'email': LatchParameter(
    display_name="Email",
    rules=[
        LatchRule(
            regex=r"^[^@]+@[^@]+\.[^@]+$",
            message="Must be a valid email address"
        ),
        LatchRule(
            regex=r"^.{5,100}$",
            message="Email must be between 5 and 100 characters"
        )
    ]
)
```