From cded7c78e0bd390244f5d1cffcb4f8e38aa1a169 Mon Sep 17 00:00:00 2001 From: Arda Tekin <2003arda2003@gmail.com> Date: Thu, 19 Nov 2026 23:57:36 +0200 Subject: [PATCH] feat: make the rig: graph section optional RIG publication metadata is a Translator requirement, not a graph building one; drafts and internal pipelines had to author a full RIG before anything validated (#274). - Graph.rig becomes optional. Without it, build-kg emits KGX only and skips compile_rig; a build-time warning notes the absent publication metadata instead of erroring. - Defined fallbacks replace every rig-derived value: graph infores comes from a new config-level infores field (valid infores CURIE; defaults to infores:tablassert), artifacts land in a new output_dir field (defaults to the current directory). Both are rejected when rig: is set, where rig.source_info.infores_id / rig.artifact_base_path stay authoritative. - Top-level infores is exempted from the legacy-keys rejection only when rig: is absent: with rig present the rejection is unchanged, and the negative legacy corpus (MOKG.yaml) still fails on description with the migration pointer. data.get(rig) (not 'rig' in data) is the guard, because validate_assignment re-runs before-validators on the default-filled dict where rig=None looks present. - uuid_namespace keeps routing through Graph.infores_id, so RIG-bearing graphs derive byte-identical namespaces and edge ids (pinned by test); RIG-less graphs with uuid_fields namespace on the fallback infores. - Tcode infores, the QC study path, and compile_graph all read the properties instead of dereferencing rig directly. Tests: RIG-less validation with both fallbacks, rig/fallback conflicts, byte-parity pin for RIG-bearing graphs, a RIG-less end-to-end build smoke (KGX emitted with fallback provided_by, no .RIG.yaml), and the updated negative corpus. Docs: graph.md required/optional tables, legacy-key wording, llms.txt summary. Closes #274 --- CHANGELOG.md | 1 + docs/configuration/graph.md | 14 ++-- docs/index.md | 2 +- llms.txt | 2 +- src/tablassert/cli.py | 17 +++-- src/tablassert/lib.py | 41 +++++++---- src/tablassert/models.py | 69 ++++++++++++++++-- tests/test_cover_models.py | 49 +++++++++++++ tests/test_e2e_smoke.py | 125 ++++++++++++++++++++++++++++++++ tests/test_models.py | 16 ++-- tests/test_realworld_configs.py | 3 + 11 files changed, 300 insertions(+), 39 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4bb24097..cf5e5701 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,6 +16,7 @@ All notable changes to this project are documented in this file. ### Changed +- **The `rig:` graph section is now optional.** Graphs without `rig:` validate, `build-kg` emits KGX only (skipping `compile_rig`) with a build-time warning, and two optional top-level fallback fields, `infores` (defaulting to `infores:tablassert`) and `output_dir` (defaulting to the current directory), supply provenance and output paths when `rig:` is omitted, while being rejected when `rig:` is present so publication metadata remains authoritative. ([#288](https://github.com/SkyeAv/Tablassert/pull/288), [#274](https://github.com/SkyeAv/Tablassert/issues/274)) - **CI runs only when a release is cut or on manual dispatch.** `.github/workflows/ci.yml` no longer triggers on pull requests; it runs on a push to main that changes `project.version` in `pyproject.toml` (the `chore(release):` commit, detected by the same `detect-pyproject-version-change` action the tag and PyPI workflows use) or via `workflow_dispatch`. The PR-only `changes` path filter, the push-back `autofix` job, the `python-smoke` subset, and the CI `changelog` job are removed; formatting is now a check-only `format` job, and the changelog requirement stays enforced by the pre-push hook. Run `make check` locally before opening a pull request. - **The vulture allowlist lives in `scripts/` next to the other developer tooling.** `vulture_whitelist.py` moves to `scripts/vulture_whitelist.py` unchanged; the `[tool.vulture]` `paths` list drops the now-redundant root entry because `scripts` is already scanned, and the CI `python` path filter, the pre-commit hook comment, and the CONTRIBUTING dead-code section follow the new location. The gate is behaviorally identical: same vulture pin, same config, same allowlist content. ([#287](https://github.com/SkyeAv/Tablassert/pull/287)) diff --git a/docs/configuration/graph.md b/docs/configuration/graph.md index 2abfcd40..de72705c 100644 --- a/docs/configuration/graph.md +++ b/docs/configuration/graph.md @@ -9,7 +9,7 @@ A graph configuration file specifies: - Output knowledge graph name and version - List of table configurations to process - Database location for entity resolution -- The **required `rig:` section**: all Resource Ingest Guide (RIG) metadata emitted as `_.RIG.yaml` +- The **optional `rig:` section**: all Resource Ingest Guide (RIG) metadata emitted as `_.RIG.yaml`; omit it for drafts and internal pipelines (KGX artifacts still build) QC auditing and verbose logging are controlled at build time via the `build-kg --qc` and `build-kg --log` flags: they are **not** graph-config fields. @@ -23,22 +23,24 @@ QC auditing and verbose logging are controlled at build time via the `build-kg - | `version` | String | Knowledge graph version (used in output filenames) | | `tables` | List[Path] | Paths to table configuration YAML files | | `fullmap` | Path | Path to the fullmap redb file, or a base directory containing it | -| `rig` | RIGConfig | Resource Ingest Guide metadata (see below) | - -The legacy top-level RIG fields (`description`, `contributions`, `ui_explanation`, `infores`) are **rejected** with a migration pointer; they now live under `rig:`. ### Optional Fields | Field | Type | Description | | ------- | ------ | ------------- | +| `rig` | RIGConfig | Resource Ingest Guide metadata emitted as `_.RIG.yaml` (see below). Omit it for draft/internal builds: KGX artifacts still build, a build-time warning notes the absent publication metadata, and no `.RIG.yaml` is emitted | +| `infores` | String | RIG-less builds only: graph-level primary knowledge source infores recorded as node `provided_by` (must be a valid infores CURIE). Mutually exclusive with `rig:`; defaults to `infores:tablassert` | +| `output_dir` | Path | RIG-less builds only: local output directory for the KGX artifacts (`rig.artifact_base_path` owns it otherwise). Mutually exclusive with `rig:`; defaults to the current directory | | `uuid_fields` | List[str] | Edge fields that constitute edge identity. Only these feed the derived edge `id` (see [Stable edge ids](#stable-edge-ids)) | -| `uuid_domain` | String | Explicit UUID namespace. Defaults to `rig.source_info.infores_id` when `uuid_fields` is set, `TABLASSERT` otherwise | +| `uuid_domain` | String | Explicit UUID namespace. Defaults to the graph infores (`rig.source_info.infores_id`, else the `infores` fallback) when `uuid_fields` is set, `TABLASSERT` otherwise | | `uuid_on_collision` | `error` \| `merge` | What to do when two different edges derive one id. `error` (default) aborts; `merge` folds them into one edge. Requires `uuid_fields` (see [Merging collisions instead](#merging-collisions-instead)) | | `qc_similarity_threshold` | Float 0-1 | SapBERT cosine threshold used by QC (default 0.5) | | `qc_fuzzy_ratio_threshold` | Float 0-100 | RapidFuzz ratio threshold used by QC (default 70) | | `qc_fuzzy_partial_threshold` | Float 0-100 | RapidFuzz partial/token-set threshold used by QC (default 80) | | `qc_aliases` | Mapping[String, String] | Source-text aliases applied before QC similarity stages (default empty) | +The legacy top-level RIG fields (`description`, `contributions`, `ui_explanation`, `infores`) are **rejected when `rig:` is set** with a migration pointer; they live under `rig:`. (`infores` at the top level without `rig:` is the RIG-less fallback field, not a legacy key.) + ## Stable edge ids Every edge gets a deterministic `id`: a UUID v3 derived from the edge itself. By default it is @@ -153,7 +155,7 @@ opt-in. The default `error` behavior is unchanged in every respect. ### Namespacing Because a narrow field set no longer distinguishes graphs by accident, declaring `uuid_fields` -moves the UUID namespace onto the graph's own `rig.source_info.infores_id`. Two graphs asserting +moves the UUID namespace onto the graph's own infores (`rig.source_info.infores_id`, or the `infores` fallback on RIG-less graphs). Two graphs asserting the same triple from the same publication then still derive different ids, structurally. Set `uuid_domain` only when graphs must deliberately **share** an id space: a KG compiled in diff --git a/docs/index.md b/docs/index.md index ae64a6d9..5cf0bc97 100644 --- a/docs/index.md +++ b/docs/index.md @@ -38,7 +38,7 @@ expectations. ### Reference -- **[Configuration](configuration/graph.md)**: graph-level schema, the required `rig:` section, and stable edge ids +- **[Configuration](configuration/graph.md)**: graph-level schema, the optional `rig:` section, and stable edge ids - **[Table Configuration](configuration/table.md)**: sources, statements, entity-resolution rules, provenance, annotations - **[Advanced Example](configuration/advanced-example.md)**: a fully-annotated real-world configuration - **[API Reference](api/fullmap.md)**: `resolve()` and `quick_map()` diff --git a/llms.txt b/llms.txt index 3091f560..612da81f 100644 --- a/llms.txt +++ b/llms.txt @@ -15,7 +15,7 @@ Current CLI behavior queries an embedded redb database whose primary file is `fu ## YAML Authoring - [Table Configuration Reference](docs/configuration/table.md): the table (`Section`) schema, template/sections patterns, and field semantics. -- [Graph Configuration Reference](docs/configuration/graph.md): the Graph config fields (`name`/`version`/`tables`/`fullmap`/`rig`, plus optional `uuid_fields`/`uuid_domain`/`uuid_on_collision` and QC controls `qc_similarity_threshold`/`qc_fuzzy_ratio_threshold`/`qc_fuzzy_partial_threshold`/`qc_aliases`) and orchestration model. +- [Graph Configuration Reference](docs/configuration/graph.md): the Graph config fields (`name`/`version`/`tables`/`fullmap`, optional `rig` plus RIG-less fallbacks `infores`/`output_dir`, and `uuid_fields`/`uuid_domain`/`uuid_on_collision` with QC controls `qc_similarity_threshold`/`qc_fuzzy_ratio_threshold`/`qc_fuzzy_partial_threshold`/`qc_aliases`) and orchestration model. - [Use Case Gallery](docs/examples.md): real-world table-configuration patterns for common data types. - [Tutorial Table Example](docs/examples/tutorial-table.yaml): minimal table configuration. - [Tutorial Graph Example](docs/examples/tutorial-graph.yaml): minimal graph configuration. diff --git a/src/tablassert/cli.py b/src/tablassert/cli.py index 2fc798b2..5e5574a2 100644 --- a/src/tablassert/cli.py +++ b/src/tablassert/cli.py @@ -391,7 +391,7 @@ def build_graph_pipeline( "head": head, "linkouts": linkouts, "name": g.name, - "infores": g.rig.source_info.infores_id, + "infores": g.infores_id, "qc_similarity_threshold": g.qc_similarity_threshold, "qc_fuzzy_ratio_threshold": g.qc_fuzzy_ratio_threshold, "qc_fuzzy_partial_threshold": g.qc_fuzzy_partial_threshold, @@ -466,6 +466,13 @@ def build_graph_pipeline( progress.stage("Compiling Graph") start, advance, sub_step = progress.section_loop(len(subgraphs), "Graph") start(f"{g.name} · v{g.version}") + if g.rig is None: + logger.warning( + "Graph {name} v{version} has no `rig:` section; emitting KGX artifacts only (provided_by falls back to {infores}). Add `rig:` when the graph is headed for Translator publication.", + name=g.name, + version=g.version, + infores=g.infores_id, + ) # on_phase drives the phase tag (scan → normalize → write-nodes → write-edges → dedup → rig); # on_subgraph ticks the bar once per subgraph, so the total is len(subgraphs). compile_graph( @@ -479,6 +486,8 @@ def build_graph_pipeline( uuid_fields=g.uuid_fields, uuid_domain=g.uuid_namespace, uuid_on_collision=g.uuid_on_collision, + output_dir=g.output_dir, + infores=g.infores if g.rig is None else None, ) # Stage 7/7 (only with --qc): assert over the final NDJSON files. @@ -490,9 +499,7 @@ def build_graph_pipeline( # Association is the author's accepted default. Graphs where every section is pinned # are unaffected; a mixed graph should split or accept the stricter gate. An empty # ``category_override: {}`` pins nothing and counts as undeclared. - study_final_ndjson( - g.name, g.version, Path(g.rig.artifact_base_path), category_override_declared=any(x.statement.category_override for x in tcode) - ) + study_final_ndjson(g.name, g.version, g.artifact_path, category_override_declared=any(x.statement.category_override for x in tcode)) logger.info("Built graph {name} v{version}: {n} sections", name=g.name, version=g.version, n=n) @@ -953,7 +960,7 @@ def build_kg( cached under its own ``.head`` store, so it never reuses or replaces a full build. linkouts: Append the EdgeLinkouts per-edge record URL (``https://linkouts.skyelanegoetz.com/edges/{edge_id}``, resolved to the final - edge id after dedup) to the graph infores entry (``rig.source_info.infores_id``) + edge id after dedup) to the graph infores entry (``rig.source_info.infores_id``, or the ``infores`` fallback on RIG-less graphs) in every emitted edge's ``sources`` list, so linkouts.skyelanegoetz.com can deep-link each edge. Sections declaring ``provenance.override`` are untouched (their ``sources`` emission is author-controlled). Cached under its own diff --git a/src/tablassert/lib.py b/src/tablassert/lib.py index 0910a27a..e7f9ad10 100644 --- a/src/tablassert/lib.py +++ b/src/tablassert/lib.py @@ -2268,7 +2268,7 @@ def _write_ndjson( edges_tmp: Path, name: str, version: str, - rig: RIGConfig, + rig: RIGConfig | None, section_sources: list[dict[str, object]] | None, on_phase: Callable[[str], None] | None = None, domain: str = "TABLASSERT", @@ -2294,7 +2294,8 @@ def _write_ndjson( edges_tmp: Working ``.edges.ndjson.tmp`` output path. name: Graph name (output stems and RIG). version: Graph version string. - rig: Validated ``rig:`` graph-config section driving the RIG. + rig: Optional validated ``rig:`` graph-config section driving the RIG; + ``None`` (RIG-less build) skips the ``rig`` phase. section_sources: Per-section source descriptors for the RIG relevant-file cross-check. on_phase: Optional callback fired with ``"write-nodes"``, @@ -2331,23 +2332,27 @@ def _write_ndjson( dedup_stream(nodes_tmp, is_edges=False) # Phase: rig. Summaries come from the FINAL deduplicated KGX files, and the - # assembled document is audited before anything is written. - if on_phase is not None: - on_phase("rig") - compile_rig(name, version, rig, section_sources, nodes_tmp.with_suffix(""), edges_tmp.with_suffix("")) + # assembled document is audited before anything is written. RIG-less builds + # skip this phase entirely (#274): only the KGX artifacts are emitted. + if rig is not None: + if on_phase is not None: + on_phase("rig") + compile_rig(name, version, rig, section_sources, nodes_tmp.with_suffix(""), edges_tmp.with_suffix("")) def compile_graph( subgraphs: list[Path], name: str, version: str, - rig: RIGConfig | dict[str, Any], + rig: RIGConfig | dict[str, Any] | None, section_sources: list[dict[str, object]] | None = None, on_phase: Callable[[str], None] | None = None, on_subgraph: Callable[[], None] | None = None, uuid_fields: list[str] | None = None, uuid_domain: str | None = None, uuid_on_collision: str = "error", + output_dir: Path | None = None, + infores: str | None = None, ) -> None: """Aggregate subgraph parquets for NDJSON KGX export using a lazy scan. @@ -2359,6 +2364,8 @@ def compile_graph( ``.RIG.yaml`` (source metadata, artifact bases, provenance). A plain dict is validated as :class:`RIGConfig` first, so programmatic callers get the same config-time errors as YAML. + ``None`` builds KGX only: no ``.RIG.yaml`` is emitted and the + ``rig`` phase is skipped. section_sources: Per-section source descriptors (``local``, ``urls``) used to cross-check configured RIG relevant-file entries. on_phase: Optional callback fired with the current phase label @@ -2375,11 +2382,16 @@ def compile_graph( provided -- and to ``TABLASSERT`` otherwise. uuid_on_collision: ``error`` aborts when two different edges derive one id; ``merge`` folds them into one edge instead (``Graph.uuid_on_collision``). + output_dir: RIG-less output directory for the KGX artifacts (``Graph.output_dir``); + ignored when ``rig`` is set. + infores: RIG-less graph-level infores recorded as ``provided_by`` + (``Graph.infores_id``); ignored when ``rig`` is set. Returns: - ``None``; writes ``_.nodes.ndjson``, - ``_.edges.ndjson``, and ``_.RIG.yaml`` - into ``rig.artifact_base_path`` (created when missing). + ``None``; writes ``_.nodes.ndjson`` and + ``_.edges.ndjson`` into the output directory + (``rig.artifact_base_path``, else ``output_dir``, else the current + directory), plus ``_.RIG.yaml`` when ``rig`` is set. Raises: TablassertError: With code ``rig-validation-failed`` when the @@ -2388,8 +2400,8 @@ def compile_graph( different edges derive one id under the declared ``uuid_fields`` and ``uuid_on_collision`` is ``error``. """ - rig_cfg: RIGConfig = rig if isinstance(rig, RIGConfig) else RIGConfig.model_validate(rig) - out_dir: Path = Path(rig_cfg.artifact_base_path) + rig_cfg: RIGConfig | None = None if rig is None else (rig if isinstance(rig, RIGConfig) else RIGConfig.model_validate(rig)) + out_dir: Path = Path(rig_cfg.artifact_base_path) if rig_cfg is not None else (output_dir or Path(".")) out_dir.mkdir(parents=True, exist_ok=True) p: Path = out_dir / f"{name}_{version}.tmp" @@ -2401,11 +2413,12 @@ def compile_graph( if n.exists(): n.unlink() - domain: str = uuid_domain or (rig_cfg.source_info.infores_id if uuid_fields else "TABLASSERT") + graph_infores: str = rig_cfg.source_info.infores_id if rig_cfg is not None else (infores or "infores:tablassert") + domain: str = uuid_domain or (graph_infores if uuid_fields else "TABLASSERT") subnodes: list[pl.LazyFrame] subedges: list[pl.LazyFrame] - subnodes, subedges = _collect_subframes(subgraphs, on_phase, on_subgraph, rig_cfg.source_info.infores_id) + subnodes, subedges = _collect_subframes(subgraphs, on_phase, on_subgraph, graph_infores) _write_ndjson(subnodes, subedges, n, e, name, version, rig_cfg, section_sources, on_phase, domain, uuid_fields, uuid_on_collision) diff --git a/src/tablassert/models.py b/src/tablassert/models.py index f0aecc03..0332a1ee 100644 --- a/src/tablassert/models.py +++ b/src/tablassert/models.py @@ -1247,7 +1247,7 @@ class RIGProvenanceInfo(TablaBase): class RIGConfig(TablaBase): - """The required ``rig:`` graph-config section driving `.RIG.yaml` generation. + """The optional ``rig:`` graph-config section driving `.RIG.yaml` generation. Carries every human-authored RIG fact. The generator derives only the mechanical pieces (generated artifact file entries, observed target @@ -1325,7 +1325,20 @@ class Graph(TablaBase): version: str = Field(..., description="Graph version label.") tables: list[Path] = Field(..., description="Paths to table YAML files included in this graph.", examples=[["tables/tutorial-table.yaml"]]) fullmap: Path = Field(..., description="Base fullmap directory or fullmap redb file for entity resolution.", examples=[".fullmap"]) - rig: RIGConfig = Field(..., description="Resource Ingest Guide metadata emitted as _.RIG.yaml.") + rig: RIGConfig | None = Field( + default=None, + description="Optional Resource Ingest Guide metadata emitted as _.RIG.yaml. Omit it for draft/internal builds: KGX artifacts still build, with `infores` and `output_dir` supplying the fallbacks RIG metadata normally provides.", + ) + infores: str | None = Field( + default=None, + description="Graph-level primary knowledge source infores for builds WITHOUT `rig:`. Must be a valid infores CURIE; mutually exclusive with `rig:`. Defaults to `infores:tablassert`.", + examples=["infores:my-draft-kg"], + ) + output_dir: Path | None = Field( + default=None, + description="Local output directory for the KGX artifacts when `rig:` is absent (`rig.artifact_base_path` owns it otherwise). Mutually exclusive with `rig:`; defaults to the current directory.", + examples=["./release"], + ) uuid_fields: list[str] | None = Field( default=None, description="Edge fields that constitute edge identity; only these feed the derived edge `id`, so an attribute-only change leaves it alone. Unset hashes the whole record.", @@ -1400,21 +1413,65 @@ def reject_legacy_rig_keys(cls, data: Any) -> Any: each stale key and its new home under ``rig:`` so migration is mechanical. """ if isinstance(data, dict): - found: list[str] = sorted(k for k in data if k in LEGACY_RIG_KEYS) + # Legacy RIG keys never belong at the top level; only `infores` doubles as + # the RIG-less fallback field (#274), so it is exempt from the legacy check + # when no `rig:` section is present. With `rig:` set the top level is owned + # by `rig.source_info.infores_id` and every legacy key is rejected. + found: list[str] = sorted(k for k in data if k in LEGACY_RIG_KEYS and (k != "infores" or data.get("rig"))) if found: moves: str = "; ".join(f"`{k}` -> `{LEGACY_RIG_KEYS[k]}`" for k in found) raise TablassertValidationError( - f"RIG metadata moved under the required `rig:` section: {moves}. " + f"RIG metadata moved under the `rig:` section: {moves}. " "Top-level placement is rejected so a build can never emit a RIG that " "silently disagrees with its graph config.", code="rig-legacy-keys", ) return data + @model_validator(mode="after") + def rig_fallback_fields(self: Self) -> Self: + """Resolve the RIG-less fallback fields. + + ``infores`` and ``output_dir`` only exist for builds without ``rig:`` — with a RIG + section its ``source_info.infores_id`` / ``artifact_base_path`` are authoritative, + so a duplicate declaration is rejected instead of silently drifting. ``infores`` + must still be a valid infores CURIE: node ``provided_by`` and validate-kgx + identity checks read it either way. + """ + if self.rig is not None: + if self.infores is not None or self.output_dir is not None: + raise TablassertValidationError( + "`infores` and `output_dir` are RIG-less fallbacks; remove them when `rig:` is set (rig.source_info.infores_id and rig.artifact_base_path own both values).", + code="graph-bad-infores", + ) + return self + if self.infores is not None: + # object.__setattr__: plain assignment re-runs mode="before" validators with the + # default-filled dict under validate_assignment, where rig=None looks "present". + object.__setattr__(self, "infores", validate_infores_curie(self.infores, "graph-bad-infores")) + return self + @property def infores_id(self) -> str: - """Graph-level primary knowledge source infores (from ``rig.source_info.infores_id``).""" - return self.rig.source_info.infores_id + """Graph-level primary knowledge source infores. + + From ``rig.source_info.infores_id`` when `rig:` is set, else the explicit + ``infores`` fallback, else the documented ``infores:tablassert`` default. + """ + if self.rig is not None: + return self.rig.source_info.infores_id + return self.infores or "infores:tablassert" + + @property + def artifact_path(self) -> Path: + """Local directory the KGX artifacts are written to. + + ``rig.artifact_base_path`` when `rig:` is set, else the explicit ``output_dir`` + fallback, else the current directory. + """ + if self.rig is not None: + return Path(self.rig.artifact_base_path) + return self.output_dir or Path(".") @property def uuid_namespace(self) -> str: diff --git a/tests/test_cover_models.py b/tests/test_cover_models.py index 54bb1e70..e41b3b9b 100644 --- a/tests/test_cover_models.py +++ b/tests/test_cover_models.py @@ -10,6 +10,7 @@ from __future__ import annotations +from pathlib import Path from typing import Any import pytest @@ -41,6 +42,7 @@ def test_graph_explicit_none_rig_ui_explanation_short_circuits(rig_factory: Any) graph: Graph = Graph.model_validate( # pyright: ignore {"name": "TEST", "version": "1.0.0", "tables": ["./table.yaml"], "fullmap": "./fullmap", "rig": rig_data} ) + assert graph.rig is not None assert graph.rig.ui_explanation is None @@ -149,3 +151,50 @@ def test_section_source_label_per_kind() -> None: assert _section_source_label(NDJSON.model_validate({"kind": "ndjson", "local": "./t.ndjson", "url": urls})) == "`t.ndjson`" excel: Excel = Excel.model_validate({"kind": "excel", "local": "./t.xlsx", "url": urls, "sheet": "S1"}) assert _section_source_label(excel) == "`t.xlsx` (sheet `S1`)" + + +def test_graph_without_rig_validates_with_documented_fallbacks(rig_factory: Any) -> None: + """A RIG-less graph validates (#274): infores defaults to `infores:tablassert`, artifacts to CWD.""" + graph: Graph = Graph(name="TEST", version="1.0.0", tables=[Path("./table.yaml")], fullmap=Path("./fullmap")) + assert graph.rig is None + assert graph.infores_id == "infores:tablassert" + assert graph.artifact_path == Path(".") + assert graph.uuid_namespace == "TABLASSERT" # whole-record hash default unchanged + explicit: Graph = Graph( + name="TEST", version="1.0.0", tables=[Path("./table.yaml")], fullmap=Path("./fullmap"), infores="infores:draft-kg", output_dir=Path("./out") + ) + assert explicit.infores_id == "infores:draft-kg" + assert explicit.artifact_path == Path("./out") + namespaced: Graph = Graph( + name="TEST", + version="1.0.0", + tables=[Path("./table.yaml")], + fullmap=Path("./fullmap"), + infores="infores:draft-kg", + uuid_fields=["subject", "predicate", "object"], + ) + assert namespaced.uuid_namespace == "infores:draft-kg" + + +def test_graph_rig_conflict_with_fallback_fields(rig_factory: Any) -> None: + """`infores`/`output_dir` are RIG-less fallbacks; with `rig:` set they are rejected.""" + with pytest.raises(ValidationError): + Graph(name="TEST", version="1.0.0", tables=[Path("./table.yaml")], fullmap=Path("./fullmap"), rig=rig_factory(), infores="infores:draft-kg") + with pytest.raises(ValidationError): + Graph(name="TEST", version="1.0.0", tables=[Path("./table.yaml")], fullmap=Path("./fullmap"), rig=rig_factory(), output_dir=Path("./out")) + + +def test_graph_rig_output_unchanged_for_rig_bearing_graphs(rig_factory: Any) -> None: + """RIG-bearing graphs keep identical infores/uuid behavior (#274 pin).""" + graph: Graph = Graph( + name="TEST", + version="1.0.0", + tables=[Path("./table.yaml")], + fullmap=Path("./fullmap"), + rig=rig_factory(), + uuid_fields=["subject", "predicate", "object"], + ) + assert graph.rig is not None + assert graph.infores_id == graph.rig.source_info.infores_id + assert graph.artifact_path == Path(graph.rig.artifact_base_path) + assert graph.uuid_namespace == graph.rig.source_info.infores_id diff --git a/tests/test_e2e_smoke.py b/tests/test_e2e_smoke.py index e22a4195..f69218c2 100644 --- a/tests/test_e2e_smoke.py +++ b/tests/test_e2e_smoke.py @@ -701,3 +701,128 @@ def test_prune_command_cleans_the_final_built_graph(tmp_path: Path, monkeypatch: current: list[str] = text.splitlines() pending_built = iter(built_lines) assert all(line in pending_built for line in current) + + +def test_build_pipeline_without_rig_emits_kgx_only(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None: + """SMOKE (#274): a RIG-less graph config validates, builds KGX, passes validate_kgx, and emits no RIG. + + Node ``provided_by`` falls back to the configured ``infores`` (or ``infores:tablassert`` + default), and no ``_.RIG.yaml`` appears in the output directory. + """ + from tablassert.biolink import validate_kgx + + monkeypatch.chdir(tmp_path) + (tmp_path / ".tablassert" / "store").mkdir(parents=True) + + fullmap: Path = _build_real_redb(tmp_path / "fullmap") + + data: Path = tmp_path / "data.tsv" + data.write_text("brca1\tmapk1\nbrca1\tmapk1\n") + + table: Path = tmp_path / "table.yaml" + table_config: dict[str, Any] = { + "template": { + "source": {"kind": "text", "local": str(data), "url": ["https://example.com/data.tsv"], "delimiter": "\t"}, + "statement": { + "subject": {"method": "column", "encoding": "A"}, + "predicate": "associated_with", + "object": {"method": "column", "encoding": "B"}, + }, + "provenance": {"repo": "PMC", "publication": "PMC0000000"}, + } + } + to_yaml(table, table_config) + + out_dir: Path = tmp_path / "release" + graph: Path = tmp_path / "graph.yaml" + graph_config: dict[str, Any] = { + "name": "DRAFT_KG", + "version": "1.0.0", + "tables": [str(table)], + "fullmap": str(fullmap), + "infores": "infores:draft-kg", + "output_dir": str(out_dir), + } + to_yaml(graph, graph_config) + + build_pipeline(graph, PipelineProgress(total_stages=6)) + + nodes: Path = out_dir / "DRAFT_KG_1.0.0.nodes.ndjson" + edges: Path = out_dir / "DRAFT_KG_1.0.0.edges.ndjson" + assert nodes.is_file() + assert edges.is_file() + assert not (out_dir / "DRAFT_KG_1.0.0.RIG.yaml").exists(), "RIG-less builds must not emit a RIG" + + node_records: list[dict[str, Any]] = [json.loads(line) for line in nodes.read_text().splitlines() if line.strip()] + edge_records: list[dict[str, Any]] = [json.loads(line) for line in edges.read_text().splitlines() if line.strip()] + assert node_records + assert edge_records + for record in node_records: + assert record["provided_by"] == ["infores:draft-kg"] + assert "HGNC:1100" in edges.read_text() + report: dict[str, Any] = validate_kgx(nodes, edges) + assert report["ok"] is True + + +def test_build_pipeline_rig_and_rigless_kgx_byte_parity(tmp_path: Path, monkeypatch: pytest.MonkeyPatch, rig_factory: Any) -> None: + """SMOKE (#274): RIG-bearing and RIG-less builds with the same infores emit byte-identical KGX.""" + monkeypatch.chdir(tmp_path) + (tmp_path / ".tablassert" / "store").mkdir(parents=True) + + fullmap: Path = _build_real_redb(tmp_path / "fullmap") + data: Path = tmp_path / "data.tsv" + data.write_text("brca1\tmapk1\n") + + table: Path = tmp_path / "table.yaml" + to_yaml( + table, + { + "template": { + "source": {"kind": "text", "local": str(data), "url": ["https://example.com/data.tsv"], "delimiter": "\t"}, + "statement": { + "subject": {"method": "column", "encoding": "A"}, + "predicate": "associated_with", + "object": {"method": "column", "encoding": "B"}, + }, + "provenance": {"repo": "PMC", "publication": "PMC0000000"}, + } + }, + ) + + out_with_rig: Path = tmp_path / "out_rig" + out_without_rig: Path = tmp_path / "out_rigless" + graph_with_rig: Path = tmp_path / "graph_rig.yaml" + graph_without_rig: Path = tmp_path / "graph_rigless.yaml" + to_yaml( + graph_with_rig, + { + "name": "PARITY_KG", + "version": "1.0.0", + "tables": [str(table)], + "fullmap": str(fullmap), + "uuid_fields": ["subject", "predicate", "object"], + "rig": rig_factory( + tmp_path, infores_id="infores:parity-kg", artifact_base_path=str(out_with_rig), source_info={"description": "parity graph"} + ), + }, + ) + to_yaml( + graph_without_rig, + { + "name": "PARITY_KG", + "version": "1.0.0", + "tables": [str(table)], + "fullmap": str(fullmap), + "uuid_fields": ["subject", "predicate", "object"], + "infores": "infores:parity-kg", + "output_dir": str(out_without_rig), + }, + ) + + build_pipeline(graph_with_rig, PipelineProgress(total_stages=6)) + build_pipeline(graph_without_rig, PipelineProgress(total_stages=6)) + + assert (out_with_rig / "PARITY_KG_1.0.0.RIG.yaml").is_file() + assert not (out_without_rig / "PARITY_KG_1.0.0.RIG.yaml").exists() + assert (out_with_rig / "PARITY_KG_1.0.0.nodes.ndjson").read_bytes() == (out_without_rig / "PARITY_KG_1.0.0.nodes.ndjson").read_bytes() + assert (out_with_rig / "PARITY_KG_1.0.0.edges.ndjson").read_bytes() == (out_without_rig / "PARITY_KG_1.0.0.edges.ndjson").read_bytes() diff --git a/tests/test_models.py b/tests/test_models.py index 0a4d9482..bc3ba359 100644 --- a/tests/test_models.py +++ b/tests/test_models.py @@ -44,23 +44,27 @@ def test_section_from_minimal_yaml(fixtures_path: Path) -> None: assert section.provenance.repo == "PMC" -def test_graph_rig_section_is_required_and_defaults_apply(rig_factory: Any) -> None: - """the required rig: section validates, with RIG-schema defaults where honest.""" +def test_graph_rig_section_defaults_apply(rig_factory: Any) -> None: + """the optional rig: section validates when provided, with RIG-schema defaults where honest.""" graph: Graph = Graph( # pyright: ignore name="TEST", version="1.0.0", tables=[Path("./table.yaml")], fullmap=Path("./fullmap"), rig=rig_factory() ) assert graph.infores_id == "infores:test-kg" # Default ingest category reflects what Tablassert builds: knowledge from tables. + assert graph.rig is not None assert graph.rig.ingest_info.ingest_categories == ["translator_knowledge_creator"] # The UI prefix is optional; compose_ui_explanation always keeps the default text. + assert graph.rig is not None assert graph.rig.ui_explanation is None -def test_graph_rejects_missing_rig_section() -> None: - """a graph without a rig: section cannot build a PR-worthy RIG and is rejected.""" +def test_graph_accepts_missing_rig_section() -> None: + """a graph without a rig: section validates and falls back to the documented defaults (#274).""" data: dict[str, Any] = {"name": "TEST", "version": "1.0.0", "tables": [Path("./table.yaml")], "fullmap": Path("./fullmap")} - with pytest.raises(ValidationError): - Graph.model_validate(data) + graph: Graph = Graph.model_validate(data) + assert graph.rig is None + assert graph.infores_id == "infores:tablassert" + assert graph.artifact_path == Path(".") def test_graph_rejects_legacy_top_level_rig_keys(rig_factory: Any) -> None: diff --git a/tests/test_realworld_configs.py b/tests/test_realworld_configs.py index 4e162be5..6750e717 100644 --- a/tests/test_realworld_configs.py +++ b/tests/test_realworld_configs.py @@ -188,8 +188,11 @@ def test_multisection_v12_expands_all_sections() -> None: def test_dakp_graph_rig_populated() -> None: """The DAKP graph configuration validates with a fully populated RIG.""" graph: Graph = Graph.model_validate(from_yaml(POSITIVE / "dakp" / "graph.yaml")) + assert graph.rig is not None assert graph.rig.source_info.infores_id == "infores:multiomics-drugapprovals" + assert graph.rig is not None assert graph.rig.ingest_info is not None + assert graph.rig is not None assert graph.rig.provenance_info.contributions