hfit 0.1.0__tar.gz

hfit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Samir Nuri
+
+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.

hfit-0.1.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: hfit
+Version: 0.1.0
+Summary: Check whether a Hugging Face model fits your local hardware — without downloading the weights.
+Author-email: Samir Nuri <samirnuri714@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/snuri00/hfit
+Project-URL: Issues, https://github.com/snuri00/hfit/issues
+Keywords: huggingface,llm,vram,gpu,memory,tui,hardware,inference
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: System :: Hardware
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: huggingface_hub>=0.23
+Requires-Dist: rich>=13.0
+Requires-Dist: textual>=0.60
+Provides-Extra: full
+Requires-Dist: psutil>=5.9; extra == "full"
+Dynamic: license-file
+
+# hfit
+
+*Hugging Face + fit.*
+
+**Will this Hugging Face model run on my machine?** Find out in seconds without downloading a single weight file.
+
+Give it a model id like `Qwen/Qwen2.5-7B-Instruct`. It reads the exact
+parameter count and architecture from the Hub's metadata (a few KB of API
+calls), detects your local hardware (GPU VRAM, RAM), and tells you which
+precisions fit:
+
+```
+┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━┓
+┃ Precision           ┃  Weights ┃ KV cache ┃ Required* ┃ Verdict               ┃
+┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━┩
+│ FP16 / BF16 (native)│ 14.19 GB │  0.22 GB │  15.91 GB │ ◐ CPU/RAM only (slow) │
+│ INT8 (quantized)    │  7.09 GB │  0.22 GB │   8.47 GB │ ◐ CPU/RAM only (slow) │
+│ INT4 (quantized)    │  3.55 GB │  0.22 GB │   4.74 GB │ ● tight on GPU        │
+└─────────────────────┴──────────┴──────────┴───────────┴───────────────────────┘
+```
+
+Unlike `accelerate estimate-memory`, this compares the model against **your
+actual hardware** and includes a **KV-cache estimate** at your chosen context
+length computed exactly from the model's architecture (layers × KV heads ×
+head dim), not a flat percentage.
+
+## Install
+
+```bash
+pip install hfit
+# or from a clone of this repo:
+pip install .
+
+```
+
+Dependencies: `huggingface_hub`, `rich`, `textual`. No torch, no CUDA needed.
+
+## Usage
+
+```bash
+hfit                                  # interactive TUI
+hfit Qwen/Qwen2.5-7B-Instruct         # one-shot report
+hfit meta-llama/Llama-3.1-8B-Instruct --ctx 32768
+hfit some/gated-model --token hf_xxx
+```
+
+In the TUI: type a model id, press Enter; switch the context length from the
+dropdown to see the KV cache impact instantly (no refetch). `q` quits.
+
+Exit codes for scripting: `0` = fits somewhere (GPU or RAM), `1` = lookup
+error, `3` = does not fit at all.
+
+## What it understands
+
+- **Safetensors repos** — exact parameter count from Hub metadata.
+- **GGUF repos** (e.g. `bartowski/...-GGUF`) every quant file assessed
+  individually, for llama.cpp / Ollama / LM Studio users.
+- **Multi-component repos** (speech/vision pipelines with several weight
+  folders) reported as a stored total instead of a fake parameter count.
+- Duplicate serializations (safetensors + bin + h5, sharded + consolidated)
+  are deduplicated, not double-counted.
+
+## Platform support
+
+| Platform | GPU detection | RAM detection |
+|---|---|---|
+| Linux | `nvidia-smi`; AMD via sysfs (no ROCm needed), then `rocm-smi` | `/proc/meminfo` |
+| Windows | `nvidia-smi` (PATH or System32) | WinAPI via ctypes |
+| macOS (Apple Silicon) | unified memory (RAM = VRAM budget) | `sysctl` |
+
+`psutil` is used when available (`pip install .[full]`) but is not required.
+
+## How the estimate works
+
+```
+required = weights + KV cache(context) + overhead(0.8 GB + 5% of weights)
+```
+
+- Weights: parameters × bytes-per-parameter (4 / 2 / 1 / 0.5 for
+  FP32 / FP16 / INT8 / INT4).
+- KV cache: `2 × layers × kv_heads × head_dim × 2 bytes × context_tokens`
+  from `config.json`; a 20% margin is used when the architecture is unknown.
+- Verdicts leave ~7% VRAM and ~15% RAM headroom for the driver and OS.
+
+These are pre-flight estimates. For a definitive runtime answer, vLLM's
+`--dry-run` on the actual machine remains the ground truth.

hfit-0.1.0/README.md

@@ -0,0 +1,86 @@
+# hfit
+
+*Hugging Face + fit.*
+
+**Will this Hugging Face model run on my machine?** Find out in seconds without downloading a single weight file.
+
+Give it a model id like `Qwen/Qwen2.5-7B-Instruct`. It reads the exact
+parameter count and architecture from the Hub's metadata (a few KB of API
+calls), detects your local hardware (GPU VRAM, RAM), and tells you which
+precisions fit:
+
+```
+┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━┓
+┃ Precision           ┃  Weights ┃ KV cache ┃ Required* ┃ Verdict               ┃
+┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━┩
+│ FP16 / BF16 (native)│ 14.19 GB │  0.22 GB │  15.91 GB │ ◐ CPU/RAM only (slow) │
+│ INT8 (quantized)    │  7.09 GB │  0.22 GB │   8.47 GB │ ◐ CPU/RAM only (slow) │
+│ INT4 (quantized)    │  3.55 GB │  0.22 GB │   4.74 GB │ ● tight on GPU        │
+└─────────────────────┴──────────┴──────────┴───────────┴───────────────────────┘
+```
+
+Unlike `accelerate estimate-memory`, this compares the model against **your
+actual hardware** and includes a **KV-cache estimate** at your chosen context
+length computed exactly from the model's architecture (layers × KV heads ×
+head dim), not a flat percentage.
+
+## Install
+
+```bash
+pip install hfit
+# or from a clone of this repo:
+pip install .
+
+```
+
+Dependencies: `huggingface_hub`, `rich`, `textual`. No torch, no CUDA needed.
+
+## Usage
+
+```bash
+hfit                                  # interactive TUI
+hfit Qwen/Qwen2.5-7B-Instruct         # one-shot report
+hfit meta-llama/Llama-3.1-8B-Instruct --ctx 32768
+hfit some/gated-model --token hf_xxx
+```
+
+In the TUI: type a model id, press Enter; switch the context length from the
+dropdown to see the KV cache impact instantly (no refetch). `q` quits.
+
+Exit codes for scripting: `0` = fits somewhere (GPU or RAM), `1` = lookup
+error, `3` = does not fit at all.
+
+## What it understands
+
+- **Safetensors repos** — exact parameter count from Hub metadata.
+- **GGUF repos** (e.g. `bartowski/...-GGUF`) every quant file assessed
+  individually, for llama.cpp / Ollama / LM Studio users.
+- **Multi-component repos** (speech/vision pipelines with several weight
+  folders) reported as a stored total instead of a fake parameter count.
+- Duplicate serializations (safetensors + bin + h5, sharded + consolidated)
+  are deduplicated, not double-counted.
+
+## Platform support
+
+| Platform | GPU detection | RAM detection |
+|---|---|---|
+| Linux | `nvidia-smi`; AMD via sysfs (no ROCm needed), then `rocm-smi` | `/proc/meminfo` |
+| Windows | `nvidia-smi` (PATH or System32) | WinAPI via ctypes |
+| macOS (Apple Silicon) | unified memory (RAM = VRAM budget) | `sysctl` |
+
+`psutil` is used when available (`pip install .[full]`) but is not required.
+
+## How the estimate works
+
+```
+required = weights + KV cache(context) + overhead(0.8 GB + 5% of weights)
+```
+
+- Weights: parameters × bytes-per-parameter (4 / 2 / 1 / 0.5 for
+  FP32 / FP16 / INT8 / INT4).
+- KV cache: `2 × layers × kv_heads × head_dim × 2 bytes × context_tokens`
+  from `config.json`; a 20% margin is used when the architecture is unknown.
+- Verdicts leave ~7% VRAM and ~15% RAM headroom for the driver and OS.
+
+These are pre-flight estimates. For a definitive runtime answer, vLLM's
+`--dry-run` on the actual machine remains the ground truth.

hfit-0.1.0/hfit/__init__.py

@@ -0,0 +1,3 @@
+"""hfit — will this Hugging Face model fit on my machine?"""
+
+__version__ = "0.1.0"

hfit-0.1.0/hfit/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

hfit-0.1.0/hfit/cli.py

@@ -0,0 +1,65 @@
+"""Entry point: `hfit MODEL_ID` prints a report, no args opens the TUI."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import List, Optional
+
+from rich.console import Console
+
+from . import __version__
+from .estimate import Verdict, assess, best_verdict
+from .hw import detect
+from .model import ModelLookupError, fetch_model
+from .report import full_report, system_panel
+
+EXIT_OK, EXIT_ERROR, EXIT_NO_FIT = 0, 1, 3
+
+
+def run_check(model_id: str, ctx_tokens: int, token: Optional[str]) -> int:
+    console = Console()
+    specs = detect()
+    console.print(system_panel(specs))
+
+    with console.status(f"Fetching metadata for [bold]{model_id}[/] …"):
+        try:
+            model = fetch_model(model_id, token=token)
+        except ModelLookupError as e:
+            console.print(f"[bold red]{e}[/]")
+            return EXIT_ERROR
+
+    results = assess(model, specs, ctx_tokens)
+    console.print(full_report(model, specs, results, ctx_tokens))
+
+    verdict = best_verdict(results)
+    return EXIT_NO_FIT if verdict in (Verdict.NO_FIT, None) else EXIT_OK
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="hfit",
+        description="Check whether a Hugging Face model fits your local hardware, "
+                    "without downloading the weights.",
+    )
+    parser.add_argument("model", nargs="?",
+                        help="Hugging Face model id (org/name). Omit to open the TUI.")
+    parser.add_argument("--ctx", type=int, default=4096, metavar="TOKENS",
+                        help="context length for the KV-cache estimate (default: 4096)")
+    parser.add_argument("--token", default=None,
+                        help="HF access token for gated/private models "
+                             "(defaults to your cached huggingface-cli login)")
+    parser.add_argument("--version", action="version",
+                        version=f"%(prog)s {__version__}")
+    args = parser.parse_args(argv)
+
+    if args.model:
+        return run_check(args.model.strip().strip("/"), args.ctx, args.token)
+
+    from .tui import run_tui  # imported lazily so plain CLI use stays snappy
+    run_tui(ctx_tokens=args.ctx, token=args.token)
+    return EXIT_OK
+
+
+if __name__ == "__main__":
+    sys.exit(main())

hfit-0.1.0/hfit/estimate.py

@@ -0,0 +1,132 @@
+"""Memory math and fit verdicts.
+
+Required memory = weights + KV cache at the chosen context + runtime overhead.
+The KV cache is computed exactly from the architecture when config.json is
+available, otherwise approximated as 20% of the weights.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import List, Optional
+
+from .hw import SystemSpecs
+from .model import HFModel
+
+GiB = 1024**3
+
+# label, bytes per parameter, needs a quantized checkpoint?
+PRECISIONS = [
+    ("FP32", 4.0, False),
+    ("FP16 / BF16", 2.0, False),
+    ("INT8 (quantized)", 1.0, True),
+    ("INT4 (quantized)", 0.5, True),
+]
+
+# Fractions of reported memory treated as actually usable: leave headroom for
+# the CUDA context and fragmentation on GPUs, and for the OS on system RAM.
+GPU_HEADROOM = 0.93
+RAM_HEADROOM = 0.85
+FRAMEWORK_OVERHEAD_GB = 0.8   # CUDA/Metal context, runtime buffers
+ACTIVATION_FRACTION = 0.05    # inference activations, scales with model size
+
+
+class Verdict(Enum):
+    GPU_OK = "gpu_ok"
+    GPU_TIGHT = "gpu_tight"
+    CPU_OK = "cpu_ok"
+    NO_FIT = "no_fit"
+
+
+@dataclass
+class Assessment:
+    label: str
+    weights_gb: float
+    kv_gb: Optional[float]     # None -> folded into overhead as a rough margin
+    required_gb: float
+    verdict: Verdict
+    note: str = ""
+
+
+def _kv_gb(model: HFModel, ctx_tokens: int) -> Optional[float]:
+    if model.kv is None:
+        return None
+    return model.kv.bytes_per_token * ctx_tokens / GiB
+
+
+def _required(weights_gb: float, kv_gb: Optional[float]) -> float:
+    overhead = FRAMEWORK_OVERHEAD_GB + weights_gb * ACTIVATION_FRACTION
+    if kv_gb is None:
+        overhead += weights_gb * 0.20  # no architecture info: rough KV margin
+        kv_gb = 0.0
+    return weights_gb + kv_gb + overhead
+
+
+def _judge(required_gb: float, specs: SystemSpecs) -> Verdict:
+    ram_budget = (specs.ram_available_gb or specs.ram_total_gb * 0.8) * RAM_HEADROOM
+
+    if specs.unified_memory:
+        # One memory pool: the GPU can address (most of) system RAM.
+        if required_gb <= ram_budget:
+            return Verdict.GPU_OK
+        if required_gb <= specs.ram_total_gb * RAM_HEADROOM:
+            return Verdict.GPU_TIGHT
+        return Verdict.NO_FIT
+
+    if specs.gpus:
+        free = specs.vram_free_gb
+        vram_budget = (free if free is not None else specs.vram_total_gb) * GPU_HEADROOM
+        if required_gb <= vram_budget:
+            return Verdict.GPU_OK
+        if required_gb <= specs.vram_total_gb:
+            return Verdict.GPU_TIGHT
+    if required_gb <= ram_budget:
+        return Verdict.CPU_OK
+    return Verdict.NO_FIT
+
+
+def assess(model: HFModel, specs: SystemSpecs, ctx_tokens: int = 4096) -> List[Assessment]:
+    results: List[Assessment] = []
+    kv = _kv_gb(model, ctx_tokens)
+
+    if model.params:
+        native = (model.native_dtype or "").upper()
+        for label, bytes_pp, needs_quant in PRECISIONS:
+            weights = model.params * bytes_pp / GiB
+            required = _required(weights, kv)
+            note = ""
+            if needs_quant:
+                note = "needs a quantized build (AWQ/GPTQ/bitsandbytes)"
+            elif "16" in label and native in ("F16", "BF16", "FP16"):
+                label += "  (native)"
+            elif label == "FP32" and native in ("F16", "BF16", "FP16"):
+                note = "upcast — rarely useful for inference"
+            results.append(Assessment(label, weights, kv, required,
+                                      _judge(required, specs), note))
+
+    if model.params is None and model.weight_bytes:
+        # Multi-component pipeline repo: report the stored total, no dtype rows.
+        weights = model.weight_bytes / GiB
+        required = _required(weights, kv)
+        results.append(Assessment(
+            f"Full pipeline as stored ({model.weight_components} components)",
+            weights, kv, required, _judge(required, specs),
+            "sum of all weight folders in the repo",
+        ))
+
+    for name, size in model.gguf_files:
+        weights = size / GiB
+        required = _required(weights, kv)
+        results.append(Assessment(f"GGUF: {name}", weights, kv, required,
+                                  _judge(required, specs),
+                                  "runs with llama.cpp / Ollama / LM Studio"))
+    return results
+
+
+def best_verdict(results: List[Assessment]) -> Optional[Verdict]:
+    order = [Verdict.GPU_OK, Verdict.GPU_TIGHT, Verdict.CPU_OK, Verdict.NO_FIT]
+    for v in order:
+        if any(r.verdict == v for r in results):
+            return v
+    return None

hfit-0.1.0/hfit/hw.py

@@ -0,0 +1,231 @@
+"""Cross-platform hardware detection with no hard dependencies.
+
+Detection order per vendor, cheapest reliable source first:
+  NVIDIA  -> nvidia-smi (Linux/Windows/WSL)
+  AMD     -> /sys/class/drm sysfs (Linux, no ROCm needed), then rocm-smi
+  Apple   -> unified memory on arm64 macOS (VRAM budget == system RAM)
+  RAM     -> psutil if installed, else /proc/meminfo, sysctl, or WinAPI
+"""
+
+from __future__ import annotations
+
+import ctypes
+import glob
+import os
+import platform
+import re
+import subprocess
+import sys
+from dataclasses import dataclass, field
+from typing import List, Optional, Tuple
+
+GiB = 1024**3
+
+
+def _run(cmd: List[str], timeout: float = 10.0) -> Optional[str]:
+    try:
+        out = subprocess.run(
+            cmd, capture_output=True, text=True, timeout=timeout,
+            creationflags=getattr(subprocess, "CREATE_NO_WINDOW", 0),
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    if out.returncode != 0:
+        return None
+    return out.stdout
+
+
+@dataclass
+class GPU:
+    name: str
+    vendor: str  # "nvidia" | "amd" | "apple"
+    total_gb: float
+    free_gb: Optional[float] = None  # None when the driver can't report it
+
+
+@dataclass
+class SystemSpecs:
+    os_name: str
+    arch: str
+    cpu: str
+    cores: int
+    ram_total_gb: float
+    ram_available_gb: Optional[float]
+    gpus: List[GPU] = field(default_factory=list)
+    unified_memory: bool = False  # Apple Silicon: RAM and VRAM are one pool
+
+    @property
+    def vram_total_gb(self) -> float:
+        return sum(g.total_gb for g in self.gpus)
+
+    @property
+    def vram_free_gb(self) -> Optional[float]:
+        if not self.gpus or any(g.free_gb is None for g in self.gpus):
+            return None
+        return sum(g.free_gb for g in self.gpus)
+
+
+# --------------------------------------------------------------------------- #
+# GPU detection
+# --------------------------------------------------------------------------- #
+
+def _detect_nvidia() -> List[GPU]:
+    out = _run([
+        "nvidia-smi",
+        "--query-gpu=name,memory.total,memory.free",
+        "--format=csv,noheader,nounits",
+    ])
+    if out is None and sys.platform == "win32":
+        smi = os.path.join(os.environ.get("SystemRoot", r"C:\Windows"),
+                           "System32", "nvidia-smi.exe")
+        if os.path.exists(smi):
+            out = _run([smi, "--query-gpu=name,memory.total,memory.free",
+                        "--format=csv,noheader,nounits"])
+    gpus: List[GPU] = []
+    for line in (out or "").strip().splitlines():
+        parts = [p.strip() for p in line.split(",")]
+        if len(parts) < 3:
+            continue
+        try:
+            total, free = float(parts[-2]) / 1024, float(parts[-1]) / 1024
+        except ValueError:
+            continue
+        gpus.append(GPU(name=parts[0], vendor="nvidia", total_gb=total, free_gb=free))
+    return gpus
+
+
+def _detect_amd_sysfs() -> List[GPU]:
+    """amdgpu kernel driver exposes VRAM in sysfs — works without ROCm."""
+    gpus: List[GPU] = []
+    for dev in sorted(glob.glob("/sys/class/drm/card[0-9]*/device")):
+        try:
+            with open(os.path.join(dev, "vendor")) as f:
+                if f.read().strip().lower() != "0x1002":  # AMD PCI vendor id
+                    continue
+            with open(os.path.join(dev, "mem_info_vram_total")) as f:
+                total = int(f.read().strip()) / GiB
+            free = None
+            used_path = os.path.join(dev, "mem_info_vram_used")
+            if os.path.exists(used_path):
+                with open(used_path) as f:
+                    free = total - int(f.read().strip()) / GiB
+        except (OSError, ValueError):
+            continue
+        if total < 0.25:  # skip tiny iGPU carve-outs reported by some APUs
+            continue
+        gpus.append(GPU(name="AMD GPU (amdgpu)", vendor="amd",
+                        total_gb=total, free_gb=free))
+    return gpus
+
+
+def _detect_amd_rocm() -> List[GPU]:
+    out = _run(["rocm-smi", "--showmeminfo", "vram", "--csv"])
+    gpus: List[GPU] = []
+    for line in (out or "").strip().splitlines():
+        m = re.match(r"card(\d+),(\d+),(\d+)", line.replace(" ", ""))
+        if not m:
+            continue
+        total = int(m.group(2)) / GiB
+        free = total - int(m.group(3)) / GiB
+        gpus.append(GPU(name=f"AMD GPU {m.group(1)} (ROCm)", vendor="amd",
+                        total_gb=total, free_gb=free))
+    return gpus
+
+
+def _detect_apple(ram_total_gb: float) -> List[GPU]:
+    if sys.platform != "darwin" or platform.machine() != "arm64":
+        return []
+    chip = (_run(["sysctl", "-n", "machdep.cpu.brand_string"]) or "Apple Silicon").strip()
+    return [GPU(name=f"{chip} (unified memory)", vendor="apple",
+                total_gb=ram_total_gb, free_gb=None)]
+
+
+# --------------------------------------------------------------------------- #
+# RAM / CPU detection
+# --------------------------------------------------------------------------- #
+
+def _ram() -> Tuple[float, Optional[float]]:
+    try:
+        import psutil  # optional dependency
+        vm = psutil.virtual_memory()
+        return vm.total / GiB, vm.available / GiB
+    except ImportError:
+        pass
+
+    if sys.platform.startswith("linux"):
+        info = {}
+        try:
+            with open("/proc/meminfo") as f:
+                for line in f:
+                    key, _, rest = line.partition(":")
+                    info[key] = int(rest.strip().split()[0]) * 1024
+        except (OSError, ValueError, IndexError):
+            return 0.0, None
+        total = info.get("MemTotal", 0) / GiB
+        avail = info.get("MemAvailable")
+        return total, (avail / GiB if avail is not None else None)
+
+    if sys.platform == "darwin":
+        out = _run(["sysctl", "-n", "hw.memsize"])
+        total = int(out.strip()) / GiB if out else 0.0
+        return total, None
+
+    if sys.platform == "win32":
+        class MEMORYSTATUSEX(ctypes.Structure):
+            _fields_ = [
+                ("dwLength", ctypes.c_ulong),
+                ("dwMemoryLoad", ctypes.c_ulong),
+                ("ullTotalPhys", ctypes.c_ulonglong),
+                ("ullAvailPhys", ctypes.c_ulonglong),
+                ("ullTotalPageFile", ctypes.c_ulonglong),
+                ("ullAvailPageFile", ctypes.c_ulonglong),
+                ("ullTotalVirtual", ctypes.c_ulonglong),
+                ("ullAvailVirtual", ctypes.c_ulonglong),
+                ("ullAvailExtendedVirtual", ctypes.c_ulonglong),
+            ]
+
+        stat = MEMORYSTATUSEX()
+        stat.dwLength = ctypes.sizeof(MEMORYSTATUSEX)
+        if ctypes.windll.kernel32.GlobalMemoryStatusEx(ctypes.byref(stat)):
+            return stat.ullTotalPhys / GiB, stat.ullAvailPhys / GiB
+
+    return 0.0, None
+
+
+def _cpu_name() -> str:
+    if sys.platform.startswith("linux"):
+        try:
+            with open("/proc/cpuinfo") as f:
+                for line in f:
+                    if line.lower().startswith("model name"):
+                        return line.split(":", 1)[1].strip()
+        except OSError:
+            pass
+    elif sys.platform == "darwin":
+        out = _run(["sysctl", "-n", "machdep.cpu.brand_string"])
+        if out:
+            return out.strip()
+    return platform.processor() or platform.machine() or "Unknown CPU"
+
+
+def detect() -> SystemSpecs:
+    ram_total, ram_avail = _ram()
+
+    gpus = _detect_nvidia()
+    if not gpus and sys.platform.startswith("linux"):
+        gpus = _detect_amd_sysfs() or _detect_amd_rocm()
+    unified = False
+    if not gpus:
+        gpus = _detect_apple(ram_total)
+        unified = bool(gpus)
+
+    return SystemSpecs(
+        os_name=f"{platform.system()} {platform.release()}",
+        arch=platform.machine(),
+        cpu=_cpu_name(),
+        cores=os.cpu_count() or 1,
+        ram_total_gb=ram_total,
+        ram_available_gb=ram_avail,
+        gpus=gpus,
+        unified_memory=unified,
+    )

hfit-0.1.0/hfit/model.py

@@ -0,0 +1,200 @@
+"""Fetch model metadata from the Hugging Face Hub without downloading weights.
+
+Parameter counts come from the Hub's safetensors index (exact, free).
+Architecture details for the KV-cache estimate come from config.json (~1 KB).
+GGUF-only repos are handled per quant file, using file sizes.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import List, Optional, Tuple
+
+from huggingface_hub import HfApi, hf_hub_download
+from huggingface_hub.utils import (
+    EntryNotFoundError,
+    GatedRepoError,
+    HfHubHTTPError,
+    RepositoryNotFoundError,
+)
+
+WEIGHT_EXTS = (".safetensors", ".bin", ".pt", ".pth", ".msgpack", ".h5")
+
+# bytes per parameter for the native checkpoint, keyed by Hub dtype names
+DTYPE_BYTES = {
+    "F64": 8, "F32": 4, "F16": 2, "BF16": 2, "FP16": 2,
+    "I64": 8, "I32": 4, "I16": 2, "I8": 1, "U8": 1,
+    "F8_E4M3": 1, "F8_E5M2": 1, "I4": 0.5, "U4": 0.5,
+}
+
+
+class ModelLookupError(Exception):
+    """User-presentable failure while resolving a model."""
+
+
+@dataclass
+class KVConfig:
+    num_layers: int
+    kv_heads: int
+    head_dim: int
+
+    @property
+    def bytes_per_token(self) -> int:
+        # K and V, fp16 cache: 2 tensors * 2 bytes
+        return 2 * self.num_layers * self.kv_heads * self.head_dim * 2
+
+
+@dataclass
+class HFModel:
+    model_id: str
+    params: Optional[int]            # total parameter count, None if unknown
+    params_estimated: bool           # True when derived from file sizes
+    native_dtype: Optional[str]      # e.g. "BF16"
+    weight_bytes: Optional[int]      # sum of transformer-format weight files
+    gguf_files: List[Tuple[str, int]] = field(default_factory=list)
+    gated: bool = False
+    pipeline_tag: Optional[str] = None
+    downloads: Optional[int] = None
+    kv: Optional[KVConfig] = None
+    max_ctx: Optional[int] = None
+    weight_components: int = 0   # distinct repo folders holding weights
+
+    @property
+    def params_b(self) -> Optional[float]:
+        return self.params / 1e9 if self.params else None
+
+
+def _dig(cfg: dict, *keys, default=None):
+    for key in keys:
+        if key in cfg and cfg[key] is not None:
+            return cfg[key]
+    return default
+
+
+def _text_config(cfg: dict) -> dict:
+    """Return the sub-config that actually describes the language model."""
+    if _dig(cfg, "num_hidden_layers", "n_layer", "num_layers") is not None:
+        return cfg
+    for key in ("text_config", "llm_config", "language_config", "decoder"):
+        sub = cfg.get(key)
+        if isinstance(sub, dict) and _dig(sub, "num_hidden_layers", "n_layer") is not None:
+            return sub
+    return cfg
+
+
+def _parse_config(model_id: str, token: Optional[str]) -> Tuple[Optional[KVConfig], Optional[int], Optional[str]]:
+    try:
+        path = hf_hub_download(model_id, "config.json", token=token)
+        with open(path) as f:
+            raw = json.load(f)
+    except Exception:
+        return None, None, None
+
+    cfg = _text_config(raw)
+    dtype = _dig(cfg, "dtype", "torch_dtype") or _dig(raw, "dtype", "torch_dtype")
+    max_ctx = _dig(cfg, "max_position_embeddings", "n_positions", "max_sequence_length")
+
+    layers = _dig(cfg, "num_hidden_layers", "n_layer", "num_layers")
+    heads = _dig(cfg, "num_attention_heads", "n_head")
+    hidden = _dig(cfg, "hidden_size", "n_embd", "d_model")
+    if not (layers and heads and hidden):
+        return None, max_ctx, dtype
+
+    kv_heads = _dig(cfg, "num_key_value_heads", default=heads)
+    head_dim = _dig(cfg, "head_dim", default=hidden // heads)
+    return KVConfig(int(layers), int(kv_heads), int(head_dim)), max_ctx, dtype
+
+
+def fetch_model(model_id: str, token: Optional[str] = None) -> HFModel:
+    api = HfApi(token=token)
+    try:
+        info = api.model_info(model_id, files_metadata=True)
+    except RepositoryNotFoundError:
+        raise ModelLookupError(
+            f"Model '{model_id}' not found on the Hugging Face Hub.\n"
+            "Check the spelling — the id must be 'organization/model-name'."
+        ) from None
+    except GatedRepoError:
+        raise ModelLookupError(
+            f"'{model_id}' is a gated model. Accept its license on huggingface.co, "
+            "then log in with 'huggingface-cli login' or pass --token."
+        ) from None
+    except HfHubHTTPError as e:
+        raise ModelLookupError(f"Hub request failed for '{model_id}': {e}") from None
+    except Exception as e:
+        raise ModelLookupError(
+            f"Could not reach the Hugging Face Hub: {e}\nCheck your internet connection."
+        ) from None
+
+    gguf_files: List[Tuple[str, int]] = []
+    by_dir: dict = {}
+    for sib in info.siblings or []:
+        name, size = sib.rfilename, sib.size or 0
+        low = name.lower()
+        if low.endswith(".gguf"):
+            gguf_files.append((name, size))
+        elif low.endswith(WEIGHT_EXTS) and "optimizer" not in low:
+            dirname = name.rsplit("/", 1)[0] if "/" in name else ""
+            by_dir.setdefault(dirname, []).append((name, size))
+    gguf_files.sort(key=lambda x: x[1])
+
+    weight_bytes = 0
+    for files in by_dir.values():
+        weight_bytes += sum(size for _, size in _dedup_formats(files))
+
+    params = info.safetensors.total if info.safetensors else None
+    native_dtype = None
+    if info.safetensors and info.safetensors.parameters:
+        native_dtype = max(info.safetensors.parameters, key=info.safetensors.parameters.get)
+
+    kv, max_ctx, cfg_dtype = _parse_config(model_id, token)
+    if native_dtype is None and cfg_dtype:
+        native_dtype = str(cfg_dtype).upper().replace("FLOAT", "F").replace("BFLOAT", "BF")
+
+    params_estimated = False
+    if params is None and weight_bytes and len(by_dir) == 1:
+        # Single-model repo: estimate the count from checkpoint size and dtype.
+        # Multi-component repos (speech pipelines, VAE+LLM combos) keep params
+        # unset — a single parameter count would be misleading there.
+        per_param = DTYPE_BYTES.get(native_dtype or "", 2)
+        params = int(weight_bytes / per_param)
+        params_estimated = True
+
+    return HFModel(
+        model_id=info.id,
+        params=params,
+        params_estimated=params_estimated,
+        native_dtype=native_dtype,
+        weight_bytes=weight_bytes or None,
+        gguf_files=gguf_files,
+        gated=bool(info.gated),
+        pipeline_tag=info.pipeline_tag,
+        downloads=info.downloads,
+        kv=kv,
+        max_ctx=max_ctx,
+        weight_components=len(by_dir),
+    )
+
+
+def _dedup_formats(files: List[Tuple[str, int]]) -> List[Tuple[str, int]]:
+    """Drop redundant copies of the same weights within one repo folder.
+
+    Repos often ship several serializations side by side (safetensors + bin +
+    h5, or sharded shards + a consolidated file). Keep only the best format.
+    """
+    def fmt_rank(name: str) -> int:
+        low = name.lower()
+        if low.endswith(".safetensors"):
+            return 0
+        if low.endswith((".bin", ".pt", ".pth")):
+            return 1
+        return 2  # .h5, .msgpack
+
+    best = min(fmt_rank(n) for n, _ in files)
+    kept = [(n, s) for n, s in files if fmt_rank(n) == best]
+
+    sharded = [x for x in kept if "-of-" in x[0].rsplit("/", 1)[-1]]
+    if sharded and len(sharded) < len(kept):
+        kept = sharded  # drop consolidated.* duplicates next to shards
+    return kept

hfit-0.1.0/hfit/report.py

@@ -0,0 +1,143 @@
+"""Rich renderables shared by the CLI and the TUI."""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+from rich.console import Group, RenderableType
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+from .estimate import Assessment, Verdict, best_verdict
+from .hw import SystemSpecs
+from .model import HFModel
+
+VERDICT_STYLE = {
+    Verdict.GPU_OK:   ("✔ fits on GPU", "bold green"),
+    Verdict.GPU_TIGHT: ("● tight on GPU", "bold yellow"),
+    Verdict.CPU_OK:   ("◐ CPU/RAM only (slow)", "bold dark_orange"),
+    Verdict.NO_FIT:   ("✘ does not fit", "bold red"),
+}
+
+SUMMARY_LINE = {
+    Verdict.GPU_OK: ("This model can run comfortably on your GPU.", "green"),
+    Verdict.GPU_TIGHT: ("It fits on your GPU, but barely — close other GPU apps "
+                        "or lower gpu-memory-utilization.", "yellow"),
+    Verdict.CPU_OK: ("Too big for your GPU. It can run from system RAM "
+                     "(CPU or partial offload) — expect low speed.", "dark_orange"),
+    Verdict.NO_FIT: ("This model does not fit this machine in any listed precision.",
+                     "red"),
+}
+
+
+def _gb(x: Optional[float]) -> str:
+    return f"{x:.2f} GB" if x is not None else "—"
+
+
+def system_panel(specs: SystemSpecs) -> Panel:
+    t = Table.grid(padding=(0, 2))
+    t.add_column(style="bold cyan", justify="right")
+    t.add_column()
+    t.add_row("OS", f"{specs.os_name} ({specs.arch})")
+    t.add_row("CPU", f"{specs.cpu}  ×{specs.cores}")
+    ram = f"{specs.ram_total_gb:.1f} GB total"
+    if specs.ram_available_gb is not None:
+        ram += f", {specs.ram_available_gb:.1f} GB available"
+    t.add_row("RAM", ram)
+    if specs.gpus:
+        for g in specs.gpus:
+            vram = f"{g.total_gb:.1f} GB VRAM"
+            if g.free_gb is not None:
+                vram += f", {g.free_gb:.1f} GB free"
+            if specs.unified_memory:
+                vram = "shares system RAM (unified)"
+            t.add_row("GPU", f"{g.name} — {vram}")
+    else:
+        t.add_row("GPU", Text("none detected — verdicts use system RAM only", "dim"))
+    return Panel(t, title="[bold]Your machine", border_style="cyan")
+
+
+def model_panel(model: HFModel) -> Panel:
+    t = Table.grid(padding=(0, 2))
+    t.add_column(style="bold magenta", justify="right")
+    t.add_column()
+    if model.params_b:
+        est = "  (estimated from file sizes)" if model.params_estimated else ""
+        t.add_row("Parameters", f"{model.params_b:.2f} B{est}")
+    if model.weight_bytes:
+        size = f"{model.weight_bytes / 1024**3:.2f} GB"
+        if model.weight_components > 1:
+            size += f"  ({model.weight_components} weight components)"
+        t.add_row("On disk", size)
+    if model.native_dtype:
+        t.add_row("Native dtype", model.native_dtype)
+    if model.pipeline_tag:
+        t.add_row("Task", model.pipeline_tag)
+    if model.max_ctx:
+        t.add_row("Max context", f"{model.max_ctx:,} tokens")
+    if model.downloads is not None:
+        t.add_row("Downloads", f"{model.downloads:,}/month")
+    if model.gguf_files:
+        t.add_row("GGUF quants", f"{len(model.gguf_files)} file(s) in repo")
+    if model.gated:
+        t.add_row("Access", Text("gated — license acceptance required", "yellow"))
+    return Panel(t, title=f"[bold]{model.model_id}", border_style="magenta")
+
+
+def results_table(results: List[Assessment], ctx_tokens: int) -> Table:
+    table = Table(title=f"Fit assessment @ {ctx_tokens:,}-token context",
+                  title_style="bold", header_style="bold")
+    table.add_column("Precision", overflow="fold")
+    table.add_column("Weights", justify="right")
+    table.add_column("KV cache", justify="right")
+    table.add_column("Required*", justify="right")
+    table.add_column("Verdict")
+    table.add_column("Note", style="dim", overflow="fold")
+
+    for r in results:
+        label, style = VERDICT_STYLE[r.verdict]
+        table.add_row(
+            r.label,
+            _gb(r.weights_gb),
+            _gb(r.kv_gb),
+            _gb(r.required_gb),
+            Text(label, style=style),
+            r.note,
+        )
+    return table
+
+
+def full_report(model: HFModel, specs: SystemSpecs,
+                results: List[Assessment], ctx_tokens: int) -> RenderableType:
+    parts: List[RenderableType] = [model_panel(model)]
+
+    if not results:
+        parts.append(Text(
+            "No parameter count or weight files found for this repo — "
+            "cannot estimate memory (it may be a dataset-style or adapter repo).",
+            style="yellow",
+        ))
+        return Group(*parts)
+
+    parts.append(results_table(results, ctx_tokens))
+
+    if model.max_ctx and ctx_tokens > model.max_ctx:
+        parts.append(Text(
+            f"Note: the chosen context ({ctx_tokens:,}) exceeds this model's "
+            f"maximum ({model.max_ctx:,} tokens).", style="yellow",
+        ))
+
+    verdict = best_verdict(results)
+    if verdict is not None:
+        line, style = SUMMARY_LINE[verdict]
+        parts.append(Text(f"\n{line}", style=f"bold {style}"))
+
+    footnotes = ("*Required = weights + KV cache + runtime overhead "
+                 f"(~{0.8:.1f} GB + 5% activations).")
+    if any(r.kv_gb is None for r in results):
+        footnotes += " KV cache unknown for this architecture — a 20% margin was used."
+    footnotes += (" INT8/INT4 rows are theoretical: they need an actual quantized "
+                  "checkpoint or on-the-fly quantization.")
+    parts.append(Text(footnotes, style="dim"))
+    return Group(*parts)

hfit-0.1.0/hfit/tui.py

@@ -0,0 +1,111 @@
+"""Textual TUI: type a model id, get a fit report against this machine."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from rich.text import Text
+from textual import work
+from textual.app import App, ComposeResult
+from textual.containers import Horizontal, VerticalScroll
+from textual.widgets import Footer, Header, Input, Select, Static
+
+from . import __version__
+from .estimate import assess
+from .hw import detect
+from .model import HFModel, ModelLookupError, fetch_model
+from .report import full_report, system_panel
+
+CTX_CHOICES = [2048, 4096, 8192, 16384, 32768, 65536, 131072]
+
+
+def _ctx_label(tokens: int) -> str:
+    return f"{tokens // 1024}k context"
+
+
+class SpecCheckerApp(App):
+    TITLE = "hfit"
+    SUB_TITLE = f"v{__version__} — will it run on this machine?"
+
+    CSS = """
+    #topbar { height: 3; dock: top; }
+    #model-input { width: 1fr; }
+    #ctx-select { width: 24; }
+    #results { padding: 0 1; }
+    #system-panel { margin-bottom: 1; }
+    """
+
+    BINDINGS = [
+        ("q", "quit", "Quit"),
+        ("ctrl+l", "focus_input", "New model"),
+    ]
+
+    def __init__(self, ctx_tokens: int = 4096, token: Optional[str] = None):
+        super().__init__()
+        self.ctx_tokens = ctx_tokens if ctx_tokens in CTX_CHOICES else 4096
+        self.hf_token = token
+        self.specs = detect()
+        self.current_model: Optional[HFModel] = None
+
+    def compose(self) -> ComposeResult:
+        yield Header()
+        with Horizontal(id="topbar"):
+            yield Input(
+                placeholder="org/model-name  (e.g. Qwen/Qwen2.5-7B-Instruct) — Enter to check",
+                id="model-input",
+            )
+            yield Select(
+                [(_ctx_label(c), c) for c in CTX_CHOICES],
+                value=self.ctx_tokens, allow_blank=False, id="ctx-select",
+            )
+        with VerticalScroll(id="results"):
+            yield Static(system_panel(self.specs), id="system-panel")
+            yield Static(
+                Text("Enter a Hugging Face model id above to start.", style="dim"),
+                id="report",
+            )
+        yield Footer()
+
+    def on_mount(self) -> None:
+        self.query_one("#model-input", Input).focus()
+
+    def action_focus_input(self) -> None:
+        inp = self.query_one("#model-input", Input)
+        inp.focus()
+        inp.selection = (0, len(inp.value))
+
+    def on_input_submitted(self, event: Input.Submitted) -> None:
+        model_id = event.value.strip().strip("/")
+        if model_id:
+            self.check_model(model_id)
+
+    def on_select_changed(self, event: Select.Changed) -> None:
+        if event.select.id != "ctx-select" or event.value is None:
+            return
+        self.ctx_tokens = int(event.value)
+        if self.current_model is not None:
+            self._render(self.current_model)
+
+    @work(thread=True, exclusive=True)
+    def check_model(self, model_id: str) -> None:
+        report = self.query_one("#report", Static)
+        self.call_from_thread(
+            report.update, Text(f"Fetching metadata for {model_id} …", style="italic yellow")
+        )
+        try:
+            model = fetch_model(model_id, token=self.hf_token)
+        except ModelLookupError as e:
+            self.call_from_thread(report.update, Text(str(e), style="bold red"))
+            return
+        self.current_model = model
+        self.call_from_thread(self._render, model)
+
+    def _render(self, model: HFModel) -> None:
+        results = assess(model, self.specs, self.ctx_tokens)
+        self.query_one("#report", Static).update(
+            full_report(model, self.specs, results, self.ctx_tokens)
+        )
+
+
+def run_tui(ctx_tokens: int = 4096, token: Optional[str] = None) -> None:
+    SpecCheckerApp(ctx_tokens=ctx_tokens, token=token).run()

hfit-0.1.0/hfit.egg-info/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: hfit
+Version: 0.1.0
+Summary: Check whether a Hugging Face model fits your local hardware — without downloading the weights.
+Author-email: Samir Nuri <samirnuri714@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/snuri00/hfit
+Project-URL: Issues, https://github.com/snuri00/hfit/issues
+Keywords: huggingface,llm,vram,gpu,memory,tui,hardware,inference
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: System :: Hardware
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: huggingface_hub>=0.23
+Requires-Dist: rich>=13.0
+Requires-Dist: textual>=0.60
+Provides-Extra: full
+Requires-Dist: psutil>=5.9; extra == "full"
+Dynamic: license-file
+
+# hfit
+
+*Hugging Face + fit.*
+
+**Will this Hugging Face model run on my machine?** Find out in seconds without downloading a single weight file.
+
+Give it a model id like `Qwen/Qwen2.5-7B-Instruct`. It reads the exact
+parameter count and architecture from the Hub's metadata (a few KB of API
+calls), detects your local hardware (GPU VRAM, RAM), and tells you which
+precisions fit:
+
+```
+┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━┓
+┃ Precision           ┃  Weights ┃ KV cache ┃ Required* ┃ Verdict               ┃
+┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━┩
+│ FP16 / BF16 (native)│ 14.19 GB │  0.22 GB │  15.91 GB │ ◐ CPU/RAM only (slow) │
+│ INT8 (quantized)    │  7.09 GB │  0.22 GB │   8.47 GB │ ◐ CPU/RAM only (slow) │
+│ INT4 (quantized)    │  3.55 GB │  0.22 GB │   4.74 GB │ ● tight on GPU        │
+└─────────────────────┴──────────┴──────────┴───────────┴───────────────────────┘
+```
+
+Unlike `accelerate estimate-memory`, this compares the model against **your
+actual hardware** and includes a **KV-cache estimate** at your chosen context
+length computed exactly from the model's architecture (layers × KV heads ×
+head dim), not a flat percentage.
+
+## Install
+
+```bash
+pip install hfit
+# or from a clone of this repo:
+pip install .
+
+```
+
+Dependencies: `huggingface_hub`, `rich`, `textual`. No torch, no CUDA needed.
+
+## Usage
+
+```bash
+hfit                                  # interactive TUI
+hfit Qwen/Qwen2.5-7B-Instruct         # one-shot report
+hfit meta-llama/Llama-3.1-8B-Instruct --ctx 32768
+hfit some/gated-model --token hf_xxx
+```
+
+In the TUI: type a model id, press Enter; switch the context length from the
+dropdown to see the KV cache impact instantly (no refetch). `q` quits.
+
+Exit codes for scripting: `0` = fits somewhere (GPU or RAM), `1` = lookup
+error, `3` = does not fit at all.
+
+## What it understands
+
+- **Safetensors repos** — exact parameter count from Hub metadata.
+- **GGUF repos** (e.g. `bartowski/...-GGUF`) every quant file assessed
+  individually, for llama.cpp / Ollama / LM Studio users.
+- **Multi-component repos** (speech/vision pipelines with several weight
+  folders) reported as a stored total instead of a fake parameter count.
+- Duplicate serializations (safetensors + bin + h5, sharded + consolidated)
+  are deduplicated, not double-counted.
+
+## Platform support
+
+| Platform | GPU detection | RAM detection |
+|---|---|---|
+| Linux | `nvidia-smi`; AMD via sysfs (no ROCm needed), then `rocm-smi` | `/proc/meminfo` |
+| Windows | `nvidia-smi` (PATH or System32) | WinAPI via ctypes |
+| macOS (Apple Silicon) | unified memory (RAM = VRAM budget) | `sysctl` |
+
+`psutil` is used when available (`pip install .[full]`) but is not required.
+
+## How the estimate works
+
+```
+required = weights + KV cache(context) + overhead(0.8 GB + 5% of weights)
+```
+
+- Weights: parameters × bytes-per-parameter (4 / 2 / 1 / 0.5 for
+  FP32 / FP16 / INT8 / INT4).
+- KV cache: `2 × layers × kv_heads × head_dim × 2 bytes × context_tokens`
+  from `config.json`; a 20% margin is used when the architecture is unknown.
+- Verdicts leave ~7% VRAM and ~15% RAM headroom for the driver and OS.
+
+These are pre-flight estimates. For a definitive runtime answer, vLLM's
+`--dry-run` on the actual machine remains the ground truth.

hfit-0.1.0/hfit.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+LICENSE
+README.md
+pyproject.toml
+hfit/__init__.py
+hfit/__main__.py
+hfit/cli.py
+hfit/estimate.py
+hfit/hw.py
+hfit/model.py
+hfit/report.py
+hfit/tui.py
+hfit.egg-info/PKG-INFO
+hfit.egg-info/SOURCES.txt
+hfit.egg-info/dependency_links.txt
+hfit.egg-info/entry_points.txt
+hfit.egg-info/requires.txt
+hfit.egg-info/top_level.txt

hfit-0.1.0/hfit.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

hfit-0.1.0/hfit.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+hfit = hfit.cli:main

hfit-0.1.0/hfit.egg-info/requires.txt

@@ -0,0 +1,6 @@
+huggingface_hub>=0.23
+rich>=13.0
+textual>=0.60
+
+[full]
+psutil>=5.9

hfit-0.1.0/hfit.egg-info/top_level.txt

@@ -0,0 +1 @@
+hfit

hfit-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[project]
+name = "hfit"
+version = "0.1.0"
+description = "Check whether a Hugging Face model fits your local hardware — without downloading the weights."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Samir Nuri", email = "samirnuri714@gmail.com" }]
+keywords = ["huggingface", "llm", "vram", "gpu", "memory", "tui", "hardware", "inference"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: System :: Hardware",
+]
+dependencies = [
+    "huggingface_hub>=0.23",
+    "rich>=13.0",
+    "textual>=0.60",
+]
+
+[project.optional-dependencies]
+full = ["psutil>=5.9"]
+
+[project.urls]
+Homepage = "https://github.com/snuri00/hfit"
+Issues = "https://github.com/snuri00/hfit/issues"
+
+[project.scripts]
+hfit = "hfit.cli:main"
+
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["hfit*"]

hfit-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+