Repository navigation
Turn Cat Vision into a reproducible ML portfolio project - #1
Merged
Merged
Conversation
stefisha
force-pushed
the
feat/portfolio-ml-project
branch
from
November 2, 2026 22:59
b676322 to
bd2d2c2
Compare
There was a problem hiding this comment.
🟡 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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.

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-visionCLI 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 .andruff format --check .: pass.pytest -q: 19 passed on Python 3.11.18 / Apple Silicon CPU, TensorFlow 2.21.0.git diff --check: pass.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.