AgML: A Data Loading Layer for Agricultural Machine Learning
AgML is a centralized framework for agricultural machine learning. AgML provides access to public agricultural datasets for common agricultural deep learning tasks, with standard benchmarks and pretrained models, as well the ability to generate synthetic data and annotations.
At a glance
- What is it?
- AgML wraps public agricultural datasets behind one loader class and exports them to TensorFlow or PyTorch. It is useful if your bottleneck is dataset plumbing, not modelling, and its own README is explicit that the ag-specific ML functionality is still to come.
- Who is it for?
- Adopt AgML if you need public agricultural imagery in a TensorFlow or PyTorch training loop and want to skip writing per-dataset download and parsing code. Do not adopt it if you need agronomy-specific modelling components or a stable API: the README states that ag-specific ML functionality is a future goal, the annotation-format section is truncated, and the 0.7.x to 0.8.0 release line shows the interface is still moving.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 4 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The agricultural dataset plumbing problem AgML targets
Public agricultural imagery is scattered across university repositories, competition archives and institutional pages. Each one ships its own directory layout, its own annotation encoding and its own licence terms. A team that wants to compare a segmentation model across three crops spends more time writing parsers than writing models. AgML's answer is to put every supported dataset behind one class, agml.data.AgMLDataLoader, and to normalise the parts that downstream training code actually touches: batching, shuffling, train/val/test splitting, transforms and tensor conversion. The audience is applied ML engineers and research groups working on crop and plant imagery who already have a training pipeline and want the data end handled. It is not aimed at agronomists who want to run a model without writing Python, and it is not an annotation tool. The README is direct about scope: the library currently provides access to public agricultural datasets, and ag-specific ML functionality related to data, training and evaluation is described as a future direction.
AgMLDataLoader as the central abstraction
Everything routes through the loader. You construct it with a dataset name string, as in agml.data.AgMLDataLoader('apple_flower_segmentation'), and the library downloads the data locally on first use, then reloads from disk on later runs. That caching behaviour is stated in the usage section, and it matters: the first call on a large dataset is a network operation, not a local one.
The processing API is chainable and mutable. loader.batch(8) groups samples, loader.shuffle() randomises order, loader.mask_to_channel_basis() rewrites segmentation masks into channel form, and loader.transform() takes two arguments: transform for the input image and dual_transform for paired image and mask augmentation, with albumentations objects passed in. loader.split(train=0.8, val=0.1, test=0.1) produces loader.train_data, loader.val_data and loader.test_data.
The subtle part is the split semantics. The README states that further processing applied to the main loader propagates to the split datasets until the split attributes are accessed, after which each split must be processed independently. That is a one-way latch, and code that splits early and then tries to batch the parent will silently do nothing useful. The escape hatches are loader.eval(), loader.reset_preprocessing() and loader.disable_preprocessing(), which are worth knowing before you debug a transform that appears not to apply.
Exporting to TensorFlow and PyTorch, and the training shortcut
AgML does not ask you to adopt its own training loop. The README shows two export routes: loader.train_data.export_tensorflow() returns a tf.data.Dataset, and calling as_torch_dataset() on a loader converts data into PyTorch tensors without a full export. The README also notes that conversion happens internally within the AgMLDataLoader, which is how the loader keeps its own methods usable after conversion.
On top of that sits a small training module. The grape detection example builds a loader for 'grape_detection_californiaday', splits it, constructs agml.models.preprocessing.EfficientDetPreprocessor with image_size=512 and an albumentations augmentation list, applies it via loader.transform(processor), instantiates agml.models.DetectionModel(num_classes=loader.num_classes) and calls model.run_training(loader). The preprocessor is named for EfficientDet, so the training path is tied to specific detector families rather than being model-agnostic. Treat run_training as a baseline generator for sanity checks, not as a replacement for your own loop.
Installation, WSL and the GUI dependency
Installation is a single command: pip install agml. The README flags one environment constraint that is easy to miss until it bites. Some features, synthetic data generation named specifically, require GUI applications. Under Windows Subsystem for Linux this means configuring WSL for Linux GUI apps per Microsoft's documentation; recent WSL versions include built-in support. If your CI runs headless Linux containers, assume the synthetic data path is unavailable there unless you have arranged a display. The README does not describe a headless mode for that feature, so plan around it rather than assuming a flag exists.
The library states support for both TensorFlow and PyTorch. The README does not specify version floors for either, and it does not state which framework is installed by default with pip install agml. Verify that before you pin dependencies in a shared environment.
iNatAg and the parent-dataset filtering API
The largest single data asset described is iNatAg, with iNatAg-mini as a smaller variant. The README states the collection contains over 4 million images with species classifications and is intended for image classification. Access uses a different constructor than the standard loader: agml.data.AgMLDataLoader.from_parent("iNatAg", filters={"family_name": ["...", "..."]}) selects by scientific family, and filters={"common_name": "..."} selects by common name. This is a filtering interface over a parent collection rather than a fixed dataset name, which is a meaningfully different code path from the apple_flower_segmentation style of construction. The README does not document the full set of filter keys, so you are working from the two examples given. It also does not state download sizes or per-species counts for iNatAg-mini, which are the numbers you would want before provisioning storage.
Where AgML is the wrong tool
The clearest limitation is stated by the project itself: ag-specific ML functionality related to data, training and evaluation is described in the future tense. If you came for crop-specific loss functions, phenology-aware augmentation or agronomic evaluation metrics, they are not what this library currently offers. What exists today is dataset access plus generic deep learning plumbing.
The second limitation is documentation completeness in the supplied material. The README's annotation-format section is truncated mid-sentence, so the range of supported annotation encodings cannot be confirmed from what is available. If your dataset of interest uses an exotic format, you cannot tell from this text whether AgML handles it.
The third is API stability. The release line runs v0.7.3, v0.7.4 and then v0.8.0, a minor-version jump. In a pre-1.0 library that usually signals interface change. Pin your version. Teams that need a frozen data contract for a multi-year study should weigh that against the convenience.
Finally, the loader is a convenience layer over downloads. If your data is already local and preprocessed, or if it lives behind an institutional access agreement that AgML does not cover, the library adds a dependency without removing work.
Alternatives and the difference in approach
The obvious comparison is a general dataset library such as Hugging Face datasets. That project treats datasets as a broad, format-agnostic catalogue with its own on-disk format and streaming support, and is not organised around agricultural tasks. AgML is narrow by design: fewer datasets, but the loader, the split semantics and the TensorFlow and PyTorch export paths are built around image classification, object detection and semantic segmentation on plant imagery. If your work is agricultural, AgML removes per-dataset glue that a general library leaves to you. If your work spans domains, the general library will have more of what you need and AgML will be one more dependency.
The other realistic alternative is writing your own download and parse scripts. That is more code, but it gives you exact control over caching location, annotation remapping and version pinning, and it does not move when a pre-1.0 library changes its interface. The trade is maintenance burden against upgrade risk. AgML's value is highest when you need several datasets, because the per-dataset saving compounds.
Licence and the cost of keeping up
AgML itself is Apache-2.0, which permits commercial use and modification with the usual notice and patent-grant terms. That covers the library code, not the datasets. The README points to project-agml.github.io/datasets for browsing, and dataset licences are separate instruments set by the original collectors. Some agricultural image collections carry non-commercial or research-only terms. Nothing in the supplied material summarises those terms, so check each dataset's own licence before you ship a model trained on it. This is a factual boundary, not legal advice.
Maintenance cost has two parts. Upstream, you inherit the library's release cadence: three releases are listed between March 2025 and July 2026, with a minor-version bump at the end. Budget for reading release notes before upgrading, and pin agml in your requirements. Downstream, dataset URLs and remote layouts change without warning, and a loader that fetches on first use will fail at that moment. Cache the downloaded data in your own storage so a broken upstream URL does not block a training run. The README does not describe an offline or mirror mode, so that caching is something you arrange outside the library.
Editorial conclusion
Adopt AgML if you need public agricultural imagery in a TensorFlow or PyTorch training loop and want to skip writing per-dataset download and parsing code. Do not adopt it if you need agronomy-specific modelling components or a stable API: the README states that ag-specific ML functionality is a future goal, the annotation-format section is truncated, and the 0.7.x to 0.8.0 release line shows the interface is still moving. Before committing, verify that your target dataset appears at project-agml.github.io/datasets, confirm the annotation format it ships in, and check whether the export path you need (export_tensorflow or as_torch_dataset) is covered for that dataset's task type.
Community notes