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

> Learn how to enable temporal features in Semantica's knowledge graph construction by passing enable_temporal=True to GraphBuilder. Unlock time-aware edges and historical versioning.

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

---

**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`](https://github.com/semantica-agi/semantica/blob/main/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.

```python
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

```python
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.

```python
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`.

```python
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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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.

```python
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`](https://github.com/semantica-agi/semantica/blob/main/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.

```yaml

# config.yml

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

```

```bash
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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/rdf_exporter.py) module (located at [`semantica/kgs/export/rdf_exporter.py`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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.