# How Semantica Decisions Are Exported as W3C PROV-O RDF

> Learn how Semantica decisions export as W3C PROV-O RDF. The ProvenanceManager class creates an RDF graph mapping internal records to PROV-O and serializes it to Turtle, JSON-LD, or N-Triples.

- Repository: [Semantica /semantica](https://github.com/semantica-agi/semantica)
- Tags: how-to-guide
- Published: 2026-09-08

---

**Semantica decisions are exported as W3C PROV-O RDF by the `ProvenanceManager` class in [`semantica/provenance/manager.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/provenance/manager.py), which constructs an RDF graph mapping internal provenance records to PROV-O classes and serializes them to Turtle, JSON-LD, or N-Triples.**

Semantica is an open-source AGI framework that records every decision-making step in an internal provenance store. When interoperability or auditability is required, the framework transforms these records into standard-compliant **W3C PROV-O RDF** using a dedicated export pipeline. This article examines the implementation details, from namespace binding to qualified associations, based on the actual source code in the `semantica-agi/semantica` repository.

## The ProvenanceManager Export Architecture

The export functionality is centralized in the `ProvenanceManager` class defined in [`semantica/provenance/manager.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/provenance/manager.py). This manager maintains an internal storage of provenance entries—tracking entities, activities, and agents—and exposes the `export_prov()` method to serialize them as RDF.

### Base URI and Namespace Configuration

Every export begins with namespace setup. The manager defines a **default base URI** constant:

```python
DEFAULT_BASE_URI = "https://semantica.dev/ns#"

```

Located at line 51 of [`semantica/provenance/manager.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/provenance/manager.py), this URI serves as the default namespace for all minted identifiers. The export process binds two essential prefixes: `prov` for the standard PROV-O namespace and `ex` for the instance data (lines 56–62). Callers can override the base URI via the `base_uri` parameter to align with their own knowledge graph conventions.

## PROV-O RDF Generation Process

The `export_prov()` method iterates over all stored provenance entries via `self.storage.retrieve_all()` and maps them to the PROV-O ontology through a series of deterministic transformations.

### Entity Conversion and Attribution

For each provenance entry, the manager mints a URI using the `uri(entity_id)` helper and types it as `prov:Entity` (lines 66–69). If a timestamp exists, the export adds a `prov:generatedAtTime` literal with the `xsd:dateTime` datatype (lines 70–77).

When an `agent_id` is present, the entity is linked to a `prov:Agent` via `prov:wasAttributedTo` (lines 78–89). The manager supports agent specialization through the `_AGENT_TYPE_PROV_CLASS` map (lines 32–36), which converts internal types (`person`, `software_agent`, `organization`) to their respective PROV-O classes: `prov:Person`, `prov:SoftwareAgent`, and `prov:Organization`.

### Qualified Associations and Roles

Complex attributions use **qualified associations** modeled with RDF blank nodes (`BNode`). A blank node represents the association itself, linking the agent via `prov:agent` and specifying a role via `prov:hadRole` (lines 94–100). If no role is provided, the default value is `"generator"`.

### Delegation Chains

When an entry contains a delegation reference, the manager emits a `prov:actedOnBehalfOf` triple linking the acting agent to the delegate agent (lines 101–108). This captures scenarios where one software agent executes a decision on behalf of another.

### Activity Representation and Qualified Generation

Activities that generated entities are modeled as `prov:Activity` nodes. The manager connects entities to their generating activities using `prov:wasGeneratedBy` (lines 110–115). Optional start and end timestamps are mapped to `prov:startedAtTime` and `prov:endedAtTime` literals respectively (lines 117–122).

For detailed provenance, a **qualified generation** blank node is created using `prov:qualifiedGeneration`. This node explicitly links the entity, the activity, and the generation time via `prov:atTime` (lines 124–131).

### Activity-Agent Associations and Derivation

Distinct from entity attribution, activities are directly associated with agents using `prov:wasAssociatedWith` (lines 134–137). For entity lineage, the manager emits `prov:wasDerivedFrom` triples to indicate parent-child relationships. When entities are used as inputs, `prov:used` triples are generated alongside **qualified usage** blank nodes containing `prov:entity` references (lines 144–170).

### Invalidation and Bundle Membership

Invalidated entries trigger the creation of `prov:Invalidation` nodes, optionally annotated with `prov:invalidatedAtTime` and the invalidating agent (lines 172–189). For organizational purposes, if a `bundle_id` is present, the manager creates a `prov:Bundle` and asserts membership via `prov:hadMember` (lines 191–198).

## Serialization and Output Formats

Once the RDF graph is constructed, the manager serializes it using rdflib. Supported formats include `turtle`, `ntriples`, and `jsonld`. Notably, the method maps the user-facing `"jsonld"` string to rdflib's `"json-ld"` format for compatibility (lines 199–200).

The export is accessible both programmatically and via the CLI entry point in [`semantica/cli.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/cli.py) at line 2931, which forwards command-line arguments to `ProvenanceManager.export_prov()`.

## Usage Examples

### Python API

```python
from semantica.provenance.manager import ProvenanceManager

# Initialize the manager (typically wired into Semantica pipelines)

pm = ProvenanceManager()

# Export as Turtle with the default base URI

turtle_output = pm.export_prov(format="turtle")

# Export as JSON-LD with a custom namespace

jsonld_output = pm.export_prov(
    format="jsonld",
    base_uri="https://example.org/mykg#"
)

```

### Command Line Interface

```bash

# Export to Turtle using default settings

semantica provenance export --format turtle

# Export to JSON-LD with custom base URI

semantica provenance export \
    --format jsonld \
    --base-uri https://example.org/mykg#

```

### Pipeline Integration

```python
def execute_decision_step(input_entity, agent_id):
    # ... decision logic ...

    
    # Provenance is recorded automatically

    pm.record_generation(
        entity_id="decision_001",
        activity_id="inference_activity",
        agent_id=agent_id,
        timestamp="2024-01-15T10:30:00Z"
    )
    
    # Export for downstream auditing

    rdf_audit_trail = pm.export_prov(format="ntriples")
    return rdf_audit_trail

```

## Integration with the Semantica Ecosystem

The provenance export aligns with Semantica's broader export architecture. The `DEFAULT_BASE_URI` constant is shared with [`semantica/export/rdf_exporter.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/export/rdf_exporter.py) (line 471) and [`semantica/export/owl_exporter.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/export/owl_exporter.py) (line 40), ensuring that PROV-O exported URIs co-resolve with knowledge graph exports. This consistency allows triple stores to join provenance data with ontological definitions without namespace fragmentation.

The correctness of the PROV-O mapping is verified in [`tests/provenance/test_manager.py`](https://github.com/semantica-agi/semantica/blob/main/tests/provenance/test_manager.py), which validates qualified associations, invalidation logic, and base URI overrides against expected RDF outputs.

## Summary

- **Semantica decisions** are exported as W3C PROV-O RDF through the `ProvenanceManager.export_prov()` method in [`semantica/provenance/manager.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/provenance/manager.py).
- The export maps internal entities to `prov:Entity`, agents to specialized `prov:Agent` classes, and activities to `prov:Activity` with precise temporal annotations.
- **Qualified patterns** (generation, usage, association) use blank nodes to satisfy PROV-O provenance requirements without minting additional URIs.
- The default base URI (`https://semantica.dev/ns#`) can be overridden, and formats include Turtle, N-Triples, and JSON-LD.
- CLI access is provided via [`semantica/cli.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/cli.py), while the test suite in [`tests/provenance/test_manager.py`](https://github.com/semantica-agi/semantica/blob/main/tests/provenance/test_manager.py) ensures standards compliance.

## Frequently Asked Questions

### What is the default namespace used for PROV-O exports in Semantica?

The default base URI is `https://semantica.dev/ns#`, defined as `DEFAULT_BASE_URI` in [`semantica/provenance/manager.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/provenance/manager.py) at line 51. This namespace is bound to the `ex` prefix during export, though callers can override it via the `base_uri` parameter to integrate with external knowledge graphs.

### How does Semantica handle agent types in PROV-O RDF?

Semantica maps internal agent type strings to specific PROV-O classes using the `_AGENT_TYPE_PROV_CLASS` dictionary (lines 32–36 of [`manager.py`](https://github.com/semantica-agi/semantica/blob/main/manager.py)). The mapping converts `person` to `prov:Person`, `software_agent` to `prov:SoftwareAgent`, and `organization` to `prov:Organization`, ensuring ontological accuracy in the exported RDF.

### Can I export provenance data from the command line?

Yes. The CLI entry point in [`semantica/cli.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/cli.py) (line 2931) exposes the `semantica provenance export` command. You can specify the output format with `--format` (accepting `turtle`, `jsonld`, `ntriples`, etc.) and override the base URI with `--base-uri` to match your target triple store conventions.

### What PROV-O relationships are supported for entity lineage?

The export supports both `prov:wasDerivedFrom` for plain derivation and qualified derivation patterns. For entity usage, it emits `prov:used` triples alongside qualified usage blank nodes containing `prov:entity` references (lines 144–170 of [`manager.py`](https://github.com/semantica-agi/semantica/blob/main/manager.py)). This allows fine-grained tracking of which input entities contributed to specific decision outputs.