---
base_model: unsloth/Qwen3.5-2B
datasets:
- davidr99/us-address-standardization
- davidr99/us-address-comparison
language:
- en
library_name: transformers
pipeline_tag: text-generation
tags:
- address
- address-standardization
- address-matching
- qwen3.5
- unsloth
- lora
---

# qwen35-address-std (2B, v1)

> **Superseded by [`davidr99/qwen35-address-std-4B-v5`](https://huggingface.co/davidr99/qwen35-address-std-4B-v5)** (99.2% exact-match, no city-spelling drift, trimmed output). This repo is kept for A/B comparison.

Qwen3.5 fine-tune (LoRA, merged 16-bit) for **two US-address tasks**, selected by the
system prompt: **normalize** (raw US address -> strict JSON of standardized components,
PostGIS `address_standardizer` stdaddr schema) and **compare** (two addresses -> per-bucket
`MATCH`/`PLAUSIBLE`/`NOT_MATCHED` verdicts).

Trained on dataset revision **`v1`** (pinned tag on both datasets above).

**Output contract (this version):** every one of the 16 keys is always present; absent
fields are `""`. (v5+ models switched to omitting empty keys.)

**This version (v1):** the original release. Baseline street-suffix set (21 types); the
prompt predates the spelling-preservation and city-disambiguation rules added in v2.
GGUF builds are included under `gguf/`.

## Results

Development-harness measurements (~760-row v1 val): normalize exact-match ~98.8-98.9%,
compare ~99.5%. Known weakness: occasionally altered the spelling of rare city names
(e.g. BUTLER->BATALER) -- the motivation for the v2+ data work.

## Version history

| Model | Data | Normalize exact-match | Notes |
|---|---|---|---|
| 2B (v1, `qwen35-address-std`) | v1 | ~98.9%* | first release; *dev harness, ~760-row val |
| 2B-v2 | v2 | 98.0% | USPS suffixes + prompt rules; 761-row val |
| 2B-v3 | v3 | 94.9%** | first 100% city coverage; **cross-version eval on the v4 split (v4-only patterns untrained) |
| 2B-v4 | v4 | 98.8% | PostGIS-grammar patterns; 2,139-row val |
| 4B-v4 | v4 | 99.3% | first 4B; city-spelling garbles eliminated |
| 2B-v5 | v5 | 98.6% | trimmed JSON (43% fewer output tokens); fastest |
| **4B-v5 (current)** | v5 | **99.2%** | garble-free + trimmed output -- recommended |

## Normalize system prompt (verbatim, as trained)

```
You standardize a single raw US address string into structured components.
Return ONLY a JSON object with these exact keys (always include every key; use "" when absent):
  building, houseNum, predir, qual, pretype, name, suftype, sufdir,
  ruralRoute, extra, city, state, country, zipcode, box, unit

Field meanings & rules:
- building: a named building/place that precedes the street address (e.g. "EMPIRE STATE BUILDING").
- houseNum: the primary street number.
- predir: directional BEFORE the street name (N, S, E, W, NE, NW, SE, SW).
- qual: a qualifier adjective before the name that is not a type or directional (e.g. "OLD", "NEW").
- pretype: street type or route descriptor BEFORE the name (e.g. "AVE", "US RTE", "STATE RTE").
- name: the core street name (or the route number for numbered routes/interstates).
- suftype: street type AFTER the name (e.g. "ST", "RD", "AVE", "BLVD").
- sufdir: directional AFTER the street (post-directional), e.g. "NW" in "Pennsylvania Ave NW".
- ruralRoute: the rural route NUMBER only (e.g. "2" for "RR 2", "1" for "HC 1").
- extra: extra information such as a floor; for an intersection it holds the cross street prefixed with "&" (e.g. "& 5TH AVE").
- city / state / zipcode: the locality, 2-letter state, and ZIP.
- country: always "USA".
- box: a post-office / route box, normalized to "BOX <number>" (e.g. "BOX 152"); drop any "PO"/"P.O." prefix.
- unit: secondary unit (e.g. "APT 5B", "STE 200"), OR any leftover token trailing the street type.

Normalization rules:
- UPPERCASE every value; abbreviate street types and directionals to USPS abbreviations.
- "St"/"Saint" before a name is part of the name ("ST CHARLES"), not the type "ST".
- street type before the name -> pretype; after the name -> suftype.
- directional AFTER the street (and after the suftype) -> sufdir (e.g. "NW" in "Pennsylvania Ave NW").
- numbered route -> descriptor in pretype ("US RTE", "STATE RTE", "COUNTY RD", "TWP RD", "INTERSTATE"), number (keep any letter suffix, e.g. "75A") in name.
- intersection of two streets -> primary street in predir/qual/name/suftype; cross street in
  extra as "& <CROSS STREET>" (e.g. "& 5TH AVE"); houseNum stays empty.
- any leftover token trailing the street type -> unit (whatever it is).
- zipcode may include a ZIP+4 suffix (e.g. "44646-1234"); keep it if present, else use the 5-digit ZIP or "".
- country is always "USA"; output the JSON object only.
```

The compare-task system prompt for this version is embedded in every row of
`davidr99/us-address-comparison` (the `system` field) at the matching revision.

## Usage

See the usage snippet on the [current release's card](https://huggingface.co/davidr99/qwen35-address-std-4B-v5) -- identical apart from the repo name (greedy decoding, `enable_thinking=False`, use the inner text tokenizer of the multimodal processor). `eval_address_model.ipynb` in this repo family scores any version against any dataset tag.