Orchard ML

Type-safe deep learning framework for reproducible computer vision research

---

CI / CD
Platform
Stack
Static Analysis

---

Table of Contents

• Overview
• Hardware Requirements
• Quick Start
• Colab Notebooks
• Experiment Management
• Documentation
• Citation
• Roadmap
• License

---

Overview

Orchard ML is a research-grade PyTorch training framework engineered for reproducible, scalable computer vision experiments across diverse domains. Built on MedMNIST v2 medical imaging datasets and expanded to astronomical imaging (Galaxy10 DECals) and standard benchmarks (CIFAR-10/100), it provides a domain-agnostic platform supporting multi-resolution architectures (28×28, 32×32, 64×64, 128×128, 224×224), automated hyperparameter optimization, and cluster-safe execution.

Key Differentiators:

• Type-Safe Configuration Engine: Pydantic V2-based declarative manifests eliminate runtime errors
• Idempotent Lifecycle Orchestration: RootOrchestrator coordinates a 7-phase initialization sequence (seeding, runtime config, filesystem, logging, config persistence, infrastructure locks, environment reporting) via Context Manager with full dependency injection
• Zero-Conflict Execution: Kernel-level file locking (fcntl) prevents concurrent runs from corrupting shared resources
• Intelligent Hyperparameter Search: Optuna integration with TPE sampling and Median Pruning
• Hardware-Agnostic: Auto-detection and optimization for CPU/CUDA/MPS backends
• Audit-Grade Traceability: BLAKE2b-hashed run directories with full YAML snapshots

Supported Architectures:

Resolution	Architectures	Parameters	Use Case
28 / 32 / 64 / 128 / 224	ResNet-18	~11M	Multi-resolution baseline, transfer learning
28 / 32 / 64	MiniCNN	~95K	Fast prototyping, ablation studies
128×128	timm/efficientnet_lite0	~4.7M	Edge-friendly, mobile-optimized
128×128	timm/convnextv2_nano	~15.6M	Modern ConvNet V2, FCMAE pretrained
224×224	EfficientNet-B0	~4.0M	Efficient compound scaling
224×224	ConvNeXt-Tiny	~27.8M	Modern ConvNet design
224×224	ViT-Tiny	~5.5M	Patch-based attention, multiple weight variants

Tip

1000+ additional architectures via timm: Any model in the timm registry can be used by prefixing the name with timm/ in your recipe:

architecture:
  name: "timm/mobilenetv3_small_100"   # ~1.5M params, edge-friendly
  pretrained: true

This works with MobileNet, DenseNet, RegNet, EfficientNet-V2, and any other architecture supported by timm. See recipes/config_timm_mobilenetv3.yaml for a ready-to-use example.

---

Hardware Requirements

CPU Training (28×28 / 32×32 / 64×64)

• Supported Resolutions: 28×28, 32×32, 64×64
• Time: ~2.5 hours (ResNet-18, 28×28, 60 epochs, 16 cores)
• Time: ~5-10 minutes (MiniCNN, 28×28, 60 epochs, 16 cores)
• Architectures: ResNet-18, MiniCNN
• Use Case: Development, testing, limited hardware environments

GPU Training (All Resolutions)

• 28×28 Resolution:
  • MiniCNN: ~2-3 minutes (60 epochs)
  • ResNet-18: ~10-15 minutes (60 epochs)
• 32×32 Resolution (CIFAR-10/100):
  • MiniCNN: ~3-5 minutes (60 epochs)
  • ResNet-18: ~15-20 minutes (60 epochs)
• 64×64 Resolution:
  • MiniCNN: ~3-5 minutes (60 epochs)
  • ResNet-18: ~15-20 minutes (60 epochs)
• 128×128 Resolution (timm models):
  • EfficientNet-Lite0: ~10 minutes (60 epochs)
  • ConvNeXt V2 Nano: ~15 minutes (60 epochs)
• 224×224 Resolution:
  • EfficientNet-B0: ~30 minutes per trial (15 epochs)
  • ViT-Tiny: ~25-35 minutes per trial (15 epochs)
• VRAM: 8GB recommended for 224×224 resolution
• Architectures: ResNet-18, EfficientNet-B0, ConvNeXt-Tiny, ViT-Tiny, timm/*

Warning

224×224 training on CPU is not recommended - it would take 10+ hours per trial. High-resolution training requires GPU acceleration. Only 28×28 resolution has been tested and validated for CPU training.

Note

Apple Silicon (MPS): The codebase includes MPS backend support (device detection, seeding, memory management), but it has not been tested on real hardware. If you encounter issues, please open an issue.

Note

Data Format: Orchard ML operates on NPZ archives as its canonical data format. All datasets are downloaded or converted to NPZ before entering the training pipeline. Custom datasets in other formats (HDF5, DICOM, TIFF) can be integrated by adding a conversion step in a dedicated fetcher module — see the Galaxy10 fetcher for a reference implementation.

Representative Benchmarks (RTX 5070 Laptop GPU):

Task	Architecture	Resolution	Device	Time	Notes
Smoke Test	MiniCNN	28×28	CPU/GPU	<30s	1-epoch sanity check
Quick Training	MiniCNN	28×28	GPU	~2-3 min	60 epochs
Quick Training	MiniCNN	28×28	CPU (16 cores)	~5-10 min	60 epochs, CPU-validated
Mid-Res Training	MiniCNN	64×64	GPU	~3-5 min	60 epochs
128×128 Training	EfficientNet-Lite0	128×128	GPU	~10 min	60 epochs, timm
128×128 Training	ConvNeXt V2 Nano	128×128	GPU	~15 min	60 epochs, timm
Transfer Learning	ResNet-18	28×28	GPU	~5 min	60 epochs
Transfer Learning	ResNet-18	28×28	CPU (16 cores)	~2.5h	60 epochs, CPU-validated
High-Res Training	EfficientNet-B0	224×224	GPU	~30 min/trial	15 epochs per trial, GPU required
High-Res Training	ViT-Tiny	224×224	GPU	~25-35 min/trial	15 epochs per trial, GPU required
Optimization Study	EfficientNet-B0	224×224	GPU	~2h	4 trials (early stop at AUC≥0.9999)
Optimization Study	Various	224×224	GPU	~1.5-5h	20 trials, highly variable

Note

Timing Variance: Optimization times are highly dependent on early stopping criteria, pruning configuration, and dataset complexity:

• Early Stopping: Studies may finish in 1-3 hours if performance thresholds are met quickly (e.g., AUC ≥ 0.9999 after 4 trials)
• Full Exploration: Without early stopping, 20 trials can extend to 5+ hours
• Pruning Impact: Median pruning can save 30-50% of total time by terminating underperforming trials

---

Quick Start

Step 1: Environment Setup

Option A: Install from source (recommended)

git clone https://github.com/tomrussobuilds/orchard-ml.git

Navigate into the project directory and install in editable mode:

cd orchard-ml
pip install -e .

With development tools (linting, testing, type checking):

pip install -e ".[dev]"

Option B: Install from PyPI

pip install orchard-ml
orchard init            # generates recipe.yaml with all defaults
orchard run recipe.yaml

Step 2: Verify Installation (Optional)

# Run 1-epoch sanity check (~30 seconds, CPU/GPU)
# Downloads BloodMNIST 28×28 by default
python -m tests.smoke_test

# Note: You can skip this step - datasets are auto-downloaded on first run

Step 3: Training Workflow

Orchard ML uses the orchard CLI as the single entry point for all workflows. The pipeline behavior is controlled entirely by the YAML recipe:

• Training only: Use a config_*.yaml file (no optuna: section)
• Optimization + Training: Use an optuna_*.yaml file (has optuna: section)
• With Export: Add an export: section to your config

orchard --version                          # Verify installation
orchard run --help                         # Show available options

Training Only (Quick start)

# 28×28 resolution (CPU-compatible)
orchard run recipes/config_mini_cnn.yaml              # ~2-3 min GPU, ~5-10 min CPU
orchard run recipes/config_resnet_18.yaml             # ~10-15 min GPU, ~2.5h CPU

# 32×32 resolution (CIFAR-10/100)
orchard run recipes/config_cifar10_mini_cnn.yaml      # ~3-5 min GPU
orchard run recipes/config_cifar10_resnet_18.yaml     # ~10-15 min GPU

# 64×64 resolution (CPU/GPU)
orchard run recipes/config_mini_cnn_64.yaml           # ~3-5 min GPU

# 128×128 resolution (GPU, timm models)
orchard run recipes/config_timm_efficientnet_lite0_128.yaml  # ~10 min GPU
orchard run recipes/config_timm_convnextv2_nano_128.yaml     # ~15 min GPU

# 224×224 resolution (GPU required)
orchard run recipes/config_efficientnet_b0.yaml       # ~30 min GPU
orchard run recipes/config_vit_tiny.yaml              # ~25-35 min GPU

# Override any config value on the fly
orchard run recipes/config_mini_cnn.yaml --set training.epochs=20 --set training.seed=99

What happens:

• Dataset auto-downloaded to ./dataset/
• Training runs for 60 epochs with early stopping
• Results saved to timestamped directory in outputs/

---

Hyperparameter Optimization + Training (Full pipeline)

# 28×28 resolution - fast iteration
orchard run recipes/optuna_mini_cnn.yaml              # ~5 min GPU, ~5-10 min CPU
orchard run recipes/optuna_resnet_18.yaml             # ~15 min GPU

# 32×32 resolution - CIFAR-10/100
orchard run recipes/optuna_cifar100_mini_cnn.yaml     # ~1-2h GPU
orchard run recipes/optuna_cifar100_resnet_18.yaml    # ~3-4h GPU

# 128×128 resolution - timm model search
orchard run recipes/optuna_128.yaml                   # ~2-4h GPU

# 224×224 resolution - requires GPU
orchard run recipes/optuna_efficientnet_b0.yaml       # ~1.5-5h*, GPU
orchard run recipes/optuna_vit_tiny.yaml              # ~3-5h*, GPU

# *Time varies due to early stopping (may finish in 1-3h if target AUC reached)

What happens:

1. Optimization: Explores hyperparameter combinations with Optuna
2. Training: Full 60-epoch training with best hyperparameters found
3. Artifacts: Interactive plots, best_config.yaml, model weights

Tip

Model Search: Enable optuna.enable_model_search: true in your YAML config to let Optuna automatically explore all registered architectures for the target resolution. Use optuna.model_pool to restrict the search to a subset of architectures (e.g. ["vit_tiny", "efficientnet_b0"]).

View optimization results:

firefox outputs/*/figures/param_importances.html       # Which hyperparameters matter most
firefox outputs/*/figures/optimization_history.html    # Trial progression

---

Model Export (Production deployment)

All training configs (config_*.yaml) include ONNX export by default:

orchard run recipes/config_efficientnet_b0.yaml
# → Training + ONNX export to outputs/*/exports/model.onnx

See the Export Guide for configuration options (format, quantization, validation).

---

Colab Notebooks

Try Orchard ML directly in Google Colab — no local setup required:

Notebook	Description	Runtime	Time
Quick Start: BloodMNIST CPU	MiniCNN training on BloodMNIST 28×28 — end-to-end training, evaluation, and ONNX export	CPU	~15 min
Optuna Model Search: Galaxy10 GPU	Automatic architecture search (EfficientNet-B0, ViT-Tiny, ConvNeXt-Tiny, ResNet-18) on Galaxy10 224×224 with Optuna	T4 GPU	~30-45 min
Edge Deploy: ONNX & Quantization	ONNX export with INT8/UINT8 quantization, latency benchmarking, and edge-ready inference pipeline	CPU	~50 min

---

Experiment Management

Every run generates a complete artifact suite for total traceability. Both training-only and optimization workflows share the same RunPath orchestrator, producing BLAKE2b-hashed timestamped directories.

Browse Sample Artifacts — Excel reports, YAML configs, and diagnostic plots from real training runs. See the full artifact tree for the complete directory layout — logs, model weights, and HTML plots are generated locally and not tracked in the repo.

Browse Recipe Configs — Ready-to-use YAML configurations for every architecture and workflow. Copy the closest recipe, tweak the parameters, and run:

cp recipes/config_efficientnet_b0.yaml my_run.yaml
# edit hyperparameters, swap dataset/model, add or remove sections (optuna, export, tracking)
orchard run my_run.yaml

Tip

Annotated starter recipe: Run orchard init to generate a self-documented recipe with inline comments describing every field, its valid range, and accepted values. See recipes/starter.yaml for a reference example.

---

Documentation

Guide	Covers
Documentation Hub	Full online docs with searchable API reference and guides
Framework Guide	System architecture diagrams, design principles, component deep-dives
Architecture Guide	Supported model architectures, weight transfer, grayscale adaptation, MixUp
Configuration Guide	Full parameter reference, usage patterns, adding new datasets
Optimization Guide	Optuna integration, search space config, pruning strategies, visualization
Docker Guide	Container build instructions, GPU-accelerated execution, reproducibility mode
Export Guide	ONNX export pipeline, quantization options, validation and benchmarking
Tracking Guide	MLflow local setup, dashboard and run comparison, programmatic querying
Artifact Guide	Output directory structure, training vs optimization artifact differences
Testing Guide	Test suite, quality automation scripts, CI/CD pipeline details
orchard/ / tests/	Internal package structure, module responsibilities, extension points

Citation

@software{orchardml2026,
  author = {Tommaso Russo},
  title  = {Orchard ML: Type-Safe Deep Learning Framework},
  year   = {2026},
  url    = {https://github.com/tomrussobuilds/orchard-ml},
  note   = {PyTorch framework with Pydantic V2 configuration and Optuna optimization}
}

---

Roadmap

• Expanded Dataset Domains: Climate, remote sensing, microscopy
• Multi-modal Support: Detection, segmentation hooks
• Distributed Training: DDP, FSDP support for multi-GPU

---

License

MIT License - See LICENSE for details.

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass: pytest tests/ -v
5. Submit a pull request

For detailed guidelines, see CONTRIBUTING.md.

Contact

For questions or collaboration: GitHub Issues