Skip to content

Turn Cat Vision into a reproducible ML portfolio project - #1

Merged
stefisha merged 2 commits into
mainfrom
feat/portfolio-ml-project
Nov 2, 2026
Merged

stefisha merged 2 commits into
mainfrom
feat/portfolio-ml-project

Conversation

@stefisha

@stefisha stefisha commented Nov 2, 2026

Copy link
Copy Markdown
Owner

What changes and why

Cat Vision began as a single Colab notebook that trained and predicted on the same image collection. This PR turns it into a reproducible, documented cat-breed classification project while preserving the original experiment as historical work.

The new cat-vision CLI validates images, deduplicates exact copies, freezes stratified train/validation/test splits, trains a MobileNetV2 baseline, evaluates a saved checkpoint on held-out images, and predicts ranked labels for new photos. Training and inference share image handling, the model embeds the correct normalization, and runs persist label order, data/config/checkpoint fingerprints, completion status, package versions, Git provenance, hardware details and timing.

The repository gains a cat-themed README/banner, installation and usage examples, a resolved dependency lock, CI, contribution templates, architecture/data/experiment guides, a model card, and a verification record. The notebook is moved without content changes.

Validation

  • ruff check . and ruff format --check .: pass.
  • pytest -q: 19 passed on Python 3.11.18 / Apple Silicon CPU, TensorFlow 2.21.0.
  • TensorFlow integration test: two synthetic-image epochs, checkpoint round-trip, evaluation, predictions, preprocessing and artifact-integrity guards; no pretrained-weight download.
  • All four installed CLI commands passed a separate subprocess smoke run on generated images.
  • Source distribution and wheel build, Python compilation, local documentation links and git diff --check: pass.
  • GitHub Actions runs lightweight checks and TensorFlow smoke tests on Ubuntu/Python 3.11 from uv.lock.

ML impact and limits

The historical 88.16% figure is explicitly labeled training accuracy, not held-out performance. No new real-data result is claimed: the dataset was not present in the workspace. The documentation explains the real-data baseline procedure and near-duplicate/source-group leakage limitations. Exact byte deduplication is implemented; perceptual or animal-identity grouping is future work.

Raw images, credentials, generated runs and model weights are excluded from Git. No production serving infrastructure is added.

@stefisha
stefisha force-pushed the feat/portfolio-ml-project branch from b676322 to bd2d2c2 Compare November 2, 2026 22:59

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Unresolved defects can make installed CLI runs fail outside the checkout, let oversized images abort dataset preparation, and cause generated run files to falsely mark a clean checkout as dirty.

3 open issues
What changed in this PR

Turns Cat Vision’s notebook experiment into a packaged, reproducible cat-breed classification workflow, with documented evaluation practices and clear limits on performance claims.

Changes:

  • Adds image preparation, frozen splits, MobileNetV2 training, held-out evaluation, prediction, and traceable run artifacts.
  • Adds synthetic-data tests, pinned dependencies, a resolved lockfile, and CI.
  • Documents data handling, experiment protocols, model limitations, and the historical notebook; no new real-data accuracy is claimed.
File Description
uv.lock Locks direct and transitive dependencies.
tests/​test_pipeline.py Tests training, checkpoint loading, evaluation, and artifact guards.
tests/​test_data.py Tests data contracts, validation, and preparation.
tests/​conftest.py Generates reusable synthetic image fixtures.
src/​cat_vision/​pipeline.py Implements training, evaluation, prediction, and run provenance.
src/​cat_vision/​model.py Defines MobileNetV2 with embedded normalization and augmentation.
src/​cat_vision/​data.py Validates images, removes exact duplicates, and freezes splits.
src/​cat_vision/​cli.py Exposes the four workflow commands.
src/​cat_vision/​__init__.py Introduces package metadata.
README.md Explains setup, usage, project scope, and results status.
pyproject.toml Defines packaging, dependencies, CLI entry point, and tooling.
notebooks/​README.md Explains the historical notebook’s limitations.
Makefile Adds installation, checking, and testing shortcuts.
docs/​verification.md Records validation performed and remaining evidence gaps.
docs/​model-card.md Documents intended use and model limitations.
docs/​experiments.md Defines experiment protocols and run artifacts.
docs/​data.md Documents input requirements, split policy, and leakage risks.
docs/​architecture.md Explains pipeline boundaries and design decisions.
CONTRIBUTING.md Defines development and ML contribution practices.
configs/​baseline.json Provides the initial training configuration.
CHANGELOG.md Summarizes the reproducible project foundation.
assets/​banner.svg Adds Cat Vision branding.
.gitignore Excludes local environments, data, runs, weights, and credentials.
.github/​workflows/​ci.yml Adds lightweight checks and TensorFlow smoke testing.
.github/​pull_request_template.md Prompts for validation and ML-impact details.
.github/​ISSUE_TEMPLATE/​bug_report.yml Collects reproducible bug reports and environment details.

Review effort: Max

Comment thread src/cat_vision/cli.py Resolved
Comment thread src/cat_vision/data.py Resolved
Comment thread src/cat_vision/pipeline.py Resolved
@stefisha
stefisha merged commit 2267279 into main Nov 2, 2026
4 checks passed
@stefisha
stefisha deleted the feat/portfolio-ml-project branch November 2, 2026 23:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants