feat(phase-32): add api/routes/resolve.py with 4 endpoints

GET /resolve?name=...&kind=person -- normalise + canonicalise a single name
GET /resolve/alias?name=... -- O(1) lookup in pre-built alias graph
POST /resolve/batch -- resolve list of records (max 500), merge duplicates
GET /resolve/stats -- alias graph statistics

The /resolve/alias and /resolve/stats endpoints share the _alias_graph singleton
loaded at startup from data/processed/alias_graph.json. The /resolve/batch
endpoint creates a temporary resolver for the request at the caller's threshold.

api/routes/resolve.py

@@ -0,0 +1,181 @@
+"""
+BharatGraph - Phase 32: Entity Resolution API
+GET /resolve?name=Sh.+Ram+Kumar&kind=person
+  -> canonical_id, normalised_name, score, aliases
+
+GET /resolve/alias?name=Ram+Kumar
+  -> canonical_id from alias graph (O(1) lookup)
+
+POST /resolve/batch
+  -> resolve a list of names against each other (cross-dataset matching)
+
+Pure ASCII.
+"""
+from fastapi import APIRouter, Query, HTTPException, Depends
+from typing import Optional, List
+from pydantic import BaseModel
+from loguru import logger
+
+from processing.entity_resolver_v2 import EntityResolverV2, normalise_indian_name
+from processing.canonical_id import canonical_id
+from processing.alias_graph import AliasGraph
+
+router = APIRouter(prefix="/resolve", tags=["resolve"])
+
+# Module-level resolver (shared across requests)
+_resolver = EntityResolverV2(threshold=0.82)
+
+
+# ---- Pydantic models ---------------------------------------------------
+
+class ResolveRecord(BaseModel):
+    name: str
+    kind: str = "person"  # "person" or "company"
+    cin:  Optional[str] = None
+    pan:  Optional[str] = None
+    gstin: Optional[str] = None
+    source: Optional[str] = None
+
+
+class BatchResolveRequest(BaseModel):
+    records: List[ResolveRecord]
+    threshold: float = 0.82
+    name_field: str = "name"
+
+
+class ResolveResponse(BaseModel):
+    input_name:      str
+    normalised_name: str
+    canonical_id:    str
+    kind:            str
+    aliases:         List[dict] = []
+    score:           float = 1.0
+    note:            str = ""
+
+
+class AliasLookupResponse(BaseModel):
+    input_name:   str
+    canonical_id: str
+    found:        bool
+
+
+# ---- Routes ------------------------------------------------------------
+
+@router.get("", response_model=ResolveResponse)
+def resolve_name(
+    name: str = Query(..., min_length=1, max_length=300,
+                      description="Name to resolve (person or company)"),
+    kind: str = Query("person", description="'person' or 'company'"),
+):
+    """
+    Normalise and canonicalise a single name.
+    Returns the normalised form, canonical SHA-256 ID, and any aliases
+    found in the current in-memory resolver state.
+
+    Example:
+      GET /resolve?name=Sh.+Ram+Kumar&kind=person
+    """
+    if kind not in ("person", "company"):
+        raise HTTPException(status_code=400,
+                            detail="kind must be 'person' or 'company'")
+    try:
+        norm = normalise_indian_name(name, kind)
+        cid  = canonical_id(norm)
+        return ResolveResponse(
+            input_name      = name,
+            normalised_name = norm,
+            canonical_id    = cid,
+            kind            = kind,
+            score           = 1.0,
+            note            = "Direct normalisation -- no cross-record matching performed",
+        )
+    except Exception as e:
+        logger.error(f"[Resolve] Error: {type(e).__name__}")
+        raise HTTPException(status_code=500, detail="Resolution failed")
+
+
+@router.get("/alias", response_model=AliasLookupResponse)
+def alias_lookup(
+    name: str = Query(..., min_length=1, max_length=300,
+                      description="Name variant to look up in alias graph"),
+):
+    """
+    O(1) lookup in the pre-built alias graph.
+    Returns the canonical_id if this name variant has been seen before,
+    empty string if not found.
+
+    The alias graph is built by the pipeline after each run and loaded
+    at startup. Fast for any name seen during ingestion.
+
+    Example:
+      GET /resolve/alias?name=RAHUL+KUMAR
+    """
+    try:
+        # Import the singleton from main to share state
+        from api.main import _alias_graph
+        cid = _alias_graph.resolve(name)
+        return AliasLookupResponse(
+            input_name   = name,
+            canonical_id = cid,
+            found        = bool(cid),
+        )
+    except ImportError:
+        return AliasLookupResponse(
+            input_name   = name,
+            canonical_id = "",
+            found        = False,
+        )
+    except Exception as e:
+        logger.error(f"[Resolve/alias] Error: {type(e).__name__}")
+        raise HTTPException(status_code=500, detail="Alias lookup failed")
+
+
+@router.post("/batch")
+def batch_resolve(body: BatchResolveRequest):
+    """
+    Resolve a list of records against each other.
+    Identifies duplicates and assigns canonical IDs.
+    Maximum 500 records per request (HuggingFace CPU limit).
+
+    Returns merged canonical records with alias lists.
+    """
+    if len(body.records) > 500:
+        raise HTTPException(status_code=400,
+                            detail="Maximum 500 records per batch request")
+    try:
+        resolver = EntityResolverV2(threshold=body.threshold)
+        raw = []
+        for rec in body.records:
+            d = {"name": rec.name, "kind": rec.kind}
+            if rec.cin:    d["cin"]    = rec.cin
+            if rec.pan:    d["pan"]    = rec.pan
+            if rec.gstin:  d["gstin"]  = rec.gstin
+            if rec.source: d["_source"] = rec.source
+            raw.append(d)
+
+        resolved = resolver.resolve_dataset(raw, name_field="name")
+        merged   = len(body.records) - len(resolved)
+
+        return {
+            "input_count":     len(body.records),
+            "canonical_count": len(resolved),
+            "merged_count":    merged,
+            "threshold":       body.threshold,
+            "records":         resolved,
+        }
+    except Exception as e:
+        logger.error(f"[Resolve/batch] Error: {type(e).__name__}")
+        raise HTTPException(status_code=500, detail="Batch resolution failed")
+
+
+@router.get("/stats")
+def resolve_stats():
+    """
+    Return alias graph statistics: how many aliases are indexed,
+    how many unique canonical IDs, avg aliases per entity.
+    """
+    try:
+        from api.main import _alias_graph
+        return {"alias_graph": _alias_graph.stats()}
+    except ImportError:
+        return {"alias_graph": {"total_aliases": 0, "unique_canonical_ids": 0}}