How to Enable Temporal Support When Building a Knowledge Graph with Semantica

Enable temporal support in Semantica by passing enable_temporal=True to the GraphBuilder constructor or build_kg() function, or by setting the KG_ENABLE_TEMPORAL=true environment variable before running your script.

Semantica is an open-source framework for constructing knowledge graphs that evolve over time. When you enable temporal support while building a knowledge graph with Semantica, the GraphBuilder class parses validity periods from relationships and embeds chronological metadata directly into the graph structure. This activates downstream components like TemporalGraphQuery and TemporalVersionManager, allowing you to execute time-aware queries and create versioned snapshots of your data.

Understanding Temporal Knowledge Graphs

In Semantica, a temporal knowledge graph tracks when relationships are valid through time-stamped edges. According to the semantica-agi/semantica source code, the system parses fields like valid_from and valid_until from your source documents using utilities in semantica/kg/temporal_model.py. This feature is disabled by default and must be explicitly activated to enable the parsing pipeline and metadata tracking required for temporal reasoning.

Four Methods to Enable Temporal Support

You can activate temporal support through multiple configuration paths depending on your deployment architecture and coding style.

1. Pass the Flag to GraphBuilder

The most direct approach is providing the enable_temporal parameter when instantiating the core builder class. In semantica/kg/graph_builder.py (lines 57-78), the GraphBuilder.__init__ method stores this flag as the instance attribute self.enable_temporal and injects "temporal_enabled": True into the resulting graph's metadata dictionary.

from semantica.kg import GraphBuilder

builder = GraphBuilder(
    merge_entities=True,
    resolve_conflicts=True,
    enable_temporal=True,        # Activates temporal parsing

    temporal_granularity="day"   # Optional: controls timestamp precision

)

kg = builder.build(sources=[my_documents])
print(kg["metadata"]["temporal_enabled"])   # → True

2. Set the Environment Variable

For containerized or production deployments, export KG_ENABLE_TEMPORAL=true before execution. The KGConfig._load_env_vars method in semantica/kg/config.py (lines 96-104) reads this environment variable and merges the boolean value into the global configuration object, which GraphBuilder consumes automatically during instantiation.

export KG_ENABLE_TEMPORAL=true
python build_graph.py

3. Configure via a Config File

Add the setting to a YAML or TOML configuration file under the kg section. The KGConfig._load_config_file method in semantica/kg/config.py (lines 81-92) merges these values into the internal configuration dictionary that propagates to the builder.

# config.yaml

kg:
  enable_temporal: true
  temporal_granularity: month
  merge_entities: true

Load the configuration before building your graph:

from semantica.kg.config import kg_config
from semantica.kg.methods import build_kg

kg_config._load_config_file("config.yaml")
kg = build_kg(sources=my_documents)  # Temporal support active automatically

4. Use the build_kg Helper

The convenience wrapper build_kg in semantica/kg/methods.py (lines 64-78) accepts the flag directly and forwards it to GraphBuilder. Specify method="temporal" to explicitly select the temporal building path and activate temporal field parsing.

from semantica.kg.methods import build_kg

kg = build_kg(
    sources=my_documents,
    method="temporal",
    enable_temporal=True
)

Architectural Components Activated

When you enable temporal support, Semantica initializes specialized subsystems to handle validity periods and time-based queries.

TemporalModel Utilities

The TemporalModel class in semantica/kg/temporal_model.py provides normalization functions such as parse_temporal_value and deserialize_relationship_temporal_fields. These utilities convert ISO-8601 timestamps into internal representations and handle open-ended validity periods using the TemporalBound.OPEN constant when valid_until is unspecified.

Query and Version Management

With temporal support enabled, you can utilize TemporalGraphQuery (defined in semantica/kg/temporal_query.py) to execute Allen-style temporal interval queries and compute relationships between time periods. The system also instantiates TemporalVersionManager to handle graph snapshotting, allowing you to export or analyze the knowledge graph state at specific historical timestamps.

Summary

• Pass enable_temporal=True to GraphBuilder or build_kg() for direct activation, or set the KG_ENABLE_TEMPORAL environment variable for configuration-free deployments
• The builder stores the flag in self.enable_temporal and sets "temporal_enabled": True in graph metadata
• Temporal fields (valid_from, valid_until) are parsed using TemporalModel utilities in semantica/kg/temporal_model.py
• Activated graphs support TemporalGraphQuery for point-in-time lookups and Allen-relation queries
• TemporalVersionManager enables snapshotting and versioning of temporal knowledge graphs

Frequently Asked Questions

Does enabling temporal support affect graph build performance?

Yes, temporal parsing introduces computational overhead during the construction phase. The TemporalModel utilities in semantica/kg/temporal_model.py must validate and normalize ISO-8601 timestamps for every relationship containing temporal fields. However, query performance remains optimized because GraphBuilder creates temporal indexes when enable_temporal is True, allowing TemporalGraphQuery to execute point-in-time lookups without scanning the entire graph.

What date formats does Semantica support for temporal fields?

Semantica accepts ISO-8601 formatted timestamps through the parse_temporal_value function. You can specify open-ended validity periods by omitting the valid_until field or explicitly setting it to TemporalBound.OPEN, which the system interprets as valid indefinitely from the valid_from date. The deserialize_relationship_temporal_fields function handles normalization of these values during the build process.

Can I convert an existing static graph to a temporal graph?

No, you must rebuild the graph with enable_temporal=True. The GraphBuilder class only parses temporal metadata during the initial build phase in semantica/kg/graph_builder.py. Static graphs lack the required temporal indexes and metadata entries that TemporalGraphQuery and TemporalVersionManager require for time-aware operations. Reprocess your source documents with temporal fields included and the flag enabled.

Is temporal granularity configurable?

Yes. When instantiating GraphBuilder, pass the temporal_granularity parameter with values such as "day", "month", or "year". According to the implementation in semantica/kg/graph_builder.py, this setting controls how timestamps are bucketed and indexed, affecting storage efficiency and the precision of temporal queries executed through TemporalGraphQuery.

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