Install & Compatibility
Where this runs
tested against v0.0.20 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.10
✕ build_error
✓ 57.63s
py 3.11
✕ build_error
✓ 55.99s
py 3.12
✕ build_error
✓ 54.45s
py 3.13
✕ build_error
✕ build_error
py 3.9
✕ build_error
✓ 59.48s
3072MB installed
● package 3072MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Task
✓ from seqio import Task
Mixture
✓ from seqio import Mixture
FunctionDataSource
✓ from seqio import FunctionDataSource
Feature
✓ from seqio import Feature
Vocabulary
✓ from seqio import Vocabulary
preprocessors
✓ from seqio import preprocessors
get_mixture_or_task
✓ from seqio import get_mixture_or_task
This quickstart demonstrates how to define a custom task in SeqIO, including a data source function, a preprocessor to convert data into integer IDs, and a mock vocabulary. It registers the task and then retrieves a processed `tf.data.Dataset` for inspection. This setup forms the basis for training sequence models.
import seqio
import tensorflow as tf
import functools
# 1. Define a minimal mock vocabulary (required for seqio.Feature)
class SimpleVocabulary(seqio.Vocabulary):
def _encode(self, s): return [ord(c) for c in s] # Simple char to int
def _decode(self, ids): return "".join([chr(i) for i in ids]) # Simple int to char
@property
def EOS_ID(self): return 1
@property
def vocab_size(self): return 256 # ASCII range
# 2. Define a data source function that returns a tf.data.Dataset
def my_data_source_fn(split, shuffle_files=False):
if split == "train":
return tf.data.Dataset.from_tensor_slices({
"inputs": ["hello world", "python is fun"],
"targets": ["olleh dlrow", "nohtyp si nuf"] # Simple reverse task
})
raise ValueError(f"Unknown split: {split}")
# 3. Define a simple preprocessor (converts string to integer IDs)
@seqio.map_over_dataset_fn
def tokenize_example(example):
return {
"inputs": tf.constant([ord(c) for c in example["inputs"].numpy().decode()], dtype=tf.int32),
"targets": tf.constant([ord(c) for c in example["targets"].numpy().decode()], dtype=tf.int32),
}
# 4. Register the task with SeqIO
seqio.Task.make_task(
name="simple_reverse_task",
source=seqio.FunctionDataSource(
dataset_fn=my_data_source_fn,
splits=["train"]
),
preprocessors=[
tokenize_example,
functools.partial(seqio.preprocessors.trim_and_pad,
output_features={"inputs": 20, "targets": 20}),
seqio.preprocessors.append_eos_after_trim,
],
output_features={
"inputs": seqio.Feature(vocabulary=SimpleVocabulary(), add_eos=True),
"targets": seqio.Feature(vocabulary=SimpleVocabulary(), add_eos=True)
}
)
# 5. Retrieve the task and get its processed dataset
task = seqio.get_mixture_or_task("simple_reverse_task")
ds = task.get_dataset(
sequence_length={"inputs": 20, "targets": 20}, # Max sequence length for features
split="train",
shuffle=False
)
# 6. Iterate through an example to verify
for ex in ds.take(1):
print("\n--- Processed Example ---")
print("Raw features:", {k: v.numpy() for k, v in ex.items()})
decoded_inputs = task.output_features["inputs"].vocabulary.decode(ex["inputs"].numpy())
decoded_targets = task.output_features["targets"].vocabulary.decode(ex["targets"].numpy())
print(f"Decoded inputs: '{decoded_inputs}'")
print(f"Decoded targets: '{decoded_targets}'")
Errors
Common errors & fixes
ValueError: No dataset found for split 'validation' for task 'my_task'
The specified split ('validation') was not listed in the `splits` argument when defining the `seqio.FunctionDataSource` or `seqio.TfdsDataSource` for the task.
fixEnsure the `splits` list in your `seqio.FunctionDataSource` (or equivalent) includes all splits you intend to use, e.g., `splits=["train", "validation"]`.
AttributeError: module 'tensorflow' has no attribute 'lookup'
This often indicates a version mismatch between `tensorflow` and `seqio`/`t5` dependencies. Specific `tf.lookup` functions or modules might have moved or been deprecated.
fixUpgrade `tensorflow` to a compatible version (usually `>=2.9.0` for `seqio`) and ensure `t5` (if used) is also up-to-date. Check `seqio`'s `setup.py` for exact `tensorflow` requirements.
gin.config.exceptions.InvalidConfigError: Unreachable configurable 'MyClass' for value
This error from `gin-config` means that a class or function expected to be configurable by Gin was not decorated with `@gin.configurable` or imported correctly before `gin.parse_config_file` or `gin.enter_interactive_mode` was called.
fixVerify that all classes and functions intended for Gin configuration are decorated with `@gin.configurable`. Ensure the Python module containing these configurables is imported before any Gin configuration takes place.
TypeError: 'tf.Tensor' object is not iterable
This typically occurs in a preprocessor function when attempting to iterate directly over a `tf.Tensor` that represents a scalar or a single element, or when string operations are performed on a `tf.Tensor` instead of its decoded `.numpy()` value.
fixWhen working with `tf.Tensor` within preprocessors, especially for string manipulation, remember to convert the tensor to a NumPy array and then decode it to a Python string: `tensor.numpy().decode('utf-8')`. Convert back to `tf.Tensor` before returning. Upgrade
Version history
0.0.20latest on PyPI · released Aug 28, 2025
Audit
Dependencies
tensorflowoptionalCommon backend for sequence models and data pipelines
t5optionalOften used in conjunction with SeqIO for T5 model training
gin-configrequiredUsed for declarative configuration of tasks and models
absl-pyrequiredGoogle's Python Common Libraries, used internally
numpyrequiredFundamental numerical computing library
jaxoptionalAlternative backend for high-performance numerical computing