Unify Flutter model resolution around metadata

[glenn-jocher]

Summary

• move official model download, caching, and metadata inspection into the package
• make task optional in YOLO and YOLOView when exported metadata already provides it
• delete the example-only model manager/model enums and simplify the example onto package APIs
• update README/docs to document the new metadata-first YOLO26 flow

What changed

• added a package-level resolver that handles official model IDs, remote URLs, Flutter assets on Android, and metadata inspection
• added native inspectModel hooks on Android and iOS for task/label metadata
• kept predict() and YOLOView separate, but made them share the same resolver path
• removed the example's duplicated model ontology and downloader
• replaced the hardcoded v0.2.0 release URL with latest-release downloads

Verification

• flutter analyze
• flutter test
• flutter build apk --debug in example/
• flutter build ios --simulator --no-codesign in example/

🛠️ PR Summary

_{Made with ❤️ by Ultralytics Actions}

WARNING ⚠️ this PR is very large, summary may not cover all changes.

🌟 Summary

This PR makes YOLO Flutter model loading much simpler and smarter by adding package-level model resolution, automatic metadata-based task detection, and a major docs/example cleanup around official YOLO26-first workflows 🚀

📊 Key Changes

• Added package-level model resolution for multiple model sources: official model IDs, remote URLs, local files, and Flutter assets 📦
• Made task optional in more places by resolving it from exported model metadata across YOLO, YOLOView, and YOLOViewController.switchModel() 🧠
• Added a new inspectModel capability on Android to read model metadata without fully loading the model 🔍
• Expanded Android metadata parsing from just labels to richer metadata like task, labels, image size, stride, channels, and more 🛠️
• Replaced hardcoded release URL assumptions with an official model catalog + latest-release resolution approach, improving how official models are discovered and loaded 🌐
• Updated defaults from YOLO11n to YOLO26n in key places, aligning with the latest recommended model ✅
• Simplified the example app by removing its custom model manager and model tables, so it now uses the same package logic as real user apps ✂️
• Cleaned up and rewrote large parts of the docs and READMEs to focus on a metadata-first, official-model-first workflow for both single-image and camera inference 📚
• Removed outdated or redundant setup guidance, including unnecessary Android storage permission references 🧹

🎯 Purpose & Impact

• Makes model loading easier for developers: users can now pass a model ID, asset path, file path, or URL with less custom setup 🙌
• Reduces boilerplate by letting the plugin infer the task automatically when model metadata is available, which lowers the chance of configuration mistakes 🎯
• Improves reliability and maintainability by moving model resolution logic into the package instead of duplicating it in the example app 🔄
• Makes official model usage more future-proof by avoiding brittle assumptions about fixed release URLs or app-bundled assets 🔐
• Helps new users get started faster with YOLO26 as the default path, clearer docs, and simpler examples ⚡
• Gives advanced users better tooling for custom exports through metadata inspection and more flexible loading options 🧪
• Overall, this PR should make the Flutter plugin feel more polished, easier to integrate, and easier to scale across different app setups 📱

[codecov]

Codecov Report

❌ Patch coverage is 41.54412% with 159 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
lib/core/yolo_model_resolver.dart	29.53%	136 Missing ⚠️
lib/yolo.dart	50.00%	18 Missing ⚠️
lib/yolo_view.dart	86.11%	5 Missing ⚠️

📢 Thoughts on this report? Let us know!

[UltralyticsAssistant]

👋 Hello @glenn-jocher, thank you for submitting a ultralytics/yolo-flutter-app 🚀 PR! This is an automated message to help with review readiness—an engineer will assist shortly. Please review the checklist below:

• ✅ Define a Purpose: Clearly explain the purpose of your fix or feature in your PR description, and link to any relevant issues. Ensure your commit messages are clear, concise, and adhere to the project's conventions.
• ✅ Synchronize with Source: Confirm your PR is synchronized with the ultralytics/yolo-flutter-app main branch. If it's behind, update it by clicking the 'Update branch' button or by running git pull and git merge main locally.
• ✅ Ensure CI Checks Pass: Verify all Ultralytics Continuous Integration (CI) checks are passing. If any checks fail, please address the issues.
• ✅ Update Documentation: Update the relevant documentation for any new or modified features.
• ✅ Add Tests: If applicable, include or update tests to cover your changes, and confirm that all tests are passing.
• ✅ Sign the CLA: Please ensure you have signed our Contributor License Agreement if this is your first Ultralytics PR by writing "I have read the CLA Document and I sign the CLA" in a new message.
• ✅ Minimize Changes: Limit your changes to the minimum necessary for your bug fix or feature addition. "It is not daily increase but daily decrease, hack away the unessential. The closer to the source, the less wastage there is." — Bruce Lee

For more guidance, please refer to our Contributing Guide. Don't hesitate to leave a comment if you have any questions. Thank you for contributing to Ultralytics! 🚀🙂

[UltralyticsAssistant]

🔍 PR Review

_{Made with ❤️ by Ultralytics Actions}

Overall the metadata-first resolver refactor looks solid, but there are a few important issues to address before merging: a race in YOLOView can leave the widget on a stale model, cached downloads can get stuck on partial/corrupt files, and the new zip extraction path handling introduces a Zip Slip vulnerability for remote model archives.

💬 Posted 3 inline comments

[glenn-jocher]

Final hardening pass pushed in dd8a43e. This fixes the live review findings (atomic downloads, safe zip extraction, stale YOLOView resolution), replaces the generated official-model matrix with a small explicit per-platform catalog that matches the real release assets, and simplifies the example to only present official task/model combinations that actually exist on the running platform.\n\nRe-verified locally on this head with:\n- flutter analyze\n- flutter test\n- flutter build apk --debug (example/)\n- flutter build ios --simulator --no-codesign (example/)\n\nThis leaves the package closer to the intended DX: official IDs are truthful, custom model paths remain first-class, and users can drop in exported models without maintaining duplicate task/model state in the example.

[UltralyticsAssistant]

🎉 Huge thanks for getting this merged, @glenn-jocher — this is a fantastic step forward for the Flutter experience.

As Leonardo da Vinci said, “Simplicity is the ultimate sophistication.” That fits this PR perfectly: simplifying model loading, enabling metadata-first task detection, and aligning everything around YOLO26 makes the package much more intuitive, reliable, and developer-friendly.

Really appreciate the care behind both the implementation and the docs cleanup here. This kind of work makes the whole ecosystem easier to adopt and more polished for everyone building with Ultralytics. 🚀