How to Enable Temporal Features in Semantica's Knowledge Graph Construction

Pass enable_temporal=True when instantiating semantica.kg.graph_builder.GraphBuilder to activate time-aware edges, granular time resolution, and historical versioning capabilities.

The semantica-agi/semantica library supports temporal knowledge graphs (TKGs) that track relationship validity across time. Enabling these features requires explicit configuration during the GraphBuilder initialization, after which the system records temporal metadata for edges and supports snapshot versioning. This guide explains exactly how to activate and utilize temporal capabilities using the actual implementation in the source code.

Configuring the GraphBuilder for Temporal Support

Temporal support is disabled by default in Semantica. According to the source code in semantica/kg/graph_builder.py, you must explicitly set the flag during instantiation to enable time-aware graph construction.

Setting the enable_temporal Flag

The constructor stores the temporal configuration in self.enable_temporal (lines 57‑63). When set to True, the builder records temporal metadata for all subsequent edges and includes a temporal_enabled flag in the graph’s top-level metadata.

from semantica.kg.graph_builder import GraphBuilder

builder = GraphBuilder(
    merge_entities=True,
    resolve_conflicts=True,
    enable_temporal=True,  # Activate temporal KG support

)

Optional Temporal Parameters

You can fine-tune temporal behavior using additional constructor parameters:

• temporal_granularity – Controls time resolution (e.g., "second", "minute", "day")
• track_history – Enables full change history tracking
• version_snapshots – Creates versioned snapshots of graph states

builder = GraphBuilder(
    enable_temporal=True,
    temporal_granularity="day",
    track_history=True,
    version_snapshots=True,
)

Building and Validating Temporal Graphs

When you invoke the build() method, the flag is written into the metadata dictionary (lines 30‑33), setting "temporal_enabled": True. You should verify this metadata field to confirm that subsequent temporal-aware tools will recognize the graph as temporal.

raw_data = {
    "entities": [
        {"id": "alice", "metadata": {"name": "Alice"}},
        {"id": "bob", "metadata": {"name": "Bob"}},
    ],
    "relationships": [
        {
            "source": "alice",
            "target": "bob",
            "type": "KNOWS",
            "metadata": {"certainty": 0.9},
        }
    ],
}

graph = builder.build(raw_data)

# Verify temporal support is active

assert graph["metadata"]["temporal_enabled"] is True
print("Temporal KG enabled:", graph["metadata"]["temporal_enabled"])

Adding Time-Aware Edges and Relationships

Once temporal support is enabled, use the add_temporal_edge method to create edges with specific validity periods. This method accepts valid_from and valid_until timestamps along with optional temporal_metadata.

builder.add_temporal_edge(
    graph,
    source="alice",
    target="bob",
    relationship="WORKED_WITH",
    valid_from="2022-01-01T00:00:00Z",
    valid_until="2023-12-31T23:59:59Z",
    temporal_metadata={"precision": "day"},
)

Querying and Visualizing Temporal Data

Semantica provides specialized tools that recognize the temporal_enabled flag and expose functions for temporal analysis.

Temporal Queries and Version Management

The TemporalVersionManager class in semantica/kg/temporal_query.py provides utilities for querying historical snapshots and managing version history. These tools require that the graph was constructed with enable_temporal=True to function correctly.

Timeline Visualization

The TemporalVisualizer class in semantica/visualization/temporal_visualizer.py reads the temporal metadata to generate interactive timelines. Use this to visualize how relationships evolve over the valid time periods defined in your edges.

from semantica.visualization.temporal_visualizer import TemporalVisualizer

visualizer = TemporalVisualizer()
visualizer.visualize_timeline(graph, output="interactive")

Command-Line Activation

When using Semantica's CLI entry point (semantica/cli.py), you can enable temporal features via configuration file rather than Python code. The CLI forwards kg.enable_temporal and related settings to the GraphBuilder automatically.

# config.yml

kg:
  enable_temporal: true
  temporal_granularity: day
  track_history: true
  version_snapshots: true

semantica run --config config.yml

Summary

• Temporal support is disabled by default and requires enable_temporal=True in the GraphBuilder constructor
• The flag is stored in self.enable_temporal (lines 57‑63 of semantica/kg/graph_builder.py) and written to graph metadata (lines 30‑33)
• Use add_temporal_edge with valid_from and valid_until parameters to create time-bounded relationships
• The TemporalVersionManager and TemporalVisualizer require the temporal flag to be set to function correctly
• Configure temporal features via CLI by setting kg.enable_temporal: true in your YAML configuration file

Frequently Asked Questions

Is temporal support enabled by default in Semantica?

No. According to the source code in semantica/kg/graph_builder.py, temporal support is explicitly opt-in. You must pass enable_temporal=True to the GraphBuilder constructor (lines 57‑63), otherwise the builder will not record temporal metadata or enable time-aware edge functionality.

What timestamp format does add_temporal_edge expect?

The method accepts ISO 8601 formatted strings for the valid_from and valid_until parameters, such as "2022-01-01T00:00:00Z". You can also include additional precision specifications in the temporal_metadata dictionary to indicate granularity (e.g., {"precision": "day"}), which should align with the temporal_granularity setting configured in the builder.

Can I export temporal knowledge graphs to RDF formats?

Yes. When enable_temporal=True, the rdf_exporter.py module (located at semantica/kgs/export/rdf_exporter.py) recognizes the temporal_enabled flag and can export graphs using OWL-Time ontologies. This allows integration with standard semantic web tools that understand temporal validity periods.

How do I query historical snapshots of a temporal graph?

Use the TemporalVersionManager class defined in semantica/kg/temporal_query.py. This utility provides methods for retrieving specific snapshots based on timestamps and browsing version history. These functions only work correctly when the graph was originally constructed with both enable_temporal=True and version_snapshots=True parameters.

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