How Semantica Decisions Are Exported as W3C PROV-O RDF

Semantica decisions are exported as W3C PROV-O RDF by the ProvenanceManager class in 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. 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:

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

Located at line 51 of 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 at line 2931, which forwards command-line arguments to ProvenanceManager.export_prov().

Usage Examples

Python API

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

# 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

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 (line 471) and 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, 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.
• 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, while the test suite in 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 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). 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 (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). This allows fine-grained tracking of which input entities contributed to specific decision outputs.

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