# What Is a Marginal Fit in llmfit? Understanding Memory Constraints and Performance Risks

> Discover what a marginal fit in llmfit means. Understand memory constraints and performance risks of running models with minimal headroom.

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

---

**A "Marginal" fit in llmfit means the model meets the minimum memory requirement but leaves dangerously little headroom, making it runnable but prone to slowdowns and out-of-memory failures under load.**

The `llmfit` tool classifies language-model-to-hardware compatibility into four distinct levels. Understanding where **Marginal** sits in this hierarchy—and why it triggers warnings throughout the codebase—helps you make informed decisions about which models to deploy.

## The Four Fit Levels in llmfit

`llmfit` ranks model compatibility using the `FitLevel` enum defined in [`llmfit-core/src/fit.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-core/src/fit.rs). The levels progress from ideal to unusable:

- **Perfect** – abundant headroom, optimal performance
- **Good** – comfortable memory margin, reliable operation
- **Marginal** – minimum memory met but tight, warning state
- **Too Tight** – insufficient memory, not runnable

The **Marginal** variant carries explicit commentary in the source: *"Minimum memory met but tight"* (line 181 of [`fit.rs`](https://github.com/AlexsJones/llmfit/blob/main/fit.rs)). This single phrase captures the essential trade-off: technically possible, operationally risky.

## What Causes a Marginal Fit Classification

### Memory Pressure Without Safety Margin

The core algorithm applies a **1.2× headroom factor** when evaluating fits. A Marginal classification occurs when:

- RAM or VRAM usage sits just below the hardware limit
- The 20% safety buffer is nearly exhausted
- No meaningful room remains for runtime allocations

### Common CPU-Only Scenarios

Per the source code comments, Marginal fits frequently appear in **CPU-only inference paths**. Systems meeting the bare minimum memory threshold—common in constrained environments or when running larger models on consumer hardware—fall into this category by default.

## Performance Implications of Marginal Fits

Deploying a Marginally-fitted model introduces several operational concerns:

| Risk | Mechanism |
|------|-----------|
| **Memory exhaustion** | Heavy prompts or batching trigger OOM kills |
| **Paging/swapping** | System resorts to disk when buffers overflow |
| **Throughput degradation** | Little room for optimization or parallelization |
| **Extension blocking** | Cannot add LoRA adapters or context windows |

The model remains **runnable**—it passes the filter logic and appears in CLI/TUI output. However, `llmfit` explicitly discourages Marginal selections for production workloads requiring predictable performance.

## How llmfit Surfaces Marginal Fits in the Interface

### TUI Color Coding

In [`llmfit-tui/src/display.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-tui/src/display.rs) (lines 254–255), Marginal maps to **orange**, signaling caution:

```rust
FitLevel::Marginal => Color::Rgb(255, 165, 0), // orange

```

This visual warning appears alongside the standard bullet indicator, creating immediate recognition without blocking selection.

### CLI Filtering

Users can explicitly isolate Marginal models via the `--fit` flag:

```bash

# Show only marginally-fitting models

cargo run -- --cli --fit marginal

```

The filter implementation in [`llmfit-tui/src/tui_app.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-tui/src/tui_app.rs) (lines 1820–1822) treats `FitFilter::Marginal` as a distinct queryable state, enabling targeted inspection of borderline candidates.

## Working with Marginal Fits Programmatically

### Filtering by Fit Level in Rust

Access the classification through `llmfit-core` types:

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

fn audit_marginal_models(models: &[ModelFit]) -> Vec<&ModelFit> {
    models
        .iter()
        .filter(|f| f.fit_level == FitLevel::Marginal)
        .inspect(|f| eprintln!(
            "⚠ {}: score {:.1}, memory tight",
            f.model.name, f.score
        ))
        .collect()
}

```

### Rendering Custom Indicators

The TUI selects symbols in [`llmfit-tui/src/tui_ui.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-tui/src/tui_ui.rs) (line 691):

```rust
fn fit_indicator(level: FitLevel) -> &'static str {
    match level {
        FitLevel::Perfect   => "●",
        FitLevel::Good      => "●",
        FitLevel::Marginal  => "●",   // orange warning applied
        FitLevel::TooTight  => "●",
    }
}

```

Note that all runnable levels share the same symbol; color carries the semantic distinction.

## When to Accept or Reject Marginal Fits

**Accept when:**
- Prototyping or single-user inference
- Input sizes are strictly bounded and known
- No alternatives exist for the target hardware

**Reject when:**
- Serving multiple concurrent requests
- Operating under latency requirements
- Planning to fine-tune or extend the model
- Running unattended or automated pipelines

## Summary

- **Marginal fits** in `llmfit` indicate models that satisfy minimum memory requirements but lack operational headroom, as defined in [`llmfit-core/src/fit.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-core/src/fit.rs).
- The 1.2× headroom heuristic determines classification; CPU-only inference commonly produces these edge cases.
- Runtime risks include OOM failures, swapping, and blocked extensibility.
- The TUI renders Marginal fits in **orange** ([`llmfit-tui/src/display.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-tui/src/display.rs)), and the CLI supports `--fit marginal` filtering.
- Marginal models are runnable but not recommended for production workloads requiring reliable throughput.

## Frequently Asked Questions

### How does llmfit calculate whether a fit is Marginal versus Good?

The calculation uses a **multiplier-based headroom system**. In [`llmfit-core/src/fit.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-core/src/fit.rs), the analyzer compares projected memory consumption against available hardware capacity. A model scoring above the minimum threshold but failing to maintain comfortable margin—quantified through the internal 1.2× factor—receives Marginal classification rather than Good.

### Can I run a Marginally-fitted model safely?

**Yes, but with constraints.** The model loads and executes. However, the minimal buffer space means operations that increase memory pressure—longer contexts, larger batches, or concurrent inference—can trigger catastrophic failures. Treat Marginal as a development or evaluation tier, not a deployment standard.

### Why does the TUI use the same bullet symbol for Perfect, Good, and Marginal?

The **symbol remains constant** (`●`) across all runnable categories to reduce visual clutter, while **color carries the semantic load**: green for Perfect/Good, orange for Marginal. This design choice in [`llmfit-tui/src/tui_ui.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-tui/src/tui_ui.rs) prioritizes scanning speed over encoding multiple variables into glyph shapes.

### Does llmfit prevent loading Marginally-fitted models?

**No.** Marginal fits pass all runtime filters and appear in default model listings. The classification serves as advisory guidance, not a hard gate. Users retain full control to override warnings, with the understanding that operational stability becomes their responsibility.