Also available as a Python package
pip install indian-address-parser
Source, CLI, and a benchmark comparison against
shiprocket-ai/open-tinybert-indian-address-ner
are on GitHub: innerkorehq/indian-address-parser.
Datasets
Two loading paths
Training was done with MLX (mlx-lm's lora
command) on Apple Silicon. The repo root has a PEFT-format conversion of that adapter
so it loads on any platform (CUDA, MPS, CPU) via standard transformers+peft — the
mlx/ subfolder has the original MLX artifacts for Apple Silicon users. Both were
verified to produce matching output (13/15 identical on a held-out spot check; the 2
differences landed on fields already noted as ambiguous below — consistent with
floating-point differences between backends on a near-tied decision, not a conversion error).
import torch
from peft import PeftModel
from transformers import AutoModelForCausalLM, AutoTokenizer
repo = "gagan1985/qwen3-0.6b-indian-address-parser"
tokenizer = AutoTokenizer.from_pretrained(repo)
base = AutoModelForCausalLM.from_pretrained("Qwen/Qwen3-0.6B", torch_dtype=torch.bfloat16)
model = PeftModel.from_pretrained(base, repo)
SYSTEM_PROMPT = (
"You are an Indian address parser. Given a raw address string, extract address "
"fields and return them as a JSON object. Use null for fields not present in the "
"address. Output only the JSON object, no explanation.\n\n"
"Fields: houseNumber, houseName, poi, street, subsubLocality, subLocality, "
"locality, village, subDistrict, district, city, state, pincode"
)
messages = [
{"role": "system", "content": SYSTEM_PROMPT},
{"role": "user", "content": "Parse this address:\n<your address here>"},
]
text = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True, enable_thinking=False)
inputs = tokenizer(text, return_tensors="pt").to(model.device)
out = model.generate(**inputs, max_new_tokens=256, do_sample=False, pad_token_id=tokenizer.eos_token_id)
print(tokenizer.decode(out[0][inputs["input_ids"].shape[1]:], skip_special_tokens=True))
Or use the included inference.py / evaluate.py (download the repo, then
python inference.py --model Qwen/Qwen3-0.6B --adapter . "<address>").
Option B — MLX (Apple Silicon)
mlx_lm.load's adapter_path only accepts a local directory, not an HF repo ID — so
fetch the mlx/ subfolder first, then point at it locally:
from huggingface_hub import snapshot_download
import mlx_lm
local_dir = snapshot_download("gagan1985/qwen3-0.6b-indian-address-parser", allow_patterns=["mlx/*"])
model, tokenizer = mlx_lm.load("Qwen/Qwen3-0.6B", adapter_path=f"{local_dir}/mlx")
messages = [
{"role": "system", "content": SYSTEM_PROMPT},
{"role": "user", "content": "Parse this address:\n<your address here>"},
]
prompt = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True, enable_thinking=False)
print(mlx_lm.generate(model, tokenizer, prompt=prompt, max_tokens=512, verbose=False))
Or use mlx/inference_mlx.py / mlx/evaluate_mlx.py from a local checkout.
Fields
houseNumber, houseName, poi, street, subsubLocality, subLocality,
locality, village, subDistrict, district, city, state, pincode
Training data
- 5,008 gold-labeled records: 9 human-reviewed (Label Studio) + 4,999 LLM-reviewed
(
deepseek/deepseek-v4-pro via OpenRouter, span-verified against the raw address text
— any field value not found verbatim in the source string was dropped, not guessed)
- Sourced from two distinct raw formats: Indian MCA (Ministry of Corporate Affairs)
company-registration addresses, and bank/business-correspondent branch addresses
- Split 4,266 train / 237 val / 237 test (deduplicated)
Training config
Table with columns: Parameter, Value| Parameter | Value |
|---|
| Base model | Qwen/Qwen3-0.6B (28 layers) |
| LoRA rank / alpha / dropout | 16 / 32 / 0.05 |
| Target modules | q_proj, k_proj, v_proj, o_proj, gate_proj, up_proj, down_proj |
| Fine-tuned layers | 16 (of 28) |
| Iterations | 2000 (≈3.75 epochs at batch=8) |
| Learning rate | 2e-4 |
| Trainable params | 5.77M / 596M (0.968%) |
Evaluation (237 held-out test samples)
- JSON parse rate: 100%
- Overall exact match (all present fields): 19.0%
- Mean per-field accuracy: 82.4%
Table with columns: Field, Accuracy, Recall, Gold presence| Field | Accuracy | Recall | Gold presence |
|---|
| pincode | 100.0% | 100.0% | 100.0% |
| state | 94.9% | 96.2% | 98.7% |
| district | 94.9% | 95.1% | 68.8% |
| houseNumber | 90.3% | 84.5% | 54.4% |
| city |
Known limitations
locality/subLocality/subsubLocality/village overlap conceptually. These
represent the same "named area, different granularity" concept, and disagreements are
often the model extracting the correct substring into an adjacent bucket rather than
a genuine extraction miss — the gold labels themselves are sometimes inconsistent here
(the same place name occasionally appears in two of these fields simultaneously in gold).street sometimes over-absorbs multi-part location clusters (e.g. "KARBI PATH, ZOO
NARENGI ROAD, BAMUNIMAIDAN" tagged entirely as street instead of being split across
street/subsubLocality/subLocality), likely because that split pattern is
underrepresented in training data (subsubLocality/subLocality gold presence is only
~21-27%).- Source addresses occasionally contain data artifacts (e.g. duplicated substrings from
the original MCA records, like
"PEDANANDIPALLE AGRAHARAMPEDANANDIPALLE AGRAHARAM")
that the model sometimes reproduces with minor copy errors.
Files in this repo
Root (PEFT format):
adapter_model.safetensors + adapter_config.json — standard PEFT LoRA adaptertokenizer.json, tokenizer_config.json, vocab.json, merges.txt,
special_tokens_map.json, added_tokens.json, chat_template.jinja — tokenizer filesinference.py / evaluate.py — CLI scripts (single address, stdin/file batch, or
full test-set evaluation) using transformers+peft- — shared constants (, field list, prompt template)
mlx/ (original MLX format, Apple Silicon):
adapters.safetensors + adapter_config.json — mlx-lm's native adapter format
(adapter_config.json here is mlx-lm's training-run metadata, not a PEFT LoraConfig)inference_mlx.py / evaluate_mlx.py — same CLI shape as the root scripts, via mlx-lmconfig.py — same constants, duplicated here so this subfolder is usable standalone