sourcelock 0.1.0__py3-none-any.whl

hc_source/adapters/_demo.py

@@ -0,0 +1,258 @@
+"""Reference adapter.
+
+This is a complete, working adapter over a static JSON fixture shipped inside
+the package. It exists to prove the interface end to end offline, and to be the
+thing you copy when writing a real route. Read it top to bottom before writing
+``hc_source/adapters/<route>.py``; see ADAPTER_GUIDE.md for the rules.
+
+The only thing unusual about it is its transport: it reads a packaged file via
+a ``file://`` URL instead of an HTTPS endpoint, so ``hc-source doctor`` is green
+on a laptop with no network. Everything else -- contract, canaries, typed
+params, guard, receipts -- is exactly what a real adapter does.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from datetime import date
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from ..http import FetchResult, fetch_json
+from ..interfaces import Canary, CanaryObservation, SourceAdapter, ToolResult, ToolSpec
+from ..receipts import build_receipt
+from ..schemas import SourceContract
+
+SOURCE_ID = "demo"
+TRANSFORM_VERSION = "1"
+
+#: Environment override, used by the test suite to simulate upstream drift.
+FIXTURE_ENV_VAR = "HC_SOURCE_DEMO_FIXTURE"
+
+CONTRACT = SourceContract(
+    source_id=SOURCE_ID,
+    authority_url="file://<packaged>/hc_source/adapters/_demo_fixture.json",
+    fallback_url=None,
+    license_notes="Synthetic reference data. Public domain; not derived from any real source.",
+    cadence="never (static fixture)",
+    effective_date_semantics=(
+        "effective_from is the release publication date; effective_to is null while the "
+        "release is current."
+    ),
+    invariants=[
+        "release_id is a year.month string that only moves forward",
+        "every record carries code, short_description, and effective_from",
+        "codes match ^DEMO[0-9]{3}$",
+    ],
+)
+
+NON_CLAIMS = [
+    "DOES_NOT_PROVE_COVERAGE: presence of a code in this release says nothing about whether "
+    "any payer covers or pays for it.",
+    "DOES_NOT_PROVE_CURRENCY: this is the pinned release, which may lag the upstream publisher.",
+]
+
+
+def packaged_fixture_path() -> Path:
+    return Path(__file__).with_name("_demo_fixture.json")
+
+
+def fixture_path() -> Path:
+    override = os.environ.get(FIXTURE_ENV_VAR)
+    return Path(override) if override else packaged_fixture_path()
+
+
+def _load() -> tuple[FetchResult, dict[str, Any]]:
+    """Read the release through the shared transport, so we get a hash for free."""
+    return fetch_json(fixture_path().as_uri())
+
+
+def _schema_hash(payload: dict[str, Any]) -> str:
+    """Hash the declared shape only -- not the data -- so drift and schema change differ."""
+    shape = json.dumps(payload.get("schema", []), sort_keys=True, separators=(",", ":"))
+    return hashlib.sha256(shape.encode("utf-8")).hexdigest()
+
+
+def _as_date(value: Any) -> date | None:
+    return date.fromisoformat(value) if isinstance(value, str) else None
+
+
+# --------------------------------------------------------------------------
+# Typed public parameters
+# --------------------------------------------------------------------------
+
+
+class NoParams(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+
+class LookupCodeParams(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    code: str = Field(pattern=r"^DEMO[0-9]{3}$", description="Demo code, e.g. DEMO001.")
+    include_retired: bool = Field(
+        default=False, description="Return the record even if the release marks it retired."
+    )
+
+
+# --------------------------------------------------------------------------
+# Handlers
+# --------------------------------------------------------------------------
+
+
+def _get_release(_: NoParams) -> ToolResult:
+    result, payload = _load()
+    data = {
+        "release_id": payload["release_id"],
+        "effective_from": payload.get("effective_from"),
+        "effective_to": payload.get("effective_to"),
+        "record_count": len(payload.get("records", [])),
+        "schema": payload.get("schema", []),
+    }
+    return ToolResult(
+        data=data,
+        receipt=build_receipt(
+            contract=CONTRACT,
+            route="demo.get_release",
+            fetch=result,
+            source_version=payload["release_id"],
+            transform_version=TRANSFORM_VERSION,
+            effective_from=_as_date(payload.get("effective_from")),
+            effective_to=_as_date(payload.get("effective_to")),
+            non_claims=NON_CLAIMS,
+        ),
+    )
+
+
+def _lookup_code(params: LookupCodeParams) -> ToolResult:
+    result, payload = _load()
+    warnings: list[str] = []
+
+    match = next((r for r in payload.get("records", []) if r.get("code") == params.code), None)
+    if match is not None and match.get("retired") and not params.include_retired:
+        warnings.append(
+            f"The requested code is retired in release {payload['release_id']}; "
+            "pass include_retired=true to see it."
+        )
+        match = None
+    elif match is None:
+        warnings.append(
+            f"The requested code was not found in release {payload['release_id']}."
+        )
+
+    return ToolResult(
+        data=match,
+        receipt=build_receipt(
+            contract=CONTRACT,
+            route="demo.lookup_code",
+            fetch=result,
+            source_version=payload["release_id"],
+            transform_version=TRANSFORM_VERSION,
+            effective_from=_as_date(payload.get("effective_from")),
+            effective_to=_as_date(payload.get("effective_to")),
+            warnings=warnings,
+            non_claims=NON_CLAIMS,
+        ),
+    )
+
+
+# --------------------------------------------------------------------------
+# Canaries
+# --------------------------------------------------------------------------
+
+
+def _observe_release() -> CanaryObservation:
+    result, payload = _load()
+    return CanaryObservation(
+        value=str(payload["release_id"]),
+        schema_hash=_schema_hash(payload),
+        upstream_status=result.status,
+        note="release id and declared column set",
+    )
+
+
+def _observe_record_count() -> CanaryObservation:
+    _, payload = _load()
+    return CanaryObservation(
+        value=str(len(payload.get("records", []))),
+        note="row count of the pinned release",
+    )
+
+
+def _release_remediation(status, observed, expected) -> str:
+    from ..schemas import CanaryStatus
+
+    if status is CanaryStatus.SCHEMA_CHANGED:
+        return (
+            "The demo release kept its id but changed its column set. Review the new columns, "
+            "bump TRANSFORM_VERSION in hc_source/adapters/_demo.py if the mapping changed, then "
+            "re-pin with `hc-source lock init`."
+        )
+    if status is CanaryStatus.UNREACHABLE:
+        return (
+            "The demo fixture could not be read. Check HC_SOURCE_DEMO_FIXTURE if it is set, "
+            "otherwise reinstall the package; then run `hc-source doctor` again."
+        )
+    return (
+        f"The demo source published release {observed}; source-lock.json pins {expected}. "
+        "Review the diff, then re-pin with `hc-source lock init`."
+    )
+
+
+class DemoAdapter(SourceAdapter):
+    source_id = SOURCE_ID
+    contract = CONTRACT
+
+    # Every canary here reads vendored data, so there is no network to be flaky
+    # and a retry would just repeat a deterministic answer.
+    canary_retries = 0
+
+    def canaries(self) -> list[Canary]:
+        return [
+            Canary(
+                canary_id="demo.release_id",
+                source_id=SOURCE_ID,
+                description="Release id and declared column set of the demo source.",
+                observe=_observe_release,
+                remediation=(
+                    "The demo source moved. Review the change, then re-pin with "
+                    "`hc-source lock init`."
+                ),
+                remediation_for=_release_remediation,
+            ),
+            Canary(
+                canary_id="demo.record_count",
+                source_id=SOURCE_ID,
+                description="Number of records in the demo release.",
+                observe=_observe_record_count,
+                remediation=(
+                    "The demo release gained or lost rows. Confirm the change is real upstream, "
+                    "then re-pin with `hc-source lock init`."
+                ),
+            ),
+        ]
+
+    def tools(self) -> list[ToolSpec]:
+        return [
+            ToolSpec(
+                name="demo.get_release",
+                description="Return the pinned demo release: id, effective dates, and column set.",
+                params_model=NoParams,
+                handler=_get_release,
+                tags=("metadata",),
+            ),
+            ToolSpec(
+                name="demo.lookup_code",
+                description="Look up one demo code in the pinned release.",
+                params_model=LookupCodeParams,
+                handler=_lookup_code,
+                tags=("lookup",),
+            ),
+        ]
+
+
+ADAPTER = DemoAdapter()

hc_source/adapters/_demo_fixture.json

@@ -0,0 +1,25 @@
+{
+  "source": "SourceLock demo source",
+  "release_id": "2026.07",
+  "effective_from": "2026-07-01",
+  "effective_to": null,
+  "schema": ["code", "short_description", "effective_from"],
+  "records": [
+    {
+      "code": "DEMO001",
+      "short_description": "Reference item one",
+      "effective_from": "2026-07-01"
+    },
+    {
+      "code": "DEMO002",
+      "short_description": "Reference item two",
+      "effective_from": "2026-07-01"
+    },
+    {
+      "code": "DEMO003",
+      "short_description": "Reference item three, retired",
+      "effective_from": "2026-01-01",
+      "retired": true
+    }
+  ]
+}

hc_source/adapters/_leie_sample.csv

@@ -0,0 +1,15 @@
+LASTNAME,FIRSTNAME,MIDNAME,BUSNAME,GENERAL,SPECIALTY,UPIN,NPI,DOB,ADDRESS,CITY,STATE,ZIP,EXCLTYPE,EXCLDATE,REINDATE,WAIVERDATE,WVRSTATE
+"","","","#1 MARKETING SERVICE, INC","OTHER BUSINESS","SOBER HOME","","0000000000","","239 BRIGHTON BEACH AVENUE","BROOKLYN","NY","11235","1128a1","20200319","00000000","00000000",""
+"","","","101 FIRST CARE PHARMACY INC","OTHER BUSINESS","PHARMACY","","1972902351","","C/O 609 W 191ST STREET, APT D","NEW YORK","NY","10040","1128b8","20220320","00000000","00000000",""
+"ABAD-SANTOS","CRISELDA","CALAYAN","","PHYSICIAN (MD, DO)","PSYCHIATRY","","1760461826","00000000","8506 N ADIR DR","WEST HILLS","CA","91304","1128b4","20250120","00000000","00000000",""
+"ABADI","JAMSHEED","S","","PHYSICIAN (MD, DO)","INTERNAL MEDICINE","C04537","1477537496","00000000","89 WEEKS ROAD","E WILLISTON PARK","NY","11596","1128b4","20140520","00000000","00000000",""
+"FRASER","JEFFREY","LOREN","","PHYSICIAN (MD, DO)","FAMILY PRACTICE","","1790792380","00000000","1402 E 8TH ST","HICKMAN","NE","68372","1128a4","20210819","00000000","20230324","NC"
+"MIRANDA","EDUARDO","SIRIA","","PHYSICIAN (MD, DO)","INTERNAL MEDICINE","","1285673012","00000000","8306 ESTATE DRIVE","LAREDO","TX","78045","1128a1","20150618","00000000","20150618","TX"
+"WAHIB","SAMIR","","","PHYSICIAN (MD, DO)","GYN/OBS","","1851353866","00000000","2204 N SECTION ST","SULLIVAN","IN","47882","1128a1","20240118","00000000","20240227","IN"
+"","","","ABSOLUTE MEDICAL SUPPLIES SERV","DME COMPANY","DME - GENERAL","","1588302186","","246 STADDEN ROAD, STE 105","TANNERSVILLE","PA","18372","1128Aa","20260624","00000000","00000000",""
+"","","","ASSURE HOLDINGS CORP","PHYSICIAN PRACTICE (","SURGERY","","0000000000","","7887 E BELLEVIEW AVE, SUITE 50","DENVER","CO","80111","BRCH SA","20250320","00000000","00000000",""
+"","","","CHARTER HOME HEALTH, LLC","OTHER BUSINESS","HOME HEALTH AGENCY","","1104927508","","2798 O'NEAL LANE, BUILDING C","BATON ROUGE","LA","70816","BRCH CIA","20200812","00000000","00000000",""
+"BELGADO","PAULINO","G JR","","MEDICAL PRACTICE, MD","GENERAL PRACTICE/FP","B51476","0000000000","19010101","154 SEVENTH STREET","CLINTONVILLE","WI","54929","1156","19900703","00000000","00000000",""
+"","","","JEWISH MEMORIAL HOSPITAL","HOSPITAL","","","0000000000","","BROADWAY AND 196TH ST","NEW YORK","NY","10040","1160","19830705","00000000","00000000",""
+"","","","UPHILL MEDICAL ASSOCIATES","MEDICAL GROUP","","","0000000000","","C/O 31 CENTRE ST SOUTH, #7","ONTARIO L6W2X7","XX","00000","1128a1","20040908","00000000","00000000",""
+"CAMPBELL","FREDDY","ELTON","","DME COMPANY","OWNER/OPERATOR","","0000000000","00000000","FCI COLEMAN MEDIUM","COLEMAN","FM","33521","1128a1","20090618","00000000","00000000",""