moca-reader 0.6.0__py3-none-any.whl

moca_reader/embedders.py

@@ -0,0 +1,224 @@
+"""MOCA's standard embedding models (sidecar index specification §5.1), run locally, as Reader embedders.
+
+An index built with one of them (``moca-index build --model``) and a question embedded with the same one match,
+whichever tool did each: this Reader, the TypeScript and .NET Readers, or the MOCA MCP server. Each model is a local
+ONNX file pinned by Hugging Face commit and SHA-256, run with the convention every tool shares: the role's prefix, the
+model's own tokenizer cut as Hugging Face's Python tokenizer cuts (the start token, the first tokens that fit, the end
+token), one text per run (the 8-bit files quantize activations per run), then CLS or mean pooling and unit length.
+
+The files live in a model store, one folder per model: ``~/.moca/models``, or ``MOCA_MODELS``. This module never
+downloads: install a model with ``npx @openmoca/moca-embed models add <model>`` or ``moca-mcp models add <model>``.
+It needs the ``onnx`` extra: ``pip install "moca-reader[onnx]"``.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+ONNX_FILE = "onnx/model_quantized.onnx"
+
+
+@dataclass(frozen=True)
+class StandardModel:
+    """One standard model: its short id, the name and version an index records, and how it is run."""
+
+    id: str
+    name: str
+    version: str
+    dimensions: int
+    pooling: str
+    max_tokens: int
+    query_prefix: str
+    document_prefix: str
+    repository: str
+    commit: str
+    licence: str
+    files: dict[str, str] = field(default_factory=dict)
+
+
+STANDARD_MODELS: tuple[StandardModel, ...] = (
+    StandardModel(
+        "bge-small-en-v1.5",
+        "BAAI/bge-small-en-v1.5",
+        "onnx-q8",
+        384,
+        "cls",
+        512,
+        "Represent this sentence for searching relevant passages: ",
+        "",
+        "Xenova/bge-small-en-v1.5",
+        "ea104dacec62c0de699686887e3f920caeb4f3e3",
+        "MIT",
+        {
+            "vocab.txt": "07eced375cec144d27c900241f3e339478dec958f92fddbc551f295c992038a3",
+            "config.json": "fa73f90bf92c8cace1fbcb709626306f2bdbc9ea3e5b5f94b440df9b6aa56350",
+            "tokenizer.json": "d241a60d5e8f04cc1b2b3e9ef7a4921b27bf526d9f6050ab90f9267a1f9e5c66",
+            "tokenizer_config.json": "9261e7d79b44c8195c1cada2b453e55b00aeb81e907a6664974b4d7776172ab3",
+            "special_tokens_map.json": "b6d346be366a7d1d48332dbc9fdf3bf8960b5d879522b7799ddba59e76237ee3",
+            ONNX_FILE: "6c9c6101a956d62dfb5e7190c538226c0c5bb9cb27b651234b6df063ee7dbfe4",
+        },
+    ),
+    StandardModel(
+        "nomic-embed-text-v1.5",
+        "nomic-ai/nomic-embed-text-v1.5",
+        "onnx-q8",
+        768,
+        "mean",
+        2048,
+        "search_query: ",
+        "search_document: ",
+        "nomic-ai/nomic-embed-text-v1.5",
+        "e9b6763023c676ca8431644204f50c2b100d9aab",
+        "Apache-2.0",
+        {
+            "vocab.txt": "07eced375cec144d27c900241f3e339478dec958f92fddbc551f295c992038a3",
+            "config.json": "9ab00bd92cee80a569f708140b7b6c1661a65891ff3765b1519e181ba2f2c92b",
+            "tokenizer.json": "d241a60d5e8f04cc1b2b3e9ef7a4921b27bf526d9f6050ab90f9267a1f9e5c66",
+            "tokenizer_config.json": "d7e0000bcc80134debd2222220427e6bf5fa20a669f40a0d0d1409cc18e0a9bc",
+            "special_tokens_map.json": "5d5b662e421ea9fac075174bb0688ee0d9431699900b90662acd44b2a350503a",
+            ONNX_FILE: "b4342336debaea79de872370664b0aaeb67dea4605513d00ee236ea871a81f27",
+        },
+    ),
+    StandardModel(
+        "all-MiniLM-L6-v2",
+        "sentence-transformers/all-MiniLM-L6-v2",
+        "onnx-q8",
+        384,
+        "mean",
+        256,
+        "",
+        "",
+        "Xenova/all-MiniLM-L6-v2",
+        "751bff37182d3f1213fa05d7196b954e230abad9",
+        "Apache-2.0",
+        {
+            "vocab.txt": "07eced375cec144d27c900241f3e339478dec958f92fddbc551f295c992038a3",
+            "config.json": "7135149f7cffa1a573466c6e4d8423ed73b62fd2332c575bf738a0d033f70df7",
+            "tokenizer.json": "da0e79933b9ed51798a3ae27893d3c5fa4a201126cef75586296df9b4d2c62a0",
+            "tokenizer_config.json": "9261e7d79b44c8195c1cada2b453e55b00aeb81e907a6664974b4d7776172ab3",
+            "special_tokens_map.json": "b6d346be366a7d1d48332dbc9fdf3bf8960b5d879522b7799ddba59e76237ee3",
+            ONNX_FILE: "afdb6f1a0e45b715d0bb9b11772f032c399babd23bfc31fed1c170afc848bdb1",
+        },
+    ),
+    StandardModel(
+        "multilingual-e5-small",
+        "intfloat/multilingual-e5-small",
+        "onnx-q8",
+        384,
+        "mean",
+        512,
+        "query: ",
+        "passage: ",
+        "Xenova/multilingual-e5-small",
+        "761b726dd34fb83930e26aab4e9ac3899aa1fa78",
+        "MIT",
+        {
+            "sentencepiece.bpe.model": "cfc8146abe2a0488e9e2a0c56de7952f7c11ab059eca145a0a727afce0db2865",
+            "config.json": "cb99455288675345e1a4f411438d5d0adbba5fbd3a67ea4fb03c015433b996c1",
+            "tokenizer.json": "0b44a9d7b51c3c62626640cda0e2c2f70fdacdc25bbbd68038369d14ebdf4c39",
+            "tokenizer_config.json": "a1d6bc8734a6f635dc158508bef000f8e2e5a759c7d92f984b2c86e5ff53425b",
+            "special_tokens_map.json": "d05497f1da52c5e09554c0cd874037a083e1dc1b9cfd48034d1c717f1afc07a7",
+            ONNX_FILE: "f80102d3f2a1229f387d3c81909990d8945513e347b0eab049f7de3c6f98c193",
+        },
+    ),
+)
+
+
+def default_model_store() -> Path:
+    """``MOCA_MODELS``, else ``~/.moca/models``."""
+    configured = os.environ.get("MOCA_MODELS")
+    return Path(configured) if configured else Path.home() / ".moca" / "models"
+
+
+def find_standard_model(id_or_name: str) -> StandardModel | None:
+    """A standard model by short id (any case) or recorded name."""
+    return next((m for m in STANDARD_MODELS if m.id.lower() == id_or_name.lower() or m.name == id_or_name), None)
+
+
+def installed_models(store: str | os.PathLike[str] | None = None) -> list[StandardModel]:
+    """The standard models whose files are all present in a store (not yet checked)."""
+    root = Path(store) if store is not None else default_model_store()
+    return [m for m in STANDARD_MODELS if all((root / m.id / f).exists() for f in m.files)]
+
+
+def _sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as stream:
+        for chunk in iter(lambda: stream.read(1 << 20), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def _require(id_or_name: str) -> StandardModel:
+    model = find_standard_model(id_or_name)
+    if model is None:
+        raise ValueError(f"not a standard model: {id_or_name} ({', '.join(m.id for m in STANDARD_MODELS)})")
+    return model
+
+
+class StandardEmbedder:
+    """A standard model as a Reader embedder: ``embed(texts, role)`` with role ``"query"`` or ``"document"``."""
+
+    def __init__(self, model: StandardModel, folder: Path) -> None:
+        try:
+            import numpy as np
+            import onnxruntime  # type: ignore[import-untyped,import-not-found,unused-ignore]
+            from tokenizers import Tokenizer  # type: ignore[import-not-found,unused-ignore]
+        except ImportError as error:  # pragma: no cover - depends on the environment
+            raise ImportError('the standard models need the onnx extra: pip install "moca-reader[onnx]"') from error
+        self._np: Any = np
+        self.model = model
+        self.name = model.name
+        self.version = model.version
+        self.dimensions = model.dimensions
+        self.query_prefix = model.query_prefix
+        self.document_prefix = model.document_prefix
+        self._tokenizer: Any = Tokenizer.from_file(str(folder / "tokenizer.json"))
+        self._tokenizer.no_truncation()
+        self._tokenizer.no_padding()
+        options = onnxruntime.SessionOptions()
+        options.graph_optimization_level = onnxruntime.GraphOptimizationLevel.ORT_ENABLE_ALL
+        self._session: Any = onnxruntime.InferenceSession(
+            str(folder / ONNX_FILE), options, providers=["CPUExecutionProvider"]
+        )
+
+    def embed(self, texts: Sequence[str], role: str = "document") -> list[list[float]]:
+        prefix = self.query_prefix if role == "query" else self.document_prefix
+        return [self._embed_one(prefix + text) for text in texts]
+
+    def _embed_one(self, text: str) -> list[float]:
+        np = self._np
+        ids = self._tokenizer.encode(text).ids
+        if len(ids) > self.model.max_tokens:
+            ids = [*ids[: self.model.max_tokens - 1], ids[-1]]
+        shape = (1, len(ids))
+        inputs = {
+            "input_ids": np.array(ids, dtype=np.int64).reshape(shape),
+            "attention_mask": np.ones(shape, dtype=np.int64),
+            "token_type_ids": np.zeros(shape, dtype=np.int64),
+        }
+        hidden: Any = self._session.run(None, inputs)[0][0].astype(np.float64)
+        vector = hidden[0] if self.model.pooling == "cls" else hidden.mean(axis=0)
+        norm = float(np.linalg.norm(vector))
+        result: list[float] = (vector / norm if norm > 0 else vector).astype(np.float32).tolist()
+        return result
+
+
+def standard_embedder(id_or_name: str, store: str | os.PathLike[str] | None = None) -> StandardEmbedder:
+    """Loads a standard model from a store, after checking each file against its pinned SHA-256."""
+    model = _require(id_or_name)
+    folder = (Path(store) if store is not None else default_model_store()) / model.id
+    for file, expected in model.files.items():
+        path = folder / file
+        if not path.exists():
+            raise FileNotFoundError(
+                f"{model.id} is not installed in {folder.parent}: run: npx @openmoca/moca-embed models add {model.id}"
+            )
+        if _sha256(path) != expected:
+            raise ValueError(f"{model.id}: {file} does not match its pinned SHA-256")
+    return StandardEmbedder(model, folder)

moca_reader/evidence_text.py

@@ -0,0 +1,187 @@
+"""Evidence checks against sources inside the package (Reader contract §7).
+
+W3C Web Annotation says selector text "MUST be normalized", with HTML and XML tags removed and character
+entities replaced. These are MOCA's exact normalisation rules per source type, so every Reader reaches the
+same answer. Positions count Unicode code points of the normalised text.
+"""
+
+from __future__ import annotations
+
+import math
+import re
+from dataclasses import dataclass
+from typing import Any
+
+from ._js import js_split_ws, js_trim
+
+_KINDS = [
+    (re.compile(r"\.(txt|text)\Z", re.I | re.A), "text"),
+    (re.compile(r"\.(md|markdown)\Z", re.I | re.A), "markdown"),
+    (re.compile(r"\.(html|htm)\Z", re.I | re.A), "html"),
+    (re.compile(r"\.vtt\Z", re.I | re.A), "webvtt"),
+]
+_MEDIA_FRAGMENTS = re.compile(r"^https?://www\.w3\.org/TR/media-frags/?\Z")
+_ENTITIES = {"amp": "&", "lt": "<", "gt": ">", "quot": '"', "apos": "'", "nbsp": "\u00a0"}
+_ENTITY = re.compile(r"&(#x[0-9a-f]+|#[0-9]+|[a-z]+);", re.I | re.A)
+
+
+def source_kind(path: str) -> str | None:
+    for pattern, kind in _KINDS:
+        if pattern.search(path):
+            return kind
+    return None
+
+
+def _decode_entities(text: str) -> str:
+    def entity(m: re.Match[str]) -> str:
+        e = m[1]
+        if e[0] == "#":
+            cp = int(e[2:], 16) if e[1] in "xX" else int(e[1:], 10)
+            return chr(cp) if cp <= 0x10FFFF else m[0]
+        return _ENTITIES.get(e.lower(), m[0])
+
+    return _ENTITY.sub(entity, text)
+
+
+def markdown_text(source: str) -> str:
+    """Markdown to text: images and links become their text; heading and list markers go; *, _ and ` go."""
+    text = re.sub(r"!?\[([^\]]*)\]\([^)]*\)", r"\1", source)
+    lines = [
+        re.sub(
+            r"^[\t\n\v\f\r \u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]*(?:[-*+]|[0-9]+[.)])[\t\n\v\f\r \u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]+",
+            "",
+            re.sub(
+                r"^[\t\n\v\f\r \u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]*#{1,6}[\t\n\v\f\r \u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]+",
+                "",
+                line,
+            ),
+        )
+        for line in text.split("\n")
+    ]
+    return re.sub(r"[*_`]", "", "\n".join(lines))
+
+
+def html_text(source: str) -> str:
+    """HTML to text: script and style elements removed, tags removed, entities decoded."""
+    without = re.sub(
+        r"<(script|style)\b[^>]*>[\s\S]*?</\1[\t\n\v\f\r \u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]*>",
+        "",
+        source,
+        flags=re.I | re.A,
+    )
+    return _decode_entities(re.sub(r"<[^>]*>", "", without))
+
+
+def _number(text: str) -> float:
+    try:
+        return float(text) if js_trim(text) else 0.0
+    except ValueError:
+        return math.nan
+
+
+def _seconds(ts: str) -> float:
+    t = js_trim(ts)
+    m = re.match(r"^(?:([0-9]+):)?([0-9]{1,2}):([0-9]{2}(?:\.[0-9]+)?)\Z", t)
+    if m:
+        return _number(m[1] or "0") * 3600 + _number(m[2]) * 60 + _number(m[3])
+    m = re.match(r"^([0-9]+(?:\.[0-9]+)?)\Z", t)
+    return _number(m[1]) if m else math.nan
+
+
+@dataclass
+class Cue:
+    start: float
+    end: float
+    text: str
+
+
+def webvtt(source: str) -> tuple[list[Cue], str]:
+    """WebVTT cues and their payload text, cue tags removed and entities decoded, joined with LF."""
+    blocks = re.split(r"\n{2,}", re.sub(r"\r\n?", "\n", source))
+    cues: list[Cue] = []
+    for block in blocks[1:]:
+        lines = block.split("\n")
+        at = next((i for i, line in enumerate(lines) if "-->" in line), -1)
+        if at < 0:
+            continue
+        start_text, _, rest = lines[at].partition("-->")
+        start = _seconds(start_text)
+        end = _seconds((js_split_ws(rest) or [""])[0])
+        text = "\n".join(_decode_entities(re.sub(r"<[^>]*>", "", line)) for line in lines[at + 1 :])
+        if math.isfinite(start) and math.isfinite(end):
+            cues.append(Cue(start, end, text))
+    return cues, "\n".join(c.text for c in cues)
+
+
+def normalised_text(raw: str, kind: str) -> str:
+    if kind == "markdown":
+        return markdown_text(raw)
+    if kind == "html":
+        return html_text(raw)
+    if kind == "webvtt":
+        return webvtt(raw)[1]
+    return raw
+
+
+def media_time_range(value: Any) -> tuple[float, float] | None:
+    """A Media Fragments temporal value ``t=start[,end]`` (seconds or hh:mm:ss), or None."""
+    m = re.search(r"(?:^|&)t=(?:npt:)?([^,&]*)(?:,([^&]*))?", "" if value is None else str(value))
+    if not m:
+        return None
+    start = 0.0 if m[1] == "" else _seconds(m[1])
+    end = math.inf if m[2] is None else _seconds(m[2])
+    if not math.isfinite(start) or math.isnan(end) or end < start:
+        return None
+    return start, end
+
+
+def _is_integer(value: Any) -> bool:
+    return (isinstance(value, int) and not isinstance(value, bool)) or (isinstance(value, float) and value.is_integer())
+
+
+def selector_matches(selector: Any, text: str) -> bool | None:
+    """None when the selector type is not checked."""
+    kind = selector.get("type") if isinstance(selector, dict) else None
+    if kind == "TextQuoteSelector":
+        exact = selector.get("exact")
+        if not isinstance(exact, str) or exact == "":
+            return False
+        prefix = selector["prefix"] if isinstance(selector.get("prefix"), str) else ""
+        suffix = selector["suffix"] if isinstance(selector.get("suffix"), str) else ""
+        # One search for prefix + exact + suffix: the same answer as checking each occurrence of exact, without
+        # rescanning the text for every one.
+        return (prefix + exact + suffix) in text
+    # Contract §7: a TextPositionSelector on its own proves only that its offsets are in range, so it is not
+    # checked: `matched` stays absent.
+    if kind == "TextPositionSelector":
+        return None
+    return None
+
+
+def check_selector(selector: dict[str, Any], raw: str, kind: str, prepared: str | None = None) -> bool | None:
+    """Checks one selector against a source's raw text; None when it cannot be checked against this source."""
+    if selector.get("type") == "FragmentSelector":
+        conforms = selector.get("conformsTo")
+        if not _MEDIA_FRAGMENTS.match(conforms if isinstance(conforms, str) else "") or kind != "webvtt":
+            return None
+        window = media_time_range(selector.get("value"))
+        if window is None:
+            return False
+        return any(window[0] < c.end and window[1] > c.start for c in webvtt(raw)[0])
+    # The quote is normalised as the source is, so markup in either never decides a match.
+    quote = _normalise_quote(selector, kind) if selector.get("type") == "TextQuoteSelector" else selector
+    return selector_matches(quote, prepared if prepared is not None else normalised_text(raw, kind))
+
+
+def _normalise_quote(selector: dict[str, Any], kind: str) -> dict[str, Any]:
+    # A quote from captions is cue text already; Markdown and HTML quotes lose markup as their sources do.
+    if kind not in ("markdown", "html"):
+        return selector
+    return {
+        **selector,
+        **{
+            k: normalised_text(selector[k], kind)
+            for k in ("exact", "prefix", "suffix")
+            if isinstance(selector.get(k), str)
+        },
+    }

moca_reader/frontmatter.py

@@ -0,0 +1,151 @@
+"""YAML frontmatter for OKF concept documents.
+
+Parsed with the YAML 1.2 core schema (package spec §5): timestamps, ``yes``, ``no`` and ``on`` stay strings
+exactly as written, and aliases are refused (Reader contract §3). PyYAML's own resolvers follow YAML 1.1, so
+this reads PyYAML's event stream and resolves plain scalars itself, as the .NET Reader does.
+"""
+
+from __future__ import annotations
+
+import math
+import re
+from dataclasses import dataclass
+from typing import Any
+
+import yaml
+
+from ._js import js_trim, number_to_string
+from .digest import utf8
+
+_OPEN = re.compile(r"^---[ \t]*\r?\n")
+# Package spec §5.1: only LF ends a line (CRLF is LF after CR).
+_CLOSE = re.compile(r"(?:^|(?<=\n))---[ \t]*(?:\r?\n|\Z)")
+
+
+@dataclass
+class FrontmatterSplit:
+    present: bool
+    body: str
+    body_offset: int
+    line: int = 1
+    raw: str | None = None
+    data: Any = None
+    error: str | None = None
+
+
+def split_frontmatter(text: str, max_bytes: float = math.inf) -> FrontmatterSplit:
+    """Splits a document into frontmatter and body; ``body_offset`` is the UTF-8 byte offset of the body."""
+    bom = "\ufeff" if text.startswith("\ufeff") else ""
+    rest = text[len(bom) :]
+    opened = _OPEN.match(rest)
+    if not opened:
+        return FrontmatterSplit(False, text, len(utf8(bom)))
+    after_open = rest[opened.end() :]
+    closed = _CLOSE.search(after_open)
+    if not closed:
+        return FrontmatterSplit(True, text, 0, error="frontmatter block is not closed with ---")
+    raw = after_open[: closed.start()]
+    consumed = bom + opened.group(0) + after_open[: closed.end()]
+    result = FrontmatterSplit(True, text[len(consumed) :], len(utf8(consumed)), raw=raw)
+    if len(utf8(raw)) > max_bytes:
+        result.error = f"frontmatter is larger than the {int(max_bytes)}-byte limit"
+        return result
+    try:
+        result.data = {} if js_trim(raw) == "" else load_core_schema(raw)
+    except yaml.YAMLError as err:
+        mark = getattr(err, "problem_mark", None) or getattr(err, "context_mark", None)
+        result.error = str(getattr(err, "problem", None) or err)
+        if mark is not None:
+            result.line = mark.line + 2
+        return result
+    if not isinstance(result.data, dict):
+        result.error = "frontmatter is not a YAML mapping"
+    return result
+
+
+_NULL = re.compile(r"^(?:null|Null|NULL|~)?\Z")
+_BOOL = re.compile(r"^(?:true|True|TRUE|false|False|FALSE)\Z")
+_INT = re.compile(r"^[-+]?[0-9]+\Z")
+_OCT = re.compile(r"^0o[0-7]+\Z")
+_HEX = re.compile(r"^0x[0-9a-fA-F]+\Z")
+_FLOAT = re.compile(r"^[-+]?(?:\.[0-9]+|[0-9]+(?:\.[0-9]*)?)(?:[eE][-+]?[0-9]+)?\Z")
+_STR_TAG = "tag:yaml.org,2002:str"
+
+
+class _Error(yaml.MarkedYAMLError):
+    pass
+
+
+def _error(message: str, event: Any) -> _Error:
+    """An error at an event, with its position, for C002's line number."""
+    return _Error(None, None, message, event.start_mark)
+
+
+def _resolve(event: yaml.ScalarEvent) -> Any:
+    value = event.value
+    # Quoted and block scalars, and explicitly tagged strings, are always strings.
+    if event.style is not None or event.tag in (_STR_TAG, "!"):
+        return value
+    if _NULL.match(value):
+        return None
+    if _BOOL.match(value):
+        return value.lower() == "true"
+    if _INT.match(value):
+        return int(value)
+    if _OCT.match(value):
+        return int(value[2:], 8)
+    if _HEX.match(value):
+        return int(value[2:], 16)
+    if _FLOAT.match(value):
+        return float(value)
+    return value
+
+
+def _key_text(key: Any) -> str:
+    if key is None:
+        return "null"
+    if isinstance(key, str):
+        return key
+    return number_to_string(key)
+
+
+def load_core_schema(text: str) -> Any:
+    """Loads one YAML document with the YAML 1.2 core schema; aliases and duplicate keys are errors."""
+    events = iter(yaml.parse(text, Loader=yaml.SafeLoader))
+
+    def node(event: yaml.Event) -> Any:
+        if isinstance(event, yaml.AliasEvent):
+            # Alias expansion is a denial-of-service vector (Reader contract §3, "YAML aliases in frontmatter: 0").
+            raise _error("YAML aliases are not allowed in frontmatter", event)
+        if isinstance(event, yaml.ScalarEvent):
+            return _resolve(event)
+        if isinstance(event, yaml.SequenceStartEvent):
+            out: list[Any] = []
+            for e in events:
+                if isinstance(e, yaml.SequenceEndEvent):
+                    return out
+                out.append(node(e))
+        if isinstance(event, yaml.MappingStartEvent):
+            mapping: dict[str, Any] = {}
+            for e in events:
+                if isinstance(e, yaml.MappingEndEvent):
+                    return mapping
+                if not isinstance(e, yaml.ScalarEvent):
+                    raise _error("mapping keys must be scalars", e)
+                key = _key_text(_resolve(e))
+                if key in mapping:
+                    raise _error(f'duplicated mapping key "{key}"', e)
+                mapping[key] = node(next(events))
+        raise _error(f"unexpected YAML event {type(event).__name__}", event)
+
+    first = next(events)  # StreamStart
+    del first
+    start = next(events)
+    if isinstance(start, yaml.StreamEndEvent):
+        return None
+    value = node(next(events))
+    next(events)  # DocumentEnd
+    after = next(events)
+    if not isinstance(after, yaml.StreamEndEvent):
+        raise _Error(None, None, "expected a single document in the frontmatter", after.start_mark)
+    return value