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

> Discover the four LLM model fitting categories in llmfit: Perfect, Good, Marginal, and TooTight. Learn how FitLevel classifies hardware compatibility for your LLM models.

- Repository: [Alex Jones/llmfit](https://github.com/AlexsJones/llmfit)
- Tags: deep-dive
- Published: 2026-08-19

---

**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`](https://github.com/AlexsJones/llmfit/blob/main/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`](https://github.com/AlexsJones/llmfit/blob/main/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`](https://github.com/AlexsJones/llmfit/blob/main/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`](https://github.com/AlexsJones/llmfit/blob/main/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`](https://github.com/AlexsJones/llmfit/blob/main/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`](https://github.com/AlexsJones/llmfit/blob/main/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:

```rust
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:

```rust
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:

```rust
// 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`](https://github.com/AlexsJones/llmfit/blob/main/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`](https://github.com/AlexsJones/llmfit/blob/main/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`](https://github.com/AlexsJones/llmfit/blob/main/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`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-tui/src/serve_api.rs) for API-level filtering.