Skip to content

llm_ports.provenance

llm_ports.provenance

Data rights in PROV-O terms: ContentItem, Activity, DataClass and print_gate.

Activity dataclass

Activity(
    id: str = "",
    role: str = "",
    pack: str = "",
    pack_sha: str = "",
    model: str = "",
    git_sha: str = "",
    started_at: datetime | None = None,
    ended_at: datetime | None = None,
)

A prov:Activity: one generation.

Every field is optional: a deterministic writer has no model or pack. An empty string means "not recorded", never "none".

prov

prov() -> dict[str, Any]

Return the PROV-JSON-shaped view of this activity; empty fields are omitted.

ContentItem dataclass

ContentItem(
    kind: str,
    id: str,
    data_class: DataClass,
    as_of: datetime | date | None = None,
    body: str = "",
    claims: tuple[Claim, ...] | None = None,
    evidence: Mapping[str, Chunk] = dict(),
    uses: tuple[str, ...] = (),
    activity: Activity | None = None,
    verdict: str | None = None,
    status: str = "ok",
)

A prov:Entity: one printed thing.

Attributes:

  • claims (tuple[Claim, ...] | None) –

    The body decomposed into claims, or None when it never was (print_gate then reports unclaimed rather than guessing either way).

  • evidence (Mapping[str, Chunk]) –

    Id to Chunk: the universe the claims may cite.

  • uses (tuple[str, ...]) –

    prov:used: the source ids, or item ids, it was made from.

  • verdict (str | None) –

    The writer's own check (ok, degraded, refused, ...) as written; None when none was recorded.

  • status (str) –

    What the reader is shown: ok, unavailable, ...

prov

prov() -> dict[str, Any]

The PROV-JSON-shaped view of this item (vocabulary only: no namespace document).

DataClass dataclass

DataClass(
    rights: str,
    private: bool = False,
    link_required: bool = False,
)

A rights tier, a privacy flag and an attribution duty.

Classes order on rights through rank.

Attributes:

  • rights (str) –

    One of RIGHTS.

  • private (bool) –

    PII or the owner's personal data; only the operator audience may see it.

  • link_required (bool) –

    The licence owes a link back to the original (an ODRL duty).

Raises:

  • ValueError –

    When rights is not one of RIGHTS.

rank property

rank: int

The rights tier's index in RIGHTS; higher is more restrictive.

join

join(*others: DataClass) -> DataClass

Return the most restrictive of self and others: max rights, any private, any link owed.

allows

allows(audience: str) -> bool

Return whether an item of this class may be printed for audience.

Raises:

  • ValueError –

    When audience is not one of AUDIENCES.

GateVerdict dataclass

GateVerdict(
    ok: bool, reason: str | None = None, detail: str = ""
)

The result of print_gate.

Attributes:

  • ok (bool) –

    Whether the item may be printed.

  • reason (str | None) –

    One of REFUSALS when not ok; None when ok.

  • detail (str) –

    What failed, for a human reader.

join_all

join_all(classes: Iterable[DataClass]) -> DataClass | None

Return the join of a possibly empty set of classes; None (unknown, never public) when it is empty.

print_gate

print_gate(item: ContentItem, audience: str) -> GateVerdict

Return whether item may be printed for audience.

Pure. The rules run in REFUSALS order, and the first that fails is the reason.

Raises:

  • ValueError –

    When audience is not one of AUDIENCES.