netrias_client 0.1.0__py3-none-any.whl

netrias_client/_validators.py

@@ -0,0 +1,192 @@
+"""Validate inputs for harmonization.
+
+'why': fail fast with clear, actionable messages prior to network calls
+"""
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+
+from ._errors import FileValidationError, MappingValidationError, OutputLocationError
+
+
+# OBVIOUS HARD-CODED SIZE LIMIT: 250 MB maximum CSV size prior to upload
+HARD_MAX_CSV_BYTES = 250 * 1024 * 1024
+
+
+def validate_source_path(path: Path) -> Path:
+    """Ensure the CSV exists, is a file, has a .csv extension, and respects size limits."""
+
+    _require_exists(path, "source CSV not found")
+    _require_is_file(path, "source path is not a file")
+    _require_suffix(path, ".csv", "unsupported file extension for source CSV")
+    _require_not_too_large(path)
+    return path
+
+
+def validate_manifest_path(path: Path) -> Path:
+    """Ensure the manifest JSON exists and is a file."""
+
+    _require_exists(path, "manifest JSON not found")
+    _require_is_file(path, "manifest path is not a file")
+    _require_suffix(path, ".json", "manifest must be a .json file")
+    return path
+
+
+def validate_output_path(path: Path | None, source_name: str, allow_versioning: bool = False) -> Path:
+    """Return a valid output file path, creating parent directories when needed.
+
+    Defaults to `<CWD>/<source_name>.harmonized.csv` when `path` is None or a directory.
+    """
+
+    candidate = _resolve_output_candidate(path, source_name)
+    _ensure_parent(candidate)
+    _require_parent_writable(candidate)
+    if allow_versioning:
+        candidate = _next_available_path(candidate)
+    else:
+        _require_not_exists(candidate)
+    return candidate
+
+
+def validate_target_schema(schema: str) -> str:
+    """Ensure the target schema identifier is a non-empty string."""
+
+    candidate = (schema or "").strip()
+    if not candidate:
+        raise MappingValidationError("target_schema must be a non-empty string")
+    return candidate
+
+
+def validate_target_version(version: str) -> str:
+    """Ensure the target version identifier is a non-empty string."""
+
+    candidate = (version or "").strip()
+    if not candidate:
+        raise MappingValidationError("target_version must be a non-empty string")
+    return candidate
+
+
+def validate_top_k(top_k: int | None) -> int | None:
+    """Ensure top_k is a positive integer when provided."""
+
+    if top_k is None:
+        return None
+    if top_k < 1:
+        raise MappingValidationError("top_k must be a positive integer")
+    return top_k
+
+
+def validate_column_samples(columns: Mapping[str, Sequence[object]]) -> dict[str, list[str]]:
+    """Normalize column sample data for mapping discovery."""
+
+    if not columns:
+        raise MappingValidationError("column data must include at least one column")
+    normalized: dict[str, list[str]] = {}
+    for raw_name, values in columns.items():
+        name = _normalized_column_name(raw_name)
+        samples = _normalized_samples(name, values)
+        normalized[name] = samples
+    return normalized
+
+
+def _require_exists(path: Path, message: str) -> None:
+    if not path.exists():
+        raise FileValidationError(f"{message}: {path}")
+
+
+def _require_is_file(path: Path, message: str) -> None:
+    if not path.is_file():
+        raise FileValidationError(f"{message}: {path}")
+
+
+def _require_suffix(path: Path, suffix: str, message: str) -> None:
+    if path.suffix.lower() != suffix:
+        raise FileValidationError(f"{message}: {path.suffix}")
+
+
+def _require_not_too_large(path: Path) -> None:
+    try:
+        size = os.path.getsize(path)
+    except OSError as exc:
+        raise FileValidationError(f"unable to stat source CSV: {exc}") from exc
+    if size > HARD_MAX_CSV_BYTES:
+        raise FileValidationError(
+            f"source CSV exceeds hard-coded limit of {HARD_MAX_CSV_BYTES // (1024 * 1024)} MB (got {size} bytes)"
+        )
+
+
+def _resolve_output_candidate(path: Path | None, source_name: str) -> Path:
+    if path is None:
+        return Path.cwd() / f"{source_name}.harmonized.csv"
+    if path.exists() and path.is_dir():
+        return path / f"{source_name}.harmonized.csv"
+    return path
+
+
+def _ensure_parent(candidate: Path) -> None:
+    parent = candidate.parent
+    if not parent.exists():
+        try:
+            parent.mkdir(parents=True, exist_ok=True)
+        except OSError as exc:
+            raise OutputLocationError(f"unable to create output directory {parent}: {exc}") from exc
+
+
+def _require_parent_writable(candidate: Path) -> None:
+    parent = candidate.parent
+    if parent.exists() and not os.access(parent, os.W_OK):
+        raise OutputLocationError(f"output directory not writable: {parent}")
+
+
+def _require_not_exists(candidate: Path) -> None:
+    if candidate.exists():
+        raise OutputLocationError(f"refusing to overwrite existing file: {candidate}")
+
+
+def _next_available_path(candidate: Path) -> Path:
+    if not candidate.exists():
+        return candidate
+    stem = candidate.stem
+    suffix = candidate.suffix
+    parent = candidate.parent
+    index = 1
+    while index < 1000:
+        versioned = parent / f"{stem}.v{index}{suffix}"
+        if not versioned.exists():
+            return versioned
+        index += 1
+    raise OutputLocationError(
+        f"unable to determine unique output path after {index - 1} attempts for {candidate}"
+    )
+
+
+def _normalized_column_name(raw_name: object) -> str:
+    if not isinstance(raw_name, str):
+        raise MappingValidationError("column names must be strings")
+    name = raw_name.strip()
+    if not name:
+        raise MappingValidationError("column names must be non-empty strings")
+    return name
+
+
+def _normalized_samples(column_name: str, values: Sequence[object] | None) -> list[str]:
+    sequence = _require_sequence(column_name, values)
+    samples = [sample for sample in (_coerced_sample(value) for value in sequence) if sample]
+    if not samples:
+        raise MappingValidationError(f"column '{column_name}' must include at least one non-empty sample value")
+    return samples
+
+
+def _require_sequence(column_name: str, values: Sequence[object] | None) -> Sequence[object]:
+    if values is None or isinstance(values, (str, bytes)):
+        raise MappingValidationError(f"column '{column_name}' values must be a sequence of samples")
+    return values
+
+
+def _coerced_sample(value: object) -> str | None:
+    if value is None:
+        return None
+    text = str(value).strip()
+    return text or None

netrias_client/scripts.py

@@ -0,0 +1,313 @@
+"""Coordinate project command entry points.
+
+'why': centralize developer workflows for `uv run` execution
+"""
+from __future__ import annotations
+
+import argparse
+import logging
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Final, cast
+
+_LOGGER = logging.getLogger("netrias_client.scripts")
+_COMMANDS: Final[tuple[tuple[str, ...], ...]] = (
+    ("pytest",),
+    ("ruff", "check", "."),
+    ("basedpyright", "."),
+)
+_REPO_ROOT: Final[Path] = Path(__file__).resolve().parents[2]
+_PYPROJECT_PATH: Final[Path] = _REPO_ROOT / "pyproject.toml"
+_PACKAGE_INIT_PATH: Final[Path] = Path(__file__).resolve().parent / "__init__.py"
+_DIST_PATH: Final[Path] = _REPO_ROOT / "dist"
+_VERSION_PATTERN: Final[re.Pattern[str]] = re.compile(r'^version\s*=\s*"(?P<value>[^"]+)"$', re.MULTILINE)
+_INIT_VERSION_PATTERN: Final[re.Pattern[str]] = re.compile(r'^__version__\s*=\s*"(?P<value>[^"]+)"$', re.MULTILINE)
+_REPOSITORY_CONFIG: Final[dict[str, tuple[str, str | None]]] = {
+    "testpypi": ("TEST_PYPI_TOKEN", "https://test.pypi.org/legacy/"),
+    "pypi": ("PYPI_TOKEN", None),
+}
+
+
+@dataclass(frozen=True)
+class ReleaseOptions:
+    """Capture release CLI arguments as structured options.
+
+    'why': keep parsing separate from orchestration logic
+    """
+
+    version: str | None
+    bump: str
+    repository: str | None
+
+
+def check() -> None:
+    """Run the combined test and lint pipeline invoked by `uv run check`.
+
+    'why': provide a single entry point that exits early on the first failure
+    """
+
+    _ensure_logging()
+    for command in _COMMANDS:
+        _run_command_or_raise(command)
+
+
+def live_check() -> None:
+    """Execute the live service smoke test harness.
+
+    'why': exercise production endpoints without duplicating CLI plumbing
+    """
+
+    _run_command_or_raise(("python", "-m", "netrias_client.live_test.test"))
+
+
+def release(argv: Sequence[str] | None = None) -> None:
+    """Run the release pipeline: bump version, validate, build, publish.
+
+    'why': streamline TestPyPI/PyPI releases from a single script
+    """
+
+    options = _parse_release_args(argv)
+    _ensure_logging()
+    target_version = _determine_target_version(options)
+    _update_versions(target_version)
+    _LOGGER.info("version synchronized → %s", target_version)
+    check()
+    artifacts = _build_distributions()
+    _verify_artifacts(artifacts)
+    if options.repository:
+        _publish_artifacts(options.repository)
+
+
+def _ensure_logging() -> None:
+    """Provision a minimalist logging configuration for script execution."""
+
+    if not _LOGGER.handlers:
+        logging.basicConfig(level=logging.INFO, format="%(message)s")
+
+
+def _run_command(command: Sequence[str], *, env: Mapping[str, str] | None = None, display_command: Sequence[str] | None = None) -> int:
+    """Run `command` and return its exit status without raising on failure.
+
+    'why': centralize subprocess logging and leave error handling to callers
+    """
+
+    shown = display_command or command
+    _LOGGER.info("→ %s", " ".join(shown))
+    completed = subprocess.run(command, check=False, env=dict(env) if env else None)
+    return completed.returncode
+
+
+def _run_command_or_raise(
+    command: Sequence[str],
+    *,
+    env: Mapping[str, str] | None = None,
+    display_command: Sequence[str] | None = None,
+) -> None:
+    """Execute `command` and abort immediately on failure.
+
+    'why': surface the first failing command to halt composite workflows
+    """
+
+    exit_code = _run_command(command, env=env, display_command=display_command)
+    if exit_code != 0:
+        raise SystemExit(exit_code)
+
+
+def _parse_release_args(argv: Sequence[str] | None) -> ReleaseOptions:
+    """Parse CLI arguments into a `ReleaseOptions` instance.
+
+    'why': isolate argparse wiring for straightforward testing
+    """
+
+    parser = argparse.ArgumentParser(prog="uv run release")
+    group = parser.add_mutually_exclusive_group()
+    _ = group.add_argument("--version", help="Explicit semantic version to publish")
+    _ = group.add_argument("--bump", choices=("patch", "minor", "major"), default="patch", help="Increment the current version")
+    _ = parser.add_argument("--publish", choices=("testpypi", "pypi"), dest="repository", help="Publish artifacts after verification")
+    namespace = parser.parse_args(list(argv) if argv is not None else sys.argv[1:])
+    version_arg = cast(str | None, getattr(namespace, "version", None))
+    bump_arg = cast(str | None, getattr(namespace, "bump", None))
+    repository_arg = cast(str | None, getattr(namespace, "repository", None))
+    bump = bump_arg or "patch"
+    return ReleaseOptions(version=version_arg, bump=bump, repository=repository_arg)
+
+
+def _determine_target_version(options: ReleaseOptions) -> str:
+    """Decide the release version based on explicit input or a bump type.
+
+    'why': ensure both pyproject and package versions stay aligned
+    """
+
+    current = _read_version(_PYPROJECT_PATH, _VERSION_PATTERN)
+    _assert_versions_match(current)
+    if options.version:
+        return options.version
+    return _bump_semver(current, options.bump)
+
+
+def _assert_versions_match(expected: str) -> None:
+    """Verify the package and pyproject versions are identical before bumping.
+
+    'why': prevent partial version updates that ship inconsistent metadata
+    """
+
+    package_version = _read_version(_PACKAGE_INIT_PATH, _INIT_VERSION_PATTERN)
+    if package_version != expected:
+        message = " ".join(
+            [
+                f"Package version mismatch: pyproject.toml has {expected}",
+                f"but src/netrias_client/__init__.py has {package_version}",
+            ]
+        )
+        raise RuntimeError(message)
+
+
+def _read_version(path: Path, pattern: re.Pattern[str]) -> str:
+    """Extract a version string from `path` using `pattern`.
+
+    'why': share parsing logic between pyproject and package metadata
+    """
+
+    text = path.read_text(encoding="utf-8")
+    match = pattern.search(text)
+    if match is None:
+        raise RuntimeError(f"Could not locate version string in {path}")
+    return match.group("value")
+
+
+def _bump_semver(version: str, bump: str) -> str:
+    """Return a new semantic version string incremented by `bump` type.
+
+    'why': keep release increments predictable without external tooling
+    """
+
+    major_str, minor_str, patch_str = version.split(".")
+    major, minor, patch = int(major_str), int(minor_str), int(patch_str)
+    if bump == "major":
+        return f"{major + 1}.0.0"
+    if bump == "minor":
+        return f"{major}.{minor + 1}.0"
+    return f"{major}.{minor}.{patch + 1}"
+
+
+def _update_versions(version: str) -> None:
+    """Write `version` to pyproject.toml and the package __init__ module.
+
+    'why': guarantee distribution metadata matches the Python package
+    """
+
+    _replace_version(_PYPROJECT_PATH, _VERSION_PATTERN, f'version = "{version}"')
+    _replace_version(_PACKAGE_INIT_PATH, _INIT_VERSION_PATTERN, f'__version__ = "{version}"')
+
+
+def _replace_version(path: Path, pattern: re.Pattern[str], replacement: str) -> None:
+    """Swap the first version match in `path` with `replacement`.
+
+    'why': avoid manual editing and keep formatting stable
+    """
+
+    text = path.read_text(encoding="utf-8")
+    updated, count = pattern.subn(replacement, text, count=1)
+    if count != 1:
+        raise RuntimeError(f"Failed to update version in {path}")
+    _ = path.write_text(updated, encoding="utf-8")
+
+
+def _build_distributions() -> list[Path]:
+    """Build wheel and sdist artifacts and return their paths.
+
+    'why': provide a clean slate before handing artifacts to verifiers
+    """
+
+    if _DIST_PATH.exists():
+        shutil.rmtree(_DIST_PATH)
+    _run_command_or_raise(("uv", "build"))
+    return sorted(_DIST_PATH.glob("*"))
+
+
+def _verify_artifacts(artifacts: Sequence[Path]) -> None:
+    """Run metadata checks and a local install smoke test for `artifacts`.
+
+    'why': catch packaging issues before publishing to a remote index
+    """
+
+    dist_files = [
+        path
+        for path in artifacts
+        if path.suffix == ".whl" or tuple(path.suffixes[-2:]) == (".tar", ".gz")
+    ]
+    if not dist_files:
+        raise RuntimeError("No distribution artifacts produced; run `uv build` first")
+    _run_command_or_raise(("uv", "run", "twine", "check", *[str(path) for path in dist_files]))
+    _smoke_test_artifacts(dist_files)
+
+
+def _smoke_test_artifacts(artifacts: Sequence[Path]) -> None:
+    """Install the wheel into a temp venv and import the package.
+
+    'why': validate that the built wheel installs and exposes metadata
+    """
+
+    wheel = next((path for path in artifacts if path.suffix == ".whl"), None)
+    if wheel is None:
+        raise RuntimeError("Wheel artifact missing; expected *.whl after build")
+    with tempfile.TemporaryDirectory() as tmp_dir:
+        env_path = Path(tmp_dir) / "venv"
+        _create_virtualenv(env_path)
+        python_path = _resolve_python(env_path)
+        if not python_path.exists():
+            raise RuntimeError(f"Smoke test interpreter missing: {python_path}")
+        _LOGGER.info("smoke test interpreter → %s", python_path)
+        _run_command_or_raise((str(python_path), "-m", "pip", "install", str(wheel)))
+        _run_command_or_raise((str(python_path), "-c", "import netrias_client as pkg; print(pkg.__version__)"))
+
+
+def _create_virtualenv(target: Path) -> None:
+    """Create a fresh virtual environment at `target` with pip installed.
+
+    'why': isolate smoke tests from the developer environment
+    """
+
+    _run_command_or_raise(("uv", "venv", str(target), "--seed"))
+
+
+def _resolve_python(env_path: Path) -> Path:
+    """Locate the Python executable underneath `env_path`.
+
+    'why': handle platform differences without duplicating logic
+    """
+
+    bin_dir = env_path / ("Scripts" if sys.platform == "win32" else "bin")
+    candidates = ("python", "python3", "python.exe")
+    for candidate in candidates:
+        python_path = bin_dir / candidate
+        if python_path.exists():
+            return python_path
+    raise RuntimeError(f"Python executable not found under {bin_dir}")
+
+
+def _publish_artifacts(repository: str) -> None:
+    """Publish artifacts to the requested repository via `uv publish`.
+
+    'why': keep credential handling opinionated yet minimal
+    """
+
+    if repository not in _REPOSITORY_CONFIG:
+        raise RuntimeError(f"Unsupported repository '{repository}'")
+    env_var, publish_url = _REPOSITORY_CONFIG[repository]
+    token = os.environ.get(env_var)
+    if not token:
+        raise RuntimeError(f"Set {env_var} before publishing to {repository}")
+    command: list[str] = ["uv", "publish", "--username", "__token__", "--password", token]
+    display: list[str] = ["uv", "publish", "--username", "__token__", "--password", "******"]
+    if publish_url:
+        command.extend(["--publish-url", publish_url])
+        display.extend(["--publish-url", publish_url])
+    _run_command_or_raise(tuple(command), display_command=tuple(display))

netrias_client-0.1.0.dist-info/METADATA

@@ -0,0 +1,178 @@
+Metadata-Version: 2.4
+Name: netrias_client
+Version: 0.1.0
+Summary: Python client for the Netrias harmonization API
+Project-URL: Homepage, https://github.com/netrias/netrias_client
+Project-URL: Repository, https://github.com/netrias/netrias_client
+Project-URL: Documentation, https://github.com/netrias/netrias_client#readme
+Author-email: Chris Harman <charman@netrias.com>
+License: MIT License
+        
+        Copyright (c) 2025 Netrias
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: api,cde,client,harmonization,netrias
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: boto3
+Requires-Dist: httpx
+Provides-Extra: dev
+Requires-Dist: basedpyright; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: python-dotenv>=1.0; extra == 'dev'
+Requires-Dist: ruff>=0.5.0; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Requires-Dist: ty; extra == 'dev'
+Requires-Dist: typing-extensions; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Netrias Client
+
+"""Explain how to install and exercise the Netrias harmonization client."""
+
+## Install with `uv`
+- Install `uv` once (or update): `curl -LsSf https://astral.sh/uv/install.sh | sh`
+- Sync dependencies for a project that consumes the client:
+  ```bash
+  uv add netrias_client
+  uv add python-dotenv  # optional helper for loading .env files
+  ```
+- Prefer `uv run <command>` for executing scripts so the managed environment is reused automatically.
+
+### Alternative: `pip`
+```bash
+python -m pip install netrias_client
+python -m pip install python-dotenv  # optional
+```
+
+## Quickstart Script
+Reference script (save as `main.py`) showing a full harmonization round-trip:
+
+```python
+#!/usr/bin/env -S uv run python
+# /// script
+# requires-python = ">=3.13"
+# dependencies = ["netrias_client", "python-dotenv"]
+# ///
+
+"""Exercise the packaged Netrias client against the live APIs."""
+
+import asyncio
+import os
+from pathlib import Path
+from typing import Final
+
+from dotenv import load_dotenv
+from netrias_client import NetriasClient, __version__ as CLIENT_VERSION
+
+load_dotenv(override=True)
+
+CSV_PATH: Final[Path] = Path("data/primary_diagnosis_1.csv")
+
+
+async def main() -> None:
+    client = NetriasClient()
+    client.configure(api_key=_resolve_api_key())
+
+    manifest = client.discover_cde_mapping(
+        source_csv=CSV_PATH,
+        target_schema="ccdi",
+    )
+
+    result = await client.harmonize_async(
+        source_path=CSV_PATH,
+        manifest=manifest,
+    )
+
+    print(f"netrias_client version: {CLIENT_VERSION}")
+    print(f"Harmonize status: {result.status}")
+    print(f"Harmonized file: {result.file_path}")
+
+
+def _resolve_api_key() -> str:
+    api_key = os.getenv("NETRIAS_API_KEY")
+    if api_key:
+        return api_key
+    msg = "Set NETRIAS_API_KEY in your environment or .env file"
+    raise RuntimeError(msg)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### Steps
+1. Install or update `uv` (see above).
+2. Export `NETRIAS_API_KEY` (or add it to a local `.env`).
+3. Adjust `CSV_PATH` to point at the source CSV you want to harmonize.
+4. Run `uv run python main.py`.
+
+## `configure()` Options
+`NetriasClient.configure(...)` accepts additional tuning knobs. You can mix and match the ones you need:
+
+| Parameter | Type | Purpose |
+| --- | --- | --- |
+| `api_key` | `str` | **Required.** Bearer token for authenticating with the Netrias services. |
+| `timeout` | `float | None` | Override the default 6-hour timeout for long-running harmonization jobs. |
+| `log_level` | `LogLevel | str | None` | Control verbosity (`INFO` by default). Accepts enum members or string names. |
+| `confidence_threshold` | `float | None` | Minimum score (0–1) for keeping discovery recommendations; lower it to capture more tentative matches. |
+| `discovery_use_gateway_bypass` | `bool | None` | Toggle the temporary AWS Lambda bypass path for discovery (defaults to `True`). Set to `False` once API Gateway limits are sufficient. |
+| `log_directory` | `Path | str | None` | Directory for per-client log files. When omitted, logs stay on stdout. |
+
+Configure only the options you need; unspecified values fall back to sensible defaults.
+
+## Usage Notes
+- `discover_cde_mapping(...)` samples CSV values and returns a manifest-ready payload; use the async variant if you’re already in an event loop.
+- Call `harmonize(...)` (sync) or `harmonize_async(...)` (async) with the manifest to download a harmonized CSV. The result object reports status, description, and the output path.
+- The package exposes `__version__` so callers can assert the installed release.
+- Optional extras (`netrias_client[aws]`) add boto3 helpers for the temporary gateway bypass.
+
+## Data Model Store (Validation)
+Query reference data for validation use cases:
+
+```python
+from netrias_client import NetriasClient
+
+client = NetriasClient()
+client.configure(api_key="...")
+
+# List available data models
+models = client.list_data_models()
+
+# List CDEs for a model version
+cdes = client.list_cdes("ccdi", "v1")
+
+# Validate a value against permissible values
+is_valid = client.validate_value("Male", "ccdi", "v1", "sex_at_birth")
+
+# Or get the full PV set for repeated lookups
+pv_set = client.get_pv_set("ccdi", "v1", "sex_at_birth")
+assert "Male" in pv_set
+```
+
+All methods have async variants (`list_data_models_async`, `validate_value_async`, etc.).