magiclabel 0.1.0__tar.gz

magiclabel-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rohan Rustagi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

magiclabel-0.1.0/PKG-INFO

@@ -0,0 +1,304 @@
+Metadata-Version: 2.4
+Name: magiclabel
+Version: 0.1.0
+Summary: AI-assisted image annotation CLI for computer vision datasets
+Author: Rohan Rustagi
+License: MIT
+Keywords: annotation,labeling,computer-vision,yolo,dataset,object-detection
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: ultralytics>=8.0.0
+Requires-Dist: typer>=0.9.0
+Requires-Dist: rich
+Requires-Dist: opencv-python
+Requires-Dist: gradio
+Requires-Dist: gradio_image_annotation
+Requires-Dist: torch
+Requires-Dist: torchvision
+Dynamic: license-file
+
+# MagicLabel
+
+> AI‑assisted image labeling CLI — go from raw images to your own trained model, end to end.
+
+Good models start with good data, and labeling that data by hand is the slowest part of any computer‑vision project. **MagicLabel** runs the whole loop from one command line:
+
+1. **Auto‑detect** objects in a folder of images — including custom objects you describe in plain words (no training needed).
+2. **Review & fix** the labels in a browser — draw, move, resize, relabel, delete.
+3. **Train** a custom YOLO model on your labeled data.
+4. **Reuse** your named model (`rohan.pt`, `findelon.pt`, …) to auto‑label the next batch — the loop closes.
+
+Everything runs **locally and free** — no account, no cloud upload, no Docker.
+
+![Python](https://img.shields.io/badge/python-3.8%2B-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+
+---
+
+## Features
+
+- 🔍 **Auto‑detect** — label an image folder with a YOLO model (the 80 COCO classes out of the box).
+- 🗣️ **Open‑vocabulary detect** — `--prompt "missile,launcher"` detects *anything you name*, with no training (YOLO‑World).
+- 🖊️ **Visual review** — a Gradio web app to draw / move / resize / relabel / delete boxes and save back to YOLO format. Type **any class name you want**.
+- 🎓 **Train** — fine‑tune a custom model on your labeled data and save it as a named `.pt`.
+- 🔄 **Export** — convert YOLO labels to COCO JSON.
+- 🏷️ **Inspect** — print the class names a YOLO model knows.
+
+---
+
+## Who is this for?
+
+Anyone who needs a labeled image dataset and a model to train on it:
+
+- **ML engineers & researchers** bootstrapping a dataset from raw images.
+- **Hobbyists & students** learning the full CV pipeline without paying for a labeling service.
+- **Privacy‑sensitive / air‑gapped users** (medical, defense, proprietary data) who can't upload images to a cloud tool.
+
+---
+
+## Requirements
+
+- **Python 3.8+**
+- Disk space for model weights (downloaded automatically on first use)
+- Works on **CPU**; a CUDA or Apple‑Silicon (MPS) GPU is used automatically when available and is much faster for training
+
+> **Heads‑up:** MagicLabel depends on `torch` and `ultralytics`, so installation pulls ~1 GB of packages. That's normal for a computer‑vision tool.
+
+---
+
+## Installation
+
+### From PyPI
+
+```bash
+pip install magiclabel
+```
+
+### From source
+
+```bash
+git clone https://github.com/your-username/magiclabel.git
+cd magiclabel
+python -m venv .venv
+source .venv/bin/activate        # Windows: .venv\Scripts\activate
+pip install -e .
+```
+
+Verify:
+
+```bash
+magiclabel --help
+```
+
+---
+
+## Quick start — the full loop
+
+```bash
+# 1. Auto-label a folder of images (closed-set, 80 COCO classes)
+magiclabel detect ./images --output ./labels
+
+#    …or detect a CUSTOM object by describing it (no training):
+magiclabel detect ./images --prompt "missile, launcher" --output ./labels
+
+# 2. Review and fix the labels in your browser
+magiclabel review ./images ./labels
+
+# 3. Train your own model on the corrected dataset
+magiclabel train ./images ./labels --name rohan.pt --epochs 50
+
+# 4. Reuse your model to auto-label the next batch
+magiclabel detect ./new_images --model rohan.pt --output ./labels2
+```
+
+---
+
+## Commands
+
+Run `magiclabel <command> --help` at any time for the full option list.
+
+### `detect` — auto‑annotate with bounding boxes
+
+Runs a model over every image in a directory and writes one YOLO‑format `.txt` per image, plus a `classes.txt` (the class list).
+
+```bash
+magiclabel detect SOURCE [OPTIONS]
+```
+
+| Option       | Default                                  | Description                                                                 |
+| ------------ | ---------------------------------------- | --------------------------------------------------------------------------- |
+| `SOURCE`     | _(required)_                             | Directory of images (`.jpg`, `.jpeg`, `.png`, `.bmp`, `.tif`)               |
+| `--prompt`   | _(none)_                                 | Comma‑separated object names for **open‑vocabulary** detection, e.g. `"missile,launcher"`. No training needed. |
+| `--model`    | `yolov8n.pt` / `yolov8s-world.pt`        | Model file. Defaults to `yolov8n.pt` (closed‑set), or `yolov8s-world.pt` when `--prompt` is given. Pass your own `.pt` to use a trained model. |
+| `--output`   | `./labels_detect`                        | Output directory for labels + `classes.txt`                                 |
+| `--conf`     | `0.25`                                   | Confidence threshold (0–1); higher = fewer, surer boxes                     |
+
+**Examples**
+
+```bash
+# Closed-set: the 80 COCO classes
+magiclabel detect ./images --conf 0.3 --output ./labels
+
+# Open-vocabulary: detect objects YOLO has never been trained on
+magiclabel detect ./images --prompt "drone, fixed-wing aircraft" --conf 0.1
+
+# Use your own trained model
+magiclabel detect ./images --model rohan.pt --output ./labels
+```
+
+> **Open‑vocabulary is great for common/clear objects and hit‑or‑miss on unusual ones** (it does the easy 70–80%). For hard objects (e.g. missiles), hand‑label a first batch in `review`, `train` a model, then `detect --model your.pt` to auto‑label the rest.
+
+---
+
+### `review` — fix annotations in your browser
+
+Launches a local web app (default: <http://127.0.0.1:7860>) to inspect and correct labels.
+
+```bash
+magiclabel review IMAGES_DIR LABELS_DIR [--model yolov8n.pt]
+```
+
+| Argument / Option | Description                                                                 |
+| ----------------- | --------------------------------------------------------------------------- |
+| `IMAGES_DIR`      | Directory of images                                                         |
+| `LABELS_DIR`      | Directory of YOLO `.txt` labels (and `classes.txt`)                         |
+| `--model`         | Model whose class names label the boxes (default `yolov8n.pt`). Use `--model none` to start a clean custom dataset with no preset names. |
+
+**In the UI you can:**
+
+- **Draw** a new box — click and drag on the image.
+- **Move / resize** — click a box and drag it or its corner handles.
+- **Set the class** — double‑click a box and **type any class name** (`missile`, `crack`, `logo`), then click the editor's apply/✓ to commit. New names are added automatically.
+- **Delete** — the box's remove button, the <kbd>Delete</kbd> key, or **Clear All Boxes**.
+- **Switch images** — the dropdown at the top (it opens on the first image that already has boxes).
+- **Save Changes** — writes boxes back to the `.txt`; the view then reloads from disk so you can confirm exactly what was saved.
+
+**Custom classes & `classes.txt`:** YOLO label files store integer class ids, so MagicLabel keeps a `classes.txt` (one name per line, id = line number) in your labels folder. Whatever name you type is mapped to a stable id behind the scenes, and new names are appended automatically. **That `classes.txt` is the class list you train on.**
+
+> Edits live only in the browser until you click **Save Changes**. Saving an image with no boxes writes an empty label file (a valid "no objects" annotation).
+
+---
+
+### `train` — train your own model
+
+Fine‑tunes a YOLO model on your labeled dataset and saves it as a named `.pt`.
+
+```bash
+magiclabel train IMAGES_DIR LABELS_DIR [OPTIONS]
+```
+
+| Option         | Default       | Description                                            |
+| -------------- | ------------- | ------------------------------------------------------ |
+| `IMAGES_DIR`   | _(required)_  | Directory of images                                    |
+| `LABELS_DIR`   | _(required)_  | Directory of YOLO labels + `classes.txt`               |
+| `--name`       | `custom.pt`   | Output model name, e.g. `rohan.pt`                     |
+| `--base`       | `yolov8n.pt`  | Base model to fine‑tune                                |
+| `--epochs`     | `50`          | Training epochs                                        |
+| `--imgsz`      | `640`         | Training image size                                    |
+| `--val-split`  | `0.2`         | Fraction of images held out for validation             |
+
+**Example**
+
+```bash
+magiclabel train ./images ./labels --name rohan.pt --epochs 100
+# → rohan.pt  (and a rohan_dataset/ folder with the train/val split + data.yaml)
+```
+
+The command builds a proper YOLO dataset (train/val split + `data.yaml`) from your labels, trains, and copies the best weights to your named file. Use it anywhere a model is accepted:
+
+```bash
+magiclabel detect ./new_images --model rohan.pt
+```
+
+> A useful model needs **dozens‑to‑hundreds of labeled images** and enough epochs. On CPU this can be slow — a GPU is much faster. Start small to validate the pipeline, then scale your data.
+
+---
+
+### `yolo2coco` — convert labels to COCO JSON
+
+```bash
+magiclabel yolo2coco IMAGES_DIR LABELS_DIR OUTPUT_JSON --class NAME [--class NAME ...]
+```
+
+| Argument / Option | Description                                                |
+| ----------------- | --------------------------------------------------------- |
+| `IMAGES_DIR`      | Directory of images                                       |
+| `LABELS_DIR`      | Directory of YOLO detection labels                        |
+| `OUTPUT_JSON`     | Path to write the COCO JSON file                          |
+| `--class`         | Class names **in class‑id order** (0, 1, 2, …), repeated  |
+
+```bash
+magiclabel yolo2coco ./images ./labels annotations.json \
+  --class person --class bicycle --class car
+```
+
+---
+
+### `export-classes` — list a model's class names
+
+```bash
+magiclabel export-classes yolov8n.pt
+# 0: person
+# 1: bicycle
+# 2: car
+# ...
+```
+
+---
+
+## Label format
+
+MagicLabel reads and writes the **YOLO detection** format: one `.txt` per image, sharing the image's base name (`dog.jpg` → `dog.txt`). Each line is one box:
+
+```text
+<class_id> <x_center> <y_center> <width> <height>
+```
+
+All four coordinates are **normalized to 0–1** relative to the image size. Example:
+
+```text
+16 0.593846 0.400000 0.250769 0.258462
+```
+
+A `classes.txt` alongside the labels maps each id to a name (id = line number).
+
+---
+
+## Tips & troubleshooting
+
+- **Model downloads:** the first run of a new model downloads its weights into the current directory and reuses them after.
+- **Speed:** detection is fast on CPU; training is much faster on a GPU (PyTorch uses CUDA/MPS automatically).
+- **"No images found":** the source must be a directory containing images with a supported extension (`.jpg`, `.jpeg`, `.png`, `.bmp`, `.tif`, `.tiff`).
+- **Port 7860 already in use:** an old review server is still running. Stop it with:
+  ```bash
+  kill $(lsof -nP -tiTCP:7860 -sTCP:LISTEN)
+  ```
+- **Restart after changes:** the review server does not hot‑reload — stop it (<kbd>Ctrl</kbd>+<kbd>C</kbd>) and run `magiclabel review …` again.
+
+---
+
+## Project structure
+
+```text
+magiclabel/
+├── cli.py          # Typer CLI entry point (detect, review, train, yolo2coco, export-classes)
+├── annotator.py    # YOLO / YOLO-World detection → label files + classes.txt
+├── review_app.py   # Gradio review/annotation web app
+├── trainer.py      # builds the dataset and trains a custom model
+├── convertor.py    # YOLO → COCO conversion
+└── utils.py        # image discovery + helpers
+```
+
+---
+
+## License
+
+Released under the [MIT License](LICENSE).

magiclabel-0.1.0/README.md

@@ -0,0 +1,277 @@
+# MagicLabel
+
+> AI‑assisted image labeling CLI — go from raw images to your own trained model, end to end.
+
+Good models start with good data, and labeling that data by hand is the slowest part of any computer‑vision project. **MagicLabel** runs the whole loop from one command line:
+
+1. **Auto‑detect** objects in a folder of images — including custom objects you describe in plain words (no training needed).
+2. **Review & fix** the labels in a browser — draw, move, resize, relabel, delete.
+3. **Train** a custom YOLO model on your labeled data.
+4. **Reuse** your named model (`rohan.pt`, `findelon.pt`, …) to auto‑label the next batch — the loop closes.
+
+Everything runs **locally and free** — no account, no cloud upload, no Docker.
+
+![Python](https://img.shields.io/badge/python-3.8%2B-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+
+---
+
+## Features
+
+- 🔍 **Auto‑detect** — label an image folder with a YOLO model (the 80 COCO classes out of the box).
+- 🗣️ **Open‑vocabulary detect** — `--prompt "missile,launcher"` detects *anything you name*, with no training (YOLO‑World).
+- 🖊️ **Visual review** — a Gradio web app to draw / move / resize / relabel / delete boxes and save back to YOLO format. Type **any class name you want**.
+- 🎓 **Train** — fine‑tune a custom model on your labeled data and save it as a named `.pt`.
+- 🔄 **Export** — convert YOLO labels to COCO JSON.
+- 🏷️ **Inspect** — print the class names a YOLO model knows.
+
+---
+
+## Who is this for?
+
+Anyone who needs a labeled image dataset and a model to train on it:
+
+- **ML engineers & researchers** bootstrapping a dataset from raw images.
+- **Hobbyists & students** learning the full CV pipeline without paying for a labeling service.
+- **Privacy‑sensitive / air‑gapped users** (medical, defense, proprietary data) who can't upload images to a cloud tool.
+
+---
+
+## Requirements
+
+- **Python 3.8+**
+- Disk space for model weights (downloaded automatically on first use)
+- Works on **CPU**; a CUDA or Apple‑Silicon (MPS) GPU is used automatically when available and is much faster for training
+
+> **Heads‑up:** MagicLabel depends on `torch` and `ultralytics`, so installation pulls ~1 GB of packages. That's normal for a computer‑vision tool.
+
+---
+
+## Installation
+
+### From PyPI
+
+```bash
+pip install magiclabel
+```
+
+### From source
+
+```bash
+git clone https://github.com/your-username/magiclabel.git
+cd magiclabel
+python -m venv .venv
+source .venv/bin/activate        # Windows: .venv\Scripts\activate
+pip install -e .
+```
+
+Verify:
+
+```bash
+magiclabel --help
+```
+
+---
+
+## Quick start — the full loop
+
+```bash
+# 1. Auto-label a folder of images (closed-set, 80 COCO classes)
+magiclabel detect ./images --output ./labels
+
+#    …or detect a CUSTOM object by describing it (no training):
+magiclabel detect ./images --prompt "missile, launcher" --output ./labels
+
+# 2. Review and fix the labels in your browser
+magiclabel review ./images ./labels
+
+# 3. Train your own model on the corrected dataset
+magiclabel train ./images ./labels --name rohan.pt --epochs 50
+
+# 4. Reuse your model to auto-label the next batch
+magiclabel detect ./new_images --model rohan.pt --output ./labels2
+```
+
+---
+
+## Commands
+
+Run `magiclabel <command> --help` at any time for the full option list.
+
+### `detect` — auto‑annotate with bounding boxes
+
+Runs a model over every image in a directory and writes one YOLO‑format `.txt` per image, plus a `classes.txt` (the class list).
+
+```bash
+magiclabel detect SOURCE [OPTIONS]
+```
+
+| Option       | Default                                  | Description                                                                 |
+| ------------ | ---------------------------------------- | --------------------------------------------------------------------------- |
+| `SOURCE`     | _(required)_                             | Directory of images (`.jpg`, `.jpeg`, `.png`, `.bmp`, `.tif`)               |
+| `--prompt`   | _(none)_                                 | Comma‑separated object names for **open‑vocabulary** detection, e.g. `"missile,launcher"`. No training needed. |
+| `--model`    | `yolov8n.pt` / `yolov8s-world.pt`        | Model file. Defaults to `yolov8n.pt` (closed‑set), or `yolov8s-world.pt` when `--prompt` is given. Pass your own `.pt` to use a trained model. |
+| `--output`   | `./labels_detect`                        | Output directory for labels + `classes.txt`                                 |
+| `--conf`     | `0.25`                                   | Confidence threshold (0–1); higher = fewer, surer boxes                     |
+
+**Examples**
+
+```bash
+# Closed-set: the 80 COCO classes
+magiclabel detect ./images --conf 0.3 --output ./labels
+
+# Open-vocabulary: detect objects YOLO has never been trained on
+magiclabel detect ./images --prompt "drone, fixed-wing aircraft" --conf 0.1
+
+# Use your own trained model
+magiclabel detect ./images --model rohan.pt --output ./labels
+```
+
+> **Open‑vocabulary is great for common/clear objects and hit‑or‑miss on unusual ones** (it does the easy 70–80%). For hard objects (e.g. missiles), hand‑label a first batch in `review`, `train` a model, then `detect --model your.pt` to auto‑label the rest.
+
+---
+
+### `review` — fix annotations in your browser
+
+Launches a local web app (default: <http://127.0.0.1:7860>) to inspect and correct labels.
+
+```bash
+magiclabel review IMAGES_DIR LABELS_DIR [--model yolov8n.pt]
+```
+
+| Argument / Option | Description                                                                 |
+| ----------------- | --------------------------------------------------------------------------- |
+| `IMAGES_DIR`      | Directory of images                                                         |
+| `LABELS_DIR`      | Directory of YOLO `.txt` labels (and `classes.txt`)                         |
+| `--model`         | Model whose class names label the boxes (default `yolov8n.pt`). Use `--model none` to start a clean custom dataset with no preset names. |
+
+**In the UI you can:**
+
+- **Draw** a new box — click and drag on the image.
+- **Move / resize** — click a box and drag it or its corner handles.
+- **Set the class** — double‑click a box and **type any class name** (`missile`, `crack`, `logo`), then click the editor's apply/✓ to commit. New names are added automatically.
+- **Delete** — the box's remove button, the <kbd>Delete</kbd> key, or **Clear All Boxes**.
+- **Switch images** — the dropdown at the top (it opens on the first image that already has boxes).
+- **Save Changes** — writes boxes back to the `.txt`; the view then reloads from disk so you can confirm exactly what was saved.
+
+**Custom classes & `classes.txt`:** YOLO label files store integer class ids, so MagicLabel keeps a `classes.txt` (one name per line, id = line number) in your labels folder. Whatever name you type is mapped to a stable id behind the scenes, and new names are appended automatically. **That `classes.txt` is the class list you train on.**
+
+> Edits live only in the browser until you click **Save Changes**. Saving an image with no boxes writes an empty label file (a valid "no objects" annotation).
+
+---
+
+### `train` — train your own model
+
+Fine‑tunes a YOLO model on your labeled dataset and saves it as a named `.pt`.
+
+```bash
+magiclabel train IMAGES_DIR LABELS_DIR [OPTIONS]
+```
+
+| Option         | Default       | Description                                            |
+| -------------- | ------------- | ------------------------------------------------------ |
+| `IMAGES_DIR`   | _(required)_  | Directory of images                                    |
+| `LABELS_DIR`   | _(required)_  | Directory of YOLO labels + `classes.txt`               |
+| `--name`       | `custom.pt`   | Output model name, e.g. `rohan.pt`                     |
+| `--base`       | `yolov8n.pt`  | Base model to fine‑tune                                |
+| `--epochs`     | `50`          | Training epochs                                        |
+| `--imgsz`      | `640`         | Training image size                                    |
+| `--val-split`  | `0.2`         | Fraction of images held out for validation             |
+
+**Example**
+
+```bash
+magiclabel train ./images ./labels --name rohan.pt --epochs 100
+# → rohan.pt  (and a rohan_dataset/ folder with the train/val split + data.yaml)
+```
+
+The command builds a proper YOLO dataset (train/val split + `data.yaml`) from your labels, trains, and copies the best weights to your named file. Use it anywhere a model is accepted:
+
+```bash
+magiclabel detect ./new_images --model rohan.pt
+```
+
+> A useful model needs **dozens‑to‑hundreds of labeled images** and enough epochs. On CPU this can be slow — a GPU is much faster. Start small to validate the pipeline, then scale your data.
+
+---
+
+### `yolo2coco` — convert labels to COCO JSON
+
+```bash
+magiclabel yolo2coco IMAGES_DIR LABELS_DIR OUTPUT_JSON --class NAME [--class NAME ...]
+```
+
+| Argument / Option | Description                                                |
+| ----------------- | --------------------------------------------------------- |
+| `IMAGES_DIR`      | Directory of images                                       |
+| `LABELS_DIR`      | Directory of YOLO detection labels                        |
+| `OUTPUT_JSON`     | Path to write the COCO JSON file                          |
+| `--class`         | Class names **in class‑id order** (0, 1, 2, …), repeated  |
+
+```bash
+magiclabel yolo2coco ./images ./labels annotations.json \
+  --class person --class bicycle --class car
+```
+
+---
+
+### `export-classes` — list a model's class names
+
+```bash
+magiclabel export-classes yolov8n.pt
+# 0: person
+# 1: bicycle
+# 2: car
+# ...
+```
+
+---
+
+## Label format
+
+MagicLabel reads and writes the **YOLO detection** format: one `.txt` per image, sharing the image's base name (`dog.jpg` → `dog.txt`). Each line is one box:
+
+```text
+<class_id> <x_center> <y_center> <width> <height>
+```
+
+All four coordinates are **normalized to 0–1** relative to the image size. Example:
+
+```text
+16 0.593846 0.400000 0.250769 0.258462
+```
+
+A `classes.txt` alongside the labels maps each id to a name (id = line number).
+
+---
+
+## Tips & troubleshooting
+
+- **Model downloads:** the first run of a new model downloads its weights into the current directory and reuses them after.
+- **Speed:** detection is fast on CPU; training is much faster on a GPU (PyTorch uses CUDA/MPS automatically).
+- **"No images found":** the source must be a directory containing images with a supported extension (`.jpg`, `.jpeg`, `.png`, `.bmp`, `.tif`, `.tiff`).
+- **Port 7860 already in use:** an old review server is still running. Stop it with:
+  ```bash
+  kill $(lsof -nP -tiTCP:7860 -sTCP:LISTEN)
+  ```
+- **Restart after changes:** the review server does not hot‑reload — stop it (<kbd>Ctrl</kbd>+<kbd>C</kbd>) and run `magiclabel review …` again.
+
+---
+
+## Project structure
+
+```text
+magiclabel/
+├── cli.py          # Typer CLI entry point (detect, review, train, yolo2coco, export-classes)
+├── annotator.py    # YOLO / YOLO-World detection → label files + classes.txt
+├── review_app.py   # Gradio review/annotation web app
+├── trainer.py      # builds the dataset and trains a custom model
+├── convertor.py    # YOLO → COCO conversion
+└── utils.py        # image discovery + helpers
+```
+
+---
+
+## License
+
+Released under the [MIT License](LICENSE).

magiclabel-0.1.0/magiclabel/__init__.py

@@ -0,0 +1,2 @@
+"""magiclabel – Open‑source CLI tool for AI‑assisted image annotation."""
+__version__ = "0.1.0"

magiclabel-0.1.0/magiclabel/annotator.py

@@ -0,0 +1,85 @@
+import cv2
+from pathlib import Path
+from typing import List, Optional
+
+from rich.progress import Progress
+
+DEFAULT_CLOSED_MODEL = "yolov8n.pt"        # closed-set: 80 COCO classes
+DEFAULT_OPEN_VOCAB_MODEL = "yolov8s-world.pt"  # open-vocabulary: detect anything from text
+
+
+def detect_images(
+    source: Path,
+    output: Path,
+    conf: float,
+    prompt_classes: Optional[List[str]] = None,
+    model_name: Optional[str] = None,
+) -> dict:
+    """Auto-annotate every image in `source` with bounding boxes.
+
+    Two modes:
+      * closed-set (default): a normal YOLO model (e.g. yolov8n.pt) detects its
+        built-in classes (the 80 COCO objects).
+      * open-vocabulary: when `prompt_classes` is given, YOLO-World detects those
+        named objects with no training (e.g. ["missile", "launcher"]).
+
+    Writes one YOLO `.txt` per image plus a `classes.txt` (the class list, in id
+    order) into `output`. Returns a summary dict {classes, images, boxes}.
+    """
+    output = Path(output)
+    output.mkdir(parents=True, exist_ok=True)
+    images = _get_image_files(source)
+    if not images:
+        raise FileNotFoundError(f"No images found in {source}")
+
+    if prompt_classes:
+        from ultralytics import YOLOWorld
+        detector = YOLOWorld(model_name or DEFAULT_OPEN_VOCAB_MODEL)
+        class_names = [c.strip() for c in prompt_classes if c.strip()]
+        if not class_names:
+            raise ValueError("No class names given in --prompt")
+        detector.set_classes(class_names)
+    else:
+        from ultralytics import YOLO
+        detector = YOLO(model_name or DEFAULT_CLOSED_MODEL)
+        class_names = [detector.names[i] for i in sorted(detector.names)]
+
+    total_boxes = 0
+    with Progress() as progress:
+        task = progress.add_task("Detecting...", total=len(images))
+        for img_path in images:
+            results = detector.predict(img_path, conf=conf, verbose=False)
+            boxes = results[0].boxes
+            if boxes is not None and len(boxes) > 0:
+                cls_ids = boxes.cls.int().tolist()
+                xyxy = boxes.xyxy.tolist()
+                abs_boxes = [[x1, y1, x2 - x1, y2 - y1] for x1, y1, x2, y2 in xyxy]
+                img = cv2.imread(str(img_path))
+                h, w = img.shape[:2]
+                _save_yolo_boxes(output / f"{img_path.stem}.txt", abs_boxes, cls_ids, w, h)
+                total_boxes += len(abs_boxes)
+            progress.advance(task)
+
+    _write_classes_file(output, class_names)
+    return {"classes": class_names, "images": len(images), "boxes": total_boxes}
+
+
+def _save_yolo_boxes(txt_path, boxes, classes, img_w, img_h):
+    with open(txt_path, "w") as f:
+        for box, cls in zip(boxes, classes):
+            x, y, w_box, h_box = box
+            xc = (x + w_box / 2) / img_w
+            yc = (y + h_box / 2) / img_h
+            nw = w_box / img_w
+            nh = h_box / img_h
+            f.write(f"{cls} {xc:.6f} {yc:.6f} {nw:.6f} {nh:.6f}\n")
+
+
+def _write_classes_file(output, class_names):
+    """Write the class list (one name per line, id == line index) for review/training."""
+    (Path(output) / "classes.txt").write_text("\n".join(class_names) + "\n")
+
+
+def _get_image_files(source):
+    from magiclabel.utils import get_image_files
+    return get_image_files(source)