MIRA — Machine Intelligence for Recycling Automation

Jugend forscht 2027

Project website: mira-vision.vercel.app

MIRA is a computer-vision research project for identifying recyclable materials and preparing them for automated sorting. It combines YOLO object detection, dataset preparation, model evaluation, model export, webcam inference, and a development dashboard for glass, metal, paper, plastic, and trash.

The current focus is a reliable perception pipeline, with Raspberry Pi deployment and tabletop robot integration as future goals.

Quick Start

Install from PyPI (recommended)

pip install mira-ai

The CLI installs as the mira command and works from any directory. Download a trained model, then start live detection:

mira download --list                  # See available models
mira download mira_exp019.pt          # Download the best detector (~5.5 MB)
mira live --model mira_exp019.pt      # Start webcam detection
mira dashboard                        # Launch the control dashboard

Install from source (development)

git clone https://github.com/jeremy341/MIRA-AI.git
cd MIRA-AI
python -m venv .venv
.venv\Scripts\Activate.ps1      # Windows PowerShell
pip install -r requirements.txt

Live Detection

.\mira live                                    # Interactive model picker
.\mira live --model mira_exp014.pt             # Direct launch
.\mira live --model mira_exp014.pt --conf 0.25 --reject 0.55 --resolution 1280x720

Dashboard

.\mira dashboard                           # Opens at http://127.0.0.1:8000
.\mira dashboard --port 8080               # Custom port
.\mira dashboard --host 0.0.0.0            # Listen on all interfaces

Research Pipeline

.\mira datasets                            # List available dataset sources
.\mira merge --sources taco_trashnet roboflow --output datasets/mira_tnr
.\mira train --config experiments/exp014_yolo11n_multidataset.yaml
.\mira export --model models/detection/mira_exp014.pt --formats tflite_int8
.\mira benchmark --models mira_exp014.pt mira_exp014_int8.tflite
.\mira models                               # List discovered models

Installation Troubleshooting

Configuration

MIRA uses mira.yaml as the single source of truth for project-wide settings. All scripts, CLI commands, and the pipeline read from this file.

# mira.yaml — key settings
classes:
  names: ["glass", "metal", "paper", "plastic", "trash"]
  count: 5

training:
  default_model: yolo11n.pt
  default_epochs: 120
  default_batch_size: 32
  default_imgsz: 640

inference:
  reject_threshold: 0.55
  default_conf: 0.5
  default_iou: 0.7

CLI flags override mira.yaml defaults:

.\mira train --epochs 200 --batch-size 16    # Override training defaults
.\mira live --conf 0.25 --reject 0.60       # Override inference defaults

Where MIRA looks for configuration

When installed from PyPI, MIRA resolves its project root in this order:

1. The MIRA_HOME environment variable, if set
2. The nearest directory containing a mira.yaml (walking up from the current directory)
3. The current working directory, using the packaged default configuration

Models, datasets, and results are stored relative to the resolved project root (e.g. mira download saves into <root>/models/detection/).

Architecture

flowchart TB
    A[Camera or image input] --> B[YOLO11n detector]
    B --> C[Post-processing and confidence thresholds]
    C --> D[Bounding boxes and class labels]
    D --> E[ByteTrack object IDs]
    D --> F[Live overlay and dashboard]
    C --> G[Model evaluation and export]
    G --> H[Edge deployment]
    H -. planned .-> I[ESP32-S3 and sorting arm]

Confidence Reject System

Models

Stage A — Classification

Stage B — Detection

Dataset

Training datasets are not included in Git. The current build uses:

All datasets are remapped to 5 unified classes: glass, metal, paper, plastic, trash.

scripts/build_balanced_dataset.py documents the expected local directories, remapping, deterministic TACO split, balancing, and manifest generation. The canonical source list is in docs/DATASET_ORIGINS.md.

Training on Kaggle

All detection models train with YOLO11n using scripts/train_detector_kaggle.py on Kaggle (free T4 GPU).

py scripts/train_detector_kaggle.py --dataset mira_tnr
py scripts/train_detector_kaggle.py --dataset mira_all --epochs 200
.\mira generate kaggle --config experiments/exp014_yolo11n_multidataset.yaml

Hardware Requirements

Known Limitations

• Crumpled paper — white crumpled paper is misclassified as plastic with 80–90% confidence. The reject threshold cannot help here (too confident). Needs more training data.
• End-on metal cans — cans facing the camera opening-first cause detection drop-outs due to limited training samples for this orientation.
• Overlapping objects — heavily stacked or occluded items reduce bounding box accuracy, particularly for paper and trash.
• Trash class — the catch-all "trash" class is the weakest performer across all experiments (as low as 7.1% mAP50) due to its inherent visual diversity.
• No RPi or robot integration benchmark — target-hardware latency, memory, and end-to-end sorting remain pending.
• Dashboard integration unverified — components and unit tests exist, but no tracked end-to-end camera/model/browser verification artifact exists.

Reproducibility

Random Seeds

All scripts use fixed random seeds for deterministic results:

• TensorFlow/Keras: seed=123
• NumPy / Python random: seed=42

Model Availability

Trained model binaries are local, gitignored files. Public detector artifacts are available from Jeremy341/MIRA-AI, and mira download places them under models/detection/.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Adding a New CLI Command

Use the plugin registry to add commands without editing existing files:

# src/cli/my_module.py
from pipeline.registry import register_command

@register_command("my-command", "Description of what it does")
def cmd_my_command(args):
    print("Hello from my command!")

def setup(parser):
    parser.add_argument("--flag", help="Custom flag")

Then import the module in src/cli/__init__.py to activate it.

License

This project is licensed under the MIT License — see the LICENSE file for details.

Acknowledgments

• Kaggle — free T4 GPU for model training
• Ultralytics — YOLO framework
• OpenCode — development assistance and code review
• TACO Dataset — Trash Annotations in Context
• Roboflow — community waste detection dataset