Batching and Input Flexibility

Supported Input Formats

You can provide input in several ways:

1. Single item (string or dict):

• For a single sequence or context.

• Example:

  python Copy

  biolm(entity="esm2-8m", action="encode", type="sequence", items="MSILVTRPSPAGEEL")
  

2. List of values (strings, numbers, etc):

• For a batch of simple items (e.g. sequences). Pass a type so the client knows how to interpret the values.

• Example:

  python Copy

  biolm(entity="esm2-8m", action="encode", type="sequence", items=["SEQ1", "SEQ2"])
  

3. List of dicts:

• For a batch of structured items. Type is inferred from the dict keys.

• Example:

  python Copy

  biolm(entity="esmfold", action="predict", items=[{"sequence": "SEQ1"}, {"sequence": "SEQ2"}])
  

4. Generators and iterators (memory-efficient):

• Pass a generator or any iterable instead of a list. The client consumes it batch-by-batch, so you never hold all items in memory at once.

• Ideal for large files, streams, or lazy data pipelines.

• Note: The generator is fully consumed during the call; you cannot iterate it again afterwards.

• Example:

  python Copy

  def sequences_from_file(path):
      with open(path) as f:
          for line in f:
              seq = line.strip()
              if seq:
                  yield {"sequence": seq}
  
  result = biolm(entity="esm2-8m", action="encode", items=sequences_from_file("sequences.txt"))
  

5. List of lists of dicts (advanced/manual batching):

• Each inner list is treated as a batch and sent as a single API request.

• Useful for custom batching, controlling batch size, or mixing valid/invalid items.

• Example:

  python Copy

  batches = [
      [{"sequence": "SEQ1"}, {"sequence": "SEQ2"}],  # batch 1
      [{"sequence": "SEQ3"}],                        # batch 2
  ]
  biolm(entity="esmfold", action="predict", items=batches)
  

How auto-batching works

The client asks the API for the model’s maximum batch size, splits your input into batches of that size, and sends each batch as a separate request. Results come back in the same order as your input. You don’t need to split manually.

Example:

# If the model's max batch size is 8, this will be split into 2 requests:
items = ["SEQ" + str(i) for i in range(12)]
result = biolm(entity="esm2-8m", action="encode", type="sequence", items=items)
# result is a list of 12 results, in order

Advanced: Manual Batching with List of Lists

• If you provide a list of lists of dicts, each inner list is treated as a batch.

• This disables auto-batching: you control the batch size and composition.

• Useful for:

  • Forcing certain items to be batched together (e.g., for error isolation).

  • Working around API limits or bugs.

  • Testing error handling with mixed valid/invalid batches.

Example:

# Two batches: first has 2 items, second has 1
items = [
    [{"sequence": "SEQ1"}, {"sequence": "BADSEQ"}],  # batch 1
    [{"sequence": "SEQ3"}],                          # batch 2
]
result = biolm(entity="esmfold", action="predict", items=items, stop_on_error=False)
# result is a flat list: [result1, result2, result3]

Input validation

• List of dicts: type is inferred from the keys.

• List of plain values (e.g. strings): pass a type (e.g. sequence) so the client knows how to interpret them.

• List of lists (manual batching): each inner list must be a list of dicts.

Sequence validity

Protein sequences must use only valid amino acid letters. The client accepts the standard set (e.g. ACDEFGHIKLMNPQRSTVWYBXZUO).

Batch size and schema

You can read the maximum batch size from the schema:

from biolm.core.http import BioLMApi
model = BioLMApi("esm2-8m")
schema = model.schema("esm2-8m", "encode")
max_batch = model.extract_max_items(schema)
print("Max batch size:", max_batch)

Batching and errors

If a batch has invalid items, the whole batch may fail. You can halt on the first error batch or process all batches and get error dicts in the results; with the API client you can also retry failed batches as single items. See Error Handling for details and examples.

Summary Table

Examples

Batching with list of dicts:

from biolm import biolm

items = [{"sequence": "SEQ1"}, {"sequence": "SEQ2"}]
result = biolm(entity="esm2-8m", action="encode", items=items)

Batching with list of values:

items = ["SEQ1", "SEQ2"]
result = biolm(entity="esm2-8m", action="encode", type="sequence", items=items)

Manual batching with list of lists:

batches = [
    [{"sequence": "SEQ1"}, {"sequence": "BADSEQ"}],  # batch 1
    [{"sequence": "SEQ3"}],                          # batch 2
]
result = biolm(entity="esmfold", action="predict", items=batches, stop_on_error=False)

Best practices

• Prefer a list of values or dicts and let the client auto-batch.

• For large datasets (files, streams), use a generator so items are consumed batch-by-batch.

• For very large result sets, write to disk (see Disk output in Client interfaces).

• Use manual batching (list of lists) only when you need custom batch sizes or composition.

See Also

• Error Handling

• Client interfaces (includes Disk output)

• Frequently Asked Questions