Normalization

Scientific-name normalization helpers.

Modules:

Name	Description
gbif	Resolve scientific names against the GBIF Species Match API.
cli	Normalize names in JSON Lines files from the command line.

normalize_spezies(name, min_confidence=None, query_param=DEFAULT_QUERY_PARAM, response_fields=None)

Resolve a species name to GBIF's canonical name.

Parameters:

Name	Type	Description	Default
name	str	Species name to resolve.	required
min_confidence	int | None	Optional minimum GBIF match confidence percentage required to return a name.	None
query_param	str	Query parameter name used to send name to GBIF.	DEFAULT_QUERY_PARAM
response_fields	list[str] | None	List of GBIF response fields to return. If not provided, all fields will be returned.	None

Returns:

Type	Description
dict[str, Any] | None	A dictionary containing the requested GBIF response fields, or None if no match is found or the
dict[str, Any] | None	match does not meet min_confidence.

Raises:

Type	Description
ValueError	If min_confidence is not between 0 and 100, inclusive.
ValueError	If GBIF returns an invalid match response.
RequestException	If the GBIF Species Match API request fails.
HTTPError	If the GBIF Species Match API returns a non-200 status code.

Source code in src/kibad_llm/normalization/gbif.py

def normalize_spezies(
    name: str,
    min_confidence: int | None = None,
    query_param: str = DEFAULT_QUERY_PARAM,
    response_fields: list[str] | None = None,
) -> dict[str, Any] | None:
    """Resolve a species name to GBIF's canonical name.

    Args:
        name: Species name to resolve.
        min_confidence: Optional minimum GBIF match confidence percentage required to return a name.
        query_param: Query parameter name used to send `name` to GBIF.
        response_fields: List of GBIF response fields to return. If not provided, all fields will be returned.

    Returns:
        A dictionary containing the requested GBIF response fields, or `None` if no match is found or the
        match does not meet `min_confidence`.

    Raises:
        ValueError: If `min_confidence` is not between 0 and 100, inclusive.
        ValueError: If GBIF returns an invalid match response.
        requests.RequestException: If the GBIF Species Match API request fails.
        requests.HTTPError: If the GBIF Species Match API returns a non-200 status code.
    """
    _validate_min_confidence(min_confidence)

    response = requests.get(
        GBIF_SPECIES_MATCH_URL,
        params={query_param: name},
        timeout=10,
    )
    response.raise_for_status()
    result = response.json()

    return _normalize_match_result(result, min_confidence, response_fields)

normalize_spezies_batch(names, min_confidence=None, query_param=DEFAULT_QUERY_PARAM, response_fields=None)

Resolve scientific names to GBIF's canonical names in one request.

Parameters:

Name	Type	Description	Default
names	list[str]	Scientific names to resolve. GBIF accepts up to 1,000 names per request.	required
min_confidence	int | None	Optional minimum GBIF match confidence percentage required to return a name.	None
query_param	str	Request-object field name used to send each scientific name to GBIF.	DEFAULT_QUERY_PARAM
response_fields	list[str] | None	List of GBIF response fields to return. If empty, all fields will be returned.	None

Returns:

Type	Description
list[dict[str, Any] | None]	A list of dictionaries containing the requested GBIF response fields, or None for names that
list[dict[str, Any] | None]	have no match or do not meet min_confidence. The order of the returned list matches the order of
list[dict[str, Any] | None]	the input names.

Raises:

Type	Description
ValueError	If min_confidence is not between 0 and 100, inclusive.
ValueError	If GBIF returns an invalid batch match response.
RequestException	If the GBIF Species Match API request fails.
HTTPError	If the GBIF Species Match API returns a non-200 status code.

Source code in src/kibad_llm/normalization/gbif.py

def normalize_spezies_batch(
    names: list[str],
    min_confidence: int | None = None,
    query_param: str = DEFAULT_QUERY_PARAM,
    response_fields: list[str] | None = None,
) -> list[dict[str, Any] | None]:
    """Resolve scientific names to GBIF's canonical names in one request.

    Args:
        names: Scientific names to resolve. GBIF accepts up to 1,000 names per request.
        min_confidence: Optional minimum GBIF match confidence percentage required to return a name.
        query_param: Request-object field name used to send each scientific name to GBIF.
        response_fields: List of GBIF response fields to return. If empty, all fields will be returned.

    Returns:
        A list of dictionaries containing the requested GBIF response fields, or `None` for names that
        have no match or do not meet `min_confidence`. The order of the returned list matches the order of
        the input `names`.

    Raises:
        ValueError: If `min_confidence` is not between 0 and 100, inclusive.
        ValueError: If GBIF returns an invalid batch match response.
        requests.RequestException: If the GBIF Species Match API request fails.
        requests.HTTPError: If the GBIF Species Match API returns a non-200 status code.
    """
    if len(names) > 1000:
        raise ValueError(
            f"Too many Scientific names to resolve ({len(names)}). GBIF accepts up to 1,000 names per request."
        )

    _validate_min_confidence(min_confidence)

    response = requests.post(
        GBIF_SPECIES_BATCH_MATCH_URL,
        json=[{query_param: name} for name in names],
        timeout=10,
    )
    response.raise_for_status()
    results = response.json()

    if not isinstance(results, list) or len(results) != len(names):
        raise ValueError("GBIF returned an invalid batch match response")

    return [_normalize_match_result(result, min_confidence, response_fields) for result in results]