LLM Model Fitting Categories in llmfit: A Complete Guide to FitLevel Classification

The llmfit library classifies LLM hardware compatibility into four distinct categories—Perfect, Good, Marginal, and TooTight—using the FitLevel enum to determine whether a model can run on available GPU or system memory.

The llmfit open-source tool solves the critical problem of matching Large Language Model (LLM) memory requirements against available hardware resources. According to the AlexsJones/llmfit source code, the library employs a strict classification system called LLM model fitting categories to quantify how comfortably a model fits within GPU VRAM or system RAM. This classification directly determines whether the GPU execution path is viable or if the model will fail to load entirely.

The Four LLM Model Fitting Categories Defined

The classification system centers on the FitLevel enum defined in llmfit-core/src/fit.rs at lines 178-183. This enum assigns one of four mutually exclusive states to every model-hardware combination:

• Perfect (Rank 3): The model fits comfortably within available GPU VRAM with recommended headroom. This category indicates the GPU path is fully viable without memory pressure.
• Good (Rank 2): The model fits but with tighter margins. This occurs when GPU memory is just sufficient or when the CPU path offers comfortable headroom for execution.
• Marginal (Rank 1): The model barely meets minimum memory requirements, leaving minimal slack. While technically runnable, this fit level carries higher risk of memory-related failures.
• TooTight (Rank 0): The model cannot fit into the available memory pool. Required memory exceeds present GPU VRAM or system RAM capacity, making execution impossible.

A model is considered runnable only when its classification is any value except TooTight.

How FitLevel Ranking Works Internally

Internally, llmfit implements a simple numeric ranking system to enable programmatic comparison. The Perfect = 3, Good = 2, Marginal = 1, TooTight = 0 mapping powers utility functions throughout the codebase.

In llmfit-tui/src/serve_api.rs at lines 968-973, the helper function fit_at_least allows filtering models by minimum acceptable fit quality. This enables API consumers to query for models meeting specific hardware compatibility thresholds.

Implementation Across the llmfit Codebase

Core Definition in llmfit-core

The foundational enum resides in llmfit-core/src/fit.rs. This module defines not only the four variants but also their semantic meanings regarding memory headroom and execution paths.

Visual Representation in the TUI

The terminal user interface translates these categories into visual indicators. In llmfit-tui/src/tui_ui.rs at lines 691-697, the fit_color function maps each FitLevel to distinct color codes—green for Perfect, yellow for Good, orange for Marginal, and red for TooTight. Similarly, llmfit-tui/src/display.rs (lines 252-255) handles table rendering styling based on these classifications.

CLI Integration and Filtering

Command-line argument parsing in llmfit-tui/src/main.rs (lines 1436-1442) leverages these categories to implement filter flags. Users can exclude models that exceed hardware limits or specifically target "Good" and above classifications.

Code Examples for Working with FitLevel

Filtering Runnable Models

To exclude models that cannot fit in available memory:

use llmfit_core::fit::{FitLevel, ModelFit};

fn runnable_models(fits: &[ModelFit]) -> Vec<&ModelFit> {
    fits.iter()
        .filter(|f| f.fit_level != FitLevel::TooTight)   // keep only runnable models
        .collect()
}

Creating Visual Indicators

Mapping fit levels to colored status indicators in a TUI:

fn fit_indicator(level: FitLevel) -> &'static str {
    match level {
        FitLevel::Perfect   => "●", // shown in green
        FitLevel::Good      => "●", // shown in yellow
        FitLevel::Marginal  => "●", // shown in orange
        FitLevel::TooTight  => "●", // shown in red
    }
}

API Query Filtering

Using the fit_at_least helper to respect minimum fit parameters in HTTP requests:

// Query parameter ?min_fit=good
let min_fit: FitLevel = FitLevel::Good;
let suitable = fits.into_iter()
    .filter(|f| fit_at_least(f.fit_level, min_fit))
    .collect::<Vec<_>>();

Summary

• llmfit uses four LLM model fitting categories—Perfect, Good, Marginal, and TooTight—to classify hardware compatibility.
• The FitLevel enum in llmfit-core/src/fit.rs assigns numeric ranks (3 to 0) enabling programmatic comparison.
• Only models rated Perfect, Good, or Marginal are considered runnable; TooTight indicates insufficient memory.
• The ranking system powers CLI filters, TUI color coding, and HTTP API queries throughout the codebase.

Frequently Asked Questions

What determines whether a model is classified as Perfect versus Good?

A model receives the Perfect classification when available GPU VRAM exceeds the model's min_vram_gb with comfortable headroom. Good indicates the model fits but with tighter margins, either on GPU with limited slack or comfortably on CPU.

Can I run a model classified as Marginal?

Yes. Marginal models are technically runnable according to the source code in llmfit-core/src/fit.rs, but they operate with minimal memory slack. This classification warns users that execution may encounter performance issues or memory-related failures under load.

How do I filter the CLI output to show only Perfect fits?

The CLI argument parsing in llmfit-tui/src/main.rs (lines 1436-1442) supports filtering parameters. You can specify minimum fit levels to exclude Marginal and TooTight results, displaying only Perfect (and optionally Good) classifications based on the numeric ranking system.

What is the numeric value assigned to each FitLevel variant?

The enum maps to integer ranks where Perfect = 3, Good = 2, Marginal = 1, and TooTight = 0. These values enable the fit_at_least comparison logic found in llmfit-tui/src/serve_api.rs for API-level filtering.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}