ShelfSight - Public Portfolio Release

ShelfSight is a retail shelf object-detection project built during Hackology II. This public version keeps the engineering work visible while removing the competition dataset, organizer task PDF, private-test metadata, trained competition weights, prediction files, and data-derived visual artifacts.

What Is Included

• Reproducible Python project setup with pyproject.toml and uv.lock.
• COCO-to-YOLO data preparation utilities.
• YOLO training wrappers and config templates.
• Inference CLI that writes COCO detection JSON.
• Prediction validation, local scoring, post-processing, and focused tests.
• A tiny synthetic sample input for smoke tests.

What Is Not Included

The original competition rules prohibited publishing competition data without organizer approval. For that reason this repository does not include:

• training images or annotations;
• synthetic competition images or annotations;
• public/private test images or metadata;
• original product taxonomy;
• submitted predictions.json files;
• model weights trained on the competition dataset;
• figures or reports generated from competition images.

The removed files are replaced by templates and safe sample artifacts where needed.

Setup

uv sync --locked
uv run pytest

Smoke Test

The deterministic smoke test skips model loading and only verifies CLI, image discovery, taxonomy loading, ID resolution, and JSON writing:

SHELFSIGHT_SKIP_MODEL=1 uv run python predict.py \
  --input examples/sample_input \
  --output /tmp/shelfsight_predictions.json

Validate the output:

uv run python -m shelfsight.inference.validate_predictions \
  --predictions /tmp/shelfsight_predictions.json \
  --input examples/sample_input

Demo Inference

If no private model is supplied, predict.py falls back to the public Ultralytics yolo11n.pt model and the included COCO-style sample taxonomy.json:

uv run python predict.py \
  --input examples/sample_input \
  --output /tmp/shelfsight_demo_predictions.json

For a custom checkpoint and taxonomy:

SHELFSIGHT_MODEL=/path/to/best.pt \
SHELFSIGHT_TAXONOMY=/path/to/taxonomy.json \
uv run python predict.py --input /path/to/images --output predictions.json

The output is a COCO detection JSON array:

[
  {
    "image_id": 1,
    "category_id": 39,
    "bbox": [100.0, 80.0, 48.0, 120.0],
    "score": 0.91
  }
]

Training With Your Own Data

Put data you are allowed to use under data/ and keep it out of git. A typical flow is:

bash scripts/01_prepare_data.sh \
  --annotations data/train/annotations.json \
  --images-dir data/train/images

DATA=data/yolo_custom/data.yaml MODEL=yolo11l.pt bash scripts/02_train_yolo_real.sh

The config files under configs/ are templates. Replace class names and paths with your own allowed dataset.

Repository Layout

configs/                  Training and inference templates
examples/                 Tiny generated sample input, safe to publish
scripts/                  Data prep, training, validation, and smoke commands
src/shelfsight/data/      COCO inspection, splitting, and YOLO conversion
src/shelfsight/inference/ COCO writing, validation, tiling, merging, ID mapping
src/shelfsight/evaluation/Local scoring and error-analysis helpers
tests/                    Unit and smoke tests
weights/                  Public manifest only; no private trained weights

Notes On Dataset And Licensing

Competition data was provided by Hackology II and is not redistributed here. The public demo path uses Ultralytics YOLO, whose licensing should be reviewed before commercial use. As of the current Ultralytics licensing page, AGPL-3.0 is the open-source route and an Enterprise license is required for proprietary or commercial usage without open-sourcing the full project.

AI coding tools, including ChatGPT/Codex, were used to assist with repository polish, testing, and documentation.

License

This public release is published under AGPL-3.0 to match the open-source licensing route for the Ultralytics YOLO dependency. Review upstream model and framework terms before reusing the project commercially.