{"id":45108339,"url":"https://github.com/tomrussobuilds/orchard-ml","last_synced_at":"2026-04-01T23:09:11.855Z","repository":{"id":327860912,"uuid":"1110208785","full_name":"tomrussobuilds/orchard-ml","owner":"tomrussobuilds","description":"Modular PyTorch framework: Pydantic schemas + Optuna optimization + resolution-aware architectures for vision research","archived":false,"fork":false,"pushed_at":"2026-03-23T14:58:11.000Z","size":11409,"stargazers_count":11,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-23T16:39:28.895Z","etag":null,"topics":["classification","computer-vision","convnext-tiny","deep-learning","detection","edge-ai","efficientnet","hyperparameter-optimization","medical-imaging","medmnist","mlflow","neural-networks","optuna","pydantic-v2","python","pytorch","resnet-18","timm","type-safety","vision-transformer"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tomrussobuilds.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-04T21:36:56.000Z","updated_at":"2026-03-23T14:58:14.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tomrussobuilds/orchard-ml","commit_stats":null,"previous_names":["tomrussobuilds/bloodmnist","tomrussobuilds/medmnist","tomrussobuilds/visionforge","tomrussobuilds/orchard-ml"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/tomrussobuilds/orchard-ml","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomrussobuilds%2Forchard-ml","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomrussobuilds%2Forchard-ml/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomrussobuilds%2Forchard-ml/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomrussobuilds%2Forchard-ml/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tomrussobuilds","download_url":"https://codeload.github.com/tomrussobuilds/orchard-ml/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomrussobuilds%2Forchard-ml/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31292813,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T21:15:39.731Z","status":"ssl_error","status_checked_at":"2026-04-01T21:15:34.046Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["classification","computer-vision","convnext-tiny","deep-learning","detection","edge-ai","efficientnet","hyperparameter-optimization","medical-imaging","medmnist","mlflow","neural-networks","optuna","pydantic-v2","python","pytorch","resnet-18","timm","type-safety","vision-transformer"],"created_at":"2026-02-19T22:11:45.759Z","updated_at":"2026-04-01T23:09:11.848Z","avatar_url":"https://github.com/tomrussobuilds.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003eOrchard ML\u003c/h1\u003e\n\u003cp align=\"center\"\u003e\u003cstrong\u003eType-safe deep learning framework for reproducible computer vision research\u003c/strong\u003e\u003c/p\u003e\n\n---\n\n\u003c!-- Badges Section --\u003e\n\u003ctable align=\"center\"\u003e\n\u003ctr\u003e\n\u003ctd align=\"right\"\u003e\u003cstrong\u003eCI / CD\u003c/strong\u003e\u003c/td\u003e\n\u003ctd align=\"center\"\u003e\n  \u003ca href=\"https://github.com/tomrussobuilds/orchard-ml/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/tomrussobuilds/orchard-ml/actions/workflows/ci.yml/badge.svg\" alt=\"CI/CD Pipeline\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://codecov.io/gh/tomrussobuilds/orchard-ml\"\u003e\u003cimg src=\"https://codecov.io/gh/tomrussobuilds/orchard-ml/branch/main/graph/badge.svg\" alt=\"Coverage\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://sonarcloud.io/summary/new_code?id=tomrussobuilds_orchard-ml\"\u003e\u003cimg src=\"https://sonarcloud.io/api/project_badges/measure?project=tomrussobuilds_orchard-ml\u0026metric=alert_status\" alt=\"Quality Gate\"\u003e\u003c/a\u003e\n  \u003ca href=\"docs/guide/MUTANTS.md\"\u003e\u003cimg src=\"https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/tomrussobuilds/7835190af6011e9051b673c8be974f8a/raw/mutmut.json\" alt=\"Mutation Score\"\u003e\u003c/a\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd align=\"right\"\u003e\u003cstrong\u003ePlatform\u003c/strong\u003e\u003c/td\u003e\n\u003ctd align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/python-3.10%20|%203.11%20|%203.12%20|%203.13%20|%203.14--dev-blue?logo=python\u0026logoColor=white\" alt=\"Python\"\u003e\n  \u003ca href=\"https://pypi.org/project/orchard-ml/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/v/orchard-ml?color=blue\u0026logo=pypi\u0026logoColor=white\u0026v=1\" alt=\"PyPI\"\u003e\u003c/a\u003e\n  \u003ca href=\"docs/guide/DOCKER.md\"\u003e\u003cimg src=\"https://img.shields.io/badge/Docker-CUDA%2012.6-2496ED?logo=docker\u0026logoColor=white\" alt=\"Docker\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-MIT-green\" alt=\"License\"\u003e\u003c/a\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd align=\"right\"\u003e\u003cstrong\u003eStack\u003c/strong\u003e\u003c/td\u003e\n\u003ctd align=\"center\"\u003e\n  \u003ca href=\"https://pytorch.org/\"\u003e\u003cimg src=\"https://img.shields.io/badge/PyTorch-2.0%2B-orange?logo=pytorch\u0026logoColor=white\" alt=\"PyTorch\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://huggingface.co/docs/timm\"\u003e\u003cimg src=\"https://img.shields.io/badge/timm-models-FF9D00?logo=huggingface\u0026logoColor=white\" alt=\"timm\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://docs.pydantic.dev/\"\u003e\u003cimg src=\"https://img.shields.io/badge/Pydantic-v2-e92063?logo=pydantic\u0026logoColor=white\" alt=\"Pydantic\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://optuna.org/\"\u003e\u003cimg src=\"https://img.shields.io/badge/Optuna-3.0%2B-00ADD8?logo=optuna\u0026logoColor=white\" alt=\"Optuna\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://onnx.ai/\"\u003e\u003cimg src=\"https://img.shields.io/badge/ONNX-export-005CED?logo=onnx\u0026logoColor=white\" alt=\"ONNX\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://mlflow.org/\"\u003e\u003cimg src=\"https://img.shields.io/badge/MLflow-tracking-0194E2?logo=mlflow\u0026logoColor=white\" alt=\"MLflow\"\u003e\u003c/a\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd align=\"right\"\u003e\u003cstrong\u003eStatic Analysis\u003c/strong\u003e\u003c/td\u003e\n\u003ctd align=\"center\"\u003e\n  \u003c!-- Dynamic badges — updated by .github/workflows/badges.yml via Gist --\u003e\n  \u003ca href=\"https://github.com/psf/black\"\u003e\u003cimg src=\"https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/tomrussobuilds/7835190af6011e9051b673c8be974f8a/raw/black.json\" alt=\"Black\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://docs.astral.sh/ruff/\"\u003e\u003cimg src=\"https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/tomrussobuilds/7835190af6011e9051b673c8be974f8a/raw/ruff.json\" alt=\"Ruff\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://mypy-lang.org/\"\u003e\u003cimg src=\"https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/tomrussobuilds/7835190af6011e9051b673c8be974f8a/raw/mypy.json\" alt=\"mypy\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://bandit.readthedocs.io/\"\u003e\u003cimg src=\"https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/tomrussobuilds/7835190af6011e9051b673c8be974f8a/raw/bandit.json\" alt=\"Bandit\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://radon.readthedocs.io/\"\u003e\u003cimg src=\"https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/tomrussobuilds/7835190af6011e9051b673c8be974f8a/raw/radon.json\" alt=\"Radon\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/tomrussobuilds/orchard-ml/actions/workflows/codeql.yml\"\u003e\u003cimg src=\"https://github.com/tomrussobuilds/orchard-ml/actions/workflows/codeql.yml/badge.svg\" alt=\"CodeQL\"\u003e\u003c/a\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n---\n\n\u003ch2\u003eTable of Contents\u003c/h2\u003e\n\n- [**Overview**](#overview)\n- [**Hardware Requirements**](#hardware-requirements)\n- [**Quick Start**](#quick-start)\n- [**Colab Notebooks**](#colab-notebooks)\n- [**Experiment Management**](#experiment-management)\n- [**Documentation**](#documentation)\n- [**Citation**](#citation)\n- [**Roadmap**](#roadmap)\n- [**License**](#license)\n\n---\n\n\u003ch2\u003eOverview\u003c/h2\u003e\n\n**Orchard ML** is a research-grade `PyTorch` training framework engineered for reproducible, scalable computer vision experiments across diverse domains. Supports **image classification** and **object detection** from a single YAML recipe. Built on [MedMNIST v2](https://zenodo.org/records/6496656) medical imaging datasets and expanded to astronomical imaging ([Galaxy10 DECals](https://zenodo.org/records/10845026)), standard benchmarks ([CIFAR-10/100](https://www.cs.toronto.edu/~kriz/cifar.html)), and pedestrian detection ([PennFudan](https://www.cis.upenn.edu/~jshi/ped_html/)), 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.\n\n**Key Differentiators:**\n- **Type-Safe Configuration Engine**: `Pydantic V2`-based declarative manifests eliminate runtime errors\n- **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\n- **Zero-Conflict Execution**: Kernel-level file locking (`fcntl`) prevents concurrent runs from corrupting shared resources\n- **Intelligent Hyperparameter Search**: `Optuna` integration with TPE sampling and Median Pruning\n- **Hardware-Agnostic**: Auto-detection and optimization for `CPU`/`CUDA`/`MPS` backends\n- **Audit-Grade Traceability**: `BLAKE2b`-hashed run directories with full `YAML` snapshots\n\n**Supported Architectures:**\n\n| Resolution | Architectures | Parameters | Use Case |\n|-----------|--------------|-----------|----------|\n| **28 / 32 / 64 / 128 / 224** | `ResNet-18` | ~11M | Multi-resolution baseline, transfer learning |\n| **28 / 32 / 64** | `MiniCNN` | ~95K | Fast prototyping, ablation studies |\n| **128×128** | `timm/efficientnet_lite0` | ~4.7M | Edge-friendly, mobile-optimized |\n| **128×128** | `timm/convnextv2_nano` | ~15.6M | Modern ConvNet V2, FCMAE pretrained |\n| **224×224** | `EfficientNet-B0` | ~4.0M | Efficient compound scaling |\n| **224×224** | `ConvNeXt-Tiny` | ~27.8M | Modern ConvNet design |\n| **224×224** | `ViT-Tiny` | ~5.5M | Patch-based attention, multiple weight variants |\n| **224×224** | `Faster R-CNN` | ~43M | Object detection (ResNet-50-FPN v2) |\n\n\u003e [!TIP]\n\u003e **1000+ additional architectures via [timm](https://huggingface.co/docs/timm)**: Any model in the `timm` registry can be used by prefixing the name with `timm/` in your recipe:\n\u003e ```yaml\n\u003e architecture:\n\u003e   name: \"timm/mobilenetv3_small_100\"   # ~1.5M params, edge-friendly\n\u003e   pretrained: true\n\u003e ```\n\u003e 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.\n\n---\n\n\u003ch2\u003eHardware Requirements\u003c/h2\u003e\n\n\u003ch3\u003eCPU Training (28×28 / 32×32 / 64×64)\u003c/h3\u003e\n\n- **Supported Resolutions**: 28×28, 32×32, 64×64\n- **Time**: ~2.5 hours (`ResNet-18`, 28×28, 60 epochs, 16 cores)\n- **Time**: ~5-10 minutes (`MiniCNN`, 28×28, 60 epochs, 16 cores)\n- **Architectures**: `ResNet-18`, `MiniCNN`\n- **Use Case**: Development, testing, limited hardware environments\n\n\u003ch3\u003eGPU Training (All Resolutions)\u003c/h3\u003e\n\n- **28×28 Resolution**:\n  - `MiniCNN`: ~2-3 minutes (60 epochs)\n  - `ResNet-18`: ~10-15 minutes (60 epochs)\n- **32×32 Resolution** (CIFAR-10/100):\n  - `MiniCNN`: ~3-5 minutes (60 epochs)\n  - `ResNet-18`: ~15-20 minutes (60 epochs)\n- **64×64 Resolution**:\n  - `MiniCNN`: ~3-5 minutes (60 epochs)\n  - `ResNet-18`: ~15-20 minutes (60 epochs)\n- **128×128 Resolution** (timm models):\n  - `EfficientNet-Lite0`: ~10 minutes (60 epochs)\n  - `ConvNeXt V2 Nano`: ~15 minutes (60 epochs)\n- **224×224 Resolution**:\n  - `EfficientNet-B0`: ~30 minutes per trial (15 epochs)\n  - `ViT-Tiny`: ~25-35 minutes per trial (15 epochs)\n- **VRAM**: 8GB recommended for 224×224 resolution\n- **Architectures**: `ResNet-18`, `EfficientNet-B0`, `ConvNeXt-Tiny`, `ViT-Tiny`, `timm/*`\n\n\u003e [!WARNING]\n\u003e **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.\n\n\u003e [!NOTE]\n\u003e **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.\n\n\u003e [!NOTE]\n\u003e **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](orchard/data_handler/fetchers/) for a reference implementation.\n\n**Representative Benchmarks** (RTX 5070 Laptop GPU):\n\n| Task | Architecture | Resolution | Device | Time | Notes |\n|------|-------------|-----------|--------|------|-------|\n| **Smoke Test** | `MiniCNN` | 28×28 | CPU/GPU | \u003c30s | 1-epoch sanity check |\n| **Quick Training** | `MiniCNN` | 28×28 | GPU | ~2-3 min | 60 epochs |\n| **Quick Training** | `MiniCNN` | 28×28 | CPU (16 cores) | ~5-10 min | 60 epochs, CPU-validated |\n| **Mid-Res Training** | `MiniCNN` | 64×64 | GPU | ~3-5 min | 60 epochs |\n| **128×128 Training** | `EfficientNet-Lite0` | 128×128 | GPU | ~10 min | 60 epochs, timm |\n| **128×128 Training** | `ConvNeXt V2 Nano` | 128×128 | GPU | ~15 min | 60 epochs, timm |\n| **Transfer Learning** | `ResNet-18` | 28×28 | GPU | ~5 min | 60 epochs |\n| **Transfer Learning** | `ResNet-18` | 28×28 | CPU (16 cores) | ~2.5h | 60 epochs, CPU-validated |\n| **High-Res Training** | `EfficientNet-B0` | 224×224 | GPU | ~30 min/trial | 15 epochs per trial, **GPU required** |\n| **High-Res Training** | `ViT-Tiny` | 224×224 | GPU | ~25-35 min/trial | 15 epochs per trial, **GPU required** |\n| **Optimization Study** | `EfficientNet-B0` | 224×224 | GPU | ~2h | 4 trials (early stop at AUC≥0.9999) |\n| **Optimization Study** | Various | 224×224 | GPU | ~1.5-5h | 20 trials, highly variable |\n\n\u003e [!NOTE]\n\u003e **Timing Variance**: Optimization times are highly dependent on early stopping criteria, pruning configuration, and dataset complexity:\n\u003e - **Early Stopping**: Studies may finish in 1-3 hours if performance thresholds are met quickly (e.g., AUC ≥ 0.9999 after 4 trials)\n\u003e - **Full Exploration**: Without early stopping, 20 trials can extend to 5+ hours\n\u003e - **Pruning Impact**: Median pruning can save 30-50% of total time by terminating underperforming trials\n\n---\n\n\u003ch2\u003eQuick Start\u003c/h2\u003e\n\n\u003ch3\u003eStep 1: Environment Setup\u003c/h3\u003e\n\n**Option A**: Install from source (recommended)\n```bash\ngit clone https://github.com/tomrussobuilds/orchard-ml.git\n```\n\nNavigate into the project directory and install in editable mode:\n```bash\ncd orchard-ml\npip install -e .\n```\n\nWith development tools (linting, testing, type checking):\n```bash\npip install -e \".[dev]\"\n```\n\n**Option B**: Install from PyPI\n```bash\npip install orchard-ml\norchard init            # generates recipe.yaml with all defaults\norchard run recipe.yaml\n```\n\n\u003ch3\u003eStep 2: Verify Installation (Optional)\u003c/h3\u003e\n\n```bash\n# Run 1-epoch sanity check (~30 seconds, CPU/GPU)\n# Downloads BloodMNIST 28×28 by default\npython -m tests.smoke_test\n\n# Note: You can skip this step - datasets are auto-downloaded on first run\n```\n\n\u003ch3\u003eStep 3: Training Workflow\u003c/h3\u003e\n\nOrchard ML uses the `orchard` CLI as the **single entry point** for all workflows. The pipeline behavior is controlled entirely by the `YAML` recipe:\n\n- **Training only**: Use a `config_*.yaml` file (no `optuna:` section)\n- **Optimization + Training**: Use an `optuna_*.yaml` file (has `optuna:` section)\n- **With Export**: Add an `export:` section to your config\n\n```bash\norchard --version                          # Verify installation\norchard run --help                         # Show available options\n```\n\n\u003ch4\u003eTraining Only (Quick start)\u003c/h4\u003e\n\n```bash\n# 28×28 resolution (CPU-compatible)\norchard run recipes/config_mini_cnn.yaml              # ~2-3 min GPU, ~5-10 min CPU\norchard run recipes/config_resnet_18.yaml             # ~10-15 min GPU, ~2.5h CPU\n\n# 32×32 resolution (CIFAR-10/100)\norchard run recipes/config_cifar10_mini_cnn.yaml      # ~3-5 min GPU\norchard run recipes/config_cifar10_resnet_18.yaml     # ~10-15 min GPU\n\n# 64×64 resolution (CPU/GPU)\norchard run recipes/config_mini_cnn_64.yaml           # ~3-5 min GPU\n\n# 128×128 resolution (GPU, timm models)\norchard run recipes/config_timm_efficientnet_lite0_128.yaml  # ~10 min GPU\norchard run recipes/config_timm_convnextv2_nano_128.yaml     # ~15 min GPU\n\n# 224×224 resolution (GPU required)\norchard run recipes/config_efficientnet_b0.yaml       # ~30 min GPU\norchard run recipes/config_vit_tiny.yaml              # ~25-35 min GPU\n\n# Override any config value on the fly\norchard run recipes/config_mini_cnn.yaml --set training.epochs=20 --set training.seed=99\n```\n\n**What happens:**\n- Dataset auto-downloaded to `./dataset/`\n- Training runs for 60 epochs with early stopping\n- Results saved to timestamped directory in `outputs/`\n\n---\n\n\u003ch4\u003eHyperparameter Optimization + Training (Full pipeline)\u003c/h4\u003e\n\n```bash\n# 28×28 resolution - fast iteration\norchard run recipes/optuna_mini_cnn.yaml              # ~5 min GPU, ~5-10 min CPU\norchard run recipes/optuna_resnet_18.yaml             # ~15 min GPU\n\n# 32×32 resolution - CIFAR-10/100\norchard run recipes/optuna_cifar100_mini_cnn.yaml     # ~1-2h GPU\norchard run recipes/optuna_cifar100_resnet_18.yaml    # ~3-4h GPU\n\n# 128×128 resolution - timm model search\norchard run recipes/optuna_128.yaml                   # ~2-4h GPU\n\n# 224×224 resolution - requires GPU\norchard run recipes/optuna_efficientnet_b0.yaml       # ~1.5-5h*, GPU\norchard run recipes/optuna_vit_tiny.yaml              # ~3-5h*, GPU\n\n# *Time varies due to early stopping (may finish in 1-3h if target AUC reached)\n```\n\n**What happens:**\n1. **Optimization**: Explores hyperparameter combinations with `Optuna`\n2. **Training**: Full 60-epoch training with best hyperparameters found\n3. **Artifacts**: Interactive plots, best_config.yaml, model weights\n\n\u003e [!TIP]\n\u003e **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\"]`).\n\n**View optimization results:**\n```bash\nfirefox outputs/*/figures/param_importances.html       # Which hyperparameters matter most\nfirefox outputs/*/figures/optimization_history.html    # Trial progression\n```\n\n---\n\n\u003ch4\u003eModel Export (Production deployment)\u003c/h4\u003e\n\nAll training configs (`config_*.yaml`) include `ONNX` export by default:\n```bash\norchard run recipes/config_efficientnet_b0.yaml\n# → Training + ONNX export to outputs/*/exports/model.onnx\n```\n\nSee the [Export Guide](docs/guide/EXPORT.md) for configuration options (format, quantization, validation).\n\n---\n\n\u003ch2\u003eColab Notebooks\u003c/h2\u003e\n\nTry Orchard ML directly in Google Colab — no local setup required:\n\n| Notebook | Description | Runtime | Time |\n|----------|-------------|---------|------|\n| [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/tomrussobuilds/orchard-ml/blob/main/notebooks/01_quickstart_bloodmnist_cpu.ipynb) **[Quick Start: BloodMNIST CPU](notebooks/01_quickstart_bloodmnist_cpu.ipynb)** | `MiniCNN` training on `BloodMNIST` 28×28 — end-to-end training, evaluation, and `ONNX` export | CPU | ~15 min |\n| [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/tomrussobuilds/orchard-ml/blob/main/notebooks/02_galaxy10_optuna_model_search.ipynb) **[Optuna Model Search: Galaxy10 GPU](notebooks/02_galaxy10_optuna_model_search.ipynb)** | Automatic architecture search (`EfficientNet-B0`, `ViT-Tiny`, `ConvNeXt-Tiny`, `ResNet-18`) on Galaxy10 224×224 with `Optuna` | T4 GPU | ~30-45 min |\n| [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/tomrussobuilds/orchard-ml/blob/main/notebooks/03_edge_deploy_onnx_quantize.ipynb) **[Edge Deploy: ONNX \u0026 Quantization](notebooks/03_edge_deploy_onnx_quantize.ipynb)** | `ONNX` export with `INT8`/`UINT8` quantization, latency benchmarking, and edge-ready inference pipeline | CPU | ~50 min |\n\n---\n\n\u003ch2\u003eExperiment Management\u003c/h2\u003e\n\nEvery 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.\n\n**[Browse Sample Artifacts](./docs/artifacts)** — Excel reports, `YAML` configs, and diagnostic plots from real training runs.\nSee the [full artifact tree](docs/artifacts/artifacts_structure.png) for the complete directory layout — logs, model weights, and HTML plots are generated locally and not tracked in the repo.\n\n**[Browse Recipe Configs](./recipes)** — Ready-to-use `YAML` configurations for every architecture and workflow.\nCopy the closest recipe, tweak the parameters, and run:\n```bash\ncp recipes/config_efficientnet_b0.yaml my_run.yaml\n# edit hyperparameters, swap dataset/model, add or remove sections (optuna, export, tracking)\norchard run my_run.yaml\n```\n\n\u003e [!TIP]\n\u003e **Annotated starter recipe**: Run `orchard init` to generate a self-documented recipe with inline comments describing every field, its valid range, and accepted values. Use `orchard init --task detection` for a detection-ready template. See [`recipes/starter_classification.yaml`](recipes/starter_classification.yaml) for a reference example.\n\n---\n\n\u003ch2\u003eDocumentation\u003c/h2\u003e\n\n| Guide | Covers |\n|-------|--------|\n| [**Documentation Hub**](https://tomrussobuilds.github.io/orchard-ml/) | Full online docs with searchable API reference and guides |\n| [Framework Guide](docs/guide/FRAMEWORK.md) | System architecture diagrams, design principles, component deep-dives |\n| [Architecture Guide](docs/guide/ARCHITECTURE.md) | Supported model architectures, weight transfer, grayscale adaptation, `MixUp` |\n| [Configuration Guide](docs/guide/CONFIGURATION.md) | Full parameter reference, usage patterns, adding new datasets |\n| [Optimization Guide](docs/guide/OPTIMIZATION.md) | `Optuna` integration, search space config, pruning strategies, visualization |\n| [Docker Guide](docs/guide/DOCKER.md) | Container build instructions, GPU-accelerated execution, reproducibility mode |\n| [Export Guide](docs/guide/EXPORT.md) | `ONNX` export pipeline, quantization options, validation and benchmarking |\n| [Tracking Guide](docs/guide/TRACKING.md) | `MLflow` local setup, dashboard and run comparison, programmatic querying |\n| [Artifact Guide](docs/guide/ARTIFACTS.md) | Output directory structure, training vs optimization artifact differences |\n| [Testing Guide](docs/guide/TESTING.md) | Test suite, quality automation scripts, CI/CD pipeline details |\n| [`orchard/`](orchard/README.md) / [`tests/`](tests/README.md) | Internal package structure, module responsibilities, extension points |\n\n\u003ch2\u003eCitation\u003c/h2\u003e\n\n```bibtex\n@software{orchardml2026,\n  author = {Tommaso Russo},\n  title  = {Orchard ML: Type-Safe Deep Learning Framework},\n  year   = {2026},\n  url    = {https://github.com/tomrussobuilds/orchard-ml},\n  note   = {PyTorch framework with Pydantic V2 configuration and Optuna optimization}\n}\n```\n\n---\n\n\u003ch2\u003eRoadmap\u003c/h2\u003e\n\n- **Expanded Dataset Domains**: Climate, remote sensing, microscopy\n- **Multi-modal Support**: Segmentation hooks, bbox visualization\n- **Distributed Training**: `DDP`, `FSDP` support for multi-GPU\n\n---\n\n\u003ch2\u003eLicense\u003c/h2\u003e\n\nMIT License - See [LICENSE](LICENSE) for details.\n\n\u003ch2\u003eContributing\u003c/h2\u003e\n\nContributions welcome! Please:\n1. Fork the repository\n2. Create a feature branch\n3. Add tests for new functionality\n4. Ensure all tests pass: `pytest tests/ -v`\n5. Submit a pull request\n\nFor detailed guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md).\n\n\u003ch2\u003eContact\u003c/h2\u003e\n\nFor questions or collaboration: [GitHub Issues](https://github.com/tomrussobuilds/orchard-ml/issues)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftomrussobuilds%2Forchard-ml","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftomrussobuilds%2Forchard-ml","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftomrussobuilds%2Forchard-ml/lists"}