INSTRUCTIONS.md

# Insect Label Parser — Setup Instructions

This tool reads raw entomology collection label text and extracts structured
data (country, state, locality, date, collector, elevation, etc.) as JSON.
It runs entirely on your computer — no internet connection required after
the one-time setup.

---

## Step 1 — Which file do I need?

Copy one of these files from `output/gguf/` to your computer:

| File | Size | Use when |
|------|------|----------|
| `ento-label-parser-q4_k_m.gguf` | 3.2 GB | Your computer has **8 GB RAM** (most laptops) |
| `ento-label-parser-q5_k_m.gguf` | 3.4 GB | Your computer has **16 GB RAM or more** (slightly better quality) |

Not sure how much RAM you have?
- **Mac:** Apple menu → About This Mac → look for "Memory"
- **Windows:** Settings → System → About → look for "Installed RAM"

> **The Q4 file works well for this task.** Label parsing is a simple
> extraction job — the quality difference between Q4 and Q5 is very small.

---

## Option A: LM Studio (recommended for most users — no terminal needed)

LM Studio is a free desktop app with a chat interface, similar to ChatGPT
but running fully on your own machine.

### Install

1. Go to **lmstudio.ai** and download the version for your operating system
   (Mac, Windows, or Linux)
2. Install and open it

### Load the model

1. In LM Studio, click **My Models** in the left sidebar
2. Click **"Load model from file"** (or drag the `.gguf` file into the window)
3. Navigate to the `ento-label-parser-q4_k_m.gguf` file you copied in Step 1
4. Wait for the model to load (progress bar at the bottom)

### Configure the system prompt

This step tells the model what it is supposed to do.

1. Click the **Chat** icon in the left sidebar
2. Find the **System Prompt** box (usually at the top of the right panel)
3. Paste this text exactly:

```
Parse this insect collection label and return a JSON object with the extracted fields. Only include fields that are present in the label.
```

4. Set **Temperature** to `0` in the model settings panel (this makes
   output deterministic — the same label always gives the same result)

### Parse a label

Paste the raw label text into the chat box and press Enter. The model will
return a JSON object. Example:

**Input:**
```
U.S.A., Texas: Austin, Travis Co., 15.iv.2021, J. Doe, sweeping
```

**Output:**
```json
{
  "country": "USA",
  "state": "Texas",
  "county": "Travis",
  "verbatim_locality": "Austin",
  "verbatim_date": "15.iv.2021",
  "start_date_year": "2021",
  "start_date_month": "4",
  "start_date_day": "15",
  "verbatim_collectors": "J. Doe",
  "verbatim_method": "sweeping"
}
```

---

## Option B: Ollama (for users comfortable with a terminal)

Ollama is a lightweight tool that runs models from the command line and also
exposes a local API for scripting.

### Requirement: Ollama version 0.20.7 or newer

Older versions do not support this model's architecture. Check your version:

```
ollama --version
```

If it shows a version older than 0.20.7, update from **ollama.com**.

### Install

Go to **ollama.com**, download, and install for your operating system.

### Register the model

Open a terminal, navigate to the project folder, and run:

```bash
ollama create ento-label-parser -f Modelfile
```

You only need to do this once.

### Parse a label

```bash
ollama run ento-label-parser "U.S.A., Texas: Austin, 15.iv.2021, J. Doe"
```

Or pipe a text file:

```bash
cat my_label.txt | ollama run ento-label-parser
```

---

## Troubleshooting

**The model is very slow.**
This is normal on a laptop without a dedicated GPU. The Q4 file typically
takes 5–30 seconds per label on a CPU. If you have an NVIDIA or AMD GPU
with 4+ GB of video memory, Ollama and LM Studio will use it automatically
and be much faster.

**LM Studio says "not enough memory."**
Try the Q4 file if you were using Q5. If Q4 also fails, your computer may
have less than 8 GB of RAM available — try closing other applications first.

**Ollama says "unknown model architecture: gemma4".**
Your Ollama version is too old. Update it from **ollama.com**.

**The output is not valid JSON.**
Occasionally the model will include a short thinking passage before the
JSON. Copy just the `{ ... }` portion of the output. If this happens
frequently, make sure Temperature is set to `0`.