ukam-os-builder 0.1.0.dev5__tar.gz → 0.1.0.dev8__tar.gz

{ukam_os_builder-0.1.0.dev5 → ukam_os_builder-0.1.0.dev8}/.github/workflows/ci.yml

@@ -3,9 +3,9 @@ name: Build & package
 on:
   workflow_dispatch:
   push:
-    branches: [main]
+    branches: [ main ]
     paths:
-      - "src/**"
+      - "ukam_os_builder/**"
       - "tests/**"
       - "pyproject.toml"
       - "uv.lock"
@@ -65,4 +65,4 @@ jobs:
         uses: actions/upload-artifact@v4
         with:
           name: dist
-          path: dist/*
+          path: dist/*

{ukam_os_builder-0.1.0.dev5 → ukam_os_builder-0.1.0.dev8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ukam-os-builder
-Version: 0.1.0.dev5
+Version: 0.1.0.dev8
 Summary: Download, process and transform OS address data (NGD or ABP) for UK address matching
 Project-URL: Homepage, https://github.com/moj-analytical-services/prepare_ngd_for_address_matching
 Project-URL: Repository, https://github.com/moj-analytical-services/prepare_ngd_for_address_matching
@@ -32,11 +32,14 @@ Build OS address data for `uk_address_matcher` from either NGD (National Geograp
 
 - Python `3.10+`
 - OS Data Hub package and version IDs
-- Network access to OS Downloads API
+- Network access to OS Downloads API for downloads or remote listing
+- Existing downloaded archives if you want to run offline without re-downloading
 - Credentials in `.env`:
   - `OS_PROJECT_API_KEY`
   - `OS_PROJECT_API_SECRET`
 
+If the required zip files already exist in your downloads directory, the build can now continue offline without contacting OS Data Hub. `--list-only` still requires network access because it queries remote package metadata.
+
 ## Install from PyPI
 
 ```bash
@@ -221,13 +224,10 @@ Each file contains:
 | `filename` | VARCHAR | Source file name (for example `add_gb_builtaddress.parquet`) |
 | `classificationcode` | VARCHAR | Property classification code (for example RD06 for residential) |
 | `parentuprn` | BIGINT | Parent UPRN for hierarchical addresses |
-| `rootuprn` | BIGINT | Root UPRN at the top of the hierarchy |
-| `hierarchylevel` | INTEGER | Level in the address hierarchy (1 = root) |
+| `lowertierlocalauthoritygsscode` | VARCHAR | Lower-tier local authority GSS code |
 | `floorlevel` | VARCHAR | Floor level identifier |
-| `lowestfloorlevel` | DOUBLE | Lowest floor number |
-| `highestfloorlevel` | DOUBLE | Highest floor number |
 
-Metadata columns (`classificationcode`, `parentuprn`, `rootuprn`, `hierarchylevel`, `floorlevel`, `lowestfloorlevel`, `highestfloorlevel`) are enriched via UPRN lookup from core address files. This means Royal Mail addresses and alternate address records receive metadata from their corresponding Built, Historic, or Pre-Build records.
+Metadata used in output (`classificationcode`, `parentuprn`, `lowertierlocalauthoritygsscode`, `floorlevel`) is enriched via UPRN lookup from core address files. This means Royal Mail addresses and alternate address records receive metadata from their corresponding Built, Historic, or Pre-Build records. `lowertierlocalauthoritygsscode` is always sourced from Built Address via UPRN lookup.
 
 </details>
 

{ukam_os_builder-0.1.0.dev5 → ukam_os_builder-0.1.0.dev8}/README.md

@@ -6,11 +6,14 @@ Build OS address data for `uk_address_matcher` from either NGD (National Geograp
 
 - Python `3.10+`
 - OS Data Hub package and version IDs
-- Network access to OS Downloads API
+- Network access to OS Downloads API for downloads or remote listing
+- Existing downloaded archives if you want to run offline without re-downloading
 - Credentials in `.env`:
   - `OS_PROJECT_API_KEY`
   - `OS_PROJECT_API_SECRET`
 
+If the required zip files already exist in your downloads directory, the build can now continue offline without contacting OS Data Hub. `--list-only` still requires network access because it queries remote package metadata.
+
 ## Install from PyPI
 
 ```bash
@@ -195,13 +198,10 @@ Each file contains:
 | `filename` | VARCHAR | Source file name (for example `add_gb_builtaddress.parquet`) |
 | `classificationcode` | VARCHAR | Property classification code (for example RD06 for residential) |
 | `parentuprn` | BIGINT | Parent UPRN for hierarchical addresses |
-| `rootuprn` | BIGINT | Root UPRN at the top of the hierarchy |
-| `hierarchylevel` | INTEGER | Level in the address hierarchy (1 = root) |
+| `lowertierlocalauthoritygsscode` | VARCHAR | Lower-tier local authority GSS code |
 | `floorlevel` | VARCHAR | Floor level identifier |
-| `lowestfloorlevel` | DOUBLE | Lowest floor number |
-| `highestfloorlevel` | DOUBLE | Highest floor number |
 
-Metadata columns (`classificationcode`, `parentuprn`, `rootuprn`, `hierarchylevel`, `floorlevel`, `lowestfloorlevel`, `highestfloorlevel`) are enriched via UPRN lookup from core address files. This means Royal Mail addresses and alternate address records receive metadata from their corresponding Built, Historic, or Pre-Build records.
+Metadata used in output (`classificationcode`, `parentuprn`, `lowertierlocalauthoritygsscode`, `floorlevel`) is enriched via UPRN lookup from core address files. This means Royal Mail addresses and alternate address records receive metadata from their corresponding Built, Historic, or Pre-Build records. `lowertierlocalauthoritygsscode` is always sourced from Built Address via UPRN lookup.
 
 </details>
 

{ukam_os_builder-0.1.0.dev5 → ukam_os_builder-0.1.0.dev8}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ukam-os-builder"
-version = "0.1.0.dev5"
+version = "0.1.0.dev8"
 description = "Download, process and transform OS address data (NGD or ABP) for UK address matching"
 readme = "README.md"
 requires-python = ">=3.10"

{ukam_os_builder-0.1.0.dev5 → ukam_os_builder-0.1.0.dev8}/tests/test_api.py

@@ -6,6 +6,7 @@ from textwrap import dedent
 from typing import Literal
 
 import pytest
+import requests
 
 from ukam_os_builder.api.api import create_config_and_env, run_from_config
 
@@ -295,3 +296,74 @@ def test_run_from_config_applies_schema_path_override(
 
     assert calls["step"] == "split"
     assert calls["schema_path"] == custom_schema.resolve()
+
+
+def test_run_from_config_continues_when_api_preflight_is_offline(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    monkeypatch.setenv("OS_PROJECT_API_KEY", "key")
+    monkeypatch.setenv("OS_PROJECT_API_SECRET", "secret")
+
+    config_path = tmp_path / "config.yaml"
+    _write_config(
+        config_path,
+        """
+        source:
+          type: ngd
+
+        os_downloads:
+          package_id: "16465"
+          version_id: "104444"
+        """,
+    )
+
+    calls: dict[str, object] = {}
+
+    def fake_check_api(_settings: object) -> None:
+        raise requests.exceptions.ConnectionError("offline")
+
+    def fake_run_pipeline(step: str, settings: object, force: bool, list_only: bool) -> None:
+        calls["step"] = step
+        calls["list_only"] = list_only
+
+    monkeypatch.setattr("ukam_os_builder.api.api.get_package_version", fake_check_api)
+    monkeypatch.setattr("ukam_os_builder.api.api.run_pipeline", fake_run_pipeline)
+
+    with caplog.at_level("WARNING"):
+        run_from_config(config_path=config_path, step="all")
+
+    assert calls["step"] == "all"
+    assert calls["list_only"] is False
+    assert "Could not reach OS Data Hub during API preflight" in caplog.text
+
+
+def test_run_from_config_raises_when_list_only_api_preflight_is_offline(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    monkeypatch.setenv("OS_PROJECT_API_KEY", "key")
+    monkeypatch.setenv("OS_PROJECT_API_SECRET", "secret")
+
+    config_path = tmp_path / "config.yaml"
+    _write_config(
+        config_path,
+        """
+        source:
+          type: ngd
+
+        os_downloads:
+          package_id: "16465"
+          version_id: "104444"
+        """,
+    )
+
+    def fake_check_api(_settings: object) -> None:
+        raise requests.exceptions.ConnectionError("offline")
+
+    monkeypatch.setattr("ukam_os_builder.api.api.get_package_version", fake_check_api)
+    monkeypatch.setattr("ukam_os_builder.api.api.run_pipeline", lambda **_kwargs: None)
+
+    with pytest.raises(requests.exceptions.ConnectionError, match="offline"):
+        run_from_config(config_path=config_path, step="download", list_only=True)

{ukam_os_builder-0.1.0.dev5 → ukam_os_builder-0.1.0.dev8}/tests/test_inspect_results.py

@@ -26,7 +26,7 @@ def test_inspect_flatfile_variants_uses_config_defaults(tmp_path: Path) -> None:
                     (1001::BIGINT, 'A'::VARCHAR),
                     (1001::BIGINT, 'B'::VARCHAR),
                     (1002::BIGINT, 'C'::VARCHAR)
-            ) AS t(uprn, address_concat)
+            ) AS t(unique_id, address_concat)
         ) TO '{parquet_path.as_posix()}' (FORMAT PARQUET)
         """
     )
@@ -61,7 +61,7 @@ def test_inspect_flatfile_variants_supports_abp_pattern(tmp_path: Path) -> None:
                     (2001::BIGINT, 'A'::VARCHAR),
                     (2002::BIGINT, 'B'::VARCHAR),
                     (2002::BIGINT, 'C'::VARCHAR)
-            ) AS t(uprn, address_concat)
+            ) AS t(unique_id, address_concat)
         ) TO '{parquet_path.as_posix()}' (FORMAT PARQUET)
         """
     )

{ukam_os_builder-0.1.0.dev5 → ukam_os_builder-0.1.0.dev8}/tests/test_public_api_integration.py

@@ -71,7 +71,7 @@ def test_package_root_inspect_flatfile_variants(tmp_path: Path) -> None:
                     (4001::BIGINT, 'A'::VARCHAR),
                     (4001::BIGINT, 'B'::VARCHAR),
                     (4002::BIGINT, 'C'::VARCHAR)
-            ) AS t(uprn, address_concat)
+            ) AS t(unique_id, address_concat)
         ) TO '{parquet_path.as_posix()}' (FORMAT PARQUET)
         """
     )

{ukam_os_builder-0.1.0.dev5 → ukam_os_builder-0.1.0.dev8}/tests/test_smoke.py

@@ -172,17 +172,14 @@ def test_flatfile_single_chunk(temp_settings: Settings) -> None:
     column_names = [row[0] for row in schema]
 
     expected_columns = [
-        "uprn",
+        "unique_id",
         "address_concat",
         "postcode",
         "filename",
         "classificationcode",
         "parentuprn",
-        "rootuprn",
-        "hierarchylevel",
+        "lowertierlocalauthoritygsscode",
         "floorlevel",
-        "lowestfloorlevel",
-        "highestfloorlevel",
     ]
     for col in expected_columns:
         assert col in column_names, f"Column {col} should exist in output"
@@ -231,9 +228,9 @@ def test_deduplication(temp_settings: Settings) -> None:
     # Verify no exact duplicates
     con = duckdb.connect()
     result = con.execute(f"""
-        SELECT uprn, address_concat, COUNT(*) as cnt
+        SELECT unique_id, address_concat, COUNT(*) as cnt
         FROM read_parquet('{output_files[0].as_posix()}')
-        GROUP BY uprn, address_concat
+        GROUP BY unique_id, address_concat
         HAVING COUNT(*) > 1
     """).fetchall()
 

{ukam_os_builder-0.1.0.dev5 → ukam_os_builder-0.1.0.dev8}/ukam_os_builder/__init__.py

@@ -8,7 +8,7 @@ from ukam_os_builder.os_builder.inspect_results import (
     inspect_flatfile_variants,
 )
 
-__version__ = "0.1.0.dev5"
+__version__ = "0.1.0.dev8"
 
 __all__ = [
     "create_config_and_env",

{ukam_os_builder-0.1.0.dev5 → ukam_os_builder-0.1.0.dev8}/ukam_os_builder/api/api.py

@@ -5,6 +5,7 @@ import os
 from pathlib import Path
 from typing import Any, Literal
 
+import requests
 import yaml
 
 from ukam_os_builder.api.settings import Settings, SettingsError, load_settings
@@ -344,7 +345,16 @@ def run_from_config(
 
     has_api_key = bool(os.environ.get("OS_PROJECT_API_KEY"))
     if check_api and has_api_key:
-        get_package_version(settings)
+        try:
+            get_package_version(settings)
+        except requests.exceptions.RequestException as exc:
+            if list_only:
+                raise
+            logger.warning(
+                "Could not reach OS Data Hub during API preflight (%s). "
+                "Continuing so local downloads can be used if available.",
+                exc.__class__.__name__,
+            )
 
     overwrite_effective = overwrite if overwrite is not None else bool(force)
     run_pipeline(step=step, settings=settings, force=overwrite_effective, list_only=list_only)

{ukam_os_builder-0.1.0.dev5 → ukam_os_builder-0.1.0.dev8}/ukam_os_builder/data_sources/abp/transform/runner.py

@@ -170,7 +170,7 @@ def _transform_to_flatfile_chunk(
     logger.debug("Combination and deduplication in %.2f seconds", perf_counter() - t0)
 
     # Get chunk metrics
-    chunk_metrics = con.execute("SELECT COUNT(DISTINCT uprn), COUNT(*) FROM result").fetchone()
+    chunk_metrics = con.execute("SELECT COUNT(DISTINCT unique_id), COUNT(*) FROM result").fetchone()
     chunk_uprns = chunk_metrics[0]
     chunk_rows = chunk_metrics[1]
 
@@ -244,7 +244,7 @@ def transform_to_flatfile(
         con = create_duckdb_connection(settings)
         output_path = output_paths[0]
         stats = con.execute(f"""
-            SELECT COUNT(DISTINCT uprn), COUNT(*)
+            SELECT COUNT(DISTINCT unique_id), COUNT(*)
             FROM read_parquet('{output_path.as_posix()}')
         """).fetchone()
         total_uprns = stats[0]

{ukam_os_builder-0.1.0.dev5 → ukam_os_builder-0.1.0.dev8}/ukam_os_builder/data_sources/abp/transform/stages/combine.py

@@ -62,7 +62,7 @@ def combine_and_dedupe(con: duckdb.DuckDBPyConnection) -> duckdb.DuckDBPyRelatio
             FROM deduped_filtered
         )
         SELECT
-            sr.uprn,
+            sr.uprn AS unique_id,
             sr.postcode,
             sr.address_concat,
             cb.classification_code,

{ukam_os_builder-0.1.0.dev5 → ukam_os_builder-0.1.0.dev8}/ukam_os_builder/data_sources/ngd/to_flatfile.py

@@ -97,7 +97,6 @@ def _create_metadata_lookup_view(
             """)
 
     if not union_parts:
-        # No core files found - create empty lookup
         logger.warning("No core feature files found. Metadata lookup will be empty.")
         con.execute("""
             CREATE OR REPLACE TEMP VIEW uprn_metadata_lookup AS
@@ -112,37 +111,48 @@ def _create_metadata_lookup_view(
                 CAST(NULL AS DOUBLE) AS highestfloorlevel
             WHERE 1=0
         """)
-        return
-
-    union_sql = "\nUNION ALL\n".join(union_parts)
+    else:
+        union_sql = "\nUNION ALL\n".join(union_parts)
 
-    sql = f"""
-        CREATE OR REPLACE TEMP VIEW uprn_metadata_lookup AS
-        WITH core_data AS (
-            {union_sql}
-        ),
-        ranked AS (
+        sql = f"""
+            CREATE OR REPLACE TEMP VIEW uprn_metadata_lookup AS
+            WITH core_data AS (
+                {union_sql}
+            ),
+            ranked AS (
+                SELECT
+                    *,
+                    ROW_NUMBER() OVER (
+                        PARTITION BY uprn
+                        ORDER BY source_priority
+                    ) AS rn
+                FROM core_data
+            )
             SELECT
-                *,
-                ROW_NUMBER() OVER (
-                    PARTITION BY uprn
-                    ORDER BY source_priority
-                ) AS rn
-            FROM core_data
-        )
+                uprn,
+                classificationcode,
+                parentuprn,
+                rootuprn,
+                hierarchylevel,
+                floorlevel,
+                lowestfloorlevel,
+                highestfloorlevel
+            FROM ranked
+            WHERE rn = 1;
+        """
+        con.execute(sql)
+
+    built_path = parquet_dir / "add_gb_builtaddress.parquet"
+    built_sql = f"""
+        CREATE OR REPLACE TEMP VIEW builtaddress_ltla_lookup AS
         SELECT
-            uprn,
-            classificationcode,
-            parentuprn,
-            rootuprn,
-            hierarchylevel,
-            floorlevel,
-            lowestfloorlevel,
-            highestfloorlevel
-        FROM ranked
-        WHERE rn = 1;
+            CAST(uprn AS BIGINT) AS uprn,
+            MAX(CAST(lowertierlocalauthoritygsscode AS VARCHAR)) AS lowertierlocalauthoritygsscode
+        FROM read_parquet('{built_path.as_posix()}')
+        {where_clause}
+        GROUP BY CAST(uprn AS BIGINT)
     """
-    con.execute(sql)
+    con.execute(built_sql)
 
 
 def _create_core_feature_view(
@@ -183,6 +193,7 @@ def _create_core_feature_view(
             CAST(floorlevel AS VARCHAR) AS floorlevel,
             CAST(lowestfloorlevel AS DOUBLE) AS lowestfloorlevel,
             CAST(highestfloorlevel AS DOUBLE) AS highestfloorlevel,
+            CAST(NULL AS VARCHAR) AS lowertierlocalauthoritygsscode,
             -- Internal columns for deduplication (not in final output)
             CAST(description AS VARCHAR) AS feature_type,
             CAST(addressstatus AS VARCHAR) AS address_status,
@@ -222,6 +233,7 @@ def _create_core_feature_view(
             CAST(floorlevel AS VARCHAR) AS floorlevel,
             CAST(lowestfloorlevel AS DOUBLE) AS lowestfloorlevel,
             CAST(highestfloorlevel AS DOUBLE) AS highestfloorlevel,
+            CAST(NULL AS VARCHAR) AS lowertierlocalauthoritygsscode,
             -- Internal columns for deduplication (not in final output)
             CAST(description AS VARCHAR) AS feature_type,
             CAST(addressstatus AS VARCHAR) AS address_status,
@@ -277,6 +289,7 @@ def _create_altadd_view(
             CAST(floorlevel AS VARCHAR) AS floorlevel,
             CAST(lowestfloorlevel AS DOUBLE) AS lowestfloorlevel,
             CAST(highestfloorlevel AS DOUBLE) AS highestfloorlevel,
+            CAST(NULL AS VARCHAR) AS lowertierlocalauthoritygsscode,
             -- Internal columns for deduplication (not in final output)
             '{feature_type}' AS feature_type,
             CAST(addressstatus AS VARCHAR) AS address_status,
@@ -333,6 +346,7 @@ def _create_royal_mail_view(
             CAST(NULL AS VARCHAR) AS floorlevel,
             CAST(NULL AS DOUBLE) AS lowestfloorlevel,
             CAST(NULL AS DOUBLE) AS highestfloorlevel,
+            CAST(NULL AS VARCHAR) AS lowertierlocalauthoritygsscode,
             -- Internal columns for deduplication (not in final output)
             'Royal Mail Address' AS feature_type,
             CAST(NULL AS VARCHAR) AS address_status,
@@ -363,6 +377,7 @@ def _create_royal_mail_view(
             CAST(NULL AS VARCHAR) AS floorlevel,
             CAST(NULL AS DOUBLE) AS lowestfloorlevel,
             CAST(NULL AS DOUBLE) AS highestfloorlevel,
+            CAST(NULL AS VARCHAR) AS lowertierlocalauthoritygsscode,
             -- Internal columns for deduplication (not in final output)
             'Royal Mail Address' AS feature_type,
             CAST(NULL AS VARCHAR) AS address_status,
@@ -398,12 +413,14 @@ def _enrich_with_metadata(con: duckdb.DuckDBPyConnection) -> None:
             COALESCE(a.floorlevel, m.floorlevel) AS floorlevel,
             COALESCE(a.lowestfloorlevel, m.lowestfloorlevel) AS lowestfloorlevel,
             COALESCE(a.highestfloorlevel, m.highestfloorlevel) AS highestfloorlevel,
+            b.lowertierlocalauthoritygsscode AS lowertierlocalauthoritygsscode,
             -- Internal columns for deduplication
             a.feature_type,
             a.address_status,
             a.build_status
         FROM all_full_addresses a
-        LEFT JOIN uprn_metadata_lookup m ON a.uprn = m.uprn;
+        LEFT JOIN uprn_metadata_lookup m ON a.uprn = m.uprn
+        LEFT JOIN builtaddress_ltla_lookup b ON a.uprn = b.uprn;
     """
     con.execute(sql)
 
@@ -419,11 +436,28 @@ def _create_custom_level_rows(con: duckdb.DuckDBPyConnection) -> None:
     dedup priority and never override official address data.
     """
     sql = """
-        INSERT INTO all_full_addresses_enriched
+        INSERT INTO all_full_addresses_enriched (
+            uprn,
+            address_concat,
+            postcode,
+            filename,
+            classificationcode,
+            parentuprn,
+            rootuprn,
+            hierarchylevel,
+            floorlevel,
+            lowestfloorlevel,
+            highestfloorlevel,
+            lowertierlocalauthoritygsscode,
+            feature_type,
+            address_status,
+            build_status
+        )
         WITH level_parsed AS (
             SELECT
                 uprn, address_concat, postcode, filename,
                 classificationcode, parentuprn, rootuprn,
+                lowertierlocalauthoritygsscode,
                 hierarchylevel, floorlevel, lowestfloorlevel, highestfloorlevel,
                 address_status, build_status,
                 CASE
@@ -464,6 +498,7 @@ def _create_custom_level_rows(con: duckdb.DuckDBPyConnection) -> None:
             floorlevel,
             lowestfloorlevel,
             highestfloorlevel,
+            lowertierlocalauthoritygsscode,
             'Custom Level' AS feature_type,
             address_status,
             build_status
@@ -523,17 +558,14 @@ def _create_dedup_view(con: duckdb.DuckDBPyConnection) -> None:
           WHERE feature_type NOT IN ('Non-Addressable Object')
         )
         SELECT
-          uprn,
+          uprn AS unique_id,
           address_concat,
           postcode,
           filename,
           classificationcode,
           parentuprn,
-          rootuprn,
-          hierarchylevel,
-          floorlevel,
-          lowestfloorlevel,
-          highestfloorlevel
+          lowertierlocalauthoritygsscode,
+                    floorlevel
         FROM ranked
         WHERE rn = 1;
     """

{ukam_os_builder-0.1.0.dev5 → ukam_os_builder-0.1.0.dev8}/ukam_os_builder/os_builder/inspect_results.py

@@ -12,7 +12,7 @@ SourceType = Literal["ngd", "abp"]
 logger = logging.getLogger(__name__)
 
 _DEFAULT_SELECT_COLUMNS = [
-    "uprn",
+    "unique_id",
     "address_concat",
     "postcode",
     "source",
@@ -128,9 +128,9 @@ def get_variant_statistics(
 
     stats = con.sql(f"""
         WITH variant_counts AS (
-            SELECT uprn, COUNT(*) AS variant_count
+            SELECT unique_id, COUNT(*) AS variant_count
             FROM read_parquet('{files_sql}')
-            GROUP BY uprn
+            GROUP BY unique_id
         )
         SELECT
             COUNT(*) AS total_uprns,
@@ -179,7 +179,7 @@ def get_random_uprn(
 
     select_columns = _choose_select_columns(con, files_sql, columns)
     random_uprn = con.sql(f"""
-        SELECT DISTINCT uprn
+        SELECT DISTINCT unique_id
         FROM read_parquet('{files_sql}')
         ORDER BY RANDOM()
         LIMIT 1
@@ -192,7 +192,7 @@ def get_random_uprn(
         SELECT
             {select_columns}
         FROM read_parquet('{files_sql}')
-        WHERE uprn = {int(random_uprn[0])}
+        WHERE unique_id = {int(random_uprn[0])}
         ORDER BY is_primary DESC NULLS LAST, source NULLS LAST, variant_label NULLS LAST
     """)
 
@@ -220,14 +220,14 @@ def get_random_large_uprn(
 
     selected = con.sql(f"""
         WITH variant_counts AS (
-            SELECT uprn, COUNT(*) AS variant_count
+            SELECT unique_id, COUNT(*) AS variant_count
             FROM read_parquet('{files_sql}')
             {where_filter}
-            GROUP BY uprn
-            ORDER BY variant_count DESC, uprn ASC
+            GROUP BY unique_id
+            ORDER BY variant_count DESC, unique_id ASC
             LIMIT {int(top_n)}
         )
-        SELECT uprn
+        SELECT unique_id
         FROM variant_counts
         ORDER BY RANDOM()
         LIMIT 1
@@ -240,7 +240,7 @@ def get_random_large_uprn(
         SELECT
             {select_columns}
         FROM read_parquet('{files_sql}')
-        WHERE uprn = {int(selected[0])}
+        WHERE unique_id = {int(selected[0])}
         {and_filter}
         ORDER BY is_primary DESC NULLS LAST, source NULLS LAST, variant_label NULLS LAST
     """)
@@ -269,7 +269,7 @@ def get_uprn_variants(
         SELECT
             {select_columns}
         FROM read_parquet('{files_sql}')
-        WHERE uprn = {int(uprn)}
+        WHERE unique_id = {int(uprn)}
         {and_filter}
         ORDER BY is_primary DESC NULLS LAST, source NULLS LAST, variant_label NULLS LAST
     """)
@@ -317,10 +317,10 @@ def inspect_flatfile_variants(
             WITH data AS (
                 SELECT * FROM read_parquet('{files_sql}')
             )
-            SELECT uprn, COUNT(*) AS variant_count
+            SELECT unique_id, COUNT(*) AS variant_count
             FROM data
-            GROUP BY uprn
-            ORDER BY variant_count DESC, uprn ASC
+            GROUP BY unique_id
+            ORDER BY variant_count DESC, unique_id ASC
             LIMIT 1 OFFSET {top_offset}
             """
         ).fetchone()
@@ -333,7 +333,7 @@ def inspect_flatfile_variants(
             f"""
             SELECT COUNT(*)
             FROM read_parquet('{files_sql}')
-            WHERE uprn = ?
+            WHERE unique_id = ?
             """,
             [target_uprn],
         ).fetchone()
@@ -343,7 +343,7 @@ def inspect_flatfile_variants(
         f"""
         SELECT *
         FROM read_parquet('{files_sql}')
-        WHERE uprn = ?
+        WHERE unique_id = ?
         ORDER BY 1
         """,
         [target_uprn],
@@ -358,7 +358,7 @@ def inspect_flatfile_variants(
             max_width=10_000
         )
         logger.info("Selected UPRN rows:")
-        con.sql(f"SELECT * FROM read_parquet('{files_sql}') WHERE uprn = {target_uprn}").show(
+        con.sql(f"SELECT * FROM read_parquet('{files_sql}') WHERE unique_id = {target_uprn}").show(
             max_width=10_000
         )
 

{ukam_os_builder-0.1.0.dev5 → ukam_os_builder-0.1.0.dev8}/ukam_os_builder/os_builder/os_hub.py

@@ -253,6 +253,29 @@ def download_file(
     return True
 
 
+def _use_existing_archives_or_raise(
+    downloads_dir: Path,
+    reason: str,
+    original_exc: Exception,
+) -> list[Path]:
+    """Fall back to existing local archives, or re-raise with a helpful message."""
+    existing_archives = _find_existing_download_archives(downloads_dir)
+    if existing_archives:
+        logger.warning(
+            "%s; using %d existing archive(s) in %s and skipping download "
+            "(MD5 verification against the OS Data Hub will be skipped).",
+            reason,
+            len(existing_archives),
+            downloads_dir,
+        )
+        return existing_archives
+
+    raise ValueError(
+        f"{reason}. No local zip files were found in {downloads_dir}, "
+        "so download cannot be skipped."
+    ) from original_exc
+
+
 def run_download_step(
     settings: Any,
     force: bool = False,
@@ -266,22 +289,23 @@ def run_download_step(
     except ValueError as exc:
         if list_only:
             raise
-
-        existing_archives = _find_existing_download_archives(downloads_dir)
-        if existing_archives:
-            logger.warning(
-                "No API key found; using %d existing archive(s) in %s and skipping download.",
-                len(existing_archives),
-                downloads_dir,
-            )
-            return existing_archives
-
-        raise ValueError(
-            f"{exc} No local zip files were found in {downloads_dir}, so download cannot be skipped."
-        ) from exc
+        return _use_existing_archives_or_raise(
+            downloads_dir,
+            reason="No API key found",
+            original_exc=exc,
+        )
 
     logger.info("Fetching package metadata...")
-    metadata = get_package_version(settings)
+    try:
+        metadata = get_package_version(settings)
+    except (requests.exceptions.RequestException, OSError) as exc:
+        if list_only:
+            raise
+        return _use_existing_archives_or_raise(
+            downloads_dir,
+            reason=f"Could not reach OS Data Hub ({exc.__class__.__name__})",
+            original_exc=exc,
+        )
     items = list_downloads(metadata)
 
     if list_only:

{ukam_os_builder-0.1.0.dev5 → ukam_os_builder-0.1.0.dev8}/uv.lock

@@ -1421,7 +1421,7 @@ wheels = [
 
 [[package]]
 name = "ukam-os-builder"
-version = "0.1.0.dev5"
+version = "0.1.0.dev8"
 source = { editable = "." }
 dependencies = [
     { name = "duckdb" },