How to Export Decisions to W3C PROV-O Format from Semantica

Use the semantica export provenance CLI command or call ProvenanceManager.export() to serialize decision lineage as W3C PROV-O RDF triples in Turtle, RDF/XML, or JSON-LD format.

Semantica is an open-source AI governance framework that records the who, what, when, and why behind automated decisions. When audit requirements or data lineage standards demand standards-compliant provenance traces, you can export decisions to W3C PROV-O format using the built-in provenance manager and RDF exporter.

How Provenance Export Works in Semantica

The export pipeline relies on three tightly integrated components defined in the semantica-agi/semantica repository:

1. ProvenanceManager (semantica/provenance/manager.py) – The central façade that aggregates decision events and constructs the PROV-O graph.
2. RDFExporter (semantica/export/rdf_exporter.py) – Handles RDF serialization, namespace binding, and validation.
3. CLI wrapper (semantica/cli.py) – Parses user arguments and delegates to the manager.

When a decision is recorded, ProvenanceManager creates three core PROV concepts:

• PROV-Agent – The actor or system making the decision.
• PROV-Activity – The decision-making process itself.
• PROV-Entity – The output or artifact produced by the decision.

The manager then wires these together using standard PROV relations such as prov:wasGeneratedBy, prov:wasAssociatedWith, and prov:wasDerivedFrom before handing the graph to the exporter for serialization.

Exporting Decisions via the Command Line

The fastest way to generate a PROV-O dump is through the export provenance sub-command. This invokes the internal _dry function in semantica/cli.py, which forwards your parameters to ProvenanceManager.export().

Basic Syntax

semantica export provenance \
    --format prov \
    --base-uri https://example.org/semantica/ \
    --output decisions.prov.ttl

Parameter Reference

• --format – Serialization format (prov for Turtle, or explicit turtle, rdfxml, jsonld, ntriples, n3).
• --base-uri – The IRI prefix used to mint stable identifiers for entities, activities, and agents.
• --output – Destination file path; use - to stream to stdout.

The CLI validates the format against the supported RDF exporters before invoking the manager, ensuring the output conforms to W3C PROV-O semantics.

Exporting Decisions Programmatically

For integration within Python workflows, instantiate ProvenanceManager directly and invoke its export() method.

Standard Export Workflow

from semantica.provenance.manager import ProvenanceManager

# Initialize with your backend (e.g., sqlite, neo4j)

manager = ProvenanceManager(backend="sqlite")

# ... execute decision workflow ...

# Export to PROV-O Turtle

manager.export(
    format="turtle",
    base_uri="https://example.org/semantica/",
    output_path="decisions.prov.ttl"
)

The export() method automatically:

• Binds the prov namespace to http://www.w3.org/ns/prov#
• Creates an RDFExporter instance
• Serializes the internal graph using the specified format

Exporting Specific Decisions

To retrieve and export a single decision’s provenance record, use the GET_PROVENANCE schema helper:

from semantica.provenance.manager import ProvenanceManager
from semantica.provenance.schemas import GET_PROVENANCE

manager = ProvenanceManager(backend="sqlite")
decision_id = "decision-uuid-123"

# Fetch specific provenance metadata

prov_data = manager.get_provenance(decision_id)

# Export via RDFExporter

from semantica.export.rdf_exporter import RDFExporter
exporter = RDFExporter()
exporter.export(prov_data, "single.prov.ttl", format="turtle")

This approach is defined in semantica/provenance/manager.py and leverages the schema validation found in semantica_mcp/mcp/schemas.py.

Understanding the PROV-O Output Structure

The exported RDF graph follows the W3C PROV-O ontology specification. In semantica/provenance/manager.py, the manager constructs triples using the following pattern:

from rdflib import Namespace, Graph
PROV = Namespace("http://www.w3.org/ns/prov#")
g = Graph()
g.bind("prov", PROV)

# Entity representing the decision output

g.add((entity_uri, RDF.type, PROV.Entity))

# Activity representing the decision process

g.add((activity_uri, RDF.type, PROV.Activity))

# Agent representing the decision maker

g.add((agent_uri, RDF.type, PROV.Agent))

# Relations

g.add((entity_uri, PROV.wasGeneratedBy, activity_uri))
g.add((activity_uri, PROV.wasAssociatedWith, agent_uri))

Key characteristics of the output:

• Stable IRIs – Entities use SHA-256 hashes or UUIDs appended to the --base-uri to ensure global uniqueness.
• Confidence Metadata – When available, confidence values are attached as custom data properties before normalization by RDFExporter.
• Validation – The exporter runs a compliance check against PROV-O constraints, ensuring that every Entity has a generation activity and every Activity has an associated agent.

Customization and Advanced Options

Configuring Base URIs for interoperability

The --base-uri parameter (or base_uri in Python) determines the namespace for all minted identifiers. For production deployments, align this with your organizational URI strategy:

semantica export provenance \
    --base-uri https://api.yourorg.com/provenance/2024/ \
    --format prov \
    --output lineage.ttl

Supported RDF Formats

While prov defaults to Turtle for readability, the RDFExporter supports all standard W3C formats:

• Turtle (.ttl) – Human-readable, default for PROV-O.
• RDF/XML (.rdf) – Legacy XML serialization.
• JSON-LD (.jsonld) – Modern linked-data format ideal for web APIs.
• N-Triples (.nt) – Line-based format for streaming processing.

Summary

• Command-line export is available via semantica export provenance with flags for --format, --base-uri, and --output.
• Programmatic export uses ProvenanceManager.export() in semantica/provenance/manager.py, which orchestrates the RDF serialization.
• The implementation binds the http://www.w3.org/ns/prov# namespace and generates standard PROV-O triples for entities, activities, and agents.
• Output is validated and normalized by RDFExporter in semantica/export/rdf_exporter.py, supporting Turtle, RDF/XML, and JSON-LD.

Frequently Asked Questions

What is W3C PROV-O and why does Semantica use it?

W3C PROV-O is the OWL2 ontology for representing provenance information on the web. Semantica uses it because it provides a standardized, machine-readable vocabulary for describing the lineage of AI decisions, enabling interoperability with external audit tools and regulatory compliance systems.

Can I export a subset of decisions rather than the entire provenance graph?

Yes. Use ProvenanceManager.get_provenance(decision_id) to retrieve a specific decision’s metadata, then pass that data to RDFExporter.export() directly. This avoids serializing the full provenance store when you only need lineage for a single decision trace.

Which file formats are supported for PROV-O export?

Semantica supports Turtle (the default), RDF/XML, JSON-LD, N-Triples, and N3. Specify your preferred format using the --format CLI flag or the format parameter in the Python API. Turtle is recommended for human review, while JSON-LD is preferred for API integration.

How do I validate that my exported file is valid PROV-O?

The RDFExporter performs internal validation against PROV-O constraints before writing the file. For external validation, load the exported file into a W3C PROV validator or use an RDF tool like Apache Jena to verify that all required prov:Entity, prov:Activity, and prov:Agent relationships are present and correctly typed.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}