Inspecting A Model Bundle

---
name: inspecting-a-model-bundle
description: >-
  Work out what is inside a model directory and what can actually run it. Reads
  GGUF headers, safetensors headers, adapter_config.json and config.json to
  identify whether it is GGUF, a LoRA adapter or a merged checkpoint, which
  base model it came from, which runtimes can load it directly versus which
  require conversion, and what defects the export left behind. Use when
  someone has a model folder or zip and does not know what is in it, asks what
  format a model is, asks whether a model runs with Ollama or vLLM or
  llama.cpp, or needs to check a downloaded or exported model before
  integrating it. Not for choosing which base model to fine-tune, not for
  training, and not for writing the integration code itself.
license: Apache-2.0
metadata:
  version: "0.1.0"
  author: "Edward Xi Yang, Ertas AI"
  stage: "inspect"
  previous_skill: "scoping-a-custom-model"
  next_skill: "debugging-a-bad-fine-tune"
---

# Inspecting a model bundle

Point this at any directory holding a model. It works on an `ollama pull`, a
Hugging Face download, an export from a training platform, or a zip a colleague
sent you.

## Run the inspection

From this skill's own directory:

```bash
python3 scripts/inspect_bundle.py /path/to/bundle
python3 scripts/check_defects.py /path/to/bundle
```

Both are Python 3.9+ standard library only. Nothing to install, no network
access.

If Python is unavailable, work through `references/artifact-shapes.md` by hand.
The file listing alone identifies the shape in most cases.

## The three shapes

| You see | Shape | What it is |
|---|---|---|
| A `.gguf` file, usually with a `Modelfile` | **GGUF** | Quantised, self-contained, tokenizer baked in |
| `adapter_config.json` + `adapter_model.safetensors` | **Adapter** | LoRA weights only. Useless without the exact base model |
| `config.json` + `model.safetensors` | **Merged** | A full checkpoint in Hugging Face format |

Detection is heuristic. Most bundles carry no manifest saying what they are, so
report the confidence the script gives you rather than asserting.

## Write the report

Write `BUNDLE-REPORT.md` into the user's project root. Later skills read it.
Use exactly these sections, in this order:

```markdown
# Bundle report

## Shape
<gguf | adapter | merged | unknown>, confidence <high | medium | low>
<one line per evidence item>

## Base model
<id and where it was found, or "not recorded in the bundle">

## Files
<name, size table>

## Runtimes
<runtime, direct/convert/no, note>

## Defects
<severity, title, fix. Or "none found">

## Recommended next step
<one sentence>
```

## Reading the result

**If the shape is `unknown`,** say so. Do not guess. List what was found and ask
what the user expected. A wrong guess here poisons every later step.

**If it is an adapter and no base model is recorded,** that is the most important
thing to say. The adapter cannot be loaded without it, and no amount of
inspection recovers it.

**If defects came back,** rank them for the user by whether they block the thing
the user is trying to do. A missing `generation_config.json` matters enormously
if generation never stops and not at all if they are only converting formats.

## Hand off to

- Generation is broken, repetitive, or ignores the training: **debugging-a-bad-fine-tune**
- Wanting to know if the fine-tune is actually better: **evaluating-a-tuned-model**
- Ready to put it in an app: **shipping-a-model-in-a-react-native-app**,
  **shipping-a-model-in-an-ios-app**, **shipping-a-model-in-an-android-app**, or
  **shipping-a-model-in-a-flutter-app**
- Deciding whether to run it at all: **costing-a-model-vs-an-api**