orchard-ml 0.1.0

Type-Safe Deep Learning Framework for Computer Vision

Orchard ML

Type-safe deep learning framework for reproducible computer vision research

---

CI/CD & Coverage
Code Quality
Platform
Tech Stack
Code Style
Project

---

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), it provides a domain-agnostic platform supporting multi-resolution architectures (28×28 to 224×224+), automated hyperparameter optimization, and cluster-safe execution.

Key Differentiators:

• Type-Safe Configuration Engine: Pydantic V2-based declarative manifests eliminate runtime errors
• 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×28 / 224×224	ResNet-18	~11M	Multi-resolution baseline, transfer learning
28×28	MiniCNN	~94K	Fast prototyping, ablation studies
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

---

Hardware Requirements

CPU Training (28×28 Only)

• Supported Resolution: 28×28 only
• Time: ~2.5 hours (ResNet-18, 60 epochs, 16 cores)
• Time: ~5-10 minutes (MiniCNN, 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)
• 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

[!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.

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)	~30 min	60 epochs, CPU-validated
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 PyPI
pip install orchard-ml

# Option B: Install from source
git clone https://github.com/tomrussobuilds/orchard-ml.git
cd orchard-ml
pip install -e .

# With development tools (linting, testing, type checking)
pip install -e ".[dev]"

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 - forge.py will auto-download datasets as needed

Step 3: Training Workflow

Orchard ML uses forge.py as the single entry point for all workflows. The pipeline behavior is controlled entirely by the YAML configuration:

• 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

Training Only (Quick start)

# 28×28 resolution (CPU-compatible)
python forge.py --config recipes/config_mini_cnn.yaml              # ~2-3 min GPU, ~10 min CPU
python forge.py --config recipes/config_resnet_18.yaml             # ~10-15 min GPU, ~2.5h CPU

# 224×224 resolution (GPU required)
python forge.py --config recipes/config_efficientnet_b0.yaml       # ~30 min GPU
python forge.py --config recipes/config_vit_tiny.yaml              # ~25-35 min GPU

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
python forge.py --config recipes/optuna_mini_cnn.yaml              # ~5 min GPU, ~10 min CPU
python forge.py --config recipes/optuna_resnet_18.yaml             # ~15-20 min GPU

# 224×224 resolution - requires GPU
python forge.py --config recipes/optuna_efficientnet_b0.yaml       # ~1.5-5h*, GPU
python forge.py --config 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. The optimizer will select the best model alongside the best hyperparameters.

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:

python forge.py --config 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

---

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)
python forge.py --config my_run.yaml

---

Documentation

Guide	Covers
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	1,000+ 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 configuration and Optuna optimization}
}

---

Roadmap

• Additional Architectures: EfficientNet-V2, DeiT
• 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