ddharmon 0.1.0__py3-none-any.whl

ddharmon/__init__.py

@@ -0,0 +1,54 @@
+"""ddharmon — Python client for the BioMapper2 API.
+
+Quick start::
+
+    from ddharmon import map_entity, map_entities, BioMapperClient
+
+    # Single lookup (synchronous)
+    result = map_entity("L-Histidine")
+    print(result.primary_curie)      # RM:0129894
+    print(result.confidence_tier)    # high
+
+    # Batch (synchronous, with progress bar)
+    results = map_entities(
+        [{"name": "L-Histidine"}, {"name": "Glucose"}],
+        progress=True,
+    )
+
+    # Async (in an async context)
+    async with BioMapperClient() as client:
+        result = await client.map_entity("L-Histidine")
+"""
+
+from ddharmon.client import BioMapperClient
+from ddharmon.exceptions import (
+    BioMapperAuthError,
+    BioMapperConfigError,
+    BioMapperError,
+    BioMapperRateLimitError,
+    BioMapperServerError,
+    BioMapperTimeoutError,
+)
+from ddharmon.mapper import map_entities, map_entity, summarize
+from ddharmon.models import MappingResult, MappingSummary
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Client
+    "BioMapperClient",
+    # Sync helpers
+    "map_entity",
+    "map_entities",
+    "summarize",
+    # Models
+    "MappingResult",
+    "MappingSummary",
+    # Exceptions
+    "BioMapperError",
+    "BioMapperAuthError",
+    "BioMapperConfigError",
+    "BioMapperRateLimitError",
+    "BioMapperServerError",
+    "BioMapperTimeoutError",
+]

ddharmon/client.py

@@ -0,0 +1,264 @@
+"""Async HTTP client for the BioMapper2 API."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+from typing import Any
+
+import httpx
+
+from ddharmon.exceptions import (
+    BioMapperAuthError,
+    BioMapperConfigError,
+    BioMapperRateLimitError,
+    BioMapperServerError,
+    BioMapperTimeoutError,
+)
+from ddharmon.models import MapEntityRequest, MappingResult
+
+DEFAULT_BASE_URL = "https://biomapper.expertintheloop.io/api/v1"
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_RATE_LIMIT_DELAY = 0.3  # seconds between calls in batch mode
+
+
+class BioMapperClient:
+    """Async client for the BioMapper2 API.
+
+    Handles authentication, request serialization, error mapping, and optional
+    rate-limited batch processing.
+
+    Usage (minimal)::
+
+        async with BioMapperClient() as client:
+            result = await client.map_entity("L-Histidine")
+            print(result.primary_curie)   # "RM:0129894"
+
+    Usage (with explicit key and hint)::
+
+        async with BioMapperClient(api_key="sk-...") as client:
+            result = await client.map_entity(
+                name="4,6-DIOXOHEPTANOIC ACID",
+                identifiers={"HMDB": "HMDB03349"},
+            )
+
+    Args:
+        api_key:    BioMapper API key.  Defaults to ``BIOMAPPER_API_KEY`` env var.
+        base_url:   API root URL.  Override for staging/local instances.
+        timeout:    Per-request timeout in seconds.
+        httpx_kwargs: Extra kwargs forwarded to :class:`httpx.AsyncClient`.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        **httpx_kwargs: Any,
+    ) -> None:
+        resolved_key = api_key or os.getenv("BIOMAPPER_API_KEY")
+        if not resolved_key:
+            raise BioMapperConfigError(
+                "No API key provided. Pass api_key= or set BIOMAPPER_API_KEY env var."
+            )
+        self._api_key = resolved_key
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._httpx_kwargs = httpx_kwargs
+        self._client: httpx.AsyncClient | None = None
+
+    # ------------------------------------------------------------------
+    # Context manager
+    # ------------------------------------------------------------------
+
+    async def __aenter__(self) -> BioMapperClient:
+        self._client = httpx.AsyncClient(
+            headers={"X-API-Key": self._api_key},
+            timeout=self._timeout,
+            **self._httpx_kwargs,
+        )
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        if self._client is not None:
+            await self._client.aclose()
+            self._client = None
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    @property
+    def _http(self) -> httpx.AsyncClient:
+        if self._client is None:
+            raise RuntimeError(
+                "BioMapperClient must be used as an async context manager. "
+                "Use `async with BioMapperClient() as client:`"
+            )
+        return self._client
+
+    def _raise_for_status(self, response: httpx.Response) -> None:
+        """Map HTTP status codes to typed exceptions."""
+        code = response.status_code
+        if code == 401 or code == 403:
+            raise BioMapperAuthError(
+                f"Authentication failed (HTTP {code}). Check your API key."
+            )
+        if code == 429:
+            retry_after: float | None = None
+            if ra := response.headers.get("Retry-After"):
+                try:
+                    retry_after = float(ra)
+                except ValueError:
+                    pass
+            raise BioMapperRateLimitError(
+                "Rate limit exceeded (HTTP 429).", retry_after=retry_after
+            )
+        if code >= 500:
+            raise BioMapperServerError(
+                f"Server error (HTTP {code}): {response.text[:200]}",
+                status_code=code,
+            )
+        response.raise_for_status()
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    async def health_check(self) -> dict[str, Any]:
+        """Verify connectivity and API readiness.
+
+        Returns:
+            The parsed health JSON, e.g.
+            ``{"status": "healthy", "version": "0.1.0", "mapper_initialized": True}``.
+
+        Raises:
+            BioMapperAuthError: If the key is rejected.
+            BioMapperServerError: If the service is not healthy.
+        """
+        try:
+            response = await self._http.get(f"{self._base_url}/health")
+        except httpx.TimeoutException as exc:
+            raise BioMapperTimeoutError("Health check timed out") from exc
+        self._raise_for_status(response)
+        return dict(response.json())
+
+    async def map_entity(
+        self,
+        name: str,
+        entity_type: str = "biolink:SmallMolecule",
+        identifiers: dict[str, str] | None = None,
+        annotation_mode: str = "missing",
+    ) -> MappingResult:
+        """Map a single entity name to standardized knowledge-graph identifiers.
+
+        Args:
+            name:            Compound or entity name to resolve.
+            entity_type:     Biolink entity type.  Use ``"biolink:SmallMolecule"``
+                             for metabolites.
+            identifiers:     Optional pre-existing IDs used as resolver hints,
+                             e.g. ``{"HMDB": "HMDB00177"}``.
+            annotation_mode: ``"missing"`` (default), ``"all"``, or ``"none"``.
+
+        Returns:
+            A :class:`~ddharmon.models.MappingResult` with resolved identifiers.
+
+        Raises:
+            BioMapperAuthError: If the API key is rejected.
+            BioMapperRateLimitError: If the API signals throttling.
+            BioMapperServerError: For unrecoverable 5xx errors.
+            BioMapperTimeoutError: If the request times out.
+        """
+        payload = MapEntityRequest(
+            name=name,
+            entity_type=entity_type,
+            identifiers=identifiers or {},
+            options={"annotation_mode": annotation_mode},
+        )
+
+        hmdb_hint: str | None = (identifiers or {}).get("HMDB")
+
+        try:
+            response = await self._http.post(
+                f"{self._base_url}/map/entity",
+                json=payload.model_dump(exclude_none=False),
+            )
+        except httpx.TimeoutException as exc:
+            raise BioMapperTimeoutError(f"Request timed out for '{name}'") from exc
+
+        self._raise_for_status(response)
+        data = dict[str, Any](response.json())
+        return MappingResult.from_api_response(data, query_name=name, hmdb_hint=hmdb_hint)
+
+    async def map_entities(
+        self,
+        records: list[dict[str, Any]],
+        rate_limit_delay: float = DEFAULT_RATE_LIMIT_DELAY,
+        entity_type: str = "biolink:SmallMolecule",
+        annotation_mode: str = "missing",
+        progress: bool = False,
+    ) -> list[MappingResult]:
+        """Map a batch of entity records with rate limiting.
+
+        Each record is a dict with at least a ``"name"`` key, and optionally
+        ``"identifiers"`` (``{"HMDB": "HMDB00177"}``).
+
+        Args:
+            records:           List of ``{"name": str, "identifiers": dict}`` dicts.
+            rate_limit_delay:  Seconds to sleep between API calls.  Default 0.3.
+            entity_type:       Biolink entity type for all records.
+            annotation_mode:   Annotation mode for all records.
+            progress:          Show a tqdm progress bar (requires ``ddharmon[notebook]``).
+
+        Returns:
+            List of :class:`~ddharmon.models.MappingResult`, one per input record,
+            in the same order.  Failed records return a result with ``error`` set
+            rather than raising.
+
+        Example::
+
+            async with BioMapperClient() as client:
+                results = await client.map_entities(
+                    [
+                        {"name": "L-Histidine"},
+                        {"name": "Glucose", "identifiers": {"HMDB": "HMDB00122"}},
+                    ],
+                    progress=True,
+                )
+        """
+        iter_records: Any = records
+
+        if progress:
+            try:
+                from tqdm.auto import tqdm
+
+                iter_records = tqdm(records, desc="Mapping entities")
+            except ImportError:
+                pass  # silently degrade if tqdm not installed
+
+        results: list[MappingResult] = []
+
+        for i, record in enumerate(iter_records):
+            if i > 0:
+                await asyncio.sleep(rate_limit_delay)
+
+            name: str = str(record.get("name", ""))
+            identifiers: dict[str, str] = dict(record.get("identifiers") or {})
+
+            try:
+                result = await self.map_entity(
+                    name=name,
+                    entity_type=entity_type,
+                    identifiers=identifiers or None,
+                    annotation_mode=annotation_mode,
+                )
+            except Exception as exc:  # noqa: BLE001
+                result = MappingResult(
+                    query_name=name,
+                    hmdb_hint=identifiers.get("HMDB"),
+                    error=str(exc),
+                )
+
+            results.append(result)
+
+        return results

ddharmon/exceptions.py

@@ -0,0 +1,39 @@
+"""Typed exception hierarchy for ddharmon."""
+
+from __future__ import annotations
+
+
+class BioMapperError(Exception):
+    """Base exception for all ddharmon errors."""
+
+
+class BioMapperAuthError(BioMapperError):
+    """Raised when the API key is missing or rejected (HTTP 401/403)."""
+
+
+class BioMapperRateLimitError(BioMapperError):
+    """Raised when the API signals rate limiting (HTTP 429).
+
+    Attributes:
+        retry_after: Suggested wait in seconds, if provided by the server.
+    """
+
+    def __init__(self, message: str, retry_after: float | None = None) -> None:
+        super().__init__(message)
+        self.retry_after = retry_after
+
+
+class BioMapperServerError(BioMapperError):
+    """Raised for unrecoverable 5xx responses from the API."""
+
+    def __init__(self, message: str, status_code: int) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class BioMapperTimeoutError(BioMapperError):
+    """Raised when a request exceeds the configured timeout."""
+
+
+class BioMapperConfigError(BioMapperError):
+    """Raised for invalid client configuration (missing API key, bad URL, etc.)."""

ddharmon/extras/__init__.py

@@ -0,0 +1 @@
+"""Optional extras for ddharmon."""

ddharmon/extras/metabolon/__init__.py

@@ -0,0 +1,29 @@
+"""Metabolon-specific utilities for ddharmon.
+
+Provides preprocessing and export helpers for Metabolon metabolomics data.
+Requires ``ddharmon[metabolon]`` (pandas, openpyxl).
+"""
+
+from ddharmon.extras.metabolon.export import (
+    flatten_results,
+    results_to_dataframe,
+    save_results,
+)
+from ddharmon.extras.metabolon.preprocessing import (
+    MetabolonRecord,
+    build_mapping_queue,
+    clean_compound_name,
+    extract_hmdb_id,
+)
+
+__all__ = [
+    # Preprocessing
+    "clean_compound_name",
+    "extract_hmdb_id",
+    "MetabolonRecord",
+    "build_mapping_queue",
+    # Export
+    "flatten_results",
+    "results_to_dataframe",
+    "save_results",
+]

ddharmon/extras/metabolon/export.py

@@ -0,0 +1,107 @@
+"""Export helpers for Metabolon mapping results.
+
+Requires ``ddharmon[metabolon]`` (pandas, openpyxl).
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from ddharmon.models import MappingResult, MappingSummary
+
+
+def flatten_results(results: list[MappingResult]) -> list[dict[str, Any]]:
+    """Convert mapping results to a flat list of dicts suitable for DataFrame / CSV.
+
+    Each dict has the columns::
+
+        query_name, hmdb_hint, resolved, primary_curie, chosen_kg_id,
+        confidence_score, confidence_tier,
+        hmdb_ids, pubchem_ids, chebi_ids, refmet_ids, error
+
+    Args:
+        results: Output of :func:`ddharmon.map_entities` or equivalent.
+
+    Returns:
+        List of flat dicts, one per input result.
+    """
+    flat: list[dict[str, Any]] = []
+
+    for r in results:
+        flat.append(
+            {
+                "query_name": r.query_name,
+                "hmdb_hint": r.hmdb_hint or "",
+                "resolved": r.resolved,
+                "primary_curie": r.primary_curie or "",
+                "chosen_kg_id": r.chosen_kg_id or "",
+                "confidence_score": r.confidence_score if r.confidence_score is not None else "",
+                "confidence_tier": r.confidence_tier,
+                "hmdb_ids": ";".join(r.ids_for("HMDB")),
+                "pubchem_ids": ";".join(
+                    r.ids_for("PUBCHEM.COMPOUND") or r.ids_for("PUBCHEM")
+                ),
+                "chebi_ids": ";".join(r.ids_for("CHEBI")),
+                "refmet_ids": ";".join(r.ids_for("refmet_id")),
+                "error": r.error or "",
+            }
+        )
+
+    return flat
+
+
+def results_to_dataframe(results: list[MappingResult]) -> Any:
+    """Return a pandas DataFrame of flattened mapping results.
+
+    Requires ``ddharmon[metabolon]`` (pandas).
+
+    Args:
+        results: Mapping results from any ddharmon mapping function.
+
+    Returns:
+        ``pandas.DataFrame`` with one row per result.
+    """
+    try:
+        import pandas as pd
+    except ImportError as exc:
+        raise ImportError(
+            "pandas is required for results_to_dataframe. "
+            "Install with: pip install 'ddharmon[metabolon]'"
+        ) from exc
+
+    return pd.DataFrame(flatten_results(results))
+
+
+def save_results(
+    results: list[MappingResult],
+    summary: MappingSummary | None = None,
+    json_path: str | Path | None = None,
+    tsv_path: str | Path | None = None,
+) -> None:
+    """Save mapping results to JSON and / or TSV.
+
+    Args:
+        results:   Mapping results to export.
+        summary:   Optional :class:`~ddharmon.models.MappingSummary` to embed
+                   in the JSON output.
+        json_path: If provided, write full detail (summary + raw results) here.
+        tsv_path:  If provided, write flat TSV suitable for spreadsheet review.
+
+    Raises:
+        ImportError: If tsv_path is given but pandas is not installed.
+    """
+    if json_path is not None:
+        out: dict[str, Any] = {
+            "summary": summary.model_dump() if summary else None,
+            "mappings": [r.model_dump(exclude={"raw_response"}) for r in results],
+        }
+        Path(json_path).parent.mkdir(parents=True, exist_ok=True)
+        with open(json_path, "w") as f:
+            json.dump(out, f, indent=2, default=str)
+
+    if tsv_path is not None:
+        df = results_to_dataframe(results)
+        Path(tsv_path).parent.mkdir(parents=True, exist_ok=True)
+        df.to_csv(tsv_path, sep="\t", index=False)