feat: add initial implementation of lakhua library with README, setup, and tests

Author: aialok

.github/workflows/pypi-publish.yml

@@ -0,0 +1,82 @@
+name: Publish Python Package to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+concurrency:
+  group: pypi-publish
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: libs/python
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install build twine pytest ruff mypy
+
+      - name: Install package
+        run: pip install -e ".[dev]"
+
+      - name: Run linting
+        run: ruff check .
+
+      - name: Run type checking
+        run: mypy lakhua --ignore-missing-imports
+
+      - name: Run tests
+        run: pytest
+
+      - name: Build package
+        run: python -m build
+
+      - name: Check distribution metadata
+        run: python -m twine check dist/*
+
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-dist
+          path: libs/python/dist/
+
+  publish:
+    runs-on: ubuntu-latest
+    needs: build
+    environment:
+      name: pypi
+      url: https://pypi.org/p/lakhua
+
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: python-dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+

libs/python/.gitignore

@@ -0,0 +1,30 @@
+# Python
+__pycache__/
+*.py[cod]
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+*.whl
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# Virtual environments
+venv/
+env/
+ENV/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+

libs/python/.ruff.toml

@@ -0,0 +1,13 @@
+line-length = 100
+
+[lint]
+select = ["E", "F", "I", "N", "W", "UP", "B", "C4", "PIE", "PT", "RET", "SIM"]
+ignore = []
+
+[lint.isort]
+known-first-party = ["lakhua"]
+
+[format]
+indent-style = "space"
+quote-style = "double"
+

libs/python/MANIFEST.in

@@ -0,0 +1,5 @@
+include README.md
+include LICENSE
+recursive-include lakhua/data *.json
+include lakhua/py.typed
+

libs/python/README.md

@@ -0,0 +1,165 @@
+# lakhua (Python)
+
+Offline reverse geocoding for India, optimized for fast in-memory lookups using H3 indexes.
+
+## Features
+
+- **Offline-first**: No API keys, no network dependency
+- **In-memory lookup**: Singleton loader for efficient data management
+- **Parent-resolution fallback**: Automatic fallback from resolution 5 → 4
+- **Type-safe**: Full type hints and dataclasses
+- **Modern Python**: Supports Python 3.8+
+- **Fast**: In-memory map-based lookups with minimal overhead
+
+## Installation
+
+```bash
+pip install lakhua
+```
+
+## Quick Start
+
+```python
+from lakhua import geocode
+
+location = geocode(28.6139, 77.209)
+
+if location:
+    print(location.city, location.state)
+```
+
+## API Reference
+
+### Recommended top-level APIs
+
+- `geocode(lat, lon, options=None) -> GeocodeResult | None`
+- `geocode_h3(h3_index, options=None) -> GeocodeResult | None`
+
+These helpers use the default singleton geocoder internally.
+
+### Advanced class APIs
+
+- `ReverseGeocoder.get_instance()`
+- `DataLoader.get_instance()`
+
+Use these only when you need explicit control in advanced runtime or testing scenarios.
+
+### `GeocodeOptions`
+
+```python
+@dataclass
+class GeocodeOptions:
+    resolution: int = 5        # H3 resolution for geocode(lat, lon)
+    fallback: bool = True      # Enable parent resolution fallback
+    debug: bool = False        # Print timing logs
+```
+
+### `GeocodeResult`
+
+```python
+@dataclass
+class GeocodeResult:
+    city: str
+    state: str
+    district: str | None
+    pincode: str | None
+    matched_h3: str
+    matched_resolution: int
+```
+
+Returns `None` for invalid inputs or when no match is found.
+
+## Examples
+
+### Coordinate lookup
+
+```python
+from lakhua import geocode
+
+result = geocode(12.9716, 77.5946)
+print(result)
+```
+
+### Direct H3 lookup
+
+```python
+from lakhua import geocode_h3
+
+result = geocode_h3("8560145bfffffff")
+print(result)
+```
+
+### Debug mode
+
+```python
+from lakhua import geocode, GeocodeOptions
+
+result = geocode(19.076, 72.8777, GeocodeOptions(debug=True))
+print(result)
+```
+
+### Custom resolution
+
+```python
+from lakhua import geocode, GeocodeOptions
+
+result = geocode(
+    28.6139, 77.2090,
+    GeocodeOptions(resolution=4, fallback=False)
+)
+```
+
+## Performance Notes
+
+- Data files are loaded once per process into memory
+- Lookups are map-based in-memory operations
+- Fallback adds up to two additional parent checks (5 → 4) when enabled
+- Average lookup time: < 1ms (in-memory)
+
+## Project Layout
+
+```text
+lakhua/
+  core/
+    __init__.py
+    constants.py
+    data_loader.py
+    geocoder.py
+  types.py
+  __init__.py
+  data/
+    reverse_geo_4.json
+    reverse_geo_5.json
+```
+
+## Development
+
+### Setup
+
+```bash
+pip install -e ".[dev]"
+```
+
+### Run tests
+
+```bash
+pytest
+```
+
+### Linting and formatting
+
+```bash
+ruff check .
+ruff format .
+```
+
+### Type checking
+
+```bash
+mypy lakhua
+```
+
+## License
+
+MIT
+

libs/python/lakhua/__init__.py

@@ -0,0 +1,93 @@
+"""
+lakhua: Fast, offline reverse geocoding for India.
+
+This library provides in-memory reverse geocoding using H3 spatial indexing.
+"""
+
+from lakhua.core import (
+    DATA_DIR_NAME,
+    DATA_FILE_PREFIX,
+    DEFAULT_RESOLUTION,
+    MAX_RESOLUTION,
+    MIN_RESOLUTION,
+    SUPPORTED_RESOLUTIONS,
+    DataLoader,
+    ReverseGeocoder,
+    default_data_loader,
+    default_geocoder,
+)
+from lakhua.types import GeocodeOptions, GeocodeResult, LocationDetails
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    "DATA_DIR_NAME",
+    "DATA_FILE_PREFIX",
+    "DEFAULT_RESOLUTION",
+    "MAX_RESOLUTION",
+    "MIN_RESOLUTION",
+    "SUPPORTED_RESOLUTIONS",
+    "DataLoader",
+    "ReverseGeocoder",
+    "default_data_loader",
+    "default_geocoder",
+    "GeocodeOptions",
+    "GeocodeResult",
+    "LocationDetails",
+    "geocode",
+    "geocode_h3",
+]
+
+
+def geocode(
+    lat: float,
+    lon: float,
+    options: GeocodeOptions | None = None,
+) -> GeocodeResult | None:
+    """
+    Reverse geocodes latitude/longitude into India location metadata.
+
+    Uses the library's internal singleton geocoder, so you can call this directly
+    without creating any class instance.
+
+    Args:
+        lat: Latitude in decimal degrees.
+        lon: Longitude in decimal degrees.
+        options: Lookup options such as fallback and debug logging.
+
+    Returns:
+        Matched location details, or None when input is invalid / no match exists.
+
+    Example:
+        >>> from lakhua import geocode
+        >>> result = geocode(28.6139, 77.2090)
+        >>> print(result.city, result.state)
+    """
+    return default_geocoder.geocode(lat, lon, options)
+
+
+def geocode_h3(
+    h3_index: str,
+    options: GeocodeOptions | None = None,
+) -> GeocodeResult | None:
+    """
+    Reverse geocodes an H3 cell index directly.
+
+    Uses the library's internal singleton geocoder. When fallback is enabled
+    (default), parent resolutions are checked until the minimum supported resolution.
+
+    Args:
+        h3_index: H3 cell index string.
+        options: Lookup options such as fallback and debug logging.
+
+    Returns:
+        Matched location details, or None when input is invalid / no match exists.
+
+    Example:
+        >>> from lakhua import geocode_h3
+        >>> result = geocode_h3("8560145bfffffff")
+        >>> print(result.city if result else "No match")
+    """
+    return default_geocoder.geocode_h3(h3_index, options)
+