Upload folder using huggingface_hub

README.md

@@ -1,13 +1,25 @@
 ---
 title: Indian Address Parser
-emoji: 🏠
+emoji: "\U0001F3E0"
 colorFrom: blue
 colorTo: green
 sdk: gradio
-sdk_version: "6.3.0"
+sdk_version: "6.5.1"
+python_version: "3.14"
 app_file: app.py
 pinned: false
 license: mit
+short_description: Parse Indian addresses with IndicBERTv2-CRF NER
+models:
+  - x2aqq/indian-address-parser-model
+tags:
+  - ner
+  - address-parsing
+  - indian-addresses
+  - bert
+  - crf
+preload_from_hub:
+  - x2aqq/indian-address-parser-model
 ---
 
 # Indian Address Parser
@@ -18,7 +30,7 @@ Parse unstructured Indian addresses into structured components using **IndicBERT
 
 - **Multilingual**: Supports Hindi (Devanagari) + English
 - **15 Entity Types**: House Number, Floor, Block, Gali, Colony, Area, Khasra, Pincode, etc.
-- **~80% F1 score** on held-out test data (mBERT-CRF baseline)
+- **~80% F1 score** on held-out test data (IndicBERTv2-CRF)
 - **Fast**: < 30ms inference time
 
 ## Example
@@ -43,4 +55,4 @@ PLOT NO752 FIRST FLOOR, BLOCK H-3 KH NO 24/1/3/2/2/202, KAUNWAR SINGH NAGAR NEW
 
 - **Model**: ai4bharat/IndicBERTv2-SS + CRF layer
 - **Training Data**: 600+ annotated Delhi addresses
-- **Framework**: PyTorch + HuggingFace Transformers
+- **Framework**: PyTorch + HuggingFace Transformers + Pydantic v2

requirements.txt

@@ -3,7 +3,6 @@ torch>=2.9.1
 transformers>=4.57.6
 tokenizers>=0.22.2
 huggingface_hub>=0.25.0
-gradio>=6.3.0
 pydantic>=2.12.5
 indic-transliteration>=2.3.75
 rapidfuzz>=3.14.3

src/address_parser/postprocessing/gazetteer.py

@@ -1,6 +1,5 @@
 """Delhi locality gazetteer for fuzzy matching and validation."""
 
-
 from rapidfuzz import fuzz, process
 
 

src/address_parser/postprocessing/rules.py

@@ -390,36 +390,32 @@ class RuleBasedRefiner:
         result = []
 
         for entity in entities:
-            corrected = entity.model_copy()
+            updates: dict[str, object] = {}
 
             # Expand KHASRA to include full pattern
             if entity.label == "KHASRA":
                 match = self.PATTERNS["KHASRA"].search(text)
                 if match:
-                    corrected.value = match.group(0)
-                    corrected.start = match.start()
-                    corrected.end = match.end()
+                    updates = {"value": match.group(0), "start": match.start(), "end": match.end()}
 
             # Expand BLOCK to include identifier
             elif entity.label == "BLOCK":
                 match = self.PATTERNS["BLOCK"].search(text)
                 if match:
-                    corrected.value = match.group(0)
-                    corrected.start = match.start()
-                    corrected.end = match.end()
+                    updates = {"value": match.group(0), "start": match.start(), "end": match.end()}
 
             # Expand FLOOR to include floor number
             elif entity.label == "FLOOR":
                 match = self.PATTERNS["FLOOR"].search(text)
                 if match:
-                    corrected.value = match.group(0)
-                    corrected.start = match.start()
-                    corrected.end = match.end()
+                    updates = {"value": match.group(0), "start": match.start(), "end": match.end()}
 
             # Clean up leading/trailing whitespace from value
-            corrected.value = corrected.value.strip()
+            final_value = (updates.get("value") or entity.value).strip()
+            if final_value != entity.value or updates:
+                updates["value"] = final_value
 
-            result.append(corrected)
+            result.append(entity.model_copy(update=updates) if updates else entity)
 
         return result
 
@@ -432,24 +428,27 @@ class RuleBasedRefiner:
         result = []
 
         for entity in entities:
-            adjusted = entity.model_copy()
+            new_confidence = entity.confidence
 
             # Boost confidence for pattern matches
             if entity.label in self.PATTERNS:
                 pattern = self.PATTERNS[entity.label]
                 if pattern.fullmatch(entity.value):
-                    adjusted.confidence = min(1.0, entity.confidence + 0.1)
+                    new_confidence = min(1.0, new_confidence + 0.1)
 
             # Boost confidence for gazetteer matches
             if self.gazetteer and entity.label in ("AREA", "SUBAREA", "COLONY"):
                 if self.gazetteer.is_known_locality(entity.value):
-                    adjusted.confidence = min(1.0, entity.confidence + 0.15)
+                    new_confidence = min(1.0, new_confidence + 0.15)
 
             # Reduce confidence for very short entities
             if len(entity.value) < 3:
-                adjusted.confidence = max(0.0, entity.confidence - 0.2)
+                new_confidence = max(0.0, new_confidence - 0.2)
 
-            result.append(adjusted)
+            if new_confidence != entity.confidence:
+                result.append(entity.model_copy(update={"confidence": new_confidence}))
+            else:
+                result.append(entity)
 
         return result
 
@@ -513,8 +512,7 @@ class RuleBasedRefiner:
                     continue
                 if self.gazetteer and not self.gazetteer.validate_pincode(entity.value):
                     # Pincode outside Delhi range - reduce confidence but keep
-                    entity = entity.model_copy()
-                    entity.confidence *= 0.7
+                    entity = entity.model_copy(update={"confidence": entity.confidence * 0.7})
 
             result.append(entity)
 

src/address_parser/schemas.py

@@ -1,6 +1,8 @@
-"""Pydantic schemas for address parsing I/O."""
+"""Pydantic v2 schemas for address parsing I/O."""
 
-from pydantic import BaseModel, ConfigDict, Field
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, computed_field
 
 # Entity label definitions
 ENTITY_LABELS = [
@@ -21,6 +23,13 @@ ENTITY_LABELS = [
     "STATE",
 ]
 
+# Type-safe entity label literal
+EntityLabel = Literal[
+    "AREA", "SUBAREA", "HOUSE_NUMBER", "SECTOR", "GALI",
+    "COLONY", "BLOCK", "CAMP", "POLE", "KHASRA",
+    "FLOOR", "PLOT", "PINCODE", "CITY", "STATE",
+]
+
 # BIO tag generation
 BIO_LABELS = ["O"] + [f"B-{label}" for label in ENTITY_LABELS] + [f"I-{label}" for label in ENTITY_LABELS]
 LABEL2ID = {label: i for i, label in enumerate(BIO_LABELS)}
@@ -28,15 +37,11 @@ ID2LABEL = {i: label for i, label in enumerate(BIO_LABELS)}
 
 
 class AddressEntity(BaseModel):
-    """A single extracted entity from an address."""
-
-    label: str = Field(..., description="Entity type (e.g., HOUSE_NUMBER, AREA)")
-    value: str = Field(..., description="Extracted text value")
-    start: int = Field(..., description="Start character offset in original text")
-    end: int = Field(..., description="End character offset in original text")
-    confidence: float = Field(default=1.0, ge=0.0, le=1.0, description="Confidence score")
+    """A single extracted entity from an address. Immutable after creation."""
 
     model_config = ConfigDict(
+        frozen=True,
+        str_strip_whitespace=True,
         json_schema_extra={
             "example": {
                 "label": "HOUSE_NUMBER",
@@ -45,49 +50,21 @@ class AddressEntity(BaseModel):
                 "end": 10,
                 "confidence": 0.95,
             }
-        }
+        },
     )
 
+    label: EntityLabel = Field(..., description="Entity type (e.g., HOUSE_NUMBER, AREA)")
+    value: str = Field(..., min_length=1, description="Extracted text value")
+    start: int = Field(..., ge=0, description="Start character offset in original text")
+    end: int = Field(..., ge=0, description="End character offset in original text")
+    confidence: float = Field(default=1.0, ge=0.0, le=1.0, description="Confidence score")
 
-class ParsedAddress(BaseModel):
-    """Complete parsed address with all entities."""
-
-    raw_address: str = Field(..., description="Original input address")
-    normalized_address: str = Field(..., description="Normalized/cleaned address")
-    entities: list[AddressEntity] = Field(default_factory=list, description="Extracted entities")
 
-    # Convenience accessors for common fields
-    house_number: str | None = Field(None, description="Extracted house/plot number")
-    floor: str | None = Field(None, description="Extracted floor")
-    block: str | None = Field(None, description="Extracted block")
-    gali: str | None = Field(None, description="Extracted gali/lane")
-    colony: str | None = Field(None, description="Extracted colony name")
-    area: str | None = Field(None, description="Extracted area/locality")
-    subarea: str | None = Field(None, description="Extracted sub-area")
-    sector: str | None = Field(None, description="Extracted sector")
-    khasra: str | None = Field(None, description="Extracted khasra number")
-    pincode: str | None = Field(None, description="Extracted PIN code")
-    city: str | None = Field(None, description="Extracted city")
-    state: str | None = Field(None, description="Extracted state")
-
-    def model_post_init(self, __context) -> None:
-        """Populate convenience fields from entities."""
-        entity_map = {e.label.upper(): e.value for e in self.entities}
-
-        self.house_number = entity_map.get("HOUSE_NUMBER") or entity_map.get("PLOT")
-        self.floor = entity_map.get("FLOOR")
-        self.block = entity_map.get("BLOCK")
-        self.gali = entity_map.get("GALI")
-        self.colony = entity_map.get("COLONY")
-        self.area = entity_map.get("AREA")
-        self.subarea = entity_map.get("SUBAREA")
-        self.sector = entity_map.get("SECTOR")
-        self.khasra = entity_map.get("KHASRA")
-        self.pincode = entity_map.get("PINCODE")
-        self.city = entity_map.get("CITY")
-        self.state = entity_map.get("STATE")
+class ParsedAddress(BaseModel):
+    """Complete parsed address with all entities and computed convenience accessors."""
 
     model_config = ConfigDict(
+        str_strip_whitespace=True,
         json_schema_extra={
             "example": {
                 "raw_address": "PLOT NO752 FIRST FLOOR, BLOCK H-3, NEW DELHI, 110041",
@@ -99,25 +76,97 @@ class ParsedAddress(BaseModel):
                 "house_number": "PLOT NO752",
                 "floor": "FIRST FLOOR",
             }
-        }
+        },
     )
 
+    raw_address: str = Field(..., description="Original input address")
+    normalized_address: str = Field(..., description="Normalized/cleaned address")
+    entities: list[AddressEntity] = Field(default_factory=list, description="Extracted entities")
+
+    def _get_entity(self, *labels: str) -> str | None:
+        """Look up first matching entity value by label(s)."""
+        for entity in self.entities:
+            if entity.label in labels:
+                return entity.value
+        return None
+
+    @computed_field(description="Extracted house/plot number")
+    @property
+    def house_number(self) -> str | None:
+        return self._get_entity("HOUSE_NUMBER", "PLOT")
+
+    @computed_field(description="Extracted floor")
+    @property
+    def floor(self) -> str | None:
+        return self._get_entity("FLOOR")
+
+    @computed_field(description="Extracted block")
+    @property
+    def block(self) -> str | None:
+        return self._get_entity("BLOCK")
+
+    @computed_field(description="Extracted gali/lane")
+    @property
+    def gali(self) -> str | None:
+        return self._get_entity("GALI")
+
+    @computed_field(description="Extracted colony name")
+    @property
+    def colony(self) -> str | None:
+        return self._get_entity("COLONY")
+
+    @computed_field(description="Extracted area/locality")
+    @property
+    def area(self) -> str | None:
+        return self._get_entity("AREA")
+
+    @computed_field(description="Extracted sub-area")
+    @property
+    def subarea(self) -> str | None:
+        return self._get_entity("SUBAREA")
+
+    @computed_field(description="Extracted sector")
+    @property
+    def sector(self) -> str | None:
+        return self._get_entity("SECTOR")
+
+    @computed_field(description="Extracted khasra number")
+    @property
+    def khasra(self) -> str | None:
+        return self._get_entity("KHASRA")
+
+    @computed_field(description="Extracted PIN code")
+    @property
+    def pincode(self) -> str | None:
+        return self._get_entity("PINCODE")
+
+    @computed_field(description="Extracted city")
+    @property
+    def city(self) -> str | None:
+        return self._get_entity("CITY")
+
+    @computed_field(description="Extracted state")
+    @property
+    def state(self) -> str | None:
+        return self._get_entity("STATE")
+
 
 class ParseRequest(BaseModel):
     """Request schema for parsing addresses."""
 
-    address: str = Field(..., min_length=5, max_length=500, description="Address to parse")
-    return_confidence: bool = Field(default=True, description="Include confidence scores")
-
     model_config = ConfigDict(
+        str_strip_whitespace=True,
         json_schema_extra={
             "example": {
                 "address": "PLOT NO752 FIRST FLOOR, BLOCK H-3, NEW DELHI, 110041",
                 "return_confidence": True,
             }
-        }
+        },
     )
 
+    address: str = Field(..., min_length=5, max_length=500, description="Address to parse")
+    return_confidence: bool = Field(default=True, description="Include confidence scores")
+
 
 class BatchParseRequest(BaseModel):
     """Request schema for batch parsing."""