README.md

---
title: FitCheck
emoji: ✅
colorFrom: indigo
colorTo: green
sdk: gradio
sdk_version: 6.16.0
app_file: app.py
python_version: "3.12"
pinned: false
license: mit
short_description: Honest, plain answers about what AI your computer can run
models:
  - nvidia/NVIDIA-Nemotron-3-Nano-4B-BF16
tags:
  - track:backyard
  - sponsor:nvidia
  - achievement:offbrand
  - achievement:welltuned
  - achievement:fieldnotes
---

<!--
ZeroGPU is selected in the Space's Settings (the README can't set it). The
model brick (/api/ask) only loads the LLM when SPACES_ZERO_GPU is set, so
local `python app.py` stays instant.
-->

# FitCheck

**What AI can your computer actually run?** And the other way round: **what
computer do you need for the AI you want to run?**

Tell FitCheck about your machine in plain words. It answers honestly — real
models, real memory figures, real licenses, real copy-paste commands — from
chatbots to object detection, image generation, speech, and robotics.

## Demo and social post

- Demo video: https://www.youtube.com/watch?v=nz6sBVwA7N8
- Social post: https://x.com/chandran0303/status/2066644768914837994
- Build log and write-up: https://huggingface.co/blog/build-small-hackathon/fitcheck

## Why it's trustworthy

- **A deterministic engine does the math, not an AI.** Verdicts come from a
  transparent rules engine over `catalogue.json` (110 models, generated from
  `scripts/curation.json` and verified against the Hugging Face API). Nothing in
  the verdict can be hallucinated.
- **Model sizes are exact where they can be.** For qualifying GGUF files the
  weights figure is the real Hub file size (displayed rounded to two decimals);
  other entries are parameter-count estimates, labelled as such. Chat memory
  uses each model's real architecture (GQA-aware) where available. Estimates add
  a small fixed safety buffer (a borrowed margin from community load data, not a
  FitCheck-measured confidence).
- **Provenance on every number.** The UI says whether a figure is an exact
  file size, a vendor/Hub figure, third-party aggregate data, community-reported,
  or estimated.
- **Licenses up front.** AGPL, non-commercial, and gated models are labelled
  on every card — before you build your project on one.
- **Speed estimates with receipts, not vibes.** For LLMs, FitCheck predicts
  decode tokens/sec from your memory bandwidth (decode is bandwidth-bound) and
  shows where your machine lands among **real community benchmark runs**
  ([LocalScore](https://www.localscore.ai)) on an interactive roofline chart.
  A gradient-boosted predictor (following IBM's
  [LLM-Pilot methodology](https://arxiv.org/abs/2410.02425)) is grouped by
  accelerator label in cross-validation; it beats the analytical baseline on
  median error but not on every metric, so the bands are honest, not precise.
  Vision and diffusion are compute-bound: FitCheck shows a calibrated
  compute-roofline estimate (a ceiling) for detection and diffusion, with proxy
  limits flagged, and stays silent where it has no calibration.
- **Conservative by design.** Three plain bands (Runs great / Tight, but works
  / Won't fit) that would rather under-promise than over-promise.

## What's inside

1. **The catalogue** — `scripts/curation.json` (hand-picked models across
   LLM, vision-language, vision, image/video generation, speech, music,
   embeddings, forecasting) enriched by `scripts/refresh_catalogue.py` from
   public Hub endpoints into `catalogue.json`. Re-run the script to refresh;
   the result is baked in at build time, so the *deterministic advice* needs no
   network (the parser, narrator, and live lookup do).
2. **The engine** (`engine/`) — pure Python memory math and honest banding.
   Also answers the reverse question: minimum vs comfortable hardware tiers
   for a goal ("Help me pick one" mode).
3. **The model brick** (`model_brick.py`) — NVIDIA Nemotron 3 Nano 4B running
   in-Space on ZeroGPU (hybrid Mamba-2, accelerated by prebuilt hub kernels),
   explaining the engine's numbers in plain words. It never does the math; a
   faithfulness check LOGS any figure it states that isn't in the engine's facts
   (observability only — it does not block or rewrite the answer).
4. **The frontend** (`static/`) — hand-built HTML/CSS/JS, no framework, served
   by Gradio server mode (`gr.Server`). Optional extra: paste any Hugging Face
   model id and FitCheck walks its finetune/quantized lineage to a known base
   ("if the base runs, your finetune runs") — the one clearly-labelled online
   feature.

## Run it locally

```
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
python app.py
```

Open http://127.0.0.1:7860/ (add `?go` for an instant sample result). Locally
the explainer reports the model isn't loaded (it only loads on the Space). The
deterministic advice works without network; the live Hugging Face lookup, the
spec parser, the narrator, web fonts, and the Gradio client need connectivity.

Built for the [Build Small hackathon](https://huggingface.co/build-small-hackathon)
(Backyard AI track).