guidelinely 1.0.3__py3-none-any.whl

guidelinely/__init__.py

@@ -0,0 +1,60 @@
+"""Guidelinely - Python client for the Guidelinely Environmental Guidelines API.
+
+Provides programmatic access to environmental guideline calculations and searches
+for chemical parameters in various media (water, soil, sediment).
+"""
+
+from guidelinely.auth import get_api_key
+from guidelinely.client import (
+    calculate_batch,
+    calculate_guidelines,
+    get_stats,
+    health_check,
+    list_media,
+    list_parameters,
+    list_sources,
+    readiness_check,
+    search_parameters,
+)
+from guidelinely.exceptions import (
+    GuidelinelyAPIError,
+    GuidelinelyError,
+    GuidelinelyTimeoutError,
+)
+from guidelinely.models import (
+    CalculationResponse,
+    GuidelineResponse,
+    SourceDocument,
+    SourceResponse,
+    StatsResponse,
+)
+
+try:
+    from guidelinely._version import __version__
+except ImportError:
+    __version__ = "0.0.0.dev0"  # Fallback for editable installs without build
+
+__all__ = [
+    # Client functions
+    "health_check",
+    "readiness_check",
+    "list_parameters",
+    "search_parameters",
+    "list_media",
+    "list_sources",
+    "get_stats",
+    "calculate_guidelines",
+    "calculate_batch",
+    # Models
+    "GuidelineResponse",
+    "CalculationResponse",
+    "SourceResponse",
+    "SourceDocument",
+    "StatsResponse",
+    # Exceptions
+    "GuidelinelyError",
+    "GuidelinelyAPIError",
+    "GuidelinelyTimeoutError",
+    # Auth
+    "get_api_key",
+]

guidelinely/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '1.0.3'
+__version_tuple__ = version_tuple = (1, 0, 3)
+
+__commit_id__ = commit_id = None

guidelinely/auth.py

@@ -0,0 +1,29 @@
+"""Authentication helpers for the Guidelinely API.
+
+The main API endpoints (metadata) do not require authentication.
+Calculation endpoints optionally accept an API key.
+"""
+
+import os
+from typing import Optional
+
+__all__ = ["get_api_key"]
+
+
+def get_api_key(api_key: Optional[str] = None) -> Optional[str]:
+    """Get API key from argument or GUIDELINELY_API_KEY environment variable.
+
+    Args:
+        api_key: Optional API key string. If not provided, will check environment.
+
+    Returns:
+        API key string or None if not available.
+    """
+    if api_key is not None:
+        return api_key
+
+    env_key = os.getenv("GUIDELINELY_API_KEY")
+    if env_key:
+        return env_key
+
+    return None

guidelinely/cache.py

@@ -0,0 +1,46 @@
+"""Client-side caching for Guidelinely API calculation endpoints.
+
+Uses diskcache for persistent, SQLite-backed caching that survives between runs.
+
+The cache directory can be configured via the GUIDELINELY_CACHE_DIR environment
+variable. If not set, defaults to ~/.guidelinely_cache.
+"""
+
+import os
+from pathlib import Path
+from typing import Any, Optional, cast
+
+from diskcache import Cache  # type: ignore[import-untyped]
+
+__all__ = ["get_cached", "set_cached", "cache", "CACHE_DIR"]
+
+# Cache directory: configurable via environment variable, defaults to user's home directory
+_default_cache_dir = Path.home() / ".guidelinely_cache"
+CACHE_DIR = Path(os.getenv("GUIDELINELY_CACHE_DIR", str(_default_cache_dir)))
+cache = Cache(directory=str(CACHE_DIR))
+
+
+def get_cached(key_data: dict[str, Any]) -> Optional[dict[str, Any]]:
+    """Retrieve cached response for given request data.
+
+    Args:
+        key_data: Cache key (typically dict of request parameters)
+
+    Returns:
+        Cached response data if found, None otherwise
+    """
+    result = cache.get(key_data)
+    if result is None:
+        return None
+    return cast(dict[str, Any], result)
+
+
+def set_cached(key_data: dict[str, Any], value: dict[str, Any], ttl: int = 24 * 3600) -> None:
+    """Store response in cache for given request data with TTL.
+
+    Args:
+        key_data: Cache key (typically dict of request parameters)
+        value: Response data to cache
+        ttl: Time to live in seconds (default: 24 hours)
+    """
+    cache.set(key_data, value, expire=ttl)

guidelinely/client.py

@@ -0,0 +1,469 @@
+"""Python client for the Guidelinely Environmental Guidelines API.
+
+Provides programmatic access to environmental guideline calculations and searches
+for chemical parameters in various media (water, soil, sediment).
+"""
+
+import logging
+from typing import Any, Optional, Union, cast
+
+import httpx
+
+from guidelinely.auth import get_api_key
+from guidelinely.cache import get_cached, set_cached
+from guidelinely.exceptions import GuidelinelyAPIError, GuidelinelyTimeoutError
+from guidelinely.models import (
+    CalculationResponse,
+    SourceResponse,
+    StatsResponse,
+)
+
+# Module logger for debugging API calls
+logger = logging.getLogger("guidelinely")
+
+# API base URL
+GUIDELINELY_API_BASE = "https://guidelines.1681248.com/api/v1"
+
+# Default timeout for HTTP requests (in seconds)
+DEFAULT_TIMEOUT = 30.0
+
+# Package version for User-Agent header (duplicated from __init__.py to avoid circular import)
+__version__ = "0.1.0"
+
+# User-Agent header for API request identification
+USER_AGENT = f"guidelinely-python/{__version__}"
+
+
+def _handle_error(response: httpx.Response) -> None:
+    """Extract error message from API response and raise appropriate exception.
+
+    Args:
+        response: HTTP response object with non-2xx status code.
+
+    Raises:
+        GuidelinelyAPIError: Always raised with extracted message and status code.
+    """
+    try:
+        error_body = response.json()
+        message = error_body.get("detail") or error_body.get("message") or "API request failed"
+    except Exception:
+        message = "API request failed"
+    raise GuidelinelyAPIError(message, response.status_code)
+
+
+def health_check() -> dict[str, Any]:
+    """Check if the API service is running.
+
+    Lightweight health check that returns 200 OK if the service is running.
+    Does not check dependencies.
+
+    Returns:
+        Dictionary with health status.
+
+    Raises:
+        GuidelinelyAPIError: If the API returns an error response.
+        GuidelinelyTimeoutError: If the request times out.
+
+    Example:
+        status = health_check()
+        print(status)
+    """
+    logger.debug("Performing health check")
+    try:
+        with httpx.Client(timeout=DEFAULT_TIMEOUT, headers={"User-Agent": USER_AGENT}) as client:
+            response = client.get(f"{GUIDELINELY_API_BASE}/health")
+            logger.debug(f"Health check response: {response.status_code}")
+            if response.status_code != 200:
+                _handle_error(response)
+            return cast(dict[str, Any], response.json())
+    except httpx.TimeoutException as e:
+        logger.warning(f"Health check timed out: {e}")
+        raise GuidelinelyTimeoutError(f"Request timed out: {e}") from e
+
+
+def readiness_check() -> dict[str, Any]:
+    """Check if the API is ready to handle requests.
+
+    Readiness check that verifies the service can handle requests
+    (database is accessible).
+
+    Returns:
+        Dictionary with readiness status.
+
+    Raises:
+        GuidelinelyAPIError: If the API returns an error response.
+        GuidelinelyTimeoutError: If the request times out.
+
+    Example:
+        status = readiness_check()
+        print(status)
+    """
+    logger.debug("Performing readiness check")
+    try:
+        with httpx.Client(timeout=DEFAULT_TIMEOUT, headers={"User-Agent": USER_AGENT}) as client:
+            response = client.get(f"{GUIDELINELY_API_BASE}/ready")
+            logger.debug(f"Readiness check response: {response.status_code}")
+            if response.status_code != 200:
+                _handle_error(response)
+            return cast(dict[str, Any], response.json())
+    except httpx.TimeoutException as e:
+        logger.warning(f"Readiness check timed out: {e}")
+        raise GuidelinelyTimeoutError(f"Request timed out: {e}") from e
+
+
+def list_parameters() -> list[str]:
+    """List all available chemical parameters.
+
+    Get complete list of all available chemical parameters in the database.
+
+    Returns:
+        List of parameter names.
+
+    Raises:
+        GuidelinelyAPIError: If the API returns an error response.
+        GuidelinelyTimeoutError: If the request times out.
+
+    Example:
+        params = list_parameters()
+        print(params[:5])  # ['Aluminum', 'Ammonia', 'Arsenic', 'Cadmium', 'Copper']
+    """
+    logger.debug("Listing all parameters")
+    try:
+        with httpx.Client(timeout=DEFAULT_TIMEOUT, headers={"User-Agent": USER_AGENT}) as client:
+            response = client.get(f"{GUIDELINELY_API_BASE}/parameters")
+            logger.debug(f"List parameters response: {response.status_code}")
+            if response.status_code != 200:
+                _handle_error(response)
+            return cast(list[str], response.json())
+    except httpx.TimeoutException as e:
+        logger.warning(f"List parameters timed out: {e}")
+        raise GuidelinelyTimeoutError(f"Request timed out: {e}") from e
+
+
+def search_parameters(q: str = "", media: Optional[list[str]] = None) -> list[str]:
+    """Search for chemical parameters.
+
+    Search for chemical parameters using case-insensitive substring matching.
+
+    Args:
+        q: Search query string. Empty string returns all parameters.
+        media: Optional list of media types to filter by (e.g., ["surface_water", "soil"]).
+
+    Returns:
+        List of matching parameter names.
+
+    Raises:
+        GuidelinelyAPIError: If the API returns an error response.
+        GuidelinelyTimeoutError: If the request times out.
+
+    Example:
+        # Find all ammonia-related parameters
+        ammonia = search_parameters("ammon")
+        print(ammonia)
+
+        # Find copper in surface water
+        copper_sw = search_parameters("copper", media=["surface_water"])
+    """
+    logger.debug(f"Searching parameters with q={q!r}, media={media!r}")
+    try:
+        with httpx.Client(timeout=DEFAULT_TIMEOUT, headers={"User-Agent": USER_AGENT}) as client:
+            params: dict[str, Any] = {"q": q}
+            if media:
+                params["media"] = media
+
+            response = client.get(
+                f"{GUIDELINELY_API_BASE}/parameters/search",
+                params=params,
+            )
+            logger.debug(f"Search parameters response: {response.status_code}")
+            if response.status_code != 200:
+                _handle_error(response)
+            return cast(list[str], response.json())
+    except httpx.TimeoutException as e:
+        logger.warning(f"Search parameters timed out: {e}")
+        raise GuidelinelyTimeoutError(f"Request timed out: {e}") from e
+
+
+def list_media() -> dict[str, str]:
+    """List all environmental media types.
+
+    Get list of all available environmental media types (water, soil, sediment, etc.).
+
+    Returns:
+        Dictionary mapping enum names to display names.
+
+    Raises:
+        GuidelinelyAPIError: If the API returns an error response.
+        GuidelinelyTimeoutError: If the request times out.
+
+    Example:
+        media = list_media()
+        print(media)
+    """
+    logger.debug("Listing all media types")
+    try:
+        with httpx.Client(timeout=DEFAULT_TIMEOUT, headers={"User-Agent": USER_AGENT}) as client:
+            response = client.get(f"{GUIDELINELY_API_BASE}/media")
+            logger.debug(f"List media response: {response.status_code}")
+            if response.status_code != 200:
+                _handle_error(response)
+            return cast(dict[str, str], response.json())
+    except httpx.TimeoutException as e:
+        logger.warning(f"List media timed out: {e}")
+        raise GuidelinelyTimeoutError(f"Request timed out: {e}") from e
+
+
+def list_sources() -> list[SourceResponse]:
+    """List all guideline sources and documents.
+
+    Get list of all guideline sources and their associated documents.
+
+    Returns:
+        List of SourceResponse objects with nested document information.
+
+    Raises:
+        GuidelinelyAPIError: If the API returns an error response.
+        GuidelinelyTimeoutError: If the request times out.
+
+    Example:
+        sources = list_sources()
+        print(sources[0].name)  # e.g., 'CCME'
+        print(sources[0].documents[0].title)
+    """
+    logger.debug("Listing all sources")
+    try:
+        with httpx.Client(timeout=DEFAULT_TIMEOUT, headers={"User-Agent": USER_AGENT}) as client:
+            response = client.get(f"{GUIDELINELY_API_BASE}/sources")
+            logger.debug(f"List sources response: {response.status_code}")
+            if response.status_code != 200:
+                _handle_error(response)
+            return [SourceResponse(**source) for source in response.json()]
+    except httpx.TimeoutException as e:
+        logger.warning(f"List sources timed out: {e}")
+        raise GuidelinelyTimeoutError(f"Request timed out: {e}") from e
+
+
+def get_stats() -> StatsResponse:
+    """Get database statistics.
+
+    Get statistics about the guideline database (counts of sources, documents, etc.).
+
+    Returns:
+        StatsResponse with total_parameters, total_guidelines, total_sources, total_documents.
+
+    Raises:
+        GuidelinelyAPIError: If the API returns an error response.
+        GuidelinelyTimeoutError: If the request times out.
+
+    Example:
+        stats = get_stats()
+        print(f"Total parameters: {stats.total_parameters}")
+        print(f"Total guidelines: {stats.total_guidelines}")
+    """
+    logger.debug("Getting database statistics")
+    try:
+        with httpx.Client(timeout=DEFAULT_TIMEOUT, headers={"User-Agent": USER_AGENT}) as client:
+            response = client.get(f"{GUIDELINELY_API_BASE}/stats")
+            logger.debug(f"Get stats response: {response.status_code}")
+            if response.status_code != 200:
+                _handle_error(response)
+            return StatsResponse(**response.json())
+    except httpx.TimeoutException as e:
+        logger.warning(f"Get stats timed out: {e}")
+        raise GuidelinelyTimeoutError(f"Request timed out: {e}") from e
+
+
+def calculate_guidelines(
+    parameter: str,
+    media: str,
+    context: Optional[dict[str, str]] = None,
+    target_unit: Optional[str] = None,
+    api_key: Optional[str] = None,
+) -> CalculationResponse:
+    """Calculate guidelines for a parameter.
+
+    Calculate guideline values for a specific parameter in a given media type
+    with environmental context.
+
+    Args:
+        parameter: Chemical parameter name (e.g., "Aluminum", "Copper").
+        media: Media type (e.g., "surface_water", "soil", "sediment").
+        context: Dictionary of environmental parameters as strings with units.
+            For water: pH ("7.0 1"), hardness ("100 mg/L"), temperature ("20 °C"),
+                      chloride ("50 mg/L")
+            For soil: pH ("6.5 1"), organic_matter ("3.5 %"),
+                     cation_exchange_capacity ("15 meq/100g")
+        target_unit: Optional unit to convert result to (e.g., "mg/L", "μg/L").
+        api_key: Optional API key. If None, will use GUIDELINELY_API_KEY environment variable.
+
+    Returns:
+        CalculationResponse with results, context, and total_count.
+
+    Raises:
+        GuidelinelyAPIError: If the API returns an error response.
+        GuidelinelyTimeoutError: If the request times out.
+
+    Example:
+        >>> import os
+        >>> os.environ["GUIDELINELY_API_KEY"] = "your_key"
+        >>>
+        >>> result = calculate_guidelines(
+        ...     parameter="Aluminum",
+        ...     media="surface_water",
+        ...     context={"pH": "7.0 1", "hardness": "100 mg/L"}
+        ... )
+        >>>
+        >>> print(f"Total: {result.total_count}")
+        >>> for guideline in result.results:
+        ...     print(f"{guideline.parameter}: {guideline.value} ({guideline.source})")
+    """
+    key = get_api_key(api_key)
+    logger.debug(f"Calculating guidelines for {parameter} in {media}")
+
+    # Prepare cache key (excludes api_key for security - keys should not be stored on disk)
+    cache_key = {
+        "endpoint": "calculate",
+        "parameter": parameter,
+        "media": media,
+        "context": context,
+        "target_unit": target_unit,
+    }
+
+    # Check cache first
+    cached_response = get_cached(cache_key)
+    if cached_response:
+        logger.debug("Returning cached response")
+        return CalculationResponse(**cached_response)
+
+    body: dict[str, Any] = {
+        "parameter": parameter,
+        "media": media,
+    }
+
+    if context:
+        body["context"] = context
+    if target_unit:
+        body["target_unit"] = target_unit
+
+    headers = {"User-Agent": USER_AGENT}
+    if key:
+        headers["X-API-KEY"] = key
+
+    try:
+        with httpx.Client(timeout=DEFAULT_TIMEOUT, headers={"User-Agent": USER_AGENT}) as client:
+            response = client.post(
+                f"{GUIDELINELY_API_BASE}/calculate",
+                json=body,
+                headers=headers,
+            )
+            logger.debug(f"Calculate response: {response.status_code}")
+            if response.status_code != 200:
+                _handle_error(response)
+
+            data = response.json()
+            # Cache the response
+            set_cached(cache_key, data)
+            return CalculationResponse(**data)
+    except httpx.TimeoutException as e:
+        logger.warning(f"Calculate guidelines timed out: {e}")
+        raise GuidelinelyTimeoutError(f"Request timed out: {e}") from e
+
+
+def calculate_batch(
+    parameters: list[Union[str, dict[str, Any]]],
+    media: str,
+    context: Optional[dict[str, str]] = None,
+    api_key: Optional[str] = None,
+) -> CalculationResponse:
+    """Batch calculate guidelines for multiple parameters.
+
+    Calculate guideline values for multiple parameters in a given media type
+    with shared environmental context. More efficient than multiple individual calls.
+
+    Args:
+        parameters: List of parameter names (strings), or list mixing strings and dicts
+            with 'name' and 'target_unit' fields. Maximum 50 parameters.
+        media: Media type (e.g., "surface_water", "soil").
+        context: Dictionary of environmental parameters as strings with units.
+        api_key: Optional API key. If None, will use GUIDELINELY_API_KEY environment variable.
+
+    Returns:
+        CalculationResponse with results, context, and total_count.
+
+    Raises:
+        ValueError: If more than 50 parameters provided.
+        GuidelinelyAPIError: If the API returns an error response.
+        GuidelinelyTimeoutError: If the request times out.
+
+    Example:
+        >>> import os
+        >>> os.environ["GUIDELINELY_API_KEY"] = "your_key"
+        >>>
+        >>> # Calculate multiple metals in surface water
+        >>> results = calculate_batch(
+        ...     parameters=["Aluminum", "Copper", "Lead"],
+        ...     media="surface_water",
+        ...     context={"pH": "7.0 1", "hardness": "100 mg/L"}
+        ... )
+        >>>
+        >>> # With per-parameter unit conversion
+        >>> results = calculate_batch(
+        ...     parameters=[
+        ...         "Aluminum",
+        ...         {"name": "Copper", "target_unit": "μg/L"},
+        ...         {"name": "Lead", "target_unit": "mg/L"}
+        ...     ],
+        ...     media="surface_water",
+        ...     context={"pH": "7.5 1", "hardness": "150 mg/L", "temperature": "15 °C"}
+        ... )
+    """
+    if len(parameters) > 50:
+        raise ValueError("Maximum 50 parameters per batch request")
+
+    key = get_api_key(api_key)
+    logger.debug(f"Batch calculating {len(parameters)} parameters in {media}")
+
+    # Prepare cache key (excludes api_key for security - keys should not be stored on disk)
+    cache_key = {
+        "endpoint": "calculate/batch",
+        "parameters": parameters,
+        "media": media,
+        "context": context,
+    }
+
+    # Check cache first
+    cached_response = get_cached(cache_key)
+    if cached_response:
+        logger.debug("Returning cached response")
+        return CalculationResponse(**cached_response)
+
+    body: dict[str, Any] = {
+        "parameters": parameters,
+        "media": media,
+    }
+
+    if context:
+        body["context"] = context
+
+    headers = {"User-Agent": USER_AGENT}
+    if key:
+        headers["X-API-KEY"] = key
+
+    try:
+        with httpx.Client(timeout=DEFAULT_TIMEOUT, headers={"User-Agent": USER_AGENT}) as client:
+            response = client.post(
+                f"{GUIDELINELY_API_BASE}/calculate/batch",
+                json=body,
+                headers=headers,
+            )
+            logger.debug(f"Batch calculate response: {response.status_code}")
+            if response.status_code != 200:
+                _handle_error(response)
+
+            data = response.json()
+            # Cache the response
+            set_cached(cache_key, data)
+            return CalculationResponse(**data)
+    except httpx.TimeoutException as e:
+        logger.warning(f"Batch calculate timed out: {e}")
+        raise GuidelinelyTimeoutError(f"Request timed out: {e}") from e

guidelinely/exceptions.py

@@ -0,0 +1,82 @@
+"""Custom exceptions for the Guidelinely API client.
+
+Provides structured error handling for API communication failures,
+allowing callers to catch specific exception types and access
+error details like HTTP status codes.
+"""
+
+__all__ = ["GuidelinelyError", "GuidelinelyAPIError", "GuidelinelyTimeoutError"]
+
+
+class GuidelinelyError(Exception):
+    """Base exception for all Guidelinely client errors.
+
+    All exceptions raised by the guidelinely package inherit from this class,
+    making it easy to catch all library-specific errors.
+
+    Example:
+        try:
+            result = calculate_guidelines(...)
+        except GuidelinelyError as e:
+            print(f"Guidelinely error: {e}")
+    """
+
+    pass
+
+
+class GuidelinelyAPIError(GuidelinelyError):
+    """Raised when the API returns an error response.
+
+    Provides access to both the error message and HTTP status code
+    for detailed error handling.
+
+    Attributes:
+        message: Human-readable error description from the API.
+        status_code: HTTP status code returned by the API.
+
+    Example:
+        try:
+            result = calculate_guidelines(...)
+        except GuidelinelyAPIError as e:
+            if e.status_code == 404:
+                print("Parameter not found")
+            elif e.status_code == 401:
+                print("Invalid API key")
+            else:
+                print(f"API error {e.status_code}: {e.message}")
+    """
+
+    def __init__(self, message: str, status_code: int) -> None:
+        """Initialize the API error.
+
+        Args:
+            message: Error message from the API response.
+            status_code: HTTP status code from the response.
+        """
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+
+    def __str__(self) -> str:
+        """Return formatted error string with status code."""
+        return f"[{self.status_code}] {self.message}"
+
+    def __repr__(self) -> str:
+        """Return detailed representation for debugging."""
+        return f"GuidelinelyAPIError(message={self.message!r}, status_code={self.status_code})"
+
+
+class GuidelinelyTimeoutError(GuidelinelyError):
+    """Raised when an API request times out.
+
+    This exception wraps httpx.TimeoutException to provide a consistent
+    exception hierarchy for the library.
+
+    Example:
+        try:
+            result = calculate_guidelines(...)
+        except GuidelinelyTimeoutError:
+            print("Request timed out, please try again")
+    """
+
+    pass

guidelinely/models.py

@@ -0,0 +1,138 @@
+"""Pydantic models for Guidelinely API requests and responses."""
+
+from typing import Any, Optional, Union
+
+from pydantic import BaseModel, model_validator
+
+__all__ = [
+    # Response models
+    "GuidelineResponse",
+    "CalculationResponse",
+    "SourceResponse",
+    "SourceDocument",
+    "StatsResponse",
+    "MediaResponse",
+    # Request models
+    "CalculateRequest",
+    "BatchCalculateRequest",
+    "ParameterWithUnit",
+    "SearchParametersRequest",
+]
+
+
+class GuidelineResponse(BaseModel):
+    """Single guideline result with calculated or static value.
+
+    Represents a guideline value in PostgreSQL unitrange format (e.g., '[10 μg/L,100 μg/L]').
+    """
+
+    id: int
+    parameter: str
+    parameter_specification: str
+    media: str
+    value: str  # PostgreSQL unitrange format: '[10 μg/L,100 μg/L]', '(,87.0 μg/L]', '[5.0 mg/L,)'
+    lower: Optional[float] = None  # Parsed lower bound or None if unbounded
+    upper: Optional[float] = None  # Parsed upper bound or None if unbounded
+    unit: str
+    is_calculated: bool
+    source: str
+    basis: Optional[str] = None
+    receptor: str
+    exposure_duration: str
+    guideline_type: Optional[str] = None
+    notes: Optional[str] = None
+    reference_id: Optional[int] = None
+    document_id: Optional[int] = None
+    created_at: Optional[str] = None
+    updated_at: Optional[str] = None
+    document_abbreviation: str
+    source_abbreviation: str
+
+
+class CalculationResponse(BaseModel):
+    """Response from calculation endpoints (/calculate and /calculate/batch)."""
+
+    results: list[GuidelineResponse]
+    context: dict[str, Any]  # Environmental context used for calculation
+    total_count: int
+
+
+class CalculateRequest(BaseModel):
+    """Request body for single parameter calculation."""
+
+    parameter: str
+    media: str
+    context: Optional[dict[str, str]] = None  # Environmental parameters as strings with units
+    target_unit: Optional[str] = None  # Optional unit conversion
+
+
+class ParameterWithUnit(BaseModel):
+    """Parameter specification with optional target unit for batch requests."""
+
+    name: str
+    target_unit: Optional[str] = None
+
+
+class BatchCalculateRequest(BaseModel):
+    """Request body for batch parameter calculation."""
+
+    parameters: list[Union[str, ParameterWithUnit]]  # Mix of strings and objects
+    media: str
+    context: Optional[dict[str, str]] = None
+
+    @model_validator(mode="after")
+    def validate_parameter_count(self) -> "BatchCalculateRequest":
+        """Ensure batch doesn't exceed 50 parameters.
+
+        This validation runs automatically when the model is instantiated,
+        raising ValueError if more than 50 parameters are provided.
+
+        Returns:
+            The validated model instance.
+
+        Raises:
+            ValueError: If parameters list contains more than 50 items.
+        """
+        if len(self.parameters) > 50:
+            raise ValueError("Maximum 50 parameters per batch request")
+        return self
+
+
+class SearchParametersRequest(BaseModel):
+    """Request body for parameter search (optional media filter)."""
+
+    media: Optional[list[str]] = None
+
+
+class MediaResponse(BaseModel):
+    """Response from /media endpoint mapping enum names to display names."""
+
+    # Dynamic keys, so use dict directly in practice
+    pass
+
+
+class SourceDocument(BaseModel):
+    """Nested document information within a source."""
+
+    id: int
+    title: str
+    url: Optional[str] = None
+    year: Optional[int] = None
+
+
+class SourceResponse(BaseModel):
+    """Guideline source with nested documents."""
+
+    id: int
+    name: str
+    abbreviation: str
+    documents: list[SourceDocument]
+
+
+class StatsResponse(BaseModel):
+    """Database statistics response."""
+
+    total_parameters: int
+    total_guidelines: int
+    total_sources: int
+    total_documents: int

guidelinely-1.0.3.dist-info/METADATA

@@ -0,0 +1,338 @@
+Metadata-Version: 2.4
+Name: guidelinely
+Version: 1.0.3
+Summary: Python client for the Guidelinely Environmental Guidelines API
+Author-email: Michael Davison <michael.davison@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/mpdavison/guidelinely-python
+Project-URL: Documentation, https://guidelines.1681248.com/docs
+Project-URL: Repository, https://github.com/mpdavison/guidelinely-python
+Project-URL: Bug Tracker, https://github.com/mpdavison/guidelinely-python/issues
+Keywords: environmental,guidelines,api,water quality,soil,sediment
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: diskcache>=5.6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: pytest-httpx>=0.30.0; extra == "dev"
+Requires-Dist: responses>=0.23.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: pre-commit>=3.0.0; extra == "dev"
+Dynamic: license-file
+
+# Guidelinely Python Client
+
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Python client library for the [Guidelinely API](https://guidelines.1681248.com/docs) - an environmental guideline calculation and search API.
+
+Calculate context-dependent environmental guideline values for chemical parameters (Aluminum, Copper, Lead, etc.) in various media (water, soil, sediment) based on environmental conditions (pH, hardness, temperature, etc.).
+
+This Python client mirrors the functionality of the [R client](https://github.com/mpdavison/envguidelines).
+
+## Features
+
+
+- ✅ **Metadata Queries**: List parameters, search, explore media types and sources
+- ✅ **Single Calculations**: Calculate guidelines for individual parameters
+- ✅ **Batch Calculations**: Efficiently calculate multiple parameters (up to 50)
+- ✅ **Context-Aware**: Support for pH, hardness, temperature, and other environmental factors
+- ✅ **Unit Conversion**: Optional target unit specification
+- ✅ **Type Safety**: Full Pydantic model support for request/response validation
+- ✅ **Comprehensive Tests**: Mock-based test suite with responses library
+
+## Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/mpdavison/guidelinely-python.git
+cd guidelinely-python
+
+# Install in development mode
+pip install -e .
+
+# Or install with dev dependencies
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+```python
+from guidelinely import calculate_guidelines
+
+# Calculate aluminum guidelines in surface water
+result = calculate_guidelines(
+    parameter="Aluminum",
+    media="surface_water",
+    context={
+        "pH": "7.0 1",           # pH 7.0 (dimensionless)
+        "hardness": "100 mg/L"   # Water hardness as CaCO3
+    }
+)
+
+print(f"Found {result.total_count} guidelines")
+for guideline in result.results:
+    print(f"{guideline.parameter}: {guideline.value} ({guideline.source})")
+```
+
+## API Key
+
+Calculation endpoints optionally accept an API key. Set it as an environment variable:
+
+```bash
+export GUIDELINELY_API_KEY="your_api_key_here"
+```
+
+Metadata endpoints (list parameters, search, etc.) work without authentication.
+
+## Usage Examples
+
+### Basic Metadata Queries
+
+```python
+from guidelinely import (
+    health_check,
+    list_parameters,
+    search_parameters,
+    list_media,
+    list_sources,
+    get_stats,
+)
+
+# Check API health
+status = health_check()
+
+# List all chemical parameters
+params = list_parameters()
+print(f"Available parameters: {len(params)}")
+
+# Search for ammonia-related parameters
+ammonia = search_parameters("ammon")
+print(ammonia)  # ['Ammonia', 'Ammonium', ...]
+
+# Get available media types
+media = list_media()
+# {'surface_water': 'Surface Water', 'soil': 'Soil', ...}
+
+# View guideline sources
+sources = list_sources()
+
+# Database statistics
+stats = get_stats()
+```
+
+### Single Parameter Calculation
+
+```python
+from guidelinely import calculate_guidelines
+import os
+
+os.environ["GUIDELINELY_API_KEY"] = "your_key"
+
+result = calculate_guidelines(
+    parameter="Copper",
+    media="surface_water",
+    context={
+        "pH": "7.5 1",
+        "hardness": "150 mg/L",
+        "temperature": "15 °C",
+        "chloride": "75 mg/L"
+    },
+    target_unit="μg/L"  # Optional unit conversion
+)
+
+# Filter results
+chronic_aquatic = [
+    g for g in result.results
+    if g.receptor == "Aquatic Life" and g.exposure_duration == "chronic"
+]
+```
+
+### Batch Calculations
+
+```python
+from guidelinely import calculate_batch
+
+# Calculate multiple parameters at once (more efficient)
+result = calculate_batch(
+    parameters=["Aluminum", "Copper", "Lead", "Zinc", "Cadmium"],
+    media="surface_water",
+    context={
+        "pH": "7.5 1",
+        "hardness": "150 mg/L",
+        "temperature": "15 °C"
+    }
+)
+
+print(f"Total: {result.total_count} guidelines")
+
+# With per-parameter unit conversion
+result = calculate_batch(
+    parameters=[
+        "Aluminum",
+        {"name": "Copper", "target_unit": "μg/L"},
+        {"name": "Lead", "target_unit": "mg/L"}
+    ],
+    media="surface_water",
+    context={"pH": "7.0 1", "hardness": "100 mg/L"}
+)
+```
+
+### Soil Calculations
+
+```python
+result = calculate_guidelines(
+    parameter="Lead",
+    media="soil",
+    context={
+        "pH": "6.5 1",
+        "organic_matter": "3.5 %",
+        "cation_exchange_capacity": "15 meq/100g"
+    }
+)
+```
+
+## Environmental Context Parameters
+
+All context parameters **must be strings with units** (Pint format):
+
+### Water (surface_water, groundwater)
+```python
+context = {
+    "pH": "7.0 1",           # Dimensionless - use "1" as unit
+    "hardness": "100 mg/L",  # mg/L as CaCO3
+    "temperature": "20 °C",
+    "chloride": "50 mg/L"
+}
+```
+
+### Soil
+```python
+context = {
+    "pH": "6.5 1",
+    "organic_matter": "3.5 %",
+    "cation_exchange_capacity": "15 meq/100g"
+}
+```
+
+### Sediment
+```python
+context = {
+    "pH": "7.0 1",
+    "organic_matter": "2.5 %",
+    "grain_size": "0.5 mm"
+}
+```
+
+## Data Models
+
+The library uses Pydantic for type-safe data handling:
+
+```python
+from guidelinely.models import GuidelineResponse, CalculationResponse
+
+# All API responses are strongly typed
+result: CalculationResponse = calculate_guidelines(...)
+
+# Access typed fields
+for guideline in result.results:
+    guideline.parameter  # str
+    guideline.value      # str (PostgreSQL unitrange format)
+    guideline.lower      # Optional[float]
+    guideline.upper      # Optional[float]
+    guideline.unit       # str
+    guideline.is_calculated  # bool
+```
+
+## Guideline Value Format
+
+Guidelines use PostgreSQL `unitrange` format:
+- `[10 μg/L,100 μg/L]` - Range from 10 to 100 μg/L
+- `(,87.0 μg/L]` - Upper limit only (≤87.0 μg/L)
+- `[5.0 mg/L,)` - Lower limit only (≥5.0 mg/L)
+
+Parsed into `lower`, `upper`, and `unit` fields.
+
+## Development
+
+```bash
+# Install development dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Run tests with coverage
+pytest --cov=guidelinely --cov-report=html
+
+# Format code
+black guidelinely/ tests/ examples/
+
+# Type checking
+mypy guidelinely/
+
+# Linting
+ruff check guidelinely/ tests/
+```
+
+## API Reference
+
+### Client Functions
+
+- `health_check()` - Service health check
+- `readiness_check()` - Database readiness check
+- `list_parameters()` - List all chemical parameters
+- `search_parameters(q, media)` - Search parameters
+- `list_media()` - List media types
+- `list_sources()` - List guideline sources
+- `get_stats()` - Database statistics
+- `calculate_guidelines(parameter, media, context, target_unit, api_key)` - Calculate single parameter
+- `calculate_batch(parameters, media, context, api_key)` - Batch calculate (max 50 parameters)
+
+### Models
+
+- `GuidelineResponse` - Single guideline result
+- `CalculationResponse` - Calculation endpoint response
+- `CalculateRequest` - Single calculation request body
+- `BatchCalculateRequest` - Batch calculation request body
+
+## Examples
+
+See the `examples/` directory for complete working examples:
+
+1. `01_basic_metadata.py` - Basic metadata queries
+2. `02_calculate_single_parameter.py` - Single parameter calculations
+3. `03_batch_calculations.py` - Batch calculations
+4. `04_soil_calculations.py` - Soil-specific calculations
+5. `05_advanced_workflow.py` - Advanced filtering and analysis
+
+## Resources
+
+- **API Documentation**: https://guidelines.1681248.com/docs
+- **OpenAPI Spec**: https://guidelines.1681248.com/openapi.json
+- **R Client**: https://github.com/mpdavison/envguidelines
+- **Issue Tracker**: https://github.com/mpdavison/guidelinely-python/issues
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.

guidelinely-1.0.3.dist-info/RECORD

@@ -0,0 +1,12 @@
+guidelinely/__init__.py,sha256=IjusaUQolmVzQl5pajYzz7WTJrxpha2leVwM2NbLqgU,1395
+guidelinely/_version.py,sha256=l8k828IdTfzXAlmx4oT8GsiIf2eeMAlFDALjoYk-jrU,704
+guidelinely/auth.py,sha256=hGrmMGQ9Ye9555yOJglrHOGzS3clU7z9QTg-gRYNOVo,704
+guidelinely/cache.py,sha256=V9bXeyT9_FR1ijRFXu_7R7rcZwmtBjE8TJx-ZWxniDM,1537
+guidelinely/client.py,sha256=nBXvIKHD0xYskbtjun5w7wYO5vHQK8gkxtJZx2XclkE,16808
+guidelinely/exceptions.py,sha256=d_HaNw7nqzyv-w2hRNMj2YXx2qJoOj_NkHft7fZED8k,2508
+guidelinely/models.py,sha256=Z8q1fptPa3SNuSRtwtQV8CIiIEz8cmTKRi99m_4w4A4,3817
+guidelinely-1.0.3.dist-info/licenses/LICENSE,sha256=0zH1WeuuqGNzsoBXBmOfaW_hqqVAUefUNoWYm88CdwM,1081
+guidelinely-1.0.3.dist-info/METADATA,sha256=QB6DnTRf5OGQrCdngZn0aAS3yHKE1tvCHo-5nhIXErY,9397
+guidelinely-1.0.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+guidelinely-1.0.3.dist-info/top_level.txt,sha256=zrK-evc6akaqjoD3VabEnbc1xmz_RSDDKofUnQ7COlU,12
+guidelinely-1.0.3.dist-info/RECORD,,

guidelinely-1.0.3.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

guidelinely-1.0.3.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Guidelinely Contributors
+
+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.

guidelinely-1.0.3.dist-info/top_level.txt

@@ -0,0 +1 @@
+guidelinely