tablassert 8.2.1__tar.gz → 9.1.0__tar.gz

{tablassert-8.2.1 → tablassert-9.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tablassert
-Version: 8.2.1
+Version: 9.1.0
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Science/Research
@@ -32,11 +32,13 @@ Requires-Dist: fastexcel>=0.20.2
 Requires-Dist: smolagents>=1.26.0 ; extra == 'agent'
 Requires-Dist: litellm>=1.93.0 ; extra == 'agent'
 Requires-Dist: pdfminer-six>=20221105 ; extra == 'agent'
+Requires-Dist: aria2==0.0.1b0 ; extra == 'aria2'
 Requires-Dist: dspy>=3.2.1 ; extra == 'optimize'
 Requires-Dist: scikit-learn>=1.8.0 ; extra == 'qc'
 Requires-Dist: sentence-transformers>=5.3.0 ; extra == 'qc'
 Requires-Dist: polars[rtcompat]>=1.40.1 ; extra == 'rt'
 Provides-Extra: agent
+Provides-Extra: aria2
 Provides-Extra: optimize
 Provides-Extra: qc
 Provides-Extra: rt
@@ -152,11 +154,15 @@ CSV/TSV/Excel sources; optional extras add runtime and pipeline capabilities:
 | Extra | Adds | Install |
 | ----- | ---- | ------- |
 | `rt` | CPU-compatible Polars runtime | `pip install "tablassert[rt]"` |
+| `aria2` | bundled aria2c downloader for `build-fullmap --aria2c` (Linux/Windows wheels only) | `pip install "tablassert[aria2]"` |
 | `qc` | three-stage QC audit (exact → fuzzy → BioBERT embeddings) | `pip install "tablassert[qc]"` |
 | `agent` | autonomous agent (smolagents, litellm, PDF context) | `pip install "tablassert[agent]"` |
 | `optimize` | GEPA prompt optimization for `agent --optimize` (dspy) | `pip install "tablassert[optimize]"` |
 
-QC is opt-in at build time (`build-kg --qc`). See the
+QC is opt-in at build time (`build-kg --qc`). Reaching a feature whose extra is not installed never
+produces a bare `ModuleNotFoundError`: the failure names the missing package and the exact install
+command, and for `build-kg --qc` and `tablassert agent` it arrives before the run starts rather than
+partway through. See the
 [Installation guide](https://skyeav.github.io/Tablassert/installation/) for the full matrix and the
 [CLI Reference](https://skyeav.github.io/Tablassert/cli/) for every flag.
 

{tablassert-8.2.1 → tablassert-9.1.0}/README.md

@@ -99,11 +99,15 @@ CSV/TSV/Excel sources; optional extras add runtime and pipeline capabilities:
 | Extra | Adds | Install |
 | ----- | ---- | ------- |
 | `rt` | CPU-compatible Polars runtime | `pip install "tablassert[rt]"` |
+| `aria2` | bundled aria2c downloader for `build-fullmap --aria2c` (Linux/Windows wheels only) | `pip install "tablassert[aria2]"` |
 | `qc` | three-stage QC audit (exact → fuzzy → BioBERT embeddings) | `pip install "tablassert[qc]"` |
 | `agent` | autonomous agent (smolagents, litellm, PDF context) | `pip install "tablassert[agent]"` |
 | `optimize` | GEPA prompt optimization for `agent --optimize` (dspy) | `pip install "tablassert[optimize]"` |
 
-QC is opt-in at build time (`build-kg --qc`). See the
+QC is opt-in at build time (`build-kg --qc`). Reaching a feature whose extra is not installed never
+produces a bare `ModuleNotFoundError`: the failure names the missing package and the exact install
+command, and for `build-kg --qc` and `tablassert agent` it arrives before the run starts rather than
+partway through. See the
 [Installation guide](https://skyeav.github.io/Tablassert/installation/) for the full matrix and the
 [CLI Reference](https://skyeav.github.io/Tablassert/cli/) for every flag.
 

{tablassert-8.2.1 → tablassert-9.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tablassert"
-version = "8.2.1"
+version = "9.1.0"
 description = "Extract knowledge assertions from tabular data into NCATS Translator-compliant KGX NDJSON — declaratively, with entity resolution and quality control built in."
 authors = [
     { name = "Skye Lane Goetz", email = "sgoetz@isbscience.org" }
@@ -78,6 +78,10 @@ tablassert = "tablassert.cli:APP"
 rt = [
     "polars[rtcompat]>=1.40.1",
 ]
+# PyPI distribution "aria2" exposes import module "aria2c" with a bundled aria2c binary.
+aria2 = [
+    "aria2==0.0.1b0",
+]
 qc = [
     "scikit-learn>=1.8.0",
     "sentence-transformers>=5.3.0",

{tablassert-8.2.1 → tablassert-9.1.0}/src/tablassert/_lazy.py

@@ -34,7 +34,19 @@ class LazyModule:
     def _load(self) -> Any:
         module = self._module
         if module is None:
-            module = import_module(self._name)
+            try:
+                module = import_module(self._name)
+            except ImportError as exc:
+                # Deferred: keeps this module import-light (everything imports it) and the
+                # registry lookup off the success path. A proxied optional dependency that
+                # is absent must name its extra here -- this is the LAST point that knows
+                # the module name, and the caller only sees "No module named 'x'".
+                from tablassert.extras import actionable_import_error
+
+                actionable = actionable_import_error(self._name)
+                if actionable is None:
+                    raise
+                raise actionable from exc
             self._module = module
         return module
 

{tablassert-8.2.1 → tablassert-9.1.0}/src/tablassert/agent.py

@@ -4,11 +4,11 @@ This module hosts a smolagents ``CodeAgent`` pipeline that autonomously builds
 and audits KGX knowledge graphs from PubMed Central articles. It is part of the
 OPTIONAL ``[agent]`` extra, so ``smolagents`` is imported LAZILY (via
 :class:`tablassert._lazy.LazyModule`) and the base package never requires it at
-import time. Install the extra with ``pip install tablassert[agent]``.
+import time. Install the extra with ``pip install "tablassert[agent]"``.
 
 ``dspy`` powers ONLY the GEPA prompt-optimization path (``agent --optimize``)
 and lives in its own OPTIONAL ``[optimize]`` extra
-(``pip install tablassert[optimize]``); it is likewise lazy-imported and never
+(``pip install "tablassert[optimize]"``); it is likewise lazy-imported and never
 required by ordinary agent runs.
 """
 
@@ -26,7 +26,6 @@ import xml.etree.ElementTree as ET
 from collections import Counter
 from collections.abc import Callable, Sequence
 from dataclasses import asdict, dataclass, field
-from importlib import import_module
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, ClassVar, Literal, cast
 from urllib.request import Request, urlopen
@@ -38,6 +37,7 @@ from tablassert._lazy import LazyModule
 from tablassert.biolink import ENUM_RANGED_QUALIFIERS, Categories
 from tablassert.enums import EncodingMethods
 from tablassert.errors import GraphValidationError, QcRuntimeMissingError, SectionValidationError, TablassertValidationError
+from tablassert.extras import install_command, require_module
 from tablassert.fullmap import distinct, fullmap_db_path, is_lock_contention, lookup_rows
 from tablassert.graph_registry import REGISTERED_STATUSES, register_build
 from tablassert.lib import Tcode
@@ -55,21 +55,23 @@ else:
     pl = LazyModule("polars")
     smolagents = LazyModule("smolagents")
 
-AGENT_EXTRA: str = "pip install tablassert[agent]"
-OPTIMIZE_EXTRA: str = "pip install tablassert[optimize]"
-
-# Package -> install hint for the extra that actually ships it (default: [agent]).
-_EXTRA_HINT: dict[str, str] = {"dspy": OPTIMIZE_EXTRA}
+# Published install hints, derived from the extras registry so they cannot drift from
+# either pyproject.toml or the messages users actually see.
+AGENT_EXTRA: str = install_command("agent")
+OPTIMIZE_EXTRA: str = install_command("optimize")
 
 logger = cat("AGENT")
 
 
 def _require(name: str) -> None:
-    """Import an optional dependency or raise a loud, actionable ImportError."""
-    try:
-        import_module(name)
-    except ImportError as exc:
-        raise ImportError(f"tablassert agent features require the '{name}' package. Install with {_EXTRA_HINT.get(name, AGENT_EXTRA)}.") from exc
+    """Import an optional dependency or raise a loud, actionable ImportError.
+
+    Thin wrapper over :func:`tablassert.extras.require_module`, which owns the
+    package -> extra mapping (``dspy`` belongs to ``[optimize]``, everything else the
+    agent lazy-imports to ``[agent]``) so the hints cannot drift from
+    ``pyproject.toml``.
+    """
+    require_module(name, required_by="tablassert agent features")
 
 
 def is_lazy() -> bool:
@@ -455,43 +457,44 @@ DATA_GUARDRAIL: str = (
 def excel_sheet_names(path: Path) -> list[str]:
     """Return the worksheet names of an Excel workbook (calamine preferred, openpyxl fallback).
 
-    Uses the SAME optional engines :func:`_read_excel` reads with (imported lazily), so a workbook is
-    introspectable wherever it is readable. Raises a clear ``ValueError`` naming the install path when
-    neither engine can open the workbook (a corrupt file or a missing engine).
+    Uses the SAME engines :func:`_read_excel` reads with (imported lazily), so a workbook is
+    introspectable wherever it is readable. Raises a clear ``ValueError`` naming the fix when
+    neither engine can open the workbook (a corrupt file, or a base install missing its engine).
     """
     try:
-        import fastexcel  # lazy optional engine (calamine), same as _read_excel
+        import fastexcel  # lazy import of the core calamine engine, same as _read_excel
 
         return [str(name) for name in fastexcel.read_excel(path).sheet_names]
-    except Exception as calamine_err:  # missing fastexcel OR a genuinely unreadable workbook
+    except Exception as calamine_err:  # unreadable workbook OR (rarely) a broken fastexcel install
         try:
             import openpyxl  # lazy pure-Python fallback engine, same as _read_excel
 
             return [str(name) for name in openpyxl.load_workbook(path, read_only=True).sheetnames]
         except Exception:
             raise ValueError(
-                f"Listing Excel sheets requires an excel engine (calamine/openpyxl); install tablassert[agent] or tablassert[rt]. ({calamine_err})"
+                f"Could not list Excel sheets with either engine. calamine (fastexcel) is a core dependency, so this is usually an unreadable "
+                f"workbook; `pip install openpyxl` adds the pure-Python fallback engine. ({calamine_err})"
             ) from calamine_err
 
 
 def _read_excel(path: Path, sheet: str | None = None) -> pl.DataFrame:
     """Read an Excel worksheet, preferring ``calamine`` and falling back to ``openpyxl``.
 
-    WHY two engines: the fast ``calamine`` engine needs the optional ``fastexcel``
-    package, which the base install lacks; ``openpyxl`` is a pure-Python fallback
-    that is commonly present. ``sheet`` selects a worksheet BY NAME (``None`` reads
-    the first/active sheet, matching polars' default). If neither engine can load the
-    file (both missing, or the workbook is corrupt), raise a clear ``ValueError``
-    naming the install path instead of leaking a raw engine error to the caller.
+    WHY two engines: the fast ``calamine`` engine (``fastexcel``) is a core dependency and
+    handles almost every workbook; ``openpyxl`` is a pure-Python fallback that reads some
+    files calamine rejects. ``sheet`` selects a worksheet BY NAME (``None`` reads the
+    first/active sheet, matching polars' default). If neither engine can load the file,
+    raise a clear ``ValueError`` naming the fix instead of leaking a raw engine error.
     """
     try:
         return pl.read_excel(path, engine="calamine", sheet_name=sheet)
-    except Exception as calamine_err:  # missing fastexcel OR a genuinely unreadable workbook
+    except Exception as calamine_err:  # unreadable workbook OR (rarely) a broken fastexcel install
         try:
             return pl.read_excel(path, engine="openpyxl", sheet_name=sheet)
         except Exception:
             raise ValueError(
-                f"Reading Excel requires an excel engine (calamine/openpyxl); install tablassert[agent] or tablassert[rt]. ({calamine_err})"
+                f"Could not read Excel with either engine. calamine (fastexcel) is a core dependency, so this is usually an unreadable "
+                f"workbook; `pip install openpyxl` adds the pure-Python fallback engine. ({calamine_err})"
             ) from calamine_err
 
 
@@ -572,7 +575,7 @@ def _extract_pdf_text(path: Path) -> str:
     try:
         from pdfminer.high_level import extract_text  # pyright: ignore[reportMissingImports]  # lazy optional dep ([agent] extra)
     except ImportError as exc:
-        raise ValueError(f"Reading PDF main text requires pdfminer.six; install tablassert[agent]. ({exc})") from exc
+        raise ValueError(f"Reading PDF main text requires pdfminer.six. {install_command('agent')} ({exc})") from exc
     return str(extract_text(str(path)))
 
 
@@ -2042,6 +2045,9 @@ def build_model(model_id: str | None, api_base: str | None, api_key: str | None,
 
     _require("smolagents")
     if backend == "litellm":
+        # smolagents imports litellm lazily inside LiteLLMModel; require it here so the
+        # failure names the [agent] extra instead of surfacing smolagents' own message.
+        _require("litellm")
         from smolagents import LiteLLMModel  # local import keeps module import lazy  # pyright: ignore[reportMissingImports]
 
         return LiteLLMModel(model_id=rid, api_base=rbase, api_key=rkey)

{tablassert-8.2.1 → tablassert-9.1.0}/src/tablassert/cli.py

@@ -1,11 +1,15 @@
 from __future__ import annotations
 
+import hashlib
 import re
 import shutil
 import subprocess
 import sys
+import tarfile
+import tempfile
 import time
 from collections.abc import Callable
+from importlib import import_module
 from importlib.metadata import version as get_version
 from itertools import chain
 from multiprocessing import Pool
@@ -16,6 +20,7 @@ from urllib.request import Request, urlopen
 
 import cyclopts
 
+from tablassert import extras
 from tablassert._lazy import LazyModule
 from tablassert.errors import BabelDownloadError, GraphValidationError, SectionValidationError
 from tablassert.log import cat
@@ -422,14 +427,42 @@ def download_babel_file(filename: str, url: str, destination: Path, retries: int
     raise BabelDownloadError(url, retries, last_error or RuntimeError("no attempts made")) from last_error
 
 
+def _resolve_aria2_binary() -> str:
+    """Return the bundled aria2c binary path from the optional ``[aria2]`` extra.
+
+    Raises:
+        ImportError: If the optional ``[aria2]`` extra is not installed.
+    """
+    aria2c = import_module("aria2c")
+    try:
+        binary = aria2c.ARIA2C
+    except AttributeError as e:
+        raise ImportError("aria2c.ARIA2C was not found; install the [aria2] extra") from e
+    return str(binary)
+
+
+def aria2_unavailable_detail() -> str:
+    """Explain how to get ``aria2c``, accounting for the platform.
+
+    macOS gets DIFFERENT advice on purpose: the ``aria2`` distribution publishes no macOS
+    wheels, so pointing a mac user at the extra sends them to a dead end. There the fix is
+    to drop the flag, and the default Python downloader takes over.
+    """
+    if sys.platform == "darwin":
+        return "the [aria2] extra ships no macOS wheels; drop --aria2c to use the default Python downloader"
+    return f"install the [aria2] extra: {extras.install_command('aria2')}"
+
+
 def download_babel_file_aria2c(filename: str, url: str, destination: Path, retries: int = 5) -> Path:
-    """Download one BABEL file with the optional external ``aria2c`` executable.
+    """Download one BABEL file with the bundled aria2c binary from ``[aria2]``.
 
     The helper mirrors ``download_babel_file``'s final-file cache contract but
-    delegates resume/retry behavior to aria2. Incomplete aria2 downloads leave a
-    ``<filename>.aria2`` control file next to the target; when that control file
-    exists we do NOT treat the target as a cache hit, and failures never remove
-    either file so a later run can continue.
+    delegates resume/retry behavior to aria2. The ``aria2`` PyPI package is an
+    optional extra that bundles the aria2c binary and exposes it as
+    ``aria2c.ARIA2C``, so no system ``aria2c`` executable is required. Incomplete
+    aria2 downloads leave a ``<filename>.aria2`` control file next to the target;
+    when that control file exists we do NOT treat the target as a cache hit, and
+    failures never remove either file so a later run can continue.
 
     Args:
         filename: Output basename under ``destination``.
@@ -441,8 +474,8 @@ def download_babel_file_aria2c(filename: str, url: str, destination: Path, retri
         Path to the downloaded file.
 
     Raises:
-        BabelDownloadError: If ``aria2c`` is missing, fails, or does not leave a
-            complete final file.
+        BabelDownloadError: If the ``[aria2]`` extra is missing, aria2c fails,
+            or aria2c does not leave a complete final file.
     """
     destination.mkdir(parents=True, exist_ok=True)
     final_path: Path = destination / filename
@@ -454,10 +487,11 @@ def download_babel_file_aria2c(filename: str, url: str, destination: Path, retri
         error = ValueError("aria2c retries must be a positive integer")
         raise BabelDownloadError(url, retries, error) from error
 
-    binary: str | None = shutil.which("aria2c")
-    if binary is None:
-        error = FileNotFoundError("aria2c executable not found; install aria2 or omit --aria2c")
-        raise BabelDownloadError(url, 0, error) from error
+    try:
+        binary: str = _resolve_aria2_binary()
+    except ImportError as e:
+        error = FileNotFoundError(aria2_unavailable_detail())
+        raise BabelDownloadError(url, 0, error) from e
 
     command: list[str] = [
         binary,
@@ -562,7 +596,13 @@ def build_kg(
 
     The positional config is a Graph YAML that orchestrates one or more table
     configs into a single knowledge-graph build.
+
+    ``--qc`` requires the ``[qc]`` extra (``pip install "tablassert[qc]"``); it is
+    checked before the build starts, because the audit stage runs LAST and a missing
+    extra would otherwise surface only after entity resolution has finished.
     """
+    if qc:
+        extras.require("qc", required_by="--qc")
     run(6, build_pipeline, graph_configuration_file, release=release, qc=qc, log=log, head=head)
 
 
@@ -659,7 +699,7 @@ def agent(
     Model config comes from ``--model-id``/``--api-base``/``--api-key`` OR the ``TABLASSERT_AGENT_MODEL_ID``
     / ``TABLASSERT_AGENT_API_BASE`` / ``TABLASSERT_AGENT_API_KEY`` environment variables (explicit flags win).
     Secrets are NEVER hardcoded or defaulted: a missing value fails loud (exit 2) BEFORE any model is built.
-    Requires the ``[agent]`` extra (``pip install tablassert[agent]``).
+    Requires the ``[agent]`` extra (``pip install "tablassert[agent]"``).
 
     Args:
         pmc_ids: One or more PMC article ids (positional).
@@ -730,6 +770,14 @@ def agent(
         print("tablassert agent: --gepa-threads must be a positive integer.", file=sys.stderr)
         raise SystemExit(2)
 
+    # Preflight the extras once the flags are known to be valid and BEFORE any model is
+    # built or any article fetched. smolagents is otherwise only required per-article
+    # (inside build_agent) and dspy only once GEPA starts, so an absent extra would
+    # surface after real work. --optimize needs BOTH, and reports whichever is missing.
+    extras.require("agent", required_by="tablassert agent")
+    if optimize:
+        extras.require("optimize", required_by="tablassert agent --optimize")
+
     def build_model_factory() -> object:
         return agent_mod.build_model(resolved_id, resolved_base, resolved_key, backend=backend)
 
@@ -886,6 +934,233 @@ def rebuild_agent_graph(
     print(f"tablassert rebuild-agent-graph: wrote {graph_path} with {count} table config(s).")
 
 
+class PrebuiltFullmapUnavailable(Exception):
+    """A prebuilt fullmap could not be fetched or extracted.
+
+    Raised by :func:`fetch_prebuilt_fullmap` whenever the prebuilt is absent for this
+    version, the download/extract fails, or the checksum mismatches. The
+    ``build-fullmap`` command catches it to fall back to a from-scratch BABEL build, so
+    it is control flow, not a user-facing error (it never reaches the docs-coded
+    ``TablassertError`` surface). Carries a short reason so the fallback warning is actionable.
+    """
+
+
+def _prebuilt_fullmap_urls(babel_version: str) -> tuple[str, str]:
+    """Resolve the prebuilt archive + checksum URLs for THIS Tablassert version.
+
+    RENCI publishes a prebuilt ``fullmap.tar.zst`` (and a ``sha256sum.txt``) under
+    ``{BABEL_BASE}/{babel_version}/fullmap/{tablassert_version}/``, where the version
+    directory is the INSTALLED Tablassert package version (e.g. ``9.1.0``) — resolved from
+    installed-package metadata, never hardcoded, so a new release looks itself up.
+
+    Args:
+        babel_version: BABEL snapshot label (the ``--version`` value), e.g. ``2026jul22``.
+
+    Returns:
+        ``(archive_url, checksum_url)`` for ``fullmap.tar.zst`` and ``sha256sum.txt``.
+    """
+    base: str = f"{BABEL_BASE}/{babel_version}/fullmap/{get_version('tablassert')}"
+    return f"{base}/fullmap.tar.zst", f"{base}/sha256sum.txt"
+
+
+def _fetch_prebuilt_sha256(url: str) -> str | None:
+    """Fetch ``sha256sum.txt`` and return the hex digest listed for ``fullmap.tar.zst``.
+
+    Best-effort: a missing or malformed checksum file returns ``None`` so the caller
+    proceeds without verification (with a warning) instead of blocking a download.
+
+    Args:
+        url: URL of the ``sha256sum.txt`` file.
+
+    Returns:
+        The 64-char lowercase hex sha256, or ``None`` if it could not be fetched/parsed.
+    """
+    try:
+        request: Request = Request(url, headers={"User-Agent": "tablassert"})
+        with urlopen(request, timeout=60) as response:
+            body: str = response.read().decode("utf-8", errors="replace")
+    except (HTTPError, OSError, URLError):
+        return None
+    for line in body.splitlines():
+        parts: list[str] = line.split()
+        # sha256sum format: "<hex>  <filename>" (two spaces, optional leading "*").
+        # sha256sum format: "<hex>  <filename>"; binary mode prefixes the filename with "*".
+        if len(parts) >= 2 and Path(parts[1].removeprefix("*")).name == "fullmap.tar.zst":
+            digest: str = parts[0].lower()
+            if len(digest) == 64 and all(c in "0123456789abcdef" for c in digest):
+                return digest
+    return None
+
+
+def _stream_tar(tar: tarfile.TarFile, dest: Path, on_phase: Callable[[str], None]) -> None:
+    """Extract every member of a streaming tarfile into ``dest`` (data-filtered on 3.12+).
+
+    Streaming mode (``r|``) only allows extracting each member as it is read (no random
+    access), which is exactly the loop here. PEP 706 (Python 3.12) added tar-extraction
+    filters; ``filter="data"`` strips absolute paths, traversals, and unsafe links. On
+    3.11 the kwarg is absent and is omitted — the archive is RENCI-published, but the
+    filter is cheap defense-in-depth when available.
+
+    Args:
+        tar: An open streaming-mode tarfile.
+        dest: Directory members are written into.
+        on_phase: Progress callback fired with the active step label.
+    """
+    use_data_filter: bool = sys.version_info >= (3, 12)
+    for member in tar:
+        on_phase(f"extracting {member.name}")
+        # Explicit branch so pyright sees the "data" literal (PEP 706, Python 3.12+).
+        if use_data_filter:
+            tar.extract(member, dest, filter="data")
+        else:
+            tar.extract(member, dest)
+
+
+def _extract_zst_tar(archive: Path, dest: Path, on_phase: Callable[[str], None]) -> None:
+    """Stream-extract a ``.tar.zst`` archive into ``dest`` without materializing the tar on disk.
+
+    Prefers Python 3.14+ native tarfile zstd support; on older runtimes (where ``r|zst``
+    raises ``CompressionError``) it streams the archive through the installed ``zstd``
+    binary into tarfile. Streaming keeps peak disk near the redb files' own size even
+    though the uncompressed tar is tens of GB.
+
+    Args:
+        archive: Path to the downloaded ``fullmap.tar.zst``.
+        dest: Directory members are written into (created if missing).
+        on_phase: Progress callback fired with the active step label.
+
+    Raises:
+        PrebuiltFullmapUnavailable: If the archive cannot be decompressed/extracted
+            (native zstd unavailable AND no ``zstd`` binary, a read error, or a zstd failure).
+    """
+    dest.mkdir(parents=True, exist_ok=True)
+    on_phase("opening archive")
+    # Native zstd landed in tarfile for 3.14; older interpreters reject the ``zst`` mode
+    # with CompressionError, which is caught to fall through to the zstd binary.
+    try:
+        with tarfile.open(archive, "r|zst") as tar:
+            _stream_tar(tar, dest, on_phase)
+        return
+    except tarfile.CompressionError:
+        pass
+    except (OSError, tarfile.TarError) as exc:
+        raise PrebuiltFullmapUnavailable(f"failed to read prebuilt archive: {exc}") from exc
+
+    on_phase("streaming via zstd")
+    binary: str | None = shutil.which("zstd")
+    if binary is None:
+        raise PrebuiltFullmapUnavailable("no native zstd support and the `zstd` executable was not found")
+    try:
+        proc: subprocess.Popen[bytes] = subprocess.Popen([binary, "-d", "-c", "-T0", str(archive)], stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+    except OSError as exc:
+        raise PrebuiltFullmapUnavailable(f"could not start zstd: {exc}") from exc
+    assert proc.stdout is not None
+    try:
+        with tarfile.open(fileobj=proc.stdout, mode="r|") as tar:
+            _stream_tar(tar, dest, on_phase)
+    except (OSError, tarfile.TarError) as exc:
+        raise PrebuiltFullmapUnavailable(f"failed to extract prebuilt archive: {exc}") from exc
+    finally:
+        if proc.stdout is not None:
+            proc.stdout.close()
+        proc.wait()
+    if proc.returncode not in (0, None):
+        stderr: bytes = proc.stderr.read() if proc.stderr else b""
+        detail: str = stderr.decode("utf-8", "replace").strip()[-500:]
+        raise PrebuiltFullmapUnavailable(f"zstd exited with status {proc.returncode}: {detail}")
+
+
+def fetch_prebuilt_fullmap(output: Path, progress: PipelineProgress, version: str = BABEL_VERSION, aria2c: bool = False) -> None:
+    """Download and extract a prebuilt fullmap database from RENCI (instead of building).
+
+    Two stages: download ``fullmap.tar.zst`` for THIS Tablassert version (cached +
+    resumable, optionally via ``aria2c``) beside ``output``, then stream-extract it so the
+    primary redb and its shards land beside ``output`` named after its stem. The checksum
+    published alongside the archive is verified when present.
+
+    Args:
+        output: Target primary redb path; the archive is downloaded + extracted beside it.
+        progress: Pipeline progress reporter.
+        version: BABEL snapshot label selecting the RENCI release directory (NOT the
+            Tablassert package version, which the URL derives from installed-package metadata).
+        aria2c: Use the optional aria2c executable for the archive download when true.
+
+    Raises:
+        PrebuiltFullmapUnavailable: If the prebuilt is absent for this version, the download
+            or extraction fails, or the checksum mismatches. ``build-fullmap`` catches this
+            and falls back to a from-scratch BABEL build.
+    """
+    release: str = get_version("tablassert")
+    archive_url, checksum_url = _prebuilt_fullmap_urls(version)
+    download_dir: Path = output.parent
+    archive: Path = download_dir / "fullmap.tar.zst"
+
+    # Stage 1/2: download the prebuilt archive (cached + resumable, like a BABEL file).
+    progress.stage("Downloading Prebuilt Fullmap")
+    start, advance, sub_step = progress.section_loop(1, "Download")
+    start(f"fullmap.tar.zst v{release}")
+
+    def report_progress(downloaded: int, total: int) -> None:
+        sub_step(_download_detail(downloaded, total))
+
+    try:
+        if aria2c:
+            sub_step("aria2c downloading")
+            download_babel_file_aria2c("fullmap.tar.zst", archive_url, download_dir)
+        else:
+            sub_step("downloading")
+            download_babel_file("fullmap.tar.zst", archive_url, download_dir, on_progress=report_progress)
+    except BabelDownloadError as exc:
+        raise PrebuiltFullmapUnavailable(f"prebuilt archive download failed: {exc}") from exc
+    advance()
+
+    # Best-effort checksum: RENCI publishes sha256sum.txt; verify when present, warn otherwise.
+    expected: str | None = _fetch_prebuilt_sha256(checksum_url)
+    if expected is None:
+        download_logger.warning("No sha256sum.txt at {url}; skipping integrity check", url=checksum_url)
+    else:
+        sub_step("verifying checksum")
+        hasher = hashlib.sha256()
+        with archive.open("rb") as handle:
+            for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+                hasher.update(chunk)
+        actual: str = hasher.hexdigest()
+        if actual != expected:
+            archive.unlink(missing_ok=True)
+            raise PrebuiltFullmapUnavailable(f"checksum mismatch for {archive.name}: expected {expected}, got {actual}")
+
+    # Stage 2/2: stream-extract into a temp dir ON THE SAME FILESYSTEM as the output (so
+    # the renames are atomic), then move the primary + shards beside ``output`` named
+    # after its stem. A custom --output stem is honored, not assumed to be fullmap.redb.
+    progress.stage("Extracting Fullmap")
+    start, advance, sub_step = progress.section_loop(1, "Extract")
+    start("fullmap.tar.zst")
+    sub_step("extracting")
+    download_dir.mkdir(parents=True, exist_ok=True)
+    shard_re: re.Pattern[str] = re.compile(r"\.s(\d+)\.redb$")
+    with tempfile.TemporaryDirectory(dir=download_dir) as tmp_name:
+        tmp_dir: Path = Path(tmp_name)
+        _extract_zst_tar(archive, tmp_dir, on_phase=sub_step)
+        primary_src: Path | None = None
+        shards: dict[int, Path] = {}
+        for candidate in tmp_dir.rglob("*.redb"):
+            match: re.Match[str] | None = shard_re.search(candidate.name)
+            if match:
+                shards[int(match.group(1))] = candidate
+            elif primary_src is None or candidate.name == "fullmap.redb":
+                # Prefer a primary literally named fullmap.redb when several non-shard redb files appear.
+                primary_src = candidate
+        if primary_src is None:
+            raise PrebuiltFullmapUnavailable("prebuilt archive contained no primary .redb file")
+        primary_src.replace(output)
+        for shard_index, shard_src in sorted(shards.items()):
+            shard_src.replace(output.parent / f"{output.stem}.s{shard_index}.redb")
+
+    # The extracted redb files are the cache; drop the multi-GB archive to free the space.
+    archive.unlink(missing_ok=True)
+    download_logger.info("Installed prebuilt fullmap v{release} -> {output}", release=release, output=output)
+
+
 def build_fullmap_pipeline(
     output: Path,
     progress: PipelineProgress,
@@ -905,7 +1180,7 @@ def build_fullmap_pipeline(
         cache: Directory for downloaded BABEL files.
         version: BABEL version label.
         threads: Optional thread count forwarded to Rust.
-        aria2c: Use the optional aria2c executable for downloads when true.
+        aria2c: Use the bundled aria2c binary from the optional ``[aria2]`` extra for downloads when true.
     """
     from tablassert import rs
 
@@ -967,6 +1242,42 @@ def build_fullmap(
     version: Annotated[str, cyclopts.Parameter(name=["--version", "-v"])] = BABEL_VERSION,
     threads: Annotated[int | None, cyclopts.Parameter(name=["--threads", "-t"])] = None,
     aria2c: Annotated[bool, cyclopts.Parameter(name=["--aria2c", "-a"], negative="")] = False,
+    force: Annotated[bool, cyclopts.Parameter(name=["--force", "-f"], negative="")] = False,
 ) -> None:
-    """Build an embedded fullmap redb database from hardcoded BABEL outputs."""
+    """Build an embedded fullmap redb database, or download a prebuilt one from RENCI.
+
+    By default, first try to download a prebuilt ``fullmap.tar.zst`` published for THIS
+    Tablassert version under ``{BABEL_BASE}/{version}/fullmap/<tablassert-version>/`` and
+    extract it — far faster than building from BABEL. If no prebuilt exists for this
+    version (or the download/extract fails), fall back to a from-scratch build.
+    ``--force`` / ``-f`` skips the prebuilt attempt and always builds from BABEL outputs.
+
+    ``--aria2c`` requires the ``[aria2]`` extra, checked before the first download rather
+    than on it, so an unusable flag costs nothing.
+
+    Args:
+        output: Path to write the redb file (prebuilt extraction or build output).
+        cache: Directory for downloaded BABEL files when building from scratch.
+        version: BABEL snapshot date to fetch (a RENCI stamp, NOT Tablassert's version).
+        threads: Worker threads for a from-scratch build (auto when unset).
+        aria2c: Use the bundled aria2c binary from the ``[aria2]`` extra for downloads
+            (prebuilt or BABEL).
+        force: Skip the prebuilt download and always rebuild from BABEL outputs.
+    """
+    # A complete primary redb already on disk means the DB is in place: reuse it. Only
+    # --force rebuilds once a DB exists, so it is the explicit "fresh build" knob.
+    if not force and output.is_file() and output.stat().st_size > 0:
+        print(f"tablassert build-fullmap: fullmap already present at {output}; skipping (use --force to rebuild).", file=sys.stderr)
+        return
+    # Checked here rather than earlier: the reuse path above downloads nothing, so a
+    # missing [aria2] extra is irrelevant to it and must not fail a no-op command.
+    if aria2c and not extras.is_installed("aria2"):
+        print(f"tablassert build-fullmap: --aria2c is unavailable — {aria2_unavailable_detail()}", file=sys.stderr)
+        raise SystemExit(2)
+    if not force:
+        try:
+            run(2, fetch_prebuilt_fullmap, output, version=version, aria2c=aria2c)
+            return
+        except PrebuiltFullmapUnavailable as exc:
+            logger.warning("Prebuilt fullmap unavailable ({reason}); building from BABEL outputs.", reason=exc)
     run(3, build_fullmap_pipeline, output, cache=cache, version=version, threads=threads, aria2c=aria2c)

{tablassert-8.2.1 → tablassert-9.1.0}/src/tablassert/errors.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+from collections.abc import Sequence
 from pathlib import Path
 from typing import Literal
 
@@ -7,6 +8,7 @@ DOCS_URL: str = "https://tablassert.readthedocs.io/errors/"
 
 TablassertErrorCodes = Literal[
     "qc-runtime-missing",
+    "missing-extra",
     "graph-validation-failed",
     "section-validation-failed",
     "babel-download-failed",
@@ -26,6 +28,8 @@ TablassertErrorCodes = Literal[
     "encoding-list-requires-list",
     "encoding-list-incompatible-ops",
     "encoding-list-annotation-only",
+    "annotation-split-by-requires-column",
+    "annotation-split-by-empty",
     "qualifier-auto-derived",
     "qualifier-bad-value",
     "qualifier-unsatisfiable",
@@ -72,9 +76,72 @@ class BiolinkRelocationWarning(UserWarning):
     """
 
 
+def format_missing_extra(extra: str, problem: str) -> str:
+    """Append the install instructions for ``extra`` to a one-sentence ``problem``.
+
+    Every missing-extra failure — whichever module noticed it — ends in the same
+    two commands, so a user never has to guess the package name behind an extra or
+    which installer their CLI came from.
+
+    Args:
+        extra: Extra name as it appears in ``pyproject.toml`` (``qc``, ``agent``, ...).
+        problem: One complete sentence stating what is missing and what needed it.
+
+    Returns:
+        The full message body (the docs URL is appended separately by :class:`_Coded`).
+    """
+    return f'{problem} Install the [{extra}] extra: pip install "tablassert[{extra}]" (uv: uv tool install "tablassert[{extra}]")'
+
+
+def describe_missing(missing: Sequence[str], required_by: str) -> str:
+    """Phrase the ``problem`` sentence naming the absent distributions and the feature that wanted them.
+
+    Args:
+        missing: DISTRIBUTION names (what a user types into pip: ``scikit-learn``,
+            not the ``sklearn`` import name).
+        required_by: The feature that needs them, phrased to follow "required by".
+
+    Returns:
+        A single sentence, or a generic one when ``missing`` is empty.
+    """
+    if not missing:
+        return f"{required_by} requires optional dependencies that are not installed."
+    plural: str = "y" if len(missing) == 1 else "ies"
+    names: str = ", ".join(repr(name) for name in missing)
+    return f"Missing optional dependenc{plural} {names} — required by {required_by}."
+
+
+class MissingExtraError(_Coded, ImportError):
+    """An optional extra is not installed, reported with the exact install command.
+
+    Notes:
+        Inherits ``ImportError`` rather than :class:`TablassertError` (a ``RuntimeError``)
+        so the existing ``except ImportError`` guards wrapping lazy optional imports keep
+        catching it, and so a missing package still reads as an import failure to callers
+        that never heard of Tablassert's error hierarchy.
+    """
+
+    def __init__(self, extra: str, problem: str, *, missing: Sequence[str] = ()) -> None:
+        message: str = format_missing_extra(extra, problem)
+        super().__init__(message)
+        self.message = message
+        self.code = "missing-extra"
+        self.extra = extra
+        self.missing: tuple[str, ...] = tuple(missing)
+
+
 class QcRuntimeMissingError(TablassertError):
-    def __init__(self) -> None:
-        super().__init__("QC requires optional runtime dependencies. Install tablassert[qc].", code="qc-runtime-missing")
+    """The ``[qc]`` extra is absent on a QC code path.
+
+    Notes:
+        Keeps its own ``qc-runtime-missing`` code and ``TablassertError`` base for
+        back-compat (``build_and_audit`` catches it by name, and the code is documented),
+        but shares :class:`MissingExtraError`'s message so both read identically.
+    """
+
+    def __init__(self, missing: Sequence[str] = ()) -> None:
+        super().__init__(format_missing_extra("qc", describe_missing(missing, "the QC audit")), code="qc-runtime-missing")
+        self.missing: tuple[str, ...] = tuple(missing)
 
 
 class GraphValidationError(TablassertError):

tablassert-9.1.0/src/tablassert/extras.py

@@ -0,0 +1,159 @@
+"""Optional-extra registry: which extra ships which package, and how to install it.
+
+Tablassert's base install builds knowledge graphs from CSV/TSV sources. QC, the
+autonomous agent, and GEPA prompt optimization are OPTIONAL extras, so a user can
+reach a code path whose dependencies were never installed. When that happens the
+failure must name the extra and the exact install command — never a bare
+``ModuleNotFoundError: No module named 'sklearn'`` raised hours into a build.
+
+This module is the single source of truth for that mapping. Two entry points:
+
+- :func:`require` is a PREFLIGHT check. It probes with ``importlib.util.find_spec``
+  (which does not execute the module, so it costs nothing) and is called at the CLI
+  boundary, before any expensive work starts.
+- :func:`require_module` is the LATE check for a lazy import that has already been
+  reached, used by :mod:`tablassert.agent` and :class:`tablassert._lazy.LazyModule`.
+"""
+
+from __future__ import annotations
+
+from importlib import import_module
+from importlib.util import find_spec
+from typing import Final
+
+from tablassert.errors import MissingExtraError, QcRuntimeMissingError, describe_missing
+
+# Extra -> {import name: distribution name}. Both are needed: find_spec probes the import
+# name, while the message must show the DISTRIBUTION name, which differs often enough
+# (sklearn/scikit-learn, pdfminer/pdfminer.six) that printing the module would misdirect.
+#
+# ``rt`` is absent BY DESIGN. It installs polars[rtcompat], which imports as plain
+# ``polars``, so no find_spec probe can tell it apart from the stock wheel; its hint is
+# emitted from the polars import-failure path instead (see :func:`actionable_import_error`).
+EXTRA_PACKAGES: Final[dict[str, dict[str, str]]] = {
+    "aria2": {"aria2c": "aria2"},
+    "qc": {"sklearn": "scikit-learn", "sentence_transformers": "sentence-transformers"},
+    "agent": {"smolagents": "smolagents", "litellm": "litellm", "pdfminer": "pdfminer.six"},
+    "optimize": {"dspy": "dspy"},
+}
+
+# Import name -> owning extra, derived so the two can never drift apart.
+EXTRA_FOR_MODULE: Final[dict[str, str]] = {module: extra for extra, packages in EXTRA_PACKAGES.items() for module in packages}
+
+# What each extra unlocks, phrased to follow "required by ...".
+FEATURES: Final[dict[str, str]] = {
+    "rt": "the runtime-compatible polars build",
+    "aria2": "the bundled aria2c downloader (build-fullmap --aria2c)",
+    "qc": "the QC audit",
+    "agent": "the tablassert agent",
+    "optimize": "GEPA prompt optimization (tablassert agent --optimize)",
+}
+
+# An unregistered module reaching :func:`require_module` came from the agent's dynamic
+# lazy-import path (the only place a module name is not known statically).
+_FALLBACK_EXTRA: Final[str] = "agent"
+
+
+def install_command(extra: str) -> str:
+    """Return the pip command that installs ``extra``, quoted.
+
+    The quotes are load-bearing, not cosmetic: ``pip install tablassert[agent]`` is a glob
+    pattern in zsh and fails with ``no matches found`` before pip is ever reached.
+    """
+    return f'pip install "tablassert[{extra}]"'
+
+
+def missing(extra: str) -> tuple[str, ...]:
+    """Return the distribution names in ``extra`` that are not importable.
+
+    Probes with ``find_spec``, so a present dependency is NOT imported and an absent
+    one costs nothing: safe to call on every invocation of a command.
+
+    Args:
+        extra: A detectable extra (``qc``, ``agent`` or ``optimize``).
+
+    Returns:
+        Distribution names that could not be found, in declaration order; empty when
+        the extra is fully installed.
+
+    Raises:
+        KeyError: If ``extra`` is not detectable (notably ``rt``; see the module docstring).
+    """
+    return tuple(dist for module, dist in EXTRA_PACKAGES[extra].items() if find_spec(module) is None)
+
+
+def is_installed(extra: str) -> bool:
+    """Return whether every package in ``extra`` is importable."""
+    return not missing(extra)
+
+
+def require(extra: str, *, required_by: str | None = None) -> None:
+    """Fail loudly unless ``extra`` is fully installed.
+
+    Preflight guard: call it at the point the user's intent is known (a ``--qc`` flag, the
+    ``agent`` command) rather than where the import happens, so the error arrives before
+    the work instead of after it.
+
+    Args:
+        extra: A detectable extra (``qc``, ``agent`` or ``optimize``).
+        required_by: Feature name for the message, phrased to follow "required by".
+            Defaults to the extra's entry in :data:`FEATURES`.
+
+    Raises:
+        QcRuntimeMissingError: If ``extra`` is ``qc`` and any of its packages is absent
+            (kept distinct so the documented ``qc-runtime-missing`` code still fires).
+        MissingExtraError: If any other extra is incomplete.
+    """
+    absent: tuple[str, ...] = missing(extra)
+    if not absent:
+        return
+    if extra == "qc":
+        raise QcRuntimeMissingError(absent)
+    raise MissingExtraError(extra, describe_missing(absent, required_by or FEATURES[extra]), missing=absent)
+
+
+def require_module(module: str, *, required_by: str | None = None) -> None:
+    """Import one optional module or raise an error naming the extra that ships it.
+
+    Unlike :func:`require` this actually imports, so a package that is present but broken
+    still fails here (with its own error) rather than being reported as missing.
+
+    Args:
+        module: Import name (``smolagents``, ``dspy``, ...).
+        required_by: Feature name for the message; defaults to the owning extra's entry
+            in :data:`FEATURES`.
+
+    Raises:
+        MissingExtraError: If ``module`` cannot be imported.
+    """
+    extra: str = EXTRA_FOR_MODULE.get(module, _FALLBACK_EXTRA)
+    try:
+        import_module(module)
+    except ImportError as exc:
+        dist: str = EXTRA_PACKAGES.get(extra, {}).get(module, module)
+        raise MissingExtraError(extra, describe_missing((dist,), required_by or FEATURES[extra]), missing=(dist,)) from exc
+
+
+def actionable_import_error(module: str) -> MissingExtraError | None:
+    """Return the extra-aware error to raise for a failed ``import module``, or ``None``.
+
+    Used by :class:`tablassert._lazy.LazyModule`, which imports optional and core modules
+    alike and only knows the module name. ``None`` means "nothing useful to add" — the
+    caller re-raises the original ``ImportError`` untouched.
+
+    ``polars`` is special-cased: it is a CORE dependency, so a failure to import it is
+    almost never absence but an incompatible wheel — the exact problem the ``[rt]`` extra
+    (``polars[rtcompat]``) exists to solve.
+    """
+    if module == "polars":
+        return MissingExtraError(
+            "rt",
+            "polars failed to import — if this machine's CPU lacks the instructions the default polars wheel needs, "
+            "the runtime-compatible build is the fix.",
+            missing=("polars",),
+        )
+    extra: str | None = EXTRA_FOR_MODULE.get(module)
+    if extra is None:
+        return None
+    dist: str = EXTRA_PACKAGES[extra][module]
+    return MissingExtraError(extra, describe_missing((dist,), FEATURES[extra]), missing=(dist,))

{tablassert-8.2.1 → tablassert-9.1.0}/src/tablassert/lib.py

@@ -603,6 +603,54 @@ def format_numeric(lf: pl.LazyFrame) -> pl.LazyFrame:
     return df.lazy()
 
 
+def split_expr(col: str, delimiter: str) -> pl.Expr:
+    """Build the shared "split a delimited cell into items" expression.
+
+    The single splitting primitive behind both delimiter-driven ops: ``explode_by``
+    fans the items out into rows (node encodings), ``split_by`` keeps them as a real
+    JSON array on the row (annotations). Only what happens to the items afterwards
+    differs, so the parsing rules stay defined in exactly one place.
+
+    Items are trimmed and blanks are dropped -- a trailing or doubled separator
+    (``"a;b;"``, ``"a;;b"``) is a delimited-text artifact, not a value. A null cell
+    stays null rather than becoming a one-element list of null.
+
+    Args:
+        col: Column whose string values should be split.
+        delimiter: Separator to split on.
+
+    Returns:
+        Expression yielding a ``list[str]`` column (null preserved).
+    """
+    text: pl.Expr = pl.col(col).cast(pl.String)
+    items: pl.Expr = text.str.split(delimiter).list.eval(pl.element().str.strip_chars()).list.drop_nulls()
+    return pl.when(text.is_null()).then(None).otherwise(items.list.eval(pl.element().filter(pl.element() != "")))
+
+
+def split_list(lf: pl.LazyFrame, col: str, delimiter: str) -> pl.LazyFrame:
+    """Split a delimited cell into a real JSON array, in place.
+
+    A column encoding is scalar by construction, so a multivalued Biolink slot such as
+    ``has_evidence`` fed from an aggregated cell would otherwise be emitted as a single
+    joined string -- and ``mask_illegal_edge_fields`` wraps that scalar into a
+    one-element list, so the value survives Biolink validation while consumers iterate a
+    single ``"a|b|c"`` blob instead of three ids.
+
+    Same split as ``explode``, minus the fan-out: this is the per-row counterpart of
+    ``method: list`` (the literal form covers a fixed array known at config time, this
+    covers an array that differs on every row).
+
+    Args:
+        lf: Source LazyFrame.
+        col: Annotation column to split.
+        delimiter: Separator to split on.
+
+    Returns:
+        LazyFrame with ``col`` converted to a ``list[str]`` column, blanks dropped.
+    """
+    return lf.with_columns(split_expr(col, delimiter).alias(col))
+
+
 def prefix(lf: pl.LazyFrame, col: str, prefix: str) -> pl.LazyFrame:
     expr: pl.Expr = pl.lit(prefix) + pl.col(col).cast(pl.String)
     return lf.with_columns(expr.alias(col))
@@ -634,10 +682,14 @@ def explode(lf: pl.LazyFrame, col: str, delimiter: str) -> pl.LazyFrame:
     Returns:
         LazyFrame with one row per item (the split column becomes a list
         before the explode).
+
+    Notes:
+        Shares ``split_expr`` with ``split_list`` (the ``split_by`` annotation op), so
+        both read a delimited cell the same way: items trimmed, blanks dropped. A
+        trailing/doubled separator therefore no longer fans out rows carrying ``""``,
+        which only ever failed entity resolution and dropped the edge downstream.
     """
-    expr: pl.Expr = pl.col(col).cast(pl.String).str.split(delimiter)
-    lf = lf.with_columns(expr.alias(col))
-    return lf.explode(col)
+    return lf.with_columns(split_expr(col, delimiter).alias(col)).explode(col)
 
 
 def idx(lf: pl.LazyFrame, col: str = "extracted_from_row_number") -> pl.LazyFrame:
@@ -943,7 +995,13 @@ class Tcode(Section):
             else None,
             # --head preview: randomly sample min(HEAD_ROWS, height) rows before any encoding/resolve.
             (head, (HEAD_ROWS,)) if self.head else None,
-            [op for x in self.annotations for op in self.encoding(x, x.annotation.lower())] if self.annotations else None,
+            [
+                op
+                for x in self.annotations
+                for op in [*self.encoding(x, x.annotation.lower()), *([(split_list, (x.annotation.lower(), x.split_by))] if x.split_by else [])]
+            ]
+            if self.annotations
+            else None,
             (coerce_pvalue_columns, ()),
             (coerce_study_size_columns, ()),
             (coerce_effect_size_columns, ()),
@@ -1071,6 +1129,7 @@ PHASE_OF: dict[Callable, str] = {
     retrieval_sources: "provenance",
     inline_supporting_study: "provenance",
     prune_to_class: "finalize",
+    split_list: "encode",
     sig: "significance",
     drop_not_significant: "significance",
     trim: "finalize",

{tablassert-8.2.1 → tablassert-9.1.0}/src/tablassert/models.py

@@ -495,12 +495,40 @@ class Provenance(TablaBase):
 
 class Annotation(Encoding):
     annotation: str = Field(..., description="Output column name that receives this encoded annotation.", examples=["p_value", "cohort"])
+    split_by: str | None = Field(
+        None, description="Separator splitting each cell of a `method: column` annotation into a real JSON array.", examples=["|", ";"]
+    )
 
     @field_validator("annotation", mode="after")
     @classmethod
     def clean_annotation(cls, annotation: str) -> str:
         return annotation.lower().strip()
 
+    @model_validator(mode="after")
+    def split_by_requires_a_column(self) -> Self:
+        """Enforce that ``split_by`` carries a real separator and a ``method: column`` encoding.
+
+        ``split_by`` is the per-row counterpart of ``method: list``: it turns each cell's
+        own delimited text into a real JSON array, which is the one multivalued shape a
+        literal cannot express (a list ``encoding`` is fixed at config time, so it emits
+        the same array on every row). A ``value``/``list`` encoding therefore declares its
+        members directly rather than round-tripping them through a separator.
+        """
+        if self.split_by is None:
+            return self
+        if self.method != EncodingMethods.COLUMN:
+            raise TablassertValidationError(
+                "`split_by` splits a column's per-row text and requires `method: column`; "
+                "declare a literal multivalued annotation with `method: list` instead.",
+                code="annotation-split-by-requires-column",
+            )
+        if not self.split_by:
+            # An empty separator splits into individual characters -- exactly the
+            # character-walking failure the JSON array exists to prevent.
+            raise TablassertValidationError("`split_by` must be a non-empty separator.", code="annotation-split-by-empty")
+
+        return self
+
     @model_validator(mode="after")
     def warn_when_the_slot_cannot_reach_the_edge(self) -> Self:
         # Deliberately a WARNING, not an error like the Qualifier guards above: the value is never

{tablassert-8.2.1 → tablassert-9.1.0}/src/tablassert/qc.py

@@ -14,6 +14,7 @@ else:
     sentence_transformers = LazyModule("sentence_transformers")
     pl = LazyModule("polars")
 
+from tablassert import extras
 from tablassert.errors import QcRuntimeMissingError
 from tablassert.log import cat
 from tablassert.utils import BASE
@@ -62,7 +63,7 @@ def get_biobert() -> object:
             MODEL.mkdir(parents=True, exist_ok=True)
             model.save(MODEL)  # pyright: ignore
     except ImportError as exc:
-        raise QcRuntimeMissingError() from exc
+        raise QcRuntimeMissingError(extras.missing("qc")) from exc
     return model
 
 
@@ -106,10 +107,18 @@ def fullmap_audit(
     Returns:
         LazyFrame containing only rows whose ``col`` value passed QC.
 
+    Raises:
+        QcRuntimeMissingError: If the ``[qc]`` extra is not installed.
+
     Notes:
         Collection point: pending pairs are handled eagerly because each stage
         needs the full set of survivors to batch-similarity-score them.
     """
+    # The whole extra is checked up front, not just the package the next line needs:
+    # scikit-learn is imported here but sentence-transformers only in Stage 3, so a
+    # half-installed extra would otherwise fail after the audit had already run.
+    extras.require("qc", required_by="the QC audit")
+
     # Stage 0: deletes suspected errors.
     from rapidfuzz import fuzz
     from rapidfuzz.process import cpdist