semra 0.1.0.dev0__tar.gz → 0.1.2__tar.gz

{semra-0.1.0.dev0 → semra-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: semra
-Version: 0.1.0.dev0
+Version: 0.1.2
 Summary: Semantic mapping reasoner and assembler
 Keywords: snekpack,cookiecutter,sssom,semantic mappings,ontology merging,ontology mappings
 Author: Charles Tapley Hoyt
@@ -29,7 +29,7 @@ Requires-Dist: tqdm
 Requires-Dist: more-itertools
 Requires-Dist: networkx
 Requires-Dist: bioregistry>=0.12.7
-Requires-Dist: pyobo>=0.12.0
+Requires-Dist: pyobo>=0.12.1
 Requires-Dist: bioontologies>=0.7.0
 Requires-Dist: typing-extensions
 Requires-Dist: zenodo-client
@@ -52,7 +52,8 @@ Requires-Dist: matplotlib ; extra == 'landscape-notebooks'
 Requires-Dist: pygraphviz ; extra == 'landscape-notebooks'
 Requires-Dist: pytest ; extra == 'tests'
 Requires-Dist: coverage[toml] ; extra == 'tests'
-Requires-Dist: sssom ; extra == 'tests'
+Requires-Dist: sssom>=0.4.16 ; extra == 'tests'
+Requires-Dist: httpx ; extra == 'tests'
 Requires-Dist: fastapi ; extra == 'web'
 Requires-Dist: uvicorn ; extra == 'web'
 Requires-Dist: flask ; extra == 'web'

{semra-0.1.0.dev0 → semra-0.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "semra"
-version = "0.1.0-dev"
+version = "0.1.2"
 description = "Semantic mapping reasoner and assembler"
 readme = "README.md"
 authors = [
@@ -58,7 +58,7 @@ dependencies = [
     "more_itertools",
     "networkx",
     "bioregistry>=0.12.7",
-    "pyobo>=0.12.0",
+    "pyobo>=0.12.1",
     "bioontologies>=0.7.0",
     "typing_extensions",
     "zenodo_client",
@@ -73,7 +73,8 @@ dependencies = [
 tests = [
     "pytest",
     "coverage[toml]",
-    "sssom",
+    "sssom>=0.4.16",
+    "httpx",
 ]
 docs = [
     "sphinx>=8",
@@ -225,7 +226,7 @@ known-first-party = [
 docstring-code-format = true
 
 [tool.bumpversion]
-current_version = "0.1.0-dev"
+current_version = "0.1.2"
 parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)(?:-(?P<release>[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*))?(?:\\+(?P<build>[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*))?"
 serialize = [
     "{major}.{minor}.{patch}-{release}+{build}",

{semra-0.1.0.dev0 → semra-0.1.2}/src/semra/client.py

@@ -2,10 +2,12 @@
 
 from __future__ import annotations
 
+import dataclasses
 import os
 import typing as t
 from collections import Counter
-from typing import Any, TypeAlias, cast
+from textwrap import dedent
+from typing import Any, NamedTuple, TypeAlias, cast
 
 import bioregistry
 import neo4j
@@ -13,6 +15,7 @@ import neo4j.graph
 import networkx as nx
 import pydantic
 from neo4j import ManagedTransaction, unit_of_work
+from typing_extensions import Self
 
 import semra
 from semra import Evidence, MappingSet, Reference, SimpleEvidence
@@ -24,11 +27,12 @@ from semra.rules import (
 )
 
 __all__ = [
+    "BaseClient",
+    "FullSummary",
     "Neo4jClient",
     "Node",
 ]
 
-
 Node: TypeAlias = t.Mapping[str, Any]
 
 TxResult: TypeAlias = list[list[Any]] | None
@@ -53,10 +57,125 @@ RELATIONS_CYPHER = "CALL db.relationshipTypes() YIELD relationshipType RETURN re
 CONCEPT_NAME_CYPHER = "MATCH (n:concept) WHERE n.curie = $curie RETURN n.name LIMIT 1"
 
 
-class Neo4jClient:
-    """A client to Neo4j."""
+class BaseClient:
+    """An abstract class defining all of the functionality for a mapping client."""
+
+    def get_mapping(self, curie: ReferenceHint) -> semra.Mapping | None:
+        """Get a mapping.
+
+        :param curie: Either a Reference object, a string representing a curie with
+            ``semra.mapping`` as the prefix, or a local unique identifier representing a
+            SeMRA mapping.
+
+        :returns: A semantic mapping object
+        """
+        raise NotImplementedError
+
+    def get_mapping_sets(self) -> list[MappingSet]:
+        """Get all mappings sets."""
+        raise NotImplementedError
 
-    _session: neo4j.Session | None = None
+    def get_mapping_set(self, curie: ReferenceHint) -> MappingSet | None:
+        """Get a mappings set.
+
+        :param curie: The CURIE for a mapping set, using ``semra.mappingset`` as a
+            prefix. For example, use
+            ``semra.mappingset:7831d5bc95698099fb6471667e5282cd`` for biomappings
+
+        :returns: A mapping set object
+        """
+        raise NotImplementedError
+
+    def get_evidence(self, curie: ReferenceHint) -> Evidence | None:
+        """Get an evidence.
+
+        :param curie: The CURIE for a mapping set, using ``semra.evidence`` as a prefix.
+
+        :returns: An evidence object
+        """
+        raise NotImplementedError
+
+    def summarize_predicates(self) -> t.Counter[str]:
+        """Get a counter of predicates."""
+        raise NotImplementedError
+
+    def summarize_justifications(self) -> t.Counter[str]:
+        """Get a counter of mapping justifications."""
+        raise NotImplementedError
+
+    def summarize_evidence_types(self) -> t.Counter[str]:
+        """Get a counter of evidence types."""
+        raise NotImplementedError
+
+    def summarize_mapping_sets(self) -> t.Counter[str]:
+        """Get the number of evidences in each mapping set."""
+        raise NotImplementedError
+
+    def summarize_nodes(self) -> t.Counter[str]:
+        """Get a counter of node types (concepts, evidences, mappings, mapping sets)."""
+        raise NotImplementedError
+
+    def summarize_concepts(self) -> t.Counter[tuple[str, str]]:
+        """Get a counter of prefixes in concept nodes."""
+        raise NotImplementedError
+
+    def summarize_authors(self) -> t.Counter[tuple[str, str]]:
+        """Get a counter of the number of evidences each author has contributed to."""
+        raise NotImplementedError
+
+    def get_highest_exact_matches(self, limit: int = 10) -> t.Counter[tuple[str, str]]:
+        """Get a counter of concepts with the highest exact matches.
+
+        :param limit: The number of top concepts to return
+
+        :returns: A counter with keys that are CURIE/name pairs
+        """
+        raise NotImplementedError
+
+    def get_exact_matches(
+        self, curie: ReferenceHint, *, max_distance: int | None = None
+    ) -> dict[Reference, str] | None:
+        """Get a mapping of references->name for all concepts equivalent to the given concept."""
+        raise NotImplementedError
+
+    def get_connected_component_graph(self, curie: ReferenceHint) -> nx.MultiDiGraph | None:
+        """Get a networkx MultiDiGraph representing the connected component of mappings around the given CURIE.
+
+        :param curie: A CURIE string or reference
+
+        :returns: A networkx MultiDiGraph where mappings subject CURIE strings are th
+        """
+        raise NotImplementedError
+
+    def get_concept_name(self, curie: ReferenceHint) -> str | None:
+        """Get the name for a CURIE or reference."""
+        raise NotImplementedError
+
+    def sample_mappings_from_set(self, curie: ReferenceHint, n: int = 10) -> list[ExampleMapping]:
+        """Get n mappings from a given set (by CURIE)."""
+        raise NotImplementedError
+
+    def get_example_mappings(self) -> list[ExampleMapping]:
+        """Get example mappings."""
+        raise NotImplementedError
+
+    def get_full_summary(self) -> FullSummary:
+        """Get a full summary."""
+        return FullSummary(
+            PREDICATE_COUNTER=self.summarize_predicates(),
+            MAPPING_SET_COUNTER=self.summarize_mapping_sets(),
+            NODE_COUNTER=self.summarize_nodes(),
+            JUSTIFICATION_COUNTER=self.summarize_justifications(),
+            EVIDENCE_TYPE_COUNTER=self.summarize_evidence_types(),
+            PREFIX_COUNTER=self.summarize_concepts(),
+            AUTHOR_COUNTER=self.summarize_authors(),
+            HIGH_MATCHES_COUNTER=self.get_highest_exact_matches(),
+            example_mappings=self.get_example_mappings(),
+        )
+
+
+class Neo4jClient(BaseClient):
+    """A client to Neo4j."""
 
     def __init__(
         self,
@@ -86,6 +205,7 @@ class Neo4jClient:
             for reference in RELATIONS
             if reference.curie in self._all_relations
         )
+        self._summary = None
 
     def __del__(self) -> None:
         """Ensure driver is shut down when client is destroyed."""
@@ -142,7 +262,7 @@ class Neo4jClient:
         res = self.read_query(query, curie=curie)
         return cast(Node, res[0][0])
 
-    def get_mapping(self, curie: ReferenceHint) -> semra.Mapping:
+    def get_mapping(self, curie: ReferenceHint) -> semra.Mapping | None:
         """Get a mapping.
 
         :param curie: Either a Reference object, a string representing a curie with
@@ -197,7 +317,7 @@ class Neo4jClient:
         records = self.read_query(query)
         return [MappingSet.model_validate(record) for (record,) in records]
 
-    def get_mapping_set(self, curie: ReferenceHint) -> MappingSet:
+    def get_mapping_set(self, curie: ReferenceHint) -> MappingSet | None:
         """Get a mappings set.
 
         :param curie: The CURIE for a mapping set, using ``semra.mappingset`` as a
@@ -210,7 +330,7 @@ class Neo4jClient:
         node = self._get_node_by_curie(curie, "mappingset")
         return MappingSet.model_validate(node)
 
-    def get_evidence(self, curie: ReferenceHint) -> Evidence:
+    def get_evidence(self, curie: ReferenceHint) -> Evidence | None:
         """Get an evidence.
 
         :param curie: The CURIE for a mapping set, using ``semra.evidence`` as a prefix.
@@ -220,7 +340,7 @@ class Neo4jClient:
         curie = _safe_curie(curie, SEMRA_EVIDENCE_PREFIX)
         query = "MATCH (n:evidence {curie: $curie}) RETURN n"
         res = self.read_query(query, curie=curie)
-        return SimpleEvidence.model_validate(res[0][0])  # FIXME test this?
+        return SimpleEvidence.model_validate(res[0][0])
 
     def summarize_predicates(self) -> t.Counter[str]:
         """Get a counter of predicates."""
@@ -292,7 +412,7 @@ as label, count UNION ALL
 
     def get_exact_matches(
         self, curie: ReferenceHint, *, max_distance: int | None = None
-    ) -> dict[Reference, str]:
+    ) -> dict[Reference, str] | None:
         """Get a mapping of references->name for all concepts equivalent to the given concept."""
         if isinstance(curie, Reference):
             curie = curie.curie
@@ -348,7 +468,7 @@ as label, count UNION ALL
         relations = [r[0] for r in self.read_query(edge_query, curies=sorted(component_curies))]
         return nodes, relations
 
-    def get_connected_component_graph(self, curie: ReferenceHint) -> nx.MultiDiGraph:
+    def get_connected_component_graph(self, curie: ReferenceHint) -> nx.MultiDiGraph | None:
         """Get a networkx MultiDiGraph representing the connected component of mappings around the given CURIE.
 
         :param curie: A CURIE string or reference
@@ -364,8 +484,8 @@ as label, count UNION ALL
                 g.add_edge(
                     path.start_node["curie"],
                     path.end_node["curie"],
-                    key=relationship.id,
-                    type=relationship.type,
+                    key=relationship.id,  # this is the mapping's CURIE
+                    type=relationship.type,  # this is the predicate CURIE
                 )
         return g
 
@@ -380,9 +500,7 @@ as label, count UNION ALL
         else:
             return cast(str, name)
 
-    def sample_mappings_from_set(
-        self, curie: ReferenceHint, n: int = 10
-    ) -> list[tuple[str, str, str, str, str, str]]:
+    def sample_mappings_from_set(self, curie: ReferenceHint, n: int = 10) -> list[ExampleMapping]:
         """Get n mappings from a given set (by CURIE)."""
         if isinstance(curie, Reference):
             curie = curie.curie
@@ -397,7 +515,58 @@ as label, count UNION ALL
         RETURN n.curie, n.predicate, s.curie, s.name, t.curie, t.name
         LIMIT {n}
         """
-        return list(self.read_query(query, curie=curie))  # type:ignore
+        return [ExampleMapping(*row) for row in self.read_query(query, curie=curie)]
+
+    def get_example_mappings(self) -> list[ExampleMapping]:
+        """Get example mappings."""
+        return [ExampleMapping(*row) for row in self.read_query(EXAMPLE_MAPPINGS_QUERY)]
+
+
+EXAMPLE_MAPPINGS_QUERY = dedent("""\
+    MATCH
+        (t:concept)<-[`owl:annotatedTarget`]-(n:mapping)-[`owl:annotatedSource`]->(s:concept)
+    WHERE n.predicate = 'skos:exactMatch'
+    RETURN n.curie, n.predicate, s.curie, s.name, t.curie, t.name
+    LIMIT 5
+""")
+
+
+class ExampleMapping(NamedTuple):
+    """Example mapping."""
+
+    mapping_curie: str
+    predicate: str
+    subject_curie: str
+    subject_name: str
+    object_curie: str
+    object_name: str
+
+    @classmethod
+    def from_mapping(cls, mapping: semra.Mapping) -> Self:
+        """Get from a mapping."""
+        return cls(
+            mapping.curie,
+            mapping.predicate.curie,
+            mapping.subject.curie,
+            mapping.subject.name or "",
+            mapping.object.curie,
+            mapping.object.name or "",
+        )
+
+
+@dataclasses.dataclass
+class FullSummary:
+    """A full summary object."""
+
+    PREDICATE_COUNTER: t.Counter[str] = dataclasses.field(default_factory=t.Counter)
+    MAPPING_SET_COUNTER: t.Counter[str] = dataclasses.field(default_factory=t.Counter)
+    NODE_COUNTER: t.Counter[str] = dataclasses.field(default_factory=t.Counter)
+    JUSTIFICATION_COUNTER: t.Counter[str] = dataclasses.field(default_factory=t.Counter)
+    EVIDENCE_TYPE_COUNTER: t.Counter[str] = dataclasses.field(default_factory=t.Counter)
+    PREFIX_COUNTER: t.Counter[tuple[str, str]] = dataclasses.field(default_factory=t.Counter)
+    AUTHOR_COUNTER: t.Counter[tuple[str, str]] = dataclasses.field(default_factory=t.Counter)
+    HIGH_MATCHES_COUNTER: t.Counter[tuple[str, str]] = dataclasses.field(default_factory=t.Counter)
+    example_mappings: list[ExampleMapping] = dataclasses.field(default_factory=list)
 
 
 # Follows example here:

{semra-0.1.0.dev0 → semra-0.1.2}/src/semra/database.py

@@ -14,11 +14,10 @@ import pystow
 import requests
 from bioontologies.obograph import write_warned
 from bioontologies.robot import write_getter_warnings
-from curies.vocabulary import charlie
 from pyobo.getters import NoBuildError
 from tqdm.auto import tqdm
 from tqdm.contrib.logging import logging_redirect_tqdm
-from zenodo_client import Creator, Metadata, ensure_zenodo
+from zenodo_client import update_zenodo
 
 from semra import Mapping
 from semra.io import from_jsonl, from_pyobo, write_jsonl, write_neo4j, write_sssom
@@ -26,6 +25,7 @@ from semra.io.io_utils import safe_open_writer
 from semra.pipeline import REFRESH_SOURCE_OPTION, UPLOAD_OPTION
 from semra.sources import SOURCE_RESOLVER
 from semra.sources.wikidata import get_wikidata_mappings_by_prefix
+from semra.utils import gzip_path
 
 MODULE = pystow.module("semra", "database")
 SOURCES = MODULE.module("sources")
@@ -133,32 +133,25 @@ def build(
     )
     mappings = write_jsonl(mappings, JSONL_PATH, stream=True)
     mappings = write_sssom(mappings, SSSOM_PATH, add_labels=False, prune=False, stream=True)
-    # neo4j doesn't need to stream since it's last
-    write_neo4j(mappings, NEO4J_DIR)
+    # neo4j doesn't need to stream since it's last. to avoid SIGKILLs,
+    # write the file to disk, then compress after.
+    write_neo4j(mappings, NEO4J_DIR, compress="after")
+
+    # gzip these after the fact to avoid SIGKILLs
+    jsonl_gz_path = gzip_path(JSONL_PATH)
+    sssom_gz_path = gzip_path(SSSOM_PATH)
 
     if upload:
-        # Define the metadata that will be used on initial upload
-        zenodo_metadata = Metadata(
-            title="SeMRA Mapping Database",
-            upload_type="dataset",
-            description=f"A compendium of mappings extracted from {len(summaries)} database/ontologies. "
-            f"Note that primary mappings are marked with the license of their source (when available). "
-            f"Inferred mappings are distributed under the CC0 license.",
-            creators=[
-                Creator(name="Hoyt, Charles Tapley", orcid=charlie.identifier),
-            ],
-        )
-        res = ensure_zenodo(
-            key="semra-database-test-1",
-            data=zenodo_metadata,
+        res = update_zenodo(
+            deposition_id="11082038",
             paths=[
-                SSSOM_PATH,
+                jsonl_gz_path,
+                sssom_gz_path,
                 WARNINGS_PATH,
                 ERRORS_PATH,
                 SUMMARY_PATH,
                 *NEO4J_DIR.iterdir(),
             ],
-            sandbox=True,
         )
         click.echo(res.json()["links"]["html"])
 

{semra-0.1.0.dev0 → semra-0.1.2}/src/semra/io/io.py

@@ -11,13 +11,9 @@ from collections.abc import Generator, Iterable
 from pathlib import Path
 from typing import Any, Literal, NamedTuple, TextIO, TypeVar, cast, overload
 
-import bioontologies
 import bioregistry
-import bioversions
 import pandas as pd
 import pydantic
-import pyobo
-import pyobo.utils
 import requests
 import yaml
 from tqdm.autonotebook import tqdm
@@ -55,14 +51,6 @@ DEFAULT_ONTOLOGY_CONFIDENCE = 0.9
 X = TypeVar("X", bound=pydantic.BaseModel)
 
 
-def _safe_get_version(prefix: str) -> str | None:
-    """Get a version from Bioversions, or return None if not possible."""
-    try:
-        return bioversions.get_version(prefix)
-    except (KeyError, TypeError):
-        return None
-
-
 # TODO delete this
 def from_cache_df(
     path: str | Path,
@@ -146,6 +134,8 @@ def from_pyobo(
 
     :returns: A list of semantic mapping objects
     """
+    import pyobo
+
     df: pd.DataFrame = pyobo.get_mappings_df(
         prefix, force_process=force_process, names=False, cache=cache
     )
@@ -172,6 +162,7 @@ def _from_pyobo_sssom_df(
     license: str | None = None,
     justification: Reference | None = None,
     mapping_set_name: str | None = None,
+    mapping_set_title: str | None = None,
 ) -> list[Mapping]:
     """Get mappings from a :mod:`pyobo`-flavored cache file.
 
@@ -203,18 +194,22 @@ def _from_pyobo_sssom_df(
         confidence = DEFAULT_ONTOLOGY_CONFIDENCE
     if license is None:
         license = bioregistry.get_license(prefix)
-    if mapping_set_name is None:
-        mapping_set_name = bioregistry.get_name(prefix)
+    if mapping_set_name is not None:
+        if mapping_set_title:
+            raise ValueError
+        mapping_set_title = mapping_set_name
+    if mapping_set_title is None:
+        mapping_set_title = bioregistry.get_name(prefix)
     if prefixes:
         df = _filter_sssom_by_prefixes(df, prefixes)
     return from_sssom_df(
         df,
         standardize=standardize,
         license=license,
-        version=version,
         justification=justification,
         mapping_set_confidence=confidence,
-        mapping_set_name=mapping_set_name,  # TODO rename to mapping_set_title align with SSSOM
+        mapping_set_title=mapping_set_title,
+        mapping_set_version=version,
     )
 
 
@@ -234,6 +229,8 @@ def from_bioontologies(
     prefix: str, confidence: float | None = None, **kwargs: Any
 ) -> list[Mapping]:
     """Get mappings from a given ontology via :mod:`bioontologies`."""
+    import bioontologies
+
     if confidence is None:
         confidence = DEFAULT_ONTOLOGY_CONFIDENCE
     o = bioontologies.get_obograph_by_prefix(prefix, **kwargs)
@@ -734,12 +731,12 @@ def _write_sssom_stream(
     mappings: Iterable[Mapping], file: str | Path | TextIO, *, stream: bool = False
 ) -> Generator[Mapping] | None:
     fallback_mapping_set_id = _get_fallback_mapping_set_id()
-    with safe_open_writer(file) as writer:
-        writer.writerow(SSSOM_DEFAULT_COLUMNS)
-        it = tqdm(mappings, desc="Writing SSSOM", leave=False, unit="mapping", unit_scale=True)
-        if stream:
-            return _stream_write_sssom(writer, it, fallback_mapping_set_id)
-        else:
+    it = tqdm(mappings, desc="Writing SSSOM", leave=False, unit="mapping", unit_scale=True)
+    if stream:
+        return _stream_write_sssom(file, it, fallback_mapping_set_id)
+    else:
+        with safe_open_writer(file) as writer:
+            writer.writerow(SSSOM_DEFAULT_COLUMNS)
             for mapping in it:
                 for evidence in mapping.evidence:
                     writer.writerow(_get_sssom_row(mapping, evidence, fallback_mapping_set_id))
@@ -747,12 +744,14 @@ def _write_sssom_stream(
 
 
 def _stream_write_sssom(
-    writer: Any, mappings: Iterable[Mapping], fallback_mapping_set_id: str
+    path: str | Path | TextIO, mappings: Iterable[Mapping], fallback_mapping_set_id: str
 ) -> Generator[Mapping]:
-    for mapping in mappings:
-        for evidence in mapping.evidence:
-            writer.writerow(_get_sssom_row(mapping, evidence, fallback_mapping_set_id))
-        yield mapping
+    with safe_open_writer(path) as writer:
+        writer.writerow(SSSOM_DEFAULT_COLUMNS)
+        for mapping in mappings:
+            for evidence in mapping.evidence:
+                writer.writerow(_get_sssom_row(mapping, evidence, fallback_mapping_set_id))
+            yield mapping
 
 
 def write_pickle(mappings: list[Mapping], path: str | Path) -> None:
@@ -811,19 +810,20 @@ def write_jsonl(
         unit_scale=True,
         disable=not show_progress,
     )
-    with safe_open(path, read=False) as file:
-        if stream:
-            return _stream_write_jsonl(models, file)
-        else:
+    if stream:
+        return _stream_write_jsonl(models, path)
+    else:
+        with safe_open(path, read=False) as file:
             for model in models:
                 file.write(f"{model.model_dump_json(exclude_none=True)}\n")
-            return None
+        return None
 
 
-def _stream_write_jsonl(models: Iterable[X], file: TextIO) -> Generator[X]:
-    for model in models:
-        file.write(f"{model.model_dump_json(exclude_none=True)}\n")
-        yield model
+def _stream_write_jsonl(models: Iterable[X], path: str | Path) -> Generator[X]:
+    with safe_open(path, read=False) as file:
+        for model in models:
+            file.write(f"{model.model_dump_json(exclude_none=True)}\n")
+            yield model
 
 
 # docstr-coverage:excused `overload`
@@ -841,25 +841,45 @@ def from_jsonl(
 
 
 def from_jsonl(
-    path: str | Path, *, show_progress: bool = False, stream: bool = False
+    path: str | Path,
+    *,
+    show_progress: bool = False,
+    stream: bool = False,
+    failure_action: Literal["raise", "skip"] = "skip",
 ) -> list[Mapping] | Generator[Mapping]:
     """Read a list of Mapping objects from a JSONL file."""
-    rv = _iter_read_jsonl(path, show_progress=show_progress)
+    rv = _iter_read_jsonl(path, show_progress=show_progress, failure_action=failure_action)
     if stream:
         return rv
     else:
         return list(rv)
 
 
-def _iter_read_jsonl(path: str | Path, *, show_progress: bool = False) -> Generator[Mapping]:
+def _iter_read_jsonl(
+    path: str | Path,
+    *,
+    show_progress: bool = False,
+    failure_action: Literal["raise", "skip"] = "skip",
+) -> Generator[Mapping]:
     """Stream mapping objects from a JSONL file."""
     with safe_open(path, read=True) as file:
-        for line in tqdm(
-            file,
-            desc="Reading mappings",
-            leave=False,
-            unit="mapping",
-            unit_scale=True,
-            disable=not show_progress,
+        for i, line in enumerate(
+            tqdm(
+                file,
+                desc="Reading mappings",
+                leave=False,
+                unit="mapping",
+                unit_scale=True,
+                disable=not show_progress,
+            )
         ):
-            yield Mapping.model_validate_json(line.strip())
+            try:
+                yv = Mapping.model_validate_json(line.strip())
+            except pydantic.ValidationError:
+                if failure_action == "raise":
+                    raise
+                else:
+                    logger.debug("[line:%d] failed to parse JSON", i)
+                    continue
+            else:
+                yield yv