# Where Is the llmfit Model Database Stored? A Complete Guide to the Embedded JSON Catalog

> Discover where the llmfit model database is stored. This guide explains the embedded JSON catalog within the llmfit Rust crate and how it's compiled into the binary.

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

---

**The llmfit model database is stored as an embedded JSON file ([`hf_models.json`](https://github.com/AlexsJones/llmfit/blob/main/hf_models.json)) inside the `llmfit-core` crate, compiled directly into the binary using Rust's `include_str!` macro.**

The llmfit project by AlexsJones uses an embedded catalog to track Hugging Face model specifications for hardware fit analysis. Unlike traditional databases that reside on disk or connect to external servers, the llmfit model database is baked into the compiled binary at build time. This design ensures zero runtime dependencies and instant access to model metadata without network calls.

## Location of the llmfit Model Database

The database exists in two states: as a source file in the repository and as embedded bytes in the compiled application.

### File System Location

In the source repository, the llmfit model database is stored at [`llmfit-core/data/hf_models.json`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-core/data/hf_models.json). This JSON file contains the complete catalog of Hugging Face models including parameter counts, minimum RAM requirements, and architecture details. The file sits alongside the Rust source code in the `llmfit-core` directory, making it part of the crate's static assets.

### Embedded Storage Mechanism

At compile time, Rust embeds this JSON directly into the binary. In [`llmfit-core/src/models.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-core/src/models.rs) at line 1091, the code uses the `include_str!` macro to pull the contents of [`hf_models.json`](https://github.com/AlexsJones/llmfit/blob/main/hf_models.json) into a string literal. This means the llmfit model database is stored within the executable itself, eliminating the need for external file system access during runtime.

## How the Database Is Loaded at Runtime

When you initialize the `ModelDatabase` struct, the library parses the embedded JSON string that was included at compile time. This approach provides immediate access to the catalog without I/O overhead.

```rust
use llmfit_core::models::ModelDatabase;

// Load the embedded model catalog (the HF database is built from hf_models.json)
let db = ModelDatabase::new()?;   // Returns a struct containing all models
println!("Total models loaded: {}", db.models.len());

```

The `ModelDatabase::new()` method handles the deserialization of the embedded JSON, populating the in-memory structure with all available model specifications.

## Structure and Access Patterns

Once loaded, the database provides methods to query specific models by their Hugging Face identifier. Each entry contains hardware requirements necessary for fit analysis.

```rust
// Access a specific model entry by name
if let Some(model) = db.get_by_name("meta-llama/Meta-Llama-3-8B-Instruct") {
    println!("Parameters: {}", model.parameter_count);
    println!("Min RAM (GB): {}", model.min_ram_gb);
}

```

The embedded JSON structure maps to Rust structs defined in [`llmfit-core/src/models.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-core/src/models.rs), ensuring type-safe access to fields like `parameter_count` and `min_ram_gb`.

## Refreshing the Model Database

Although the llmfit model database is stored statically in the binary, you can regenerate the source JSON file to include newer models. The repository includes [`scripts/scrape_hf_models.py`](https://github.com/AlexsJones/llmfit/blob/main/scripts/scrape_hf_models.py), which scrapes Hugging Face to produce an updated [`hf_models.json`](https://github.com/AlexsJones/llmfit/blob/main/hf_models.json). After running the script, recompiling the crate embeds the fresh data.

This architecture separates data updates from application updates: refresh the JSON source, rebuild the project, and the new database ships with the new binary.

## Summary

- The llmfit model database is stored in [`llmfit-core/data/hf_models.json`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-core/data/hf_models.json) within the source repository.
- At compile time, the database is embedded into the binary using Rust's `include_str!` macro in [`llmfit-core/src/models.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-core/src/models.rs).
- Runtime access occurs through the `ModelDatabase` struct, which parses the embedded JSON without file system I/O.
- Update the database by running [`scripts/scrape_hf_models.py`](https://github.com/AlexsJones/llmfit/blob/main/scripts/scrape_hf_models.py) to regenerate the JSON, then recompiling the crate.

## Frequently Asked Questions

### Is the llmfit model database stored locally as a separate file?

No. While the source data exists as [`hf_models.json`](https://github.com/AlexsJones/llmfit/blob/main/hf_models.json) in the repository, the llmfit model database is stored as embedded bytes inside the compiled binary. The `include_str!` macro in [`llmfit-core/src/models.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-core/src/models.rs) (line 1091) incorporates the JSON content at build time, so no separate file is required on the user's machine at runtime.

### How do I update the llmfit model database with new Hugging Face models?

Run the [`scripts/scrape_hf_models.py`](https://github.com/AlexsJones/llmfit/blob/main/scripts/scrape_hf_models.py) script to regenerate [`llmfit-core/data/hf_models.json`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-core/data/hf_models.json) with current Hugging Face data. After updating the JSON file, recompile the `llmfit-core` crate to embed the new database into your application binary.

### What format is the llmfit model database stored in?

The database is stored as a JSON file ([`hf_models.json`](https://github.com/AlexsJones/llmfit/blob/main/hf_models.json)) containing an array of model objects with fields for model ID, parameter count, minimum RAM requirements, and architecture type. This JSON format is parsed into Rust structs when `ModelDatabase::new()` is called.

### Why is the database embedded rather than loaded from disk?

Embedding the llmfit model database using `include_str!` eliminates runtime file I/O dependencies and ensures the application works immediately without configuration. This design guarantees that the model catalog is always available and version-locked to the specific release of the software.