humanbaselines 0.1.0__py3-none-any.whl

humanbaselines/__init__.py

@@ -0,0 +1,89 @@
+"""humanbaselines — Python client for the Human Crash Baselines API.
+
+>>> from humanbaselines import HumanBaselines
+>>> hb = HumanBaselines(api_key="hbk_...")        # or env HUMANBASELINES_API_KEY
+>>> hb.compute(outcome="police_reported").rate
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from .client import HumanBaselines
+from .exceptions import (
+    APIError,
+    AuthenticationError,
+    HumanBaselinesError,
+    NotFoundError,
+    ServiceUnavailableError,
+    ValidationError,
+)
+from .models import (
+    CiMethod,
+    ComputeResult,
+    DepotComputeResult,
+    DepotPin,
+    DepotSelections,
+    DriverImpairment,
+    FilterDef,
+    FilterOption,
+    FiltersResponse,
+    GeofenceSelections,
+    InTransport,
+    LightFilter,
+    MultiplierVmt,
+    Outcome,
+    PerCellResult,
+    PerSegmentResult,
+    RegionInfo,
+    RegionsResponse,
+    RoadGroup,
+    RoboTaxiWeighting,
+    RouteComputeResult,
+    RouteSelections,
+    Tier3Mode,
+    UnderReporting,
+    VehicleClass,
+    WeatherFilter,
+)
+
+__all__ = [
+    "__version__",
+    "HumanBaselines",
+    # exceptions
+    "HumanBaselinesError",
+    "APIError",
+    "AuthenticationError",
+    "ValidationError",
+    "NotFoundError",
+    "ServiceUnavailableError",
+    # request models
+    "GeofenceSelections",
+    "RouteSelections",
+    "DepotSelections",
+    "DepotPin",
+    # response models
+    "ComputeResult",
+    "PerCellResult",
+    "RouteComputeResult",
+    "PerSegmentResult",
+    "DepotComputeResult",
+    "FiltersResponse",
+    "FilterDef",
+    "FilterOption",
+    "RegionsResponse",
+    "RegionInfo",
+    # enums
+    "Outcome",
+    "VehicleClass",
+    "RoadGroup",
+    "Tier3Mode",
+    "InTransport",
+    "RoboTaxiWeighting",
+    "MultiplierVmt",
+    "UnderReporting",
+    "WeatherFilter",
+    "LightFilter",
+    "DriverImpairment",
+    "CiMethod",
+]

humanbaselines/_generated.py

@@ -0,0 +1,322 @@
+# AUTO-GENERATED -- DO NOT EDIT.
+# Generated from the live Human Crash Baselines OpenAPI schema by
+# scripts/regenerate_models.py.
+# Re-run that script after any API contract change.
+
+# generated by datamodel-codegen:
+#   filename:  humanbaselines_openapi.json
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, RootModel
+
+
+class AccessLogRequest(BaseModel):
+    email: str = Field(..., title='Email')
+    allowed: bool = Field(..., title='Allowed')
+
+
+class CiMethod(Enum):
+    fay_feuer = 'fay_feuer'
+    empirical_bayes = 'empirical_bayes'
+
+
+class ComputeRequest(BaseModel):
+    county: str = Field('travis', title='County')
+    selections: dict[str, Any] | None = Field(None, title='Selections')
+    cell_filter: list[str] | None = Field(None, title='Cell Filter')
+
+
+class SegmentId(RootModel[tuple[str, int]]):
+    root: tuple[str, int] = Field(..., max_length=2, min_length=2)
+
+
+class ComputeRouteRequest(BaseModel):
+    county: str = Field('travis', title='County')
+    segment_ids: list[SegmentId] = Field(..., title='Segment Ids')
+    selections: dict[str, Any] | None = Field(None, title='Selections')
+
+
+class DenominatorVmt(Enum):
+    calibrated = 'calibrated'
+    hpms = 'hpms'
+
+
+class DepotComputeResult(BaseModel):
+    model_config = ConfigDict(
+        extra='allow',
+    )
+
+
+class DepotPin(BaseModel):
+    lat: float = Field(..., title='Lat')
+    lon: float = Field(..., title='Lon')
+
+
+class DriverImpairment(Enum):
+    any = 'any'
+    exclude_impaired = 'exclude_impaired'
+    impaired_only = 'impaired_only'
+
+
+class FilterOption(BaseModel):
+    id: str = Field(..., title='Id')
+    label: str = Field(..., title='Label')
+
+
+class InTransport(Enum):
+    in_transport = 'in_transport'
+    include_all = 'include_all'
+
+
+class LightFilter(Enum):
+    any = 'any'
+    daylight = 'daylight'
+    dawn_dusk = 'dawn_dusk'
+    dark = 'dark'
+
+
+class MultiplierVmt(Enum):
+    calibrated = 'calibrated'
+    hpms = 'hpms'
+
+
+class Outcome(Enum):
+    police_reported = 'police_reported'
+    observed_any_injury = 'observed_any_injury'
+    airbag = 'airbag'
+    ego_airbag = 'ego_airbag'
+    ka = 'ka'
+    fatal = 'fatal'
+
+
+class PerCellResult(BaseModel):
+    model_config = ConfigDict(
+        extra='allow',
+    )
+    s2_cell: str = Field(..., title='S2 Cell')
+    count: float = Field(..., title='Count')
+    vmt: float = Field(..., title='Vmt')
+    mult_contrib: float = Field(0.0, title='Mult Contrib')
+
+
+class PerSegmentResult(BaseModel):
+    model_config = ConfigDict(
+        extra='allow',
+    )
+    route: str = Field(..., title='Route')
+    milepost: int = Field(..., title='Milepost')
+    count: float = Field(..., title='Count')
+    vmt: float = Field(..., title='Vmt')
+    length_mi: float = Field(..., title='Length Mi')
+
+
+class RegionInfo(BaseModel):
+    county: str = Field(..., title='County')
+    modes: list[str] = Field(..., title='Modes')
+
+
+class RegionsResponse(BaseModel):
+    regions: list[RegionInfo] = Field(..., title='Regions')
+    default_county: str = Field('travis', title='Default County')
+
+
+class RoadGroup(Enum):
+    interstate = 'interstate'
+    other_freeway = 'other_freeway'
+    arterial = 'arterial'
+    collector_local = 'collector_local'
+
+
+class RoboTaxiWeighting(Enum):
+    county_wide = 'county_wide'
+    operator_weighted = 'operator_weighted'
+
+
+class RouteComputeResult(BaseModel):
+    model_config = ConfigDict(
+        extra='allow',
+    )
+    N: float = Field(..., title='N')
+    trip_miles: float = Field(..., title='Trip Miles')
+    rate: float = Field(..., title='Rate')
+    rate_low: float | None = Field(None, title='Rate Low')
+    rate_high: float | None = Field(None, title='Rate High')
+    variance: float | None = Field(None, title='Variance')
+    segments: list[PerSegmentResult] | None = Field(None, title='Segments')
+
+
+class Tier3Mode(Enum):
+    marginal = 'marginal'
+    none = 'none'
+    all = 'all'
+
+
+class UnderReporting(Enum):
+    none = 'none'
+    adjusted = 'adjusted'
+
+
+class ValidationError(BaseModel):
+    loc: list[str | int] = Field(..., title='Location')
+    msg: str = Field(..., title='Message')
+    type: str = Field(..., title='Error Type')
+    input: Any | None = Field(None, title='Input')
+    ctx: dict[str, Any] | None = Field(None, title='Context')
+
+
+class VehicleClass(Enum):
+    cars = 'cars'
+    light_trucks = 'light_trucks'
+    heavy_trucks = 'heavy_trucks'
+    motorcycles = 'motorcycles'
+    buses = 'buses'
+    other = 'other'
+
+
+class WeatherFilter(Enum):
+    any = 'any'
+    dry = 'dry'
+    rain = 'rain'
+    fog = 'fog'
+    winter_storm = 'winter_storm'
+
+
+class ComputeDepotRouteRequest(BaseModel):
+    county: str = Field('travis', title='County')
+    depot_a: DepotPin
+    depot_b: DepotPin
+    selections: dict[str, Any] | None = Field(None, title='Selections')
+
+
+class ComputeResult(BaseModel):
+    model_config = ConfigDict(
+        extra='allow',
+    )
+    N: float = Field(..., title='N')
+    D_miles: float = Field(..., title='D Miles')
+    D_billions: float = Field(..., title='D Billions')
+    rate: float = Field(..., title='Rate')
+    rate_low: float | None = Field(None, title='Rate Low')
+    rate_high: float | None = Field(None, title='Rate High')
+    rate_non_dyn: float = Field(..., title='Rate Non Dyn')
+    rate_dyn: float | None = Field(None, title='Rate Dyn')
+    multiplier: float | None = Field(None, title='Multiplier')
+    cells: list[PerCellResult] | None = Field(None, title='Cells')
+
+
+class DepotSelections(BaseModel):
+    model_config = ConfigDict(
+        extra='forbid',
+    )
+    outcome: Outcome = 'police_reported'
+    severity: int = Field(1, ge=1, le=7, title='Severity')
+    ego_vehicle: list[VehicleClass] | VehicleClass = Field(
+        ['combination'], title='Ego Vehicle'
+    )
+    unresolved_nfs: Tier3Mode = 'marginal'
+    in_transport: InTransport = 'in_transport'
+    weather: list[WeatherFilter] | WeatherFilter = Field(
+        ['dry', 'rain', 'fog'], title='Weather'
+    )
+    light_condition: list[LightFilter] | LightFilter = Field(
+        'any', title='Light Condition'
+    )
+    driver_impairment: DriverImpairment = 'any'
+    under_reporting: UnderReporting = 'none'
+    ci_method: CiMethod = 'empirical_bayes'
+
+
+class FilterDef(BaseModel):
+    model_config = ConfigDict(
+        extra='allow',
+    )
+    id: str = Field(..., title='Id')
+    label: str = Field(..., title='Label')
+    affects: str = Field(..., title='Affects')
+    multiselect: bool = Field(..., title='Multiselect')
+    description: str = Field(..., title='Description')
+    options: list[FilterOption] = Field(..., title='Options')
+    default: Any | None = Field(None, title='Default')
+
+
+class FiltersResponse(BaseModel):
+    modes: dict[str, list[FilterDef]] = Field(..., title='Modes')
+
+
+class GeofenceSelections(BaseModel):
+    model_config = ConfigDict(
+        extra='forbid',
+    )
+    outcome: Outcome = 'police_reported'
+    severity: int = Field(1, ge=1, le=7, title='Severity')
+    ego_vehicle: list[VehicleClass] | VehicleClass = Field(
+        ['cars', 'light_trucks'], title='Ego Vehicle'
+    )
+    unresolved_nfs: Tier3Mode = 'marginal'
+    in_transport: InTransport = 'in_transport'
+    road_type: list[RoadGroup] | RoadGroup = Field(
+        ['arterial', 'collector_local'], title='Road Type'
+    )
+    robo_taxi_weighting: RoboTaxiWeighting = 'county_wide'
+    multiplier_vmt: MultiplierVmt = 'calibrated'
+    denominator_vmt: DenominatorVmt = 'calibrated'
+    under_reporting: UnderReporting = 'none'
+    weather: list[WeatherFilter] | WeatherFilter = Field(
+        ['dry', 'rain', 'fog'], title='Weather'
+    )
+    light_condition: list[LightFilter] | LightFilter = Field(
+        'any', title='Light Condition'
+    )
+    crash_year: list[int] | int = Field([2022], title='Crash Year')
+
+
+class HTTPValidationError(BaseModel):
+    detail: list[ValidationError] | None = Field(None, title='Detail')
+
+
+class RouteSelections(BaseModel):
+    model_config = ConfigDict(
+        extra='forbid',
+    )
+    outcome: Outcome = 'police_reported'
+    severity: int = Field(1, ge=1, le=7, title='Severity')
+    ego_vehicle: list[VehicleClass] | VehicleClass = Field(
+        ['combination'], title='Ego Vehicle'
+    )
+    unresolved_nfs: Tier3Mode = 'marginal'
+    in_transport: InTransport = 'in_transport'
+    weather: list[WeatherFilter] | WeatherFilter = Field(
+        ['dry', 'rain', 'fog'], title='Weather'
+    )
+    light_condition: list[LightFilter] | LightFilter = Field(
+        'any', title='Light Condition'
+    )
+    driver_impairment: DriverImpairment = 'any'
+    under_reporting: UnderReporting = 'none'
+    ci_method: CiMethod = 'fay_feuer'
+
+
+class V1ComputeRequest(BaseModel):
+    county: str = Field('travis', title='County')
+    selections: GeofenceSelections | None = None
+
+
+class V1DepotRequest(BaseModel):
+    county: str = Field('travis', title='County')
+    depot_a: DepotPin
+    depot_b: DepotPin
+    selections: DepotSelections | None = None
+
+
+class V1RouteRequest(BaseModel):
+    county: str = Field('travis', title='County')
+    segment_ids: list[SegmentId] = Field(
+        ...,
+        description='Ordered [route, milepost] pairs, e.g. [["I-35", 250], ["I-35", 251]].',
+        title='Segment Ids',
+    )
+    selections: RouteSelections | None = None

humanbaselines/client.py

@@ -0,0 +1,351 @@
+"""Synchronous client for the Human Crash Baselines API."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+import requests
+from requests.adapters import HTTPAdapter
+from urllib3.util.retry import Retry
+
+from .exceptions import (
+    APIError,
+    AuthenticationError,
+    NotFoundError,
+    ServiceUnavailableError,
+    ValidationError,
+)
+from .models import (
+    DEFAULT_COUNTY,
+    ComputeResult,
+    DepotComputeResult,
+    DepotPin,
+    DepotSelections,
+    FiltersResponse,
+    GeofenceSelections,
+    RegionsResponse,
+    RouteComputeResult,
+    RouteSelections,
+)
+
+DEFAULT_BASE_URL = "https://humanbaselines.com"
+
+# tuple/list of (lat, lon), a DepotPin, or a {"lat","lon"} dict
+PinLike = tuple[float, float] | list[float] | DepotPin | dict
+
+_MODE_MODELS = {
+    "geofence": GeofenceSelections,
+    "route": RouteSelections,
+    "depot": DepotSelections,
+}
+# Every valid key a bound config may carry: "county" plus the union of all
+# modes' selection fields.
+_KNOWN_CONFIG_KEYS = {"county"} | {
+    f for m in _MODE_MODELS.values() for f in m.model_fields
+}
+
+
+class HumanBaselines:
+    """Client for the Human Crash Baselines `/v1` API.
+
+    >>> hb = HumanBaselines(api_key="hbk_...")          # or env HUMANBASELINES_API_KEY
+    >>> hb.compute(outcome="police_reported").rate
+    4.05
+    >>> hb.filters().modes.keys()
+    dict_keys(['geofence', 'route', 'depot'])
+
+    Args:
+        api_key:    your API key. Falls back to the ``HUMANBASELINES_API_KEY``
+                    env var. Sent as the ``X-API-Key`` header.
+        base_url:   API host. Defaults to https://humanbaselines.com (which
+                    proxies ``/v1/*``). Point at the Cloud Run URL for non-/v1
+                    paths like ``/health``.
+        timeout:    per-request timeout in seconds.
+        max_retries: automatic retries for transient 5xx / 503 warm-up, with
+                    exponential backoff.
+        session:    bring your own ``requests.Session`` (otherwise one is made).
+        config:     a baseline definition bound to this client — a dict of
+                    ``"county"`` plus any filter fields, OR a path to a JSON file
+                    written by ``save_config`` (a ``"mode"`` key is ignored).
+                    Every ``compute*`` call inherits it (each mode uses the
+                    subset of fields it understands); per-call args override it.
+                    Validated here, so bad fields/values fail fast.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        max_retries: int = 2,
+        session: requests.Session | None = None,
+        config: dict | str | Path | None = None,
+    ):
+        api_key = api_key or os.environ.get("HUMANBASELINES_API_KEY")
+        if not api_key:
+            raise ValueError(
+                "API key required: pass api_key=... or set HUMANBASELINES_API_KEY."
+            )
+        # Retained so with_config() can rebuild a sibling client.
+        self._api_key = api_key
+        self._base_url = base_url
+        self._timeout = timeout
+        self._max_retries = max_retries
+
+        self._root = base_url.rstrip("/")
+        self._v1 = f"{self._root}/v1"
+        self._config = self._validate_config(self._load_config(config))
+
+        self._session = session or requests.Session()
+        self._session.headers.update({"X-API-Key": api_key})
+        retry = Retry(
+            total=max_retries,
+            backoff_factor=0.5,
+            status_forcelist=(502, 503, 504),
+            allowed_methods=frozenset(["GET", "POST"]),
+            raise_on_status=False,
+        )
+        adapter = HTTPAdapter(max_retries=retry)
+        self._session.mount("https://", adapter)
+        self._session.mount("http://", adapter)
+
+    @staticmethod
+    def _load_config(config: dict | str | Path | None) -> dict:
+        """Normalize the `config=` argument into a plain dict. Accepts a dict, a
+        path to a JSON file (written by save_config), or None. A top-level
+        ``"mode"`` key (save_config metadata) is stripped."""
+        if config is None:
+            return {}
+        if isinstance(config, (str, Path)):
+            config = json.loads(Path(config).read_text())
+        if not isinstance(config, dict):
+            raise TypeError(f"config must be a dict, path, or None (got {type(config).__name__})")
+        return {k: v for k, v in config.items() if k != "mode"}
+
+    @staticmethod
+    def _validate_config(config: dict) -> dict:
+        """Validate a bound config: known field names + valid values. County is
+        allowed but not value-checked here (the server resolves it)."""
+        unknown = set(config) - _KNOWN_CONFIG_KEYS
+        if unknown:
+            raise ValueError(
+                f"unknown config field(s): {sorted(unknown)}. "
+                f"Valid keys: {sorted(_KNOWN_CONFIG_KEYS)}"
+            )
+        # Value-check each field by building the mode model(s) that own it.
+        for mode, model in _MODE_MODELS.items():
+            subset = {k: v for k, v in config.items() if k in model.model_fields}
+            if subset:
+                model(**subset)  # raises on a bad value
+        return dict(config)
+
+    # -- transport ----------------------------------------------------------
+
+    def _request(self, method: str, path: str, *, versioned: bool = True,
+                 json: Any = None, params: Any = None) -> Any:
+        base = self._v1 if versioned else self._root
+        resp = self._session.request(method, base + path, json=json,
+                                     params=params, timeout=self._timeout)
+        self._raise_for_status(resp)
+        try:
+            return resp.json()
+        except ValueError:
+            raise APIError(
+                f"expected JSON from {path} but got "
+                f"{resp.headers.get('content-type')!r}. If base_url is "
+                "humanbaselines.com, only /v1/* is proxied there — use the "
+                "Cloud Run URL for non-/v1 paths like /health.",
+                status_code=resp.status_code, body=resp.text[:200],
+            )
+
+    @staticmethod
+    def _raise_for_status(resp: requests.Response) -> None:
+        if resp.ok:
+            return
+        try:
+            body: Any = resp.json()
+        except ValueError:
+            body = resp.text
+        detail = body.get("detail") if isinstance(body, dict) else body
+        msg = f"{resp.status_code} {resp.reason}: {detail}"
+        exc = {
+            401: AuthenticationError,
+            422: ValidationError,
+            404: NotFoundError,
+            503: ServiceUnavailableError,
+        }.get(resp.status_code, APIError)
+        raise exc(msg, status_code=resp.status_code, body=body)
+
+    def _overrides(self, model_cls, selections, filters: dict) -> dict:
+        """Per-call overrides as a plain dict: kwargs, a dict, or a model's
+        *explicitly-set* fields (so a model's own defaults don't clobber the
+        bound config)."""
+        if selections is not None and filters:
+            raise TypeError("pass either `selections` or filter kwargs, not both")
+        if selections is None:
+            return dict(filters)
+        if isinstance(selections, dict):
+            return dict(selections)
+        if isinstance(selections, model_cls):
+            return selections.model_dump(exclude_unset=True)
+        raise TypeError(
+            f"selections must be a {model_cls.__name__}, dict, or omitted "
+            f"(got {type(selections).__name__})"
+        )
+
+    def _resolve_selections(self, model_cls, selections, filters: dict) -> dict:
+        """Merge the bound config (subset valid for this mode) under the per-call
+        overrides, validate via the mode model, and serialize for the wire."""
+        bound = {k: v for k, v in self._config.items() if k in model_cls.model_fields}
+        overrides = self._overrides(model_cls, selections, filters)
+        # extra="forbid" keeps per-call overrides strict (a bad/foreign field
+        # errors); bound fields were already filtered to this mode.
+        model = model_cls(**{**bound, **overrides})
+        # mode="json" coerces enums to strings; warnings=False silences the
+        # str-vs-Enum default notice (generated defaults are strings, emitted
+        # value is correct).
+        return model.model_dump(mode="json", exclude_none=True, warnings=False)
+
+    def _county(self, county: str | None) -> str:
+        """Per-call county wins, else the bound config's, else the default."""
+        return county or self._config.get("county") or DEFAULT_COUNTY
+
+    @staticmethod
+    def _pin(p: PinLike) -> dict:
+        if isinstance(p, DepotPin):
+            return p.model_dump()
+        if isinstance(p, dict):
+            return DepotPin(**p).model_dump()
+        lat, lon = p  # (lat, lon) tuple/list
+        return {"lat": float(lat), "lon": float(lon)}
+
+    # -- discovery ----------------------------------------------------------
+
+    def filters(self) -> FiltersResponse:
+        """Catalog of every filter, its valid options, and per-mode defaults."""
+        return FiltersResponse.model_validate(self._request("GET", "/filters"))
+
+    def regions(self) -> RegionsResponse:
+        """Counties available on the server and which compute modes each supports."""
+        return RegionsResponse.model_validate(self._request("GET", "/regions"))
+
+    def manifest(self) -> dict:
+        """Dataset metadata (schema version, row counts, availability)."""
+        return self._request("GET", "/manifest")
+
+    def health(self) -> dict:
+        """Service status, e.g. ``{"status": "ready"}``.
+
+        Hits the unversioned ``/health`` endpoint, which is NOT proxied by
+        humanbaselines.com — use a Cloud Run ``base_url`` for this call.
+        """
+        return self._request("GET", "/health", versioned=False)
+
+    # -- compute ------------------------------------------------------------
+
+    def compute(self, selections: GeofenceSelections | dict | None = None, *,
+                county: str | None = None, **filters) -> ComputeResult:
+        """Geofence (S2-cell) crash rate. Inherits the bound config; per-call
+        args override it."""
+        sel = self._resolve_selections(GeofenceSelections, selections, filters)
+        data = self._request("POST", "/compute",
+                             json={"county": self._county(county), "selections": sel})
+        return ComputeResult.model_validate(data)
+
+    def compute_route(self, segment_ids: list[tuple[str, int]],
+                      selections: RouteSelections | dict | None = None, *,
+                      county: str | None = None, **filters) -> RouteComputeResult:
+        """Crash rate over a sequence of interstate (route, milepost) segments.
+        For route-capable regions (``travis``, ``ca_interstates``,
+        ``sw_interstates`` — see ``regions()``). Inherits the bound config;
+        per-call args override it."""
+        sel = self._resolve_selections(RouteSelections, selections, filters)
+        data = self._request("POST", "/compute/route", json={
+            "county": self._county(county),
+            "segment_ids": [list(s) for s in segment_ids],
+            "selections": sel,
+        })
+        return RouteComputeResult.model_validate(data)
+
+    def compute_depot_route(self, depot_a: PinLike, depot_b: PinLike,
+                            selections: DepotSelections | dict | None = None, *,
+                            county: str | None = None, **filters) -> DepotComputeResult:
+        """Full depot-to-depot trip rate (access + interstate + access legs).
+        For depot-capable regions (``travis``, ``ca_interstates``,
+        ``sw_interstates`` — see ``regions()``). Pins are (lat, lon) tuples,
+        DepotPins, or dicts. Inherits the bound config; per-call args override it."""
+        sel = self._resolve_selections(DepotSelections, selections, filters)
+        data = self._request("POST", "/compute/depot-route", json={
+            "county": self._county(county),
+            "depot_a": self._pin(depot_a),
+            "depot_b": self._pin(depot_b),
+            "selections": sel,
+        })
+        return DepotComputeResult.model_validate(data)
+
+    # -- bound config (the baseline "definition") ---------------------------
+
+    def config(self, mode: str = "geofence") -> dict:
+        """The full effective config for a mode — your bound values plus every
+        default filled in, with county. This is the complete definition a
+        compute call in this mode would use."""
+        if mode not in _MODE_MODELS:
+            raise ValueError(f"unknown mode {mode!r}; choose from {sorted(_MODE_MODELS)}")
+        model_cls = _MODE_MODELS[mode]
+        bound = {k: v for k, v in self._config.items() if k in model_cls.model_fields}
+        sel = model_cls(**bound).model_dump(mode="json", warnings=False)
+        return {"county": self._county(None), **sel}
+
+    def changes(self, mode: str = "geofence") -> dict:
+        """Only the settings that differ from this mode's defaults (the
+        deviations), including county if you've changed it."""
+        full = self.config(mode)
+        defaults = _MODE_MODELS[mode]().model_dump(mode="json", warnings=False)
+        defaults["county"] = DEFAULT_COUNTY
+        return {k: v for k, v in full.items() if v != defaults.get(k)}
+
+    def with_config(self, config: dict | None = None, **fields) -> "HumanBaselines":
+        """Return a NEW client with the bound config updated (this one is left
+        unchanged). Per-field merge: ``{**current, **config, **fields}``. The
+        underlying HTTP session is shared."""
+        merged = {**self._config, **(config or {}), **fields}
+        return HumanBaselines(
+            self._api_key, base_url=self._base_url, timeout=self._timeout,
+            max_retries=self._max_retries, session=self._session, config=merged,
+        )
+
+    def save_config(self, path: str | Path, mode: str = "geofence") -> None:
+        """Write the FULL effective config (every default filled in) to a JSON
+        file — a complete, self-documenting snapshot of the definition, not just
+        the deviations. A top-level ``"mode"`` key records which mode's field set
+        it captures. Defaults to geofence; pass ``mode`` for route/depot. Reload
+        with ``from_config``."""
+        payload = {"mode": mode, **self.config(mode)}
+        Path(path).write_text(json.dumps(payload, indent=2) + "\n")
+
+    @classmethod
+    def from_config(cls, source: str | Path | dict, api_key: str | None = None,
+                    **client_kwargs) -> "HumanBaselines":
+        """Explicit alternative constructor from a saved definition (path or
+        dict). Equivalent to ``HumanBaselines(api_key, config=source)`` — the
+        constructor accepts a path directly — kept for readable intent."""
+        return cls(api_key, config=source, **client_kwargs)
+
+    # -- lifecycle ----------------------------------------------------------
+
+    def close(self) -> None:
+        self._session.close()
+
+    def __enter__(self) -> "HumanBaselines":
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        cfg = f", config={self._config}" if self._config else ""
+        return f"HumanBaselines(base_url={self._root!r}{cfg})"

humanbaselines/exceptions.py

@@ -0,0 +1,54 @@
+"""Typed exception hierarchy for the Human Crash Baselines client.
+
+Every non-2xx response is mapped to one of these by status code, so callers can
+catch the specific failure they care about (auth vs. validation vs. warm-up)
+rather than parsing HTTP codes themselves.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class HumanBaselinesError(Exception):
+    """Base class for all client errors."""
+
+
+class APIError(HumanBaselinesError):
+    """A non-2xx HTTP response that isn't covered by a more specific subclass.
+
+    Carries the HTTP `status_code` and the parsed/raw response `body`.
+    """
+
+    def __init__(self, message: str, *, status_code: int | None = None, body: Any = None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.body = body
+
+
+class AuthenticationError(APIError):
+    """401 — missing or invalid API key."""
+
+
+class ValidationError(APIError):
+    """422 — the request failed server-side validation.
+
+    `errors` holds the server's field-level detail (FastAPI's `detail` list)
+    when present, so callers can see exactly which filter was rejected.
+    """
+
+    def __init__(self, message: str, *, status_code: int | None = None, body: Any = None):
+        super().__init__(message, status_code=status_code, body=body)
+        self.errors = body.get("detail") if isinstance(body, dict) else None
+
+
+class NotFoundError(APIError):
+    """404 — unknown route, or a county/resource that isn't loaded."""
+
+
+class ServiceUnavailableError(APIError):
+    """503 — the service is warming up (caches loading) or temporarily down.
+
+    The client retries these automatically before giving up; if you see this,
+    the retries were exhausted.
+    """

humanbaselines/models.py

@@ -0,0 +1,79 @@
+"""Public model surface for the Human Crash Baselines client.
+
+The types are GENERATED from the server's OpenAPI schema into `_generated.py`
+(do not edit that file by hand). The server's Pydantic models
+(`data-prep/server/schemas.py` + `catalog.py`) are the single source of truth;
+regenerate with `scripts/regenerate_models.py` after any API change. At runtime,
+`HumanBaselines.filters()` returns the live catalog of valid values + defaults.
+
+This module just re-exports the generated names the client and public API use
+(notably NOT the generated `ValidationError`/`HTTPValidationError` models, which
+would collide with the client's `ValidationError` *exception*).
+"""
+
+from __future__ import annotations
+
+from ._generated import (  # noqa: F401
+    CiMethod,
+    ComputeResult,
+    DepotComputeResult,
+    DepotPin,
+    DepotSelections,
+    DriverImpairment,
+    FilterDef,
+    FilterOption,
+    FiltersResponse,
+    GeofenceSelections,
+    InTransport,
+    LightFilter,
+    MultiplierVmt,
+    Outcome,
+    PerCellResult,
+    PerSegmentResult,
+    RegionInfo,
+    RegionsResponse,
+    RoadGroup,
+    RoboTaxiWeighting,
+    RouteComputeResult,
+    RouteSelections,
+    Tier3Mode,
+    UnderReporting,
+    VehicleClass,
+    WeatherFilter,
+)
+
+# Client-side constant (not part of the wire schema).
+DEFAULT_COUNTY = "travis"
+
+__all__ = [
+    "DEFAULT_COUNTY",
+    # request models
+    "GeofenceSelections",
+    "RouteSelections",
+    "DepotSelections",
+    "DepotPin",
+    # response models
+    "ComputeResult",
+    "PerCellResult",
+    "RouteComputeResult",
+    "PerSegmentResult",
+    "DepotComputeResult",
+    "FiltersResponse",
+    "FilterDef",
+    "FilterOption",
+    "RegionsResponse",
+    "RegionInfo",
+    # enums
+    "Outcome",
+    "VehicleClass",
+    "RoadGroup",
+    "Tier3Mode",
+    "InTransport",
+    "RoboTaxiWeighting",
+    "MultiplierVmt",
+    "WeatherFilter",
+    "LightFilter",
+    "DriverImpairment",
+    "UnderReporting",
+    "CiMethod",
+]

humanbaselines-0.1.0.dist-info/METADATA

@@ -0,0 +1,217 @@
+Metadata-Version: 2.4
+Name: humanbaselines
+Version: 0.1.0
+Summary: Python client for the Human Crash Baselines API — human-driver crash-rate baselines by region, route, and filter.
+Project-URL: Homepage, https://humanbaselines.com
+Project-URL: Documentation, https://human-baseline-api-yz2u5f75wa-uc.a.run.app/docs
+Project-URL: Repository, https://github.com/valgorithmic/humanbaselines
+Project-URL: Issues, https://github.com/valgorithmic/humanbaselines/issues
+Author: Valgorithmic, Inc.
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: api-client,autonomous-vehicles,baseline,crash,safety
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+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.10
+Requires-Dist: pydantic>=2.9
+Requires-Dist: requests>=2.31
+Provides-Extra: dev
+Requires-Dist: black; extra == 'dev'
+Requires-Dist: datamodel-code-generator>=0.25; extra == 'dev'
+Requires-Dist: isort; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: responses>=0.25; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# humanbaselines
+
+Python client for the **Human Crash Baselines API** — typed access to human-driver
+crash-rate baselines by region, route, and filter.
+
+It wraps the `/v1` REST API: construct a client with your key, call typed methods,
+get typed results back (no hand-built JSON, no remembering the auth header).
+
+## Install
+
+```bash
+pip install humanbaselines
+```
+
+Or install the latest from source:
+
+```bash
+pip install "git+https://github.com/valgorithmic/humanbaselines.git"
+# or, from a checkout:
+pip install .
+```
+
+## Quickstart
+
+```python
+from humanbaselines import HumanBaselines
+
+hb = HumanBaselines(api_key="hbk_...")          # or set HUMANBASELINES_API_KEY
+
+# Geofence crash rate (kwargs are validated client-side):
+r = hb.compute(county="travis", outcome="police_reported", ego_vehicle=["cars", "light_trucks"])
+print(r.rate, r.rate_low, r.rate_high)          # 4.055 4.0 4.1
+print(r.N, r.D_miles, len(r.cells))             # 24617.0 6.07e9 1795
+
+# Discover valid filters + defaults at runtime:
+for f in hb.filters().modes["geofence"]:
+    print(f.id, "→", [o.id for o in f.options], "default:", f.default)
+
+# Which regions / modes are available:
+hb.regions()
+```
+
+### Filters
+
+Pass filters three ways — keyword args (simplest), a typed `Selections` model,
+or a plain dict. All are validated **before** the request, so a bad value fails
+fast locally:
+
+```python
+from humanbaselines import GeofenceSelections, Outcome
+
+hb.compute(outcome="fatal", road_type=["interstate"])           # kwargs
+hb.compute(selections=GeofenceSelections(outcome=Outcome.fatal)) # typed model
+hb.compute(selections={"outcome": "fatal"})                      # dict
+```
+
+Omitted filters fall back to the API's defaults (these reproduce the web UI's
+headline numbers).
+
+### Binding a baseline definition
+
+The filter selections are really a *methodological definition* — what counts as
+a crash and what you're baselining against. Bind that definition to the client
+once and every call inherits it; per-call args override individual fields:
+
+```python
+hb = HumanBaselines(api_key="hbk_...", config={
+    "county": "travis",
+    "outcome": "fatal",
+    "ego_vehicle": ["cars", "light_trucks"],
+})
+
+hb.compute().rate                  # uses the bound definition
+hb.compute(weather=["rain"]).rate  # override just one field for this call
+
+hb.config()                        # full effective config (bound + every default)
+hb.changes()                       # only the settings that differ from the defaults
+```
+
+`config(mode="geofence")` and `changes(mode="geofence")` take an optional mode
+(each mode exposes different fields). `config()` is the complete definition a
+compute call would use; `changes()` is just your deviations from the defaults.
+
+The bound config is validated when you create the client (unknown fields or bad
+values raise immediately). It applies to **all modes** — each compute mode uses
+the subset of fields it understands (e.g. `road_type` only affects geofence,
+`ci_method` only affects route/depot), so you can keep one definition across
+modes.
+
+Derive variants immutably, and version definitions as JSON:
+
+```python
+strict = hb.with_config(under_reporting="adjusted")   # new client; hb is unchanged
+
+hb.save_config("odd_fatal_cars.json")        # full config snapshot (check into a repo, share, diff)
+
+# Load it back — pass the path straight to the constructor:
+hb2 = HumanBaselines(api_key="hbk_...", config="odd_fatal_cars.json")
+# (HumanBaselines.from_config(path, api_key=...) is an equivalent, explicit alias.)
+```
+
+### Route & depot modes
+
+Available for route/depot-capable regions — `travis`, `ca_interstates`, and
+`sw_interstates` (check `hb.regions()`). Route/depot count Class-8 combination
+trucks, so `ego_vehicle` defaults to `["combination"]` in these modes.
+
+```python
+hb.compute_route(segment_ids=[("I-35", 250), ("I-35", 251)], ego_vehicle=["combination"])
+
+hb.compute_depot_route(
+    depot_a=(30.25, -97.75),     # (lat, lon)
+    depot_b=(30.40, -97.70),
+    ci_method="fay_feuer",
+)
+```
+
+## Errors
+
+Non-2xx responses raise typed exceptions you can catch:
+
+```python
+from humanbaselines import AuthenticationError, ValidationError, ServiceUnavailableError
+
+try:
+    hb.compute(outcome="fatal")
+except AuthenticationError:        # 401 — bad/missing key
+    ...
+except ValidationError as e:       # 422 — e.errors has the field-level detail
+    print(e.errors)
+except ServiceUnavailableError:    # 503 — service warming up (auto-retried first)
+    ...
+```
+
+All inherit from `HumanBaselinesError`. The base `APIError` carries `.status_code`
+and `.body`.
+
+## Configuration
+
+| arg | default | notes |
+|---|---|---|
+| `api_key` | `$HUMANBASELINES_API_KEY` | sent as `X-API-Key` |
+| `base_url` | `https://humanbaselines.com` | proxies `/v1/*`; use the Cloud Run URL for `/health` |
+| `timeout` | `30` | seconds per request |
+| `max_retries` | `2` | exponential backoff on 502/503/504 (handles cold-start warm-up) |
+
+`HumanBaselines` is also a context manager (`with HumanBaselines(...) as hb:`).
+
+## Notes
+
+- The typed models in `_generated.py` are **generated from the server's OpenAPI
+  schema** — the server's Pydantic models are the single source of truth, so the
+  client can't drift from the API. `GET /v1/filters` is the authoritative
+  runtime source for valid values and defaults.
+- Interactive API docs: the `/docs` page on the API host.
+
+## Development
+
+```bash
+pip install -e '.[dev]'
+pytest -q                                  # mocked tests
+HUMANBASELINES_API_KEY=hbk_... pytest -q    # also runs the live smoke test
+python -m build                            # build wheel + sdist into dist/
+```
+
+### Regenerating models after an API change
+
+`src/humanbaselines/_generated.py` is generated — never hand-edit it. When the
+API contract changes, regenerate from the live OpenAPI schema:
+
+```bash
+python scripts/regenerate_models.py
+# point at a different host (e.g. local dev server):
+python scripts/regenerate_models.py --url http://localhost:8000
+```
+
+This fetches `<host>/openapi.json` (default `https://humanbaselines.com`) and runs
+`datamodel-code-generator`. Output is deterministic (no timestamps), so a clean
+`git diff` means the client is in sync with the API.
+
+> Releases are automated: a version bump in the upstream app dispatches a release
+> here, which tags `v<version>` and publishes to PyPI via Trusted Publishing.
+
+## License
+
+Apache-2.0 © Valgorithmic, Inc.

humanbaselines-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+humanbaselines/__init__.py,sha256=YGSflu-H3u-yFcA6IXSXcXpSuDbeZkA8JCBZ-FvLudY,1838
+humanbaselines/_generated.py,sha256=Dm8k72efzZbAZ2dppygxKpPr7X4UUVHOAL9gqskKDuo,9288
+humanbaselines/client.py,sha256=o5dIMCRnzrhOwdmY7-xgdyYhCOceo56r1bXR7EkUzAc,15406
+humanbaselines/exceptions.py,sha256=BayZg5_90puqMw6uqGe4Ye93kZpU5wgoiFHyKMb2Rtc,1726
+humanbaselines/models.py,sha256=Ii3Hk5tvoAeN3Pb9uzIX9ejk9Mn9IFUU5NAEyz7gna4,1957
+humanbaselines-0.1.0.dist-info/METADATA,sha256=U8UQnS1N3l7qBVaBwKjaX4hYBnMy8K7zrFM4D8ExUjY,7792
+humanbaselines-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+humanbaselines-0.1.0.dist-info/licenses/LICENSE,sha256=4WsjIy3F9zrydiFym1_-cMYcAirPXlB6BJUOiY1ZT_c,10339
+humanbaselines-0.1.0.dist-info/RECORD,,

humanbaselines-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

humanbaselines-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,184 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship made available under
+      the License, as indicated by a copyright notice that is included in
+      or attached to the work (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other transformations
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean, as submitted to the Licensor for inclusion
+      in the Work by the copyright owner or by an individual or Legal Entity
+      authorized to submit on behalf of the copyright owner. For the purposes
+      of this definition, "submitted" means any form of electronic, verbal, or
+      written communication sent to the Licensor or its representatives,
+      including but not limited to communication on electronic mailing lists,
+      source code control systems, and issue tracking systems that are managed
+      by, or on behalf of, the Licensor for the purpose of discussing and
+      improving the Work, but excluding communication that is conspicuously
+      marked or designated in writing by the copyright owner as "Not a
+      Contribution."
+
+      "Contributor" shall mean Licensor and any Legal Entity on behalf of
+      whom a Contribution has been received by the Licensor and included
+      within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by the combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, You must include a readable copy of the
+          attribution notices contained within such NOTICE file, in
+          at least one of the following places: within a NOTICE text
+          file distributed as part of the Derivative Works; within
+          the Source form or documentation, if provided along with the
+          Derivative Works; or, within a display generated by the
+          Derivative Works, if and wherever such third-party notices
+          normally appear. The contents of the NOTICE file are for
+          informational purposes only and do not modify the License.
+          You may add Your own attribution notices within Derivative
+          Works that You distribute, alongside or as an addendum to
+          the NOTICE text from the Work, provided that such additional
+          attribution notices cannot be construed as modifying the License.
+
+      You may add Your own license statement for Your modifications and
+      may provide additional grant of rights to use, copy, modify, merge,
+      publish, distribute, sublicense, and/or sell copies of the
+      Derivative Works, and to permit persons to whom the Derivative Works
+      is furnished to do so, subject to the following conditions:
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or reproducing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or exemplary damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or all other
+      commercial damages or losses), even if such Contributor has been
+      advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may offer, and charge a
+      fee for, acceptance of support, warranty, indemnity, or other
+      liability obligations and/or rights consistent with this License.
+      However, in accepting such obligations, You may offer such obligations
+      only on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 Valgorithmic, Inc. (d.b.a. Valgo)
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.