instruction

INSTRUCTIONS.md

@@ -0,0 +1,150 @@
+# 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 |
+|------|------|----------|
+| `insect-parser-q4_k_m.gguf` | 3.2 GB | Your computer has **8 GB RAM** (most laptops) |
+| `insect-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 `insect-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 insect-parser -f Modelfile
+```
+
+You only need to do this once.
+
+### Parse a label
+
+```bash
+ollama run insect-parser "U.S.A., Texas: Austin, 15.iv.2021, J. Doe"
+```
+
+Or pipe a text file:
+
+```bash
+cat my_label.txt | ollama run insect-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`.

Modelfile

@@ -0,0 +1,13 @@
+FROM ./ento-label-parser-q4_k_m.gguf
+
+SYSTEM """Parse this insect collection label and return a JSON object with the extracted fields. Only include fields that are present in the label."""
+
+# Deterministic output — this is a structured extraction task, not creative generation
+PARAMETER temperature 0.0
+PARAMETER top_p 0.9
+PARAMETER repeat_penalty 1.1
+
+# Gemma 4 uses a thinking/reasoning mode before outputting the final answer.
+# Labels are short inputs but the model may think for several hundred tokens
+# before writing the JSON. 4096 gives enough room for thinking + output.
+PARAMETER num_ctx 4096