netrias_client 0.0.1__py3-none-any.whl

netrias_client/__init__.py

@@ -0,0 +1,9 @@
+"""Expose the Netrias client facade and package metadata."""
+
+from __future__ import annotations
+
+from ._client import NetriasClient
+
+__all__ = ["NetriasClient", "__version__"]
+
+__version__ = "0.0.1"

netrias_client/_adapter.py

@@ -0,0 +1,288 @@
+"""Translate discovery results into manifest-friendly mappings.
+
+'why': bridge API recommendations to harmonization manifests while respecting confidence bounds
+"""
+from __future__ import annotations
+
+import json
+import logging
+from collections.abc import Iterable, Mapping
+from pathlib import Path
+from typing import Final, cast
+
+from ._models import MappingDiscoveryResult, MappingRecommendationOption, MappingSuggestion
+
+
+
+def build_column_mapping_payload(
+    result: MappingDiscoveryResult,
+    threshold: float,
+    logger: logging.Logger | None = None,
+) -> dict[str, dict[str, dict[str, object]]]:
+    """Convert discovery output into the manifest structure expected by harmonization."""
+
+    active_logger = logger or logging.getLogger("netrias_client")
+    strongest = strongest_targets(result, threshold=threshold, logger=active_logger)
+    return {"column_mappings": _column_entries(strongest, active_logger)}
+
+
+_COLUMN_METADATA: Final[dict[str, dict[str, object]]] = {
+    # "study_name": {"route": "api:passthrough", "targetField": "study_name"},
+    # "number_of_participants": {"route": "api:passthrough", "targetField": "number_of_participants"},
+    # "number_of_samples": {"route": "api:passthrough", "targetField": "number_of_samples"},
+    # "study_data_types": {
+    #     "route": "api:passthrough",
+    #     "targetField": "study_data_types",
+    #     "cdeId": 12_571_096,
+    #     "cde_id": 12_571_096,
+    # },
+    # "participant_id": {"route": "api:passthrough", "targetField": "participant_id"},
+    # "sample_id": {"route": "api:passthrough", "targetField": "sample_id"},
+    # "file_name": {"route": "api:passthrough", "targetField": "file_name"},
+    "primary_diagnosis": {
+        "route": "sagemaker:primary",
+        "targetField": "primary_diagnosis",
+        "cdeId": -200,
+        "cde_id": -200,
+    },
+    "therapeutic_agents": {
+        "route": "sagemaker:therapeutic_agents",
+        "targetField": "therapeutic_agents",
+        "cdeId": -203,
+        "cde_id": -203,
+    },
+    "morphology": {
+        "route": "sagemaker:morphology",
+        "targetField": "morphology",
+        "cdeId": -201,
+        "cde_id": -201,
+    },
+    # "tissue_or_organ_of_origin": {
+    #     "route": "sagemaker:tissue_origin",
+    #     "targetField": "tissue_or_organ_of_origin",
+    #     "cdeId": -204,
+    #     "cde_id": -204,
+    # },
+    # "site_of_resection_or_biopsy": {
+    #     "route": "sagemaker:sample_anatomic_site",
+    #     "targetField": "site_of_resection_or_biopsy",
+    #     "cdeId": -202,
+    #     "cde_id": -202,
+    # },
+}
+
+
+def strongest_targets(
+    result: MappingDiscoveryResult,
+    threshold: float,
+    logger: logging.Logger,
+) -> dict[str, str]:
+    """Return the highest-confidence target per column, filtered by threshold."""
+
+    if result.suggestions:
+        selected = _from_suggestions(result.suggestions, threshold)
+    else:
+        selected = _from_raw_payload(result.raw, threshold)
+
+    if selected:
+        logger.info("adapter strongest targets: %s", selected)
+    else:
+        logger.warning("adapter strongest targets empty after filtering")
+    return selected
+
+
+def _column_entries(
+    strongest: Mapping[str, str],
+    logger: logging.Logger,
+) -> dict[str, dict[str, object]]:
+    entries: dict[str, dict[str, object]] = {}
+    missing_cde: dict[str, str] = {}
+    for source, target in strongest.items():
+        entry = _initial_entry(source, target)
+        if _needs_cde(entry):
+            missing_cde[source] = target
+        entries[source] = entry
+
+    _apply_metadata_defaults(entries)
+
+    if missing_cde:
+        logger.info("adapter unresolved targets (no CDE id mapping): %s", missing_cde)
+    return entries
+
+
+def _initial_entry(source: str, target: str) -> dict[str, object]:
+    metadata = _COLUMN_METADATA.get(source)
+    if metadata is None:
+        return {"targetField": target}
+    # Preserve configured targetField when metadata defines it.
+    return dict(metadata)
+
+
+def _needs_cde(entry: Mapping[str, object]) -> bool:
+    return "cdeId" not in entry
+
+
+def _apply_metadata_defaults(entries: dict[str, dict[str, object]]) -> None:
+    for source, metadata in _COLUMN_METADATA.items():
+        if source not in entries:
+            entries[source] = dict(metadata)
+
+
+def _from_suggestions(
+    suggestions: Iterable[MappingSuggestion], threshold: float
+) -> dict[str, str]:
+    strongest: dict[str, str] = {}
+    for suggestion in suggestions:
+        option = _top_option(suggestion.options, threshold)
+        if option is None or option.target is None:
+            continue
+        strongest[suggestion.source_column] = option.target
+    return strongest
+
+
+def _from_raw_payload(payload: Mapping[str, object], threshold: float) -> dict[str, str]:
+    strongest: dict[str, str] = {}
+    for column, value in payload.items():
+        options = _coerce_options(value)
+        option = _top_option(options, threshold)
+        if option is None or option.target is None:
+            continue
+        strongest[column] = option.target
+    return strongest
+
+
+def _coerce_options(value: object) -> tuple[MappingRecommendationOption, ...]:
+    if not isinstance(value, list):
+        return ()
+    return tuple(_option_iterator(cast(list[object], value)))
+
+
+def _option_iterator(items: list[object]) -> Iterable[MappingRecommendationOption]:
+    for item in items:
+        if not isinstance(item, Mapping):
+            continue
+        option = _option_from_mapping(cast(Mapping[str, object], item))
+        if option is not None:
+            yield option
+
+
+def _option_from_mapping(item: Mapping[str, object]) -> MappingRecommendationOption | None:
+    target = item.get("target")
+    if not isinstance(target, str):
+        return None
+    similarity = item.get("similarity")
+    score: float | None = None
+    if isinstance(similarity, (float, int)):
+        score = float(similarity)
+    return MappingRecommendationOption(target=target, confidence=score, raw=item)
+
+
+def _top_option(
+    options: Iterable[MappingRecommendationOption], threshold: float
+) -> MappingRecommendationOption | None:
+    eligible = [opt for opt in options if _meets_threshold(opt, threshold)]
+    if not eligible:
+        return None
+    return max(eligible, key=lambda opt: opt.confidence or float("-inf"))
+
+
+def _meets_threshold(option: MappingRecommendationOption, threshold: float) -> bool:
+    score = option.confidence
+    if score is None:
+        return False
+    return score >= threshold
+
+def normalize_manifest_mapping(
+    manifest: Path | Mapping[str, object] | None,
+) -> dict[str, int]:
+    """Normalize manifest column→CDE entries for harmonization payloads."""
+
+    if manifest is None:
+        return {}
+    raw = _load_manifest_raw(manifest)
+    mapping = _mapping_dict(raw)
+    normalized: dict[str, int] = {}
+    for field, value in mapping.items():
+        _apply_cde_entry(normalized, field, value)
+    return normalized
+
+
+def _load_manifest_raw(manifest: Path | Mapping[str, object]) -> Mapping[str, object]:
+    if isinstance(manifest, Path):
+        content = manifest.read_text(encoding="utf-8")
+        try:
+            return cast(Mapping[str, object], json.loads(content))
+        except json.JSONDecodeError as exc:
+            raise ValueError(f"manifest must be valid JSON: {exc}") from exc
+    return manifest
+
+
+def _mapping_dict(raw: Mapping[str, object]) -> dict[str, object]:
+    mapping = _dict_if_str_mapping(raw)
+    if mapping is None:
+        return {}
+    candidate = _dict_if_str_mapping(mapping.get("column_mappings"))
+    return candidate if candidate is not None else mapping
+
+
+def _dict_if_str_mapping(value: object) -> dict[str, object] | None:
+    if isinstance(value, Mapping):
+        typed = cast(Mapping[str, object], value)
+        return dict(typed)
+    return None
+
+
+def _apply_cde_entry(destination: dict[str, int], field: object, value: object) -> None:
+    name = _clean_field(field)
+    cde_id = _coerce_cde_id(value)
+    if name is None or cde_id is None:
+        return
+    destination[name] = cde_id
+
+
+def _clean_field(field: object) -> str | None:
+    if not isinstance(field, str):
+        return None
+    name = field.strip()
+    return name or None
+
+
+def _coerce_cde_id(value: object) -> int | None:
+    candidate = _cde_candidate(value)
+    if candidate is None:
+        return None
+    return _int_from_candidate(candidate)
+
+
+def _cde_candidate(value: object) -> object | None:
+    mapping = _dict_if_str_mapping(value)
+    if mapping is not None:
+        return mapping.get("cdeId") or mapping.get("cde_id")
+    return value
+
+
+def _int_from_candidate(candidate: object) -> int | None:
+    if isinstance(candidate, bool):
+        return int(candidate)
+    if isinstance(candidate, (int, float)):
+        return _int_from_number(candidate)
+    if isinstance(candidate, str):
+        return _int_from_string(candidate)
+    return None
+
+
+def _int_from_number(value: int | float) -> int | None:
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _int_from_string(value: str) -> int | None:
+    stripped = value.strip()
+    if not stripped:
+        return None
+    try:
+        return int(stripped)
+    except ValueError:
+        return None

netrias_client/_client.py

@@ -0,0 +1,251 @@
+"""Coordinate stateful access to discovery and harmonization APIs.
+
+'why': provide a single, inspectable entry point that captures configuration once
+and exposes typed discovery and harmonization helpers (sync/async) for consumers
+"""
+from __future__ import annotations
+
+import logging
+import threading
+from collections.abc import Mapping, Sequence
+from dataclasses import replace
+from pathlib import Path
+from uuid import uuid4
+
+from ._core import harmonize as _harmonize
+from ._core import harmonize_async as _harmonize_async
+from ._discovery import (
+    discover_cde_mapping as _discover_cde_mapping,
+    discover_mapping as _discover_mapping,
+    discover_mapping_async as _discover_mapping_async,
+    discover_mapping_from_csv_async as _discover_mapping_from_csv_async,
+)
+from ._config import build_settings
+from ._errors import ClientConfigurationError
+from ._logging import configure_logger
+from ._models import HarmonizationResult, LogLevel, Settings
+
+
+ManifestPayload = dict[str, dict[str, dict[str, object]]]
+
+
+class NetriasClient:
+    """Expose discovery and harmonization workflows behind instance state.
+
+    A `NetriasClient` manages configuration snapshots (API key, URLs, thresholds,
+    bypass preferences) and threads them through every outbound call. Consumers
+    typically instantiate a client, call :meth:`configure`, and then interact via
+    the discovery/harmonization methods below.
+    """
+
+    def __init__(self) -> None:
+        """Initialise an empty client awaiting configuration."""
+
+        self._lock: threading.Lock = threading.Lock()
+        self._settings: Settings | None = None
+        self._logger_name: str = f"netrias_client.{uuid4().hex}"
+        self._logger: logging.Logger | None = None
+
+    def configure(
+        self,
+        api_key: str,
+        timeout: float | None = None,
+        log_level: LogLevel | str | None = None,
+        confidence_threshold: float | None = None,
+        discovery_use_gateway_bypass: bool | None = None,
+        log_directory: Path | str | None = None,
+    ) -> None:
+        """Validate inputs and persist a new immutable settings snapshot.
+
+        Parameters
+        ----------
+        api_key:
+            Netrias API bearer token used for authentication.
+        timeout:
+            Overall request timeout in seconds (defaults to six hours).
+        log_level:
+            Desired logging verbosity as a :class:`~netrias_client._models.LogLevel`
+            (string aliases are also accepted for convenience).
+        confidence_threshold:
+            Minimum confidence score required for discovery recommendations.
+        discovery_use_gateway_bypass:
+            When ``True`` (default) calls the temporary Lambda bypass instead of
+            API Gateway.
+        log_directory:
+            Optional directory where this client's log files should be written.
+            When omitted, logging remains stream-only.
+
+        Calling this method multiple times replaces the active snapshot and
+        reconfigures the package logger.
+        """
+
+        settings = build_settings(
+            api_key=api_key,
+            timeout=timeout,
+            log_level=log_level,
+            confidence_threshold=confidence_threshold,
+            discovery_use_gateway_bypass=discovery_use_gateway_bypass,
+            log_directory=log_directory,
+        )
+        logger = configure_logger(
+            self._logger_name,
+            settings.log_level,
+            settings.log_directory,
+        )
+        with self._lock:
+            self._settings = settings
+            self._logger = logger
+
+    @property
+    def settings(self) -> Settings:
+        """Return a defensive copy of the current settings.
+
+        'why': aid observability without exposing internal state for mutation
+        """
+
+        return self._snapshot_settings()
+
+    def discover_mapping(
+        self,
+        target_schema: str,
+        column_samples: Mapping[str, Sequence[object]],
+    ) -> ManifestPayload:
+        """Perform synchronous mapping discovery for the provided schema."""
+
+        settings = self._snapshot_settings()
+
+        return _discover_mapping(
+            settings=settings,
+            target_schema=target_schema,
+            column_samples=column_samples,
+            logger=self._require_logger(),
+        )
+
+    async def discover_mapping_async(
+        self,
+        target_schema: str,
+        column_samples: Mapping[str, Sequence[object]],
+    ) -> ManifestPayload:
+        """Async variant of :meth:`discover_mapping` with identical semantics."""
+
+        settings = self._snapshot_settings()
+
+        return await _discover_mapping_async(
+            settings=settings,
+            target_schema=target_schema,
+            column_samples=column_samples,
+            logger=self._require_logger(),
+        )
+
+    def discover_mapping_from_csv(
+        self,
+        source_csv: Path,
+        target_schema: str,
+        sample_limit: int = 25,
+    ) -> ManifestPayload:
+        """Derive column samples from a CSV file then perform mapping discovery."""
+
+        settings = self._snapshot_settings()
+
+        return _discover_cde_mapping(
+            settings=settings,
+            source_csv=source_csv,
+            target_schema=target_schema,
+            sample_limit=sample_limit,
+            logger=self._require_logger(),
+        )
+
+    def discover_cde_mapping(
+        self,
+        source_csv: Path,
+        target_schema: str,
+        sample_limit: int = 25,
+    ) -> ManifestPayload:
+        """Compatibility alias for :meth:`discover_mapping_from_csv`."""
+
+        return self.discover_mapping_from_csv(
+            source_csv=source_csv,
+            target_schema=target_schema,
+            sample_limit=sample_limit,
+        )
+
+    async def discover_mapping_from_csv_async(
+        self,
+        source_csv: Path,
+        target_schema: str,
+        sample_limit: int = 25,
+    ) -> ManifestPayload:
+        """Async variant of :meth:`discover_mapping_from_csv`."""
+
+        settings = self._snapshot_settings()
+
+        return await _discover_mapping_from_csv_async(
+            settings=settings,
+            source_csv=source_csv,
+            target_schema=target_schema,
+            sample_limit=sample_limit,
+            logger=self._require_logger(),
+        )
+
+    def harmonize(
+        self,
+        source_path: Path,
+        manifest: Path | Mapping[str, object],
+        output_path: Path | None = None,
+        manifest_output_path: Path | None = None,
+    ) -> HarmonizationResult:
+        """Execute the harmonization workflow synchronously and block.
+
+        The method accepts either a manifest mapping or a JSON file path and
+        writes the harmonized CSV to the resolved output location (which may be
+        auto-versioned). A :class:`HarmonizationResult` is always returned even on
+        failure, allowing callers to inspect status and description.
+        """
+
+        settings = self._snapshot_settings()
+
+        return _harmonize(
+            settings=settings,
+            source_path=source_path,
+            manifest=manifest,
+            output_path=output_path,
+            manifest_output_path=manifest_output_path,
+            logger=self._require_logger(),
+        )
+
+    async def harmonize_async(
+        self,
+        source_path: Path,
+        manifest: Path | Mapping[str, object],
+        output_path: Path | None = None,
+        manifest_output_path: Path | None = None,
+    ) -> HarmonizationResult:
+        """Async counterpart to :meth:`harmonize` with identical semantics."""
+
+        settings = self._snapshot_settings()
+
+        return await _harmonize_async(
+            settings=settings,
+            source_path=source_path,
+            manifest=manifest,
+            output_path=output_path,
+            manifest_output_path=manifest_output_path,
+            logger=self._require_logger(),
+        )
+
+    def _snapshot_settings(self) -> Settings:
+        """Return a copy of the current settings or raise if not configured."""
+
+        with self._lock:
+            if self._settings is None:
+                raise ClientConfigurationError(
+                    "client not configured; call configure(api_key=...) before use"
+                )
+            return replace(self._settings)
+
+    def _require_logger(self) -> logging.Logger:
+        if self._logger is None:
+            raise ClientConfigurationError(
+                "client not configured; call configure(api_key=...) before use"
+            )
+        return self._logger

netrias_client/_config.py

@@ -0,0 +1,95 @@
+"""Manage runtime client configuration.
+
+'why': centralize settings creation and validation for NetriasClient
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from ._errors import ClientConfigurationError
+from ._models import LogLevel, Settings
+
+
+DISCOVERY_BASE_URL = "https://api.netriasbdf.cloud"
+HARMONIZATION_BASE_URL = "https://tbdxz7nffi.execute-api.us-east-2.amazonaws.com"
+# TODO: remove once API Gateway latency constraints are resolved.
+BYPASS_FUNCTION = "cde-recommendation"
+BYPASS_ALIAS = "prod"
+BYPASS_REGION = "us-east-2"
+
+
+def build_settings(
+    api_key: str,
+    timeout: float | None = None,
+    log_level: LogLevel | str | None = None,
+    confidence_threshold: float | None = None,
+    discovery_use_gateway_bypass: bool | None = None,
+    log_directory: Path | str | None = None,
+) -> Settings:
+    """Return a validated Settings snapshot for the provided configuration."""
+
+    key = (api_key or "").strip()
+    if not key:
+        raise ClientConfigurationError("api_key must be a non-empty string; call configure(api_key=...) before use")
+
+    level = _normalized_level(log_level)
+    timeout_value = _validated_timeout(timeout)
+    threshold = _validated_confidence_threshold(confidence_threshold)
+    bypass_enabled = _normalized_bool(discovery_use_gateway_bypass, default=True)
+    directory = _validated_log_directory(log_directory)
+
+    return Settings(
+        api_key=key,
+        discovery_url=DISCOVERY_BASE_URL,
+        harmonization_url=HARMONIZATION_BASE_URL,
+        timeout=timeout_value,
+        log_level=level,
+        confidence_threshold=threshold,
+        discovery_use_gateway_bypass=bypass_enabled,
+        log_directory=directory,
+    )
+
+
+def _normalized_level(level: LogLevel | str | None) -> LogLevel:
+    if level is None:
+        return LogLevel.INFO
+    if isinstance(level, LogLevel):
+        return level
+    upper = level.upper()
+    try:
+        return LogLevel[upper]
+    except KeyError as exc:
+        raise ClientConfigurationError(f"unsupported log_level: {level}") from exc
+
+
+def _validated_timeout(timeout: float | None) -> float:
+    if timeout is None:
+        return 21600.0  # default to 6 hours to accommodate long-running jobs
+    if timeout <= 0:
+        raise ClientConfigurationError("timeout must be positive when provided")
+    return float(timeout)
+
+
+def _validated_confidence_threshold(value: float | None) -> float:
+    if value is None:
+        return 0.8
+    if not (0.0 <= value <= 1.0):
+        raise ClientConfigurationError("confidence_threshold must be between 0.0 and 1.0")
+    return float(value)
+
+
+def _normalized_bool(value: bool | None, default: bool = False) -> bool:
+    if value is None:
+        return default
+    return bool(value)
+
+
+def _validated_log_directory(value: Path | str | None) -> Path | None:
+    if value is None:
+        return None
+    directory = Path(value)
+    try:
+        directory.mkdir(parents=True, exist_ok=True)
+    except OSError as exc:
+        raise ClientConfigurationError(f"unable to create log directory {directory}: {exc}") from exc
+    return directory