pdssp-prov-toolkit 1.0.1__tar.gz

pdssp_prov_toolkit-1.0.1/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: pdssp_prov_toolkit
+Version: 1.0.1
+Summary: Shared W3C PROV-DM vocabulary, document helpers, and Graphviz/HTML rendering for FAIR-transformation provenance across PDSSP services.
+Author: Jean-Christophe Malapert
+Author-email: Jean-Christophe Malapert <jean-christophe.malapert@cnes.fr>
+License-Expression: Apache-2.0
+Requires-Dist: prov>=3.1.0
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# PDSSP Prov Toolkit
+
+[![image](https://img.shields.io/badge/Maintained%3F-yes-green.svg)]()
+
+![image]()
+
+Shared W3C PROV-DM vocabulary, document helpers, and Graphviz/HTML rendering for FAIR-transformation provenance across PDSSP services.
+
+## Why this exists
+
+Two PDSSP services (`ode_stac_proxy`, a live STAC proxy, and
+`geocoding-api`, an offline GeoPackage/OpenSearch pipeline) each expose a
+`GET /prov` endpoint describing how their own FAIR-transformed data is
+produced, as a W3C PROV-DM document. Both were built independently, before
+this package existed — and by the time it was extracted, each had grown
+its own, already-drifted copy of the same vocabulary and rendering code:
+
+- `geocoding-api` had added Subresource Integrity hashes pinning its
+  Viz.js CDN scripts (a real security hardening) and `wasInformedBy`/
+  `license`/`crs` support — none of which had made it back into
+  `ode_stac_proxy`.
+- `ode_stac_proxy` had added `hadMember`/`hadPlan` support — which had
+  never made it into `geocoding-api`.
+
+Neither service noticed the other's fixes, because there was nothing to
+notice — it was two copies, not one dependency. This package is that one
+dependency: the union of both, so a fix or an addition made once benefits
+every PDSSP service producing FAIR-transformation provenance, present or
+future.
+
+**What deliberately did *not* move here**: each service's own
+document-assembly logic — *which* activities and entities its own
+pipeline has, and how they connect — stays in that service. A STAC proxy
+harvesting one live upstream and a batch pipeline harvesting several
+static sources into per-body GeoPackages don't share a pipeline shape, so
+forcing one here would fit neither well. What both actually needed
+identically is the vocabulary they build records with and the code that
+turns the finished document into a graph — that's the whole scope of this
+package.
+
+## Relationship to `prov`'s own `prov.dot`
+
+This package depends on [`prov`](https://prov.readthedocs.io/), and `prov`
+already ships its own optional Graphviz export
+(`prov.dot.prov_to_dot`, via the `prov[dot]` extra) — doing, on paper, the
+same job as `pdssp_prov_toolkit.dot`. They even use the *same* node
+colours (`#FFFC87`/`#9FB1FC`/`#FED37F`), because both independently follow
+the same W3C PROV Primer / ProvToolbox convention. So why not just use it?
+
+| | `prov[dot]` | `pdssp_prov_toolkit.dot` |
+|---|---|---|
+| Extra dependency | `pydot` + `pyparsing` | none (plain string templating) |
+| Long label/URL wrapping | no — a long value renders as one unbroken line | yes — this is *why* this module exists: an unwrapped long location once made a real graph too wide to read |
+| Relation vocabulary | every PROV-DM relation, n-ary relations, nested bundles, attribute-annotation nodes | exactly the relations PDSSP's own document builders emit (Generation, Usage, Derivation, Association + `hadPlan`, Attribution, Delegation, Membership, Communication) — nothing else, because nothing else is ever produced |
+| Output | a `pydot.Dot` object | a plain DOT string, ready for client-side rendering |
+| HTML/Viz.js page | not provided | `pdssp_prov_toolkit.html.render_prov_html` — a full standalone page, SRI-pinned Viz.js, no server-side `graphviz` binary needed |
+
+In short: `prov[dot]` is the right choice for a general-purpose PROV-DM
+visualiser. This package is narrower on purpose — it only ever has to
+render what PDSSP's own toolkit-built documents contain — and adds the
+one thing that mattered enough in practice to justify not just calling
+`prov[dot]` directly: readable graphs when a label or URL is long.
+
+## Usage
+
+```python
+from pdssp_prov_toolkit import (
+    ProvAttr,
+    ProvType,
+    new_document,
+    prov_to_dot,
+    render_prov_html,
+    resolve_agent,
+    slug,
+)
+
+doc = new_document("https://example.org/api")
+source = doc.entity(
+    "source-data",
+    {ProvAttr.TYPE: ProvType.COLLECTION, ProvAttr.LABEL: "Upstream source"},
+)
+mapping = doc.activity(
+    "mapping", other_attributes={ProvAttr.TYPE: ProvType.ACTIVITY, ProvAttr.LABEL: "Mapping"}
+)
+doc.used(mapping, source)
+
+# A Graphviz DOT string, ready to render client-side (see render_prov_html)
+# or with any Graphviz-compatible tool.
+dot = prov_to_dot(doc)
+
+# A full standalone HTML page rendering that graph via Viz.js.
+page = render_prov_html(dot=dot, base="https://example.org/api", subtitle_html="Whole catalog.")
+```
+
+See each module's own docstring (`pdssp_prov_toolkit.vocab`,
+`.document`, `.dot`, `.html`) for the full API.
+
+## Installing UV
+
+To manage the dependencies of PDSSP Prov Toolkit, we use
+[UV](<https://docs.astral.sh/uv/>). If you don\'t have UV
+installed, follow these steps:
+
+1.  **Install UV**:
+
+    > ``` shell
+    > $ curl -LsSf https://astral.sh/uv/install.sh | sh
+    > ```
+
+2.  **Verify the installation**:
+
+    > ``` console
+    > $ uv --version
+    > ```
+
+Please note that this project has been tested with UV version 0.9.15.
+
+## From sources
+
+``` console
+$ git clone https://gitlab.cnes.fr/pdssp/pdssp_prov_toolkit.git
+$ cd pdssp_prov_toolkit
+$ uv sync
+```
+
+## Development
+
+``` console
+$ git clone https://gitlab.cnes.fr/pdssp/pdssp_prov_toolkit.git
+$ cd pdssp_prov_toolkit
+$ make prepare-dev
+$ source .venv/bin/activate
+$ make install-dev
+```
+
+To get more information about the preconfigured tasks:
+
+``` console
+$ make help
+```
+
+## Run tests
+
+``` console
+$ make tests
+```
+
+## Documentation
+
+The documentation is automatically deployed on
+<https://pdssp.io.cnes.fr/>pdssp_prov_toolkit based on main branch
+
+## Author
+
+👤 **Jean-Christophe Malapert**
+
+## 🤝 Contributing
+
+Contributions, issues and feature requests are welcome!
+Feel free to check [issues page](https://gitlab.cnes.fr/pdssp/pdssp_prov_toolkit/issues).
+You can also take a look at the [contributing guide](https://gitlab.cnes.fr/pdssp/pdssp_prov_toolkit/blob/main/CONTRIBUTING.rst)
+
+## 📝 License
+
+This project is [Apache V2.0](https://gitlab.cnes.fr/pdssp/pdssp_prov_toolkit/blob/main/LICENSE) licensed.

pdssp_prov_toolkit-1.0.1/README.md

@@ -0,0 +1,165 @@
+# PDSSP Prov Toolkit
+
+[![image](https://img.shields.io/badge/Maintained%3F-yes-green.svg)]()
+
+![image]()
+
+Shared W3C PROV-DM vocabulary, document helpers, and Graphviz/HTML rendering for FAIR-transformation provenance across PDSSP services.
+
+## Why this exists
+
+Two PDSSP services (`ode_stac_proxy`, a live STAC proxy, and
+`geocoding-api`, an offline GeoPackage/OpenSearch pipeline) each expose a
+`GET /prov` endpoint describing how their own FAIR-transformed data is
+produced, as a W3C PROV-DM document. Both were built independently, before
+this package existed — and by the time it was extracted, each had grown
+its own, already-drifted copy of the same vocabulary and rendering code:
+
+- `geocoding-api` had added Subresource Integrity hashes pinning its
+  Viz.js CDN scripts (a real security hardening) and `wasInformedBy`/
+  `license`/`crs` support — none of which had made it back into
+  `ode_stac_proxy`.
+- `ode_stac_proxy` had added `hadMember`/`hadPlan` support — which had
+  never made it into `geocoding-api`.
+
+Neither service noticed the other's fixes, because there was nothing to
+notice — it was two copies, not one dependency. This package is that one
+dependency: the union of both, so a fix or an addition made once benefits
+every PDSSP service producing FAIR-transformation provenance, present or
+future.
+
+**What deliberately did *not* move here**: each service's own
+document-assembly logic — *which* activities and entities its own
+pipeline has, and how they connect — stays in that service. A STAC proxy
+harvesting one live upstream and a batch pipeline harvesting several
+static sources into per-body GeoPackages don't share a pipeline shape, so
+forcing one here would fit neither well. What both actually needed
+identically is the vocabulary they build records with and the code that
+turns the finished document into a graph — that's the whole scope of this
+package.
+
+## Relationship to `prov`'s own `prov.dot`
+
+This package depends on [`prov`](https://prov.readthedocs.io/), and `prov`
+already ships its own optional Graphviz export
+(`prov.dot.prov_to_dot`, via the `prov[dot]` extra) — doing, on paper, the
+same job as `pdssp_prov_toolkit.dot`. They even use the *same* node
+colours (`#FFFC87`/`#9FB1FC`/`#FED37F`), because both independently follow
+the same W3C PROV Primer / ProvToolbox convention. So why not just use it?
+
+| | `prov[dot]` | `pdssp_prov_toolkit.dot` |
+|---|---|---|
+| Extra dependency | `pydot` + `pyparsing` | none (plain string templating) |
+| Long label/URL wrapping | no — a long value renders as one unbroken line | yes — this is *why* this module exists: an unwrapped long location once made a real graph too wide to read |
+| Relation vocabulary | every PROV-DM relation, n-ary relations, nested bundles, attribute-annotation nodes | exactly the relations PDSSP's own document builders emit (Generation, Usage, Derivation, Association + `hadPlan`, Attribution, Delegation, Membership, Communication) — nothing else, because nothing else is ever produced |
+| Output | a `pydot.Dot` object | a plain DOT string, ready for client-side rendering |
+| HTML/Viz.js page | not provided | `pdssp_prov_toolkit.html.render_prov_html` — a full standalone page, SRI-pinned Viz.js, no server-side `graphviz` binary needed |
+
+In short: `prov[dot]` is the right choice for a general-purpose PROV-DM
+visualiser. This package is narrower on purpose — it only ever has to
+render what PDSSP's own toolkit-built documents contain — and adds the
+one thing that mattered enough in practice to justify not just calling
+`prov[dot]` directly: readable graphs when a label or URL is long.
+
+## Usage
+
+```python
+from pdssp_prov_toolkit import (
+    ProvAttr,
+    ProvType,
+    new_document,
+    prov_to_dot,
+    render_prov_html,
+    resolve_agent,
+    slug,
+)
+
+doc = new_document("https://example.org/api")
+source = doc.entity(
+    "source-data",
+    {ProvAttr.TYPE: ProvType.COLLECTION, ProvAttr.LABEL: "Upstream source"},
+)
+mapping = doc.activity(
+    "mapping", other_attributes={ProvAttr.TYPE: ProvType.ACTIVITY, ProvAttr.LABEL: "Mapping"}
+)
+doc.used(mapping, source)
+
+# A Graphviz DOT string, ready to render client-side (see render_prov_html)
+# or with any Graphviz-compatible tool.
+dot = prov_to_dot(doc)
+
+# A full standalone HTML page rendering that graph via Viz.js.
+page = render_prov_html(dot=dot, base="https://example.org/api", subtitle_html="Whole catalog.")
+```
+
+See each module's own docstring (`pdssp_prov_toolkit.vocab`,
+`.document`, `.dot`, `.html`) for the full API.
+
+## Installing UV
+
+To manage the dependencies of PDSSP Prov Toolkit, we use
+[UV](<https://docs.astral.sh/uv/>). If you don\'t have UV
+installed, follow these steps:
+
+1.  **Install UV**:
+
+    > ``` shell
+    > $ curl -LsSf https://astral.sh/uv/install.sh | sh
+    > ```
+
+2.  **Verify the installation**:
+
+    > ``` console
+    > $ uv --version
+    > ```
+
+Please note that this project has been tested with UV version 0.9.15.
+
+## From sources
+
+``` console
+$ git clone https://gitlab.cnes.fr/pdssp/pdssp_prov_toolkit.git
+$ cd pdssp_prov_toolkit
+$ uv sync
+```
+
+## Development
+
+``` console
+$ git clone https://gitlab.cnes.fr/pdssp/pdssp_prov_toolkit.git
+$ cd pdssp_prov_toolkit
+$ make prepare-dev
+$ source .venv/bin/activate
+$ make install-dev
+```
+
+To get more information about the preconfigured tasks:
+
+``` console
+$ make help
+```
+
+## Run tests
+
+``` console
+$ make tests
+```
+
+## Documentation
+
+The documentation is automatically deployed on
+<https://pdssp.io.cnes.fr/>pdssp_prov_toolkit based on main branch
+
+## Author
+
+👤 **Jean-Christophe Malapert**
+
+## 🤝 Contributing
+
+Contributions, issues and feature requests are welcome!
+Feel free to check [issues page](https://gitlab.cnes.fr/pdssp/pdssp_prov_toolkit/issues).
+You can also take a look at the [contributing guide](https://gitlab.cnes.fr/pdssp/pdssp_prov_toolkit/blob/main/CONTRIBUTING.rst)
+
+## 📝 License
+
+This project is [Apache V2.0](https://gitlab.cnes.fr/pdssp/pdssp_prov_toolkit/blob/main/LICENSE) licensed.

pdssp_prov_toolkit-1.0.1/pyproject.toml

@@ -0,0 +1,81 @@
+[project]
+name = "pdssp_prov_toolkit"
+readme = "README.md"
+description = "Shared W3C PROV-DM vocabulary, document helpers, and Graphviz/HTML rendering for FAIR-transformation provenance across PDSSP services."
+license = "Apache-2.0"
+homepage = "https://gitlab.cnes.fr/pdssp/pdssp_prov_toolkit"
+version = "1.0.1"
+requires-python = ">=3.12"
+dependencies = ["prov>=3.1.0"]
+
+[[project.authors]]
+name = "Jean-Christophe Malapert"
+email = "jean-christophe.malapert@cnes.fr"
+
+[[project.packages]]
+include = "pdssp_prov_toolkit"
+
+[build-system]
+requires = ["uv_build>=0.9.14,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pdssp_prov_toolkit"]
+
+[tool.black]
+line-length = 88
+include = '\.pyi?$'
+exclude = '''
+/(
+    \.git
+  | \.hg
+  | \.mypy_cache
+  | \.tox
+  | \.venv
+  | docs
+  | scripts
+  | docker
+  | _build
+  | buck-out
+  | build
+  | dist
+)/
+'''
+
+[tool.bandit]
+exclude_dirs = [
+    ".venv",
+    "tests",
+    "scripts",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[dependency-groups]
+dev = [
+    "bump-my-version>=1.2.4",
+    "coverage>=7.12.0",
+    "mkdocs>=1.6.1",
+    "mkdocs-gen-files>=0.6.0",
+    "mkdocs-literate-nav>=0.6.2",
+    "mkdocs-macros-plugin>=1.5.0",
+    "mkdocs-material>=9.7.0",
+    "mkdocs-with-pdf>=0.9.3",
+    "mkdocstrings[python]>=1.0.0",
+    "pip-licenses>=5.5.0",
+    "pre-commit>=4.5.0",
+    "pre-commit-hooks>=6.0.0",
+    "pytest>=9.0.1",
+    "pytest-html>=4.1.1",
+    "pytest-json-report>=1.5.0",
+    "pytest-profiling>=1.8.1",
+    "pytest-mock>=3.15.1",
+    "black>=25.11.0",
+    "tox>=4.32.0",
+    "flake8>=7.3.0",
+    "mccabe>=0.7.0",
+    "mypy>=1.19.0",
+    "pylint>=4.0.4",
+    "toml>=0.10.2",
+]

pdssp_prov_toolkit-1.0.1/pyproject.toml.orig

@@ -0,0 +1,77 @@
+[project]
+name = "pdssp_prov_toolkit"
+readme = "README.md"
+description = "Shared W3C PROV-DM vocabulary, document helpers, and Graphviz/HTML rendering for FAIR-transformation provenance across PDSSP services."
+authors = [{name="Jean-Christophe Malapert", email="jean-christophe.malapert@cnes.fr"}, ]
+license = "Apache-2.0"
+packages = [{include = "pdssp_prov_toolkit"}]
+homepage = "https://gitlab.cnes.fr/pdssp/pdssp_prov_toolkit"
+version = "1.0.1"
+requires-python = ">=3.12"
+dependencies = [
+    "prov>=3.1.0",
+]
+
+# ── Build ────────────────────────────────────────────────────────────────────
+[build-system]
+requires = ["uv_build>=0.9.14,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pdssp_prov_toolkit"]
+
+# ── Dev dependencies ─────────────────────────────────────────────────────────
+[dependency-groups]
+dev = [
+    "bump-my-version>=1.2.4",
+    "coverage>=7.12.0",
+    "mkdocs>=1.6.1",
+    "mkdocs-gen-files>=0.6.0",
+    "mkdocs-literate-nav>=0.6.2",
+    "mkdocs-macros-plugin>=1.5.0",
+    "mkdocs-material>=9.7.0",
+    "mkdocs-with-pdf>=0.9.3",
+    "mkdocstrings[python]>=1.0.0",
+    "pip-licenses>=5.5.0",
+    "pre-commit>=4.5.0",
+    "pre-commit-hooks>=6.0.0",
+    "pytest>=9.0.1",
+    "pytest-html>=4.1.1",
+    "pytest-json-report>=1.5.0",
+    "pytest-profiling>=1.8.1",
+    "pytest-mock>=3.15.1",
+    "black>=25.11.0",
+    "tox>=4.32.0",
+    "flake8>=7.3.0",
+    "mccabe>=0.7.0",
+    "mypy>=1.19.0",
+    "pylint>=4.0.4",
+    "toml>=0.10.2",
+]
+
+[tool.black]
+line-length = 88
+include = '\.pyi?$'
+exclude = '''
+/(
+    \.git
+  | \.hg
+  | \.mypy_cache
+  | \.tox
+  | \.venv
+  | docs
+  | scripts
+  | docker
+  | _build
+  | buck-out
+  | build
+  | dist
+)/
+'''
+
+[tool.bandit]
+exclude_dirs = [".venv", "tests", "scripts"]
+
+# ── pytest ───────────────────────────────────────────────────────────────────
+[tool.pytest.ini_options]
+testpaths = ["tests"]

pdssp_prov_toolkit-1.0.1/src/pdssp_prov_toolkit/__init__.py

@@ -0,0 +1,48 @@
+# PDSSP Prov Toolkit - Shared W3C PROV-DM vocabulary, document helpers, and Graphviz/HTML rendering for FAIR-transformation provenance across PDSSP services.
+# Copyright (C) 2026 - CNES (Jean-Christophe Malapert for PDSSP)
+# This file is part of PDSSP Prov Toolkit <https://gitlab.cnes.fr/pdssp/pdssp_prov_toolkit>
+# SPDX-License-Identifier: Apache-2.0
+
+"""Shared W3C PROV-DM vocabulary, document helpers, and Graphviz/HTML
+rendering for FAIR-transformation provenance across PDSSP services.
+
+A library, not an application -- it configures no logging of its own
+(that is each consuming service's own decision to make) and has no CLI.
+"""
+
+from ._version import (
+    __author__,
+    __author_email__,
+    __copyright__,
+    __description__,
+    __license__,
+    __name_soft__,
+    __title__,
+    __url__,
+    __version__,
+)
+from .document import FOAF_NS, new_document, resolve_agent, slug
+from .dot import prov_to_dot
+from .html import render_prov_html
+from .vocab import ProvAttr, ProvQualifier, ProvType
+
+__all__ = [
+    "FOAF_NS",
+    "ProvAttr",
+    "ProvQualifier",
+    "ProvType",
+    "__author__",
+    "__author_email__",
+    "__copyright__",
+    "__description__",
+    "__license__",
+    "__name_soft__",
+    "__title__",
+    "__url__",
+    "__version__",
+    "new_document",
+    "prov_to_dot",
+    "render_prov_html",
+    "resolve_agent",
+    "slug",
+]

pdssp_prov_toolkit-1.0.1/src/pdssp_prov_toolkit/_version.py

@@ -0,0 +1,19 @@
+# -*- coding: utf-8 -*-
+# skeleton-python-binary -  Command-line tool that generates project templates based on predefined Python project template
+# Copyright (C) 2024-2025 - Centre National d'Etudes Spatiales
+# SPDX-License-Identifier: Apache-2.0
+# Auto-generated by skeleton-python-binary
+"""Project metadata."""
+from importlib.metadata import metadata
+
+pkg_metadata = metadata("pdssp_prov_toolkit")
+
+__name_soft__ = pkg_metadata.get("name", "unknown")
+__version__ = pkg_metadata.get("version", "0.0.0")
+__title__ = pkg_metadata.get("name", "unknown")
+__description__ = pkg_metadata.get("summary", "")
+__url__ = pkg_metadata.get("homepage", "")
+__author__ = pkg_metadata.get("authors", "unknown")
+__author_email__ = pkg_metadata.get("author-email", "unknown")
+__license__ = pkg_metadata.get("license", "")
+__copyright__ = "2026, CNES (Jean-Christophe Malapert for PDSSP)"

pdssp_prov_toolkit-1.0.1/src/pdssp_prov_toolkit/document.py

@@ -0,0 +1,97 @@
+# PDSSP Prov Toolkit - Shared W3C PROV-DM vocabulary, document helpers, and Graphviz/HTML rendering for FAIR-transformation provenance across PDSSP services.
+# Copyright (C) 2026 - CNES (Jean-Christophe Malapert for PDSSP)
+# This file is part of PDSSP Prov Toolkit <https://gitlab.cnes.fr/pdssp/pdssp_prov_toolkit>
+# SPDX-License-Identifier: Apache-2.0
+
+"""
+Generic PROV-DM document helpers.
+====================================
+Small, domain-agnostic building blocks every service assembling its own
+:class:`~prov.model.ProvDocument` needs regardless of its own pipeline
+shape (a live-mapping STAC proxy, an offline GeoPackage-compilation
+pipeline, ...): a namespaced empty document, a safe local identifier from
+a free-text name, and de-duplicated agent lookup.
+
+Deliberately excludes anything that assumes a particular pipeline shape
+(e.g. "one software agent acting on behalf of another", "a source entity
+attributed to a producer/licensor") -- those patterns are common across
+today's two PDSSP consumers of this package, but each has grown its own,
+differently-shaped set of activities/entities around them, so forcing a
+single higher-level "build me a document" helper here would either fit
+neither well or silently constrain a future consumer's own pipeline shape.
+Each service keeps that assembly logic in its own codebase, built out of
+these primitives plus :mod:`.vocab`.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from prov.model import ProvDocument
+
+from .vocab import ProvAttr
+
+#: Default FOAF namespace URI, bound to the ``foaf`` prefix by
+#: :func:`new_document`.
+FOAF_NS = "https://xmlns.com/foaf/0.1/"
+
+
+def new_document(base: str, foaf_ns: str = FOAF_NS) -> ProvDocument:
+    """Return an empty :class:`ProvDocument` namespaced for *base*.
+
+    Parameters
+    ----------
+    base:
+        Public base URL of the service (no trailing slash), used as the
+        default namespace so record identifiers resolve to real URIs.
+    foaf_ns:
+        Namespace URI bound to the ``foaf`` prefix.
+    """
+    doc = ProvDocument()
+    doc.set_default_namespace(f"{base}/prov#")
+    doc.add_namespace("foaf", foaf_ns)
+    return doc
+
+
+def slug(name: str) -> str:
+    """Turn a free-text name into a safe PROV local identifier, e.g.
+    ``"NASA PDS Geosciences Node"`` -> ``"nasa-pds-geosciences-node"``.
+
+    A PROV-N/PROV-XML identifier's local part is a QName-like token that
+    cannot contain arbitrary characters (spaces, ``/``, ...) -- this is the
+    one place in the toolkit that turns a human-facing name into something
+    safe to use as one.
+    """
+    return re.sub(r"[^a-z0-9]+", "-", name.lower()).strip("-") or "agent"
+
+
+def resolve_agent(doc: ProvDocument, agents: dict[str, Any], name: str, prov_type: str) -> Any:
+    """Return the existing agent named *name* in *agents*, or add (and
+    cache into *agents*) a new one of *prov_type* -- so the same real-world
+    party never gets a duplicate record across different callers or calls.
+
+    Parameters
+    ----------
+    doc:
+        The document to add a new agent to, if needed.
+    agents:
+        Mutable ``name -> ProvAgent`` cache, shared across every caller
+        resolving agents for *doc* (typically built up alongside whatever
+        per-pipeline agents a service adds itself).
+    name:
+        The agent's human-facing name (also used as its ``prov:label`` and
+        ``foaf:name`` when a new record is created).
+    prov_type:
+        One of :class:`~.vocab.ProvType`'s agent-shaped values (``PERSON``,
+        ``ORGANIZATION``, ``SOFTWARE_AGENT``) for a newly created record;
+        ignored when *name* already resolves to an existing agent.
+    """
+    agent = agents.get(name)
+    if agent is None:
+        agent = doc.agent(
+            slug(name),
+            {ProvAttr.TYPE: prov_type, ProvAttr.LABEL: name, ProvAttr.FOAF_NAME: name},
+        )
+        agents[name] = agent
+    return agent

pdssp_prov_toolkit-1.0.1/src/pdssp_prov_toolkit/dot.py

@@ -0,0 +1,253 @@
+# PDSSP Prov Toolkit - Shared W3C PROV-DM vocabulary, document helpers, and Graphviz/HTML rendering for FAIR-transformation provenance across PDSSP services.
+# Copyright (C) 2026 - CNES (Jean-Christophe Malapert for PDSSP)
+# This file is part of PDSSP Prov Toolkit <https://gitlab.cnes.fr/pdssp/pdssp_prov_toolkit>
+# SPDX-License-Identifier: Apache-2.0
+
+"""
+DOT (Graphviz) rendering for PROV-DM documents.
+=================================================
+Converts a :class:`prov.model.ProvDocument` into Graphviz DOT source, using
+the standard PROV-DM node shapes/colours (yellow ellipses for entities,
+blue rounded boxes for activities, orange houses for agents), matching the
+W3C PROV Primer and ProvStore/ProvToolbox conventions.
+
+Produces plain DOT *text* only -- no native ``graphviz`` binary or extra
+Python dependency beyond ``prov`` itself (deliberately not built on
+``prov``'s own optional ``prov[dot]``/``pydot`` extra, which needs a real
+dependency and does not word-wrap long labels/URLs -- see this module's
+own history for why that matters: an unwrapped long label/location made an
+early graph too wide to read). Rendering the DOT source itself happens
+client-side, in the browser, via Viz.js (see :mod:`.html`).
+
+Covers exactly the record/relation shapes the two services this toolkit
+was extracted from actually produce -- every :class:`~prov.model.ProvRecord`
+subtype ``prov`` itself defines that isn't listed in :data:`_RELATION_SPECS`
+is simply not drawn as an edge (nodes for entities/activities/agents are
+always drawn regardless). Add to :data:`_RELATION_SPECS` (and, for a new
+attribute, to :func:`_label_lines`) rather than working around a gap here.
+"""
+
+from __future__ import annotations
+
+import textwrap
+
+from prov.model import (
+    ProvActivity,
+    ProvAgent,
+    ProvAssociation,
+    ProvAttribution,
+    ProvCommunication,
+    ProvDelegation,
+    ProvDerivation,
+    ProvDocument,
+    ProvEntity,
+    ProvGeneration,
+    ProvMembership,
+    ProvRecord,
+    ProvUsage,
+)
+
+from .vocab import ProvAttr, ProvQualifier
+
+
+class ProvDotConfig:
+    ENTITY_STYLE = 'shape=ellipse, style=filled, fillcolor="#FFFC87", color="#808080"'
+    ACTIVITY_STYLE = 'shape=box, style="filled,rounded", fillcolor="#9FB1FC", color="#0000FF"'
+    AGENT_STYLE = 'shape=house, style=filled, fillcolor="#FED37F", color="#D2691E"'
+
+    #: Relation record type -> (source attribute, target attribute, edge label,
+    #: edge line style), per the PROV-DM diagram conventions. Attribute names
+    #: are :class:`~.vocab.ProvQualifier` keys.
+    RELATION_SPECS: dict[type, tuple[str, str, str, str]] = {
+        ProvGeneration: (ProvQualifier.ENTITY, ProvQualifier.ACTIVITY, "wasGeneratedBy", "solid"),
+        ProvUsage: (ProvQualifier.ACTIVITY, ProvQualifier.ENTITY, "used", "dashed"),
+        ProvDerivation: (
+            ProvQualifier.GENERATED_ENTITY,
+            ProvQualifier.USED_ENTITY,
+            "wasDerivedFrom",
+            "solid",
+        ),
+        ProvAssociation: (
+            ProvQualifier.ACTIVITY,
+            ProvQualifier.AGENT,
+            "wasAssociatedWith",
+            "dotted",
+        ),
+        ProvAttribution: (ProvQualifier.ENTITY, ProvQualifier.AGENT, "wasAttributedTo", "dotted"),
+        ProvDelegation: (
+            ProvQualifier.DELEGATE,
+            ProvQualifier.RESPONSIBLE,
+            "actedOnBehalfOf",
+            "dotted",
+        ),
+        ProvMembership: (ProvQualifier.COLLECTION, ProvQualifier.ENTITY, "hadMember", "solid"),
+        ProvCommunication: (
+            ProvQualifier.INFORMED,
+            ProvQualifier.INFORMANT,
+            "wasInformedBy",
+            "dashed",
+        ),
+    }
+
+    #: Target line length for node-label wrapping (short values stay on one
+    #: line; long URLs/descriptions get broken up).
+    WRAP_WIDTH = 50
+
+
+def prov_to_dot(doc: ProvDocument) -> str:
+    """Render *doc* as Graphviz DOT source.
+
+    Parameters
+    ----------
+    doc:
+        The PROV-DM document to render.
+
+    Returns
+    -------
+    str
+        A ``digraph`` DOT source string, ready to be rendered by any
+        Graphviz-compatible tool (the ``dot`` CLI, or client-side via
+        Viz.js).
+    """
+    lines = [
+        "digraph provenance {",
+        "  rankdir=LR;",
+        "  nodesep=0.4;",
+        "  ranksep=0.6;",
+        '  node [fontname="Helvetica,Arial,sans-serif", fontsize=11];',
+        '  edge [fontname="Helvetica,Arial,sans-serif", fontsize=9];',
+    ]
+
+    for record in doc.get_records():
+        if isinstance(record, (ProvEntity, ProvActivity, ProvAgent)):
+            lines.append(_node_line(record))
+
+    for record in doc.get_records():
+        spec = ProvDotConfig.RELATION_SPECS.get(type(record))
+        if spec is not None:
+            lines.append(_edge_line(record, *spec))
+        if isinstance(record, ProvAssociation):
+            plan_edge = _plan_edge_line(record)
+            if plan_edge is not None:
+                lines.append(plan_edge)
+
+    lines.append("}")
+    return "\n".join(lines)
+
+
+def _node_line(
+    record: ProvRecord,
+    entity_style: str = ProvDotConfig.ENTITY_STYLE,
+    activity_style: str = ProvDotConfig.ACTIVITY_STYLE,
+    agent_style: str = ProvDotConfig.AGENT_STYLE,
+) -> str:
+    """Return the DOT statement declaring one entity/activity/agent node."""
+    if isinstance(record, ProvEntity):
+        style = entity_style
+    elif isinstance(record, ProvActivity):
+        style = activity_style
+    else:
+        style = agent_style
+    # Joined with a literal "\n" (backslash-n), which Graphviz renders as a
+    # line break inside a label -- not an actual newline character, which
+    # `_escape` would otherwise be free to mangle along with the rest.
+    label = "\\n".join(_escape(line) for line in _label_lines(record))
+    return f'  "{record.identifier.localpart}" [label="{label}", {style}];'
+
+
+def _edge_line(record: ProvRecord, from_attr: str, to_attr: str, label: str, style: str) -> str:
+    """Return the DOT statement for one relation record, per *spec*."""
+    attrs = {str(key): value for key, value in record.formal_attributes}
+    src = _local(attrs.get(from_attr))
+    dst = _local(attrs.get(to_attr))
+    return f'  "{src}" -> "{dst}" [label="{label}", style={style}];'
+
+
+def _plan_edge_line(record: ProvRecord) -> str | None:
+    """Return the extra ``hadPlan`` edge for an association naming a plan.
+
+    Not covered by :data:`ProvDotConfig.RELATION_SPECS` (which only draws
+    the activity/agent edge) -- drawn only when a plan is actually present
+    (a ``wasAssociatedWith`` with no ``plan=`` produces no edge here).
+    """
+    attrs = {str(key): value for key, value in record.formal_attributes}
+    activity = attrs.get(ProvQualifier.ACTIVITY)
+    plan = attrs.get(ProvQualifier.PLAN)
+    if activity is None or plan is None:
+        return None
+    return f'  "{_local(activity)}" -> "{_local(plan)}" [label="hadPlan", style=dotted];'
+
+
+def _local(qname) -> str:
+    """Return the local part of a :class:`~prov.identifier.QualifiedName`, or ``"?"``."""
+    return qname.localpart if qname is not None else "?"
+
+
+def _label_lines(record: ProvRecord) -> list[str]:
+    """Return the lines to display inside *record*'s node: the word-wrapped
+    primary label (``prov:label``, falling back to the identifier), then
+    ``version``, ``identifier``, ``license`` and ``crs`` when present, and
+    a hard-wrapped ``prov:location`` when present -- each shown only for a
+    record that actually carries it, so a consumer that never sets e.g.
+    ``crs`` never sees an empty line.
+    """
+    lines = _wrap_text(_primary_label(record))
+    version = _first_attribute(record, ProvAttr.VERSION)
+    if version is not None:
+        lines.append(f"v{version}")
+    identifier = _first_attribute(record, ProvAttr.IDENTIFIER)
+    if identifier is not None:
+        lines.append(f"id: {identifier}")
+    license_ = _first_attribute(record, ProvAttr.LICENSE)
+    if license_ is not None:
+        lines.append(f"license: {license_}")
+    crs = _first_attribute(record, ProvAttr.CRS)
+    if crs is not None:
+        lines.append(f"crs: {crs}")
+    location = _first_attribute(record, ProvAttr.LOCATION)
+    if location is not None:
+        lines.extend(_wrap_url(str(location)))
+    return lines
+
+
+def _wrap_text(text: str, wrap_width: int = ProvDotConfig.WRAP_WIDTH) -> list[str]:
+    """Word-wrap free-form prose (e.g. a ``prov:label``) at *wrap_width*."""
+    return textwrap.wrap(text, width=wrap_width, break_on_hyphens=False) or [text]
+
+
+def _wrap_url(text: str, wrap_width: int = ProvDotConfig.WRAP_WIDTH) -> list[str]:
+    """Hard-wrap a URL into chunks of at most *wrap_width* chars, preferring
+    to break at ``&``/``/`` near the target width over a hard mid-word cut.
+    """
+    lines = []
+    remaining = text
+    while len(remaining) > wrap_width:
+        cut = wrap_width
+        for sep in ("&", "/"):
+            idx = remaining.rfind(sep, 0, wrap_width + 15)
+            if idx > wrap_width // 2:
+                cut = idx + 1
+                break
+        lines.append(remaining[:cut])
+        remaining = remaining[cut:]
+    lines.append(remaining)
+    return lines
+
+
+def _primary_label(record: ProvRecord) -> str:
+    """Return ``record``'s ``prov:label``, or its identifier if it has none."""
+    values = record.get_attribute(ProvAttr.LABEL)
+    if values:
+        return str(next(iter(values)))
+    return record.identifier.localpart
+
+
+def _first_attribute(record: ProvRecord, name: str) -> str | None:
+    """Return one value of the *name* attribute on *record*, or ``None``."""
+    values = record.get_attribute(name)
+    return str(next(iter(values))) if values else None
+
+
+def _escape(text: str) -> str:
+    """Escape backslashes and double quotes so *text* is safe inside a DOT string literal."""
+    return text.replace("\\", "\\\\").replace('"', '\\"')

pdssp_prov_toolkit-1.0.1/src/pdssp_prov_toolkit/html.py

@@ -0,0 +1,170 @@
+# PDSSP Prov Toolkit - Shared W3C PROV-DM vocabulary, document helpers, and Graphviz/HTML rendering for FAIR-transformation provenance across PDSSP services.
+# Copyright (C) 2026 - CNES (Jean-Christophe Malapert for PDSSP)
+# This file is part of PDSSP Prov Toolkit <https://gitlab.cnes.fr/pdssp/pdssp_prov_toolkit>
+# SPDX-License-Identifier: Apache-2.0
+
+"""
+HTML graph visualisation for a ``GET /prov``-style endpoint.
+===============================================================
+When a browser navigates to a provenance endpoint, a graph is the most
+legible representation of a PROV-DM document -- that is the whole point of
+the diagrams in the W3C PROV Primer -- so :func:`render_prov_html` renders
+one instead of raw PROV-JSON.
+
+The Graphviz DOT source produced by :func:`~.dot.prov_to_dot` is rendered
+into an SVG **client-side**, in the browser, via Viz.js (Graphviz compiled
+to WebAssembly/asm.js, loaded from a CDN, pinned by version and by
+Subresource Integrity hash so the CDN cannot silently swap in different
+script content). No native ``graphviz`` binary runs on the server.
+
+The SVG is shown at its native size inside a scrollable container, rather
+than shrunk with CSS to fit the viewport width: a PROV graph with several
+same-rank nodes is often wider or taller than one screen, and forcing it
+to fit would shrink its text past legibility. Scrolling (or the browser's
+own zoom) is the tradeoff that keeps the labels readable.
+
+The page also links to the raw PROV-JSON / PROV-N / PROV-XML
+serialisations, which are plain, standard PROV-DM documents that can be
+pasted or uploaded into ProvStore (https://openprovenance.org/store/) or
+any other PROV-DM-compliant tool -- this page does not call out to
+ProvStore itself, so nothing about a deployment using it is sent anywhere
+without the operator choosing to do so.
+
+Deliberately generic about *what* is being shown: :func:`render_prov_html`
+takes an already-built *subtitle_html* fragment and *query_suffix* rather
+than any scope-specific parameter name (a STAC ``collection_id``/``item_id``
+pair, a gazetteer ``planet``, or anything a future consumer's own resource
+model might add) -- building that scope-specific text/query-string is each
+caller's own job (see the parameters' own docstrings for the escaping
+contract).
+
+**Security note**: the DOT source is embedded via a hidden, HTML-escaped
+``<pre>`` element read back through ``.textContent`` in a *static* inline
+script (see :func:`render_prov_html`), rather than interpolated directly
+into a ``<script>`` block -- this sidesteps both HTML/JS string-escaping
+pitfalls and the ``</script>`` early-termination issue, regardless of what
+free-text labels end up in the DOT source.
+"""
+
+from __future__ import annotations
+
+from html import escape
+
+#: Pinned Viz.js release -- keep in lock-step with :data:`_VIZ_JS_SRI`/
+#: :data:`_VIZ_FULL_RENDER_JS_SRI` below: bumping the version without
+#: recomputing these hashes makes the browser refuse to run either script
+#: at all (a safe, loud failure -- the graph just won't render -- rather
+#: than a silent security regression).
+_VIZ_JS_BASE = "https://cdn.jsdelivr.net/npm/viz.js@2.1.2"
+_VIZ_JS_SRI = "sha384-f4dIboC5mwQKuVsNplQrKp19L8ttwIgw0LJNV0PsuIJYHTjIljdJ9cZdTqIVtk8y"
+_VIZ_FULL_RENDER_JS_SRI = "sha384-oyiaz0P9mLALNbgQC9EQ48wxHRWGopFpDEMBoCc9Rir7gWL7GrgKzr4+X9mVM77b"
+
+
+def render_prov_html(
+    *,
+    dot: str,
+    base: str,
+    subtitle_html: str,
+    query_suffix: str = "",
+    footer_extra_html: str = "",
+) -> str:
+    """Return the full HTML page visualising a PROV-DM document as a graph.
+
+    Parameters
+    ----------
+    dot:
+        Graphviz DOT source produced by :func:`~.dot.prov_to_dot`.
+    base:
+        Public base URL of the service, shown (HTML-escaped by this
+        function) in the page title.
+    subtitle_html:
+        The page's subtitle, e.g. ``"How this service's STAC catalog is
+        produced, scoped to collection <code>foo</code>."`` -- an
+        already-safe HTML fragment built by the caller (any dynamic part,
+        such as an id, must already be ``html.escape()``-d by the caller
+        before it's wrapped in ``<code>...</code>``; this function does
+        **not** escape it again, exactly like the caller's existing
+        practice before this was extracted).
+    query_suffix:
+        An already-escaped, already-``&``-prefixed query-string suffix
+        (e.g. ``"&collection_id=foo&item_id=bar"`` or ``"&planet=mars"``)
+        appended to every format-switch link so re-fetching PROV-JSON/-N/-XML
+        preserves the same scope shown here. Empty string (default) for an
+        unscoped, whole-catalog document.
+    footer_extra_html:
+        Extra HTML appended to the footer paragraph (e.g. a link to a
+        human-readable licenses/citation page) -- already-safe HTML,
+        same escaping contract as *subtitle_html*. Empty by default.
+
+    Returns
+    -------
+    str
+        A complete, standalone HTML document.
+    """
+    return f"""<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Provenance (PROV-DM) — {escape(base)}</title>
+<script src="{_VIZ_JS_BASE}/viz.js" integrity="{_VIZ_JS_SRI}" crossorigin="anonymous"></script>
+<script src="{_VIZ_JS_BASE}/full.render.js" integrity="{_VIZ_FULL_RENDER_JS_SRI}" crossorigin="anonymous"></script>
+<style>
+  :root {{ color-scheme: light dark; }}
+  body {{
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif;
+    margin: 0; padding: 1.5rem 2rem; color: #1a1a1a; background: #fff;
+  }}
+  h1 {{ font-size: 1.15rem; margin: 0 0 0.25rem; }}
+  p.sub {{ color: #666; margin: 0 0 1.25rem; font-size: 0.9rem; }}
+  #graph {{ overflow: auto; max-height: 80vh; border: 1px solid #ddd; border-radius: 6px; padding: 0.5rem; background: #fafafa; }}
+  #graph svg {{ display: block; }}
+  .legend {{ display: flex; gap: 1.5rem; margin: 0 0 1rem; font-size: 0.85rem; flex-wrap: wrap; }}
+  .swatch {{ display: inline-block; width: 0.9rem; height: 0.9rem; border-radius: 3px; margin-right: 0.35rem; vertical-align: -1px; }}
+  .formats {{ margin-top: 1.25rem; font-size: 0.9rem; }}
+  .formats a {{ margin-right: 1rem; }}
+  footer {{ margin-top: 1.5rem; font-size: 0.8rem; color: #888; }}
+  footer a {{ color: inherit; }}
+  #error {{ color: #b00020; white-space: pre-wrap; font-family: ui-monospace, monospace; margin: 0; }}
+</style>
+</head>
+<body>
+<h1>W3C PROV-DM provenance</h1>
+<p class="sub">{subtitle_html}</p>
+
+<div class="legend">
+  <span><span class="swatch" style="background:#FFFC87;border:1px solid #808080"></span>Entity</span>
+  <span><span class="swatch" style="background:#9FB1FC;border:1px solid #0000FF"></span>Activity</span>
+  <span><span class="swatch" style="background:#FED37F;border:1px solid #D2691E"></span>Agent</span>
+  <span style="color:#888">Rendered at full size — scroll to see the whole graph.</span>
+</div>
+
+<div id="graph"><p id="error" hidden></p></div>
+
+<pre id="dot-source" hidden>{escape(dot)}</pre>
+
+<div class="formats">
+  Machine-readable: <a href="?format=json{query_suffix}">PROV-JSON</a><a href="?format=provn{query_suffix}">PROV-N</a><a href="?format=xml{query_suffix}">PROV-XML</a>
+</div>
+
+<footer>
+  Rendered with the colour convention used throughout the PROV community (W3C PROV Primer,
+  ProvStore, ProvToolbox). The PROV-JSON / PROV-N / PROV-XML above are plain PROV-DM documents
+  that can be pasted or uploaded into
+  <a href="https://openprovenance.org/store/" target="_blank" rel="noopener noreferrer">ProvStore</a>
+  or any other PROV-DM-compliant tool.{footer_extra_html}
+</footer>
+
+<script>
+  var dotSource = document.getElementById('dot-source').textContent;
+  new Viz().renderSVGElement(dotSource)
+    .then(function (el) {{ document.getElementById('graph').appendChild(el); }})
+    .catch(function (err) {{
+      var e = document.getElementById('error');
+      e.hidden = false;
+      e.textContent = 'Graph rendering failed: ' + err;
+    }});
+</script>
+</body>
+</html>
+"""

pdssp_prov_toolkit-1.0.1/src/pdssp_prov_toolkit/vocab.py

@@ -0,0 +1,94 @@
+# PDSSP Prov Toolkit - Shared W3C PROV-DM vocabulary, document helpers, and Graphviz/HTML rendering for FAIR-transformation provenance across PDSSP services.
+# Copyright (C) 2026 - CNES (Jean-Christophe Malapert for PDSSP)
+# This file is part of PDSSP Prov Toolkit <https://gitlab.cnes.fr/pdssp/pdssp_prov_toolkit>
+# SPDX-License-Identifier: Apache-2.0
+
+"""
+PROV-DM / FOAF vocabulary.
+============================
+Plain string constants for the attribute keys, record-type values and
+qualified-relation attribute names used throughout this toolkit's own
+``document``/``dot`` modules, and by every service building a
+:class:`~prov.model.ProvDocument` with them.
+
+This is the union of the vocabulary independently grown by two PDSSP
+services (``ode_stac_proxy`` and ``geocoding-api``) before this package
+existed -- extracted here specifically because both had already drifted
+from each other (one had gained ``PLAN``/``COLLECTION``/``IDENTIFIER``, the
+other ``LICENSE``/``CRS``/``INFORMED``/``INFORMANT``) without either
+noticing the other's additions. Nothing here is specific to either
+service's own domain: a consumer is free to only ever use the subset it
+needs.
+"""
+
+from __future__ import annotations
+
+
+class ProvAttr:
+    """PROV-DM (and FOAF) attribute keys used on records built by this
+    toolkit (or by any caller building its own).
+    """
+
+    TYPE = "prov:type"
+    LABEL = "prov:label"
+    LOCATION = "prov:location"
+    #: Custom attributes below (not part of PROV-DM's core vocabulary) all
+    #: deliberately skip the ``prov:`` prefix -- that namespace is reserved
+    #: for the fixed set of terms PROV-XML's schema actually knows, and a
+    #: validator (ProvToolbox/ProvStore) rejects an unrecognized ``prov:*``
+    #: element/attribute outright rather than treating it as an extension
+    #: point. A bare name instead resolves against the document's own
+    #: default namespace, which is how any extension attribute must be
+    #: declared.
+    VERSION = "version"
+    #: The identifier (e.g. a STAC item/collection id) an entity represents.
+    IDENTIFIER = "identifier"
+    #: Machine-readable schema URL alongside a human-readable LOCATION.
+    SCHEMA = "schema"
+    #: The license terms an entity is distributed/available under.
+    LICENSE = "license"
+    #: The coordinate reference system an entity's geometry uses.
+    CRS = "crs"
+    FOAF_NAME = "foaf:name"
+    FOAF_HOMEPAGE = "foaf:homepage"
+
+
+class ProvType:
+    """PROV-DM record-type values used as a record's :data:`ProvAttr.TYPE`."""
+
+    COLLECTION = "prov:Collection"
+    ENTITY = "prov:Entity"
+    ACTIVITY = "prov:Activity"
+    PLAN = "prov:Plan"
+    PERSON = "prov:Person"
+    ORGANIZATION = "prov:Organization"
+    SOFTWARE_AGENT = "prov:SoftwareAgent"
+
+
+class ProvQualifier:
+    """Lowercase ``formal_attributes`` keys naming the endpoints of
+    ``prov``'s qualified n-ary relations (``ProvGeneration``, ``ProvUsage``,
+    ``ProvDerivation``, ``ProvAssociation``, ``ProvAttribution``,
+    ``ProvDelegation``, ``ProvMembership``, ``ProvCommunication``) --
+    distinct from :class:`ProvAttr` (descriptive attributes on a record)
+    and :class:`ProvType`'s capitalized record-type values.
+
+    Consumed by :func:`~.dot.prov_to_dot` to draw each relation as a graph
+    edge; a caller building relations via ``prov``'s own
+    ``doc.wasGeneratedBy()``/``doc.used()``/... helpers never needs these
+    directly (``prov`` sets the qualifiers internally) -- they matter only
+    to code that reads a relation's ``formal_attributes`` back out, as
+    :mod:`.dot` does.
+    """
+
+    ENTITY = "prov:entity"
+    ACTIVITY = "prov:activity"
+    AGENT = "prov:agent"
+    PLAN = "prov:plan"
+    GENERATED_ENTITY = "prov:generatedEntity"
+    USED_ENTITY = "prov:usedEntity"
+    DELEGATE = "prov:delegate"
+    RESPONSIBLE = "prov:responsible"
+    COLLECTION = "prov:collection"
+    INFORMED = "prov:informed"
+    INFORMANT = "prov:informant"