semantica/docs/reference/kg.md

title, description, icon

title	description	icon
Knowledge Graph Module	Graph construction, temporal models, analytics, similarity scoring, and structural embeddings.	diagram-project

semantica.kg transforms extracted entities and relationships into structured, queryable knowledge graphs. It includes temporal support, a full suite of graph analytics algorithms, node embeddings, and structural similarity scoring.

Exported Classes

from semantica.kg import (
    KnowledgeGraph,             # core graph data structure
    GraphBuilder,               # construct from entities + relationships
    GraphBuilderWithProvenance, # auto-tracks provenance for every node/edge
    EntityResolver,             # entity deduplication during construction
    GraphAnalyzer,              # temporal evolution, diversity metrics
    GraphValidator,             # schema and constraint validation
    TemporalGraphQuery,         # point-in-time snapshots, diffs, interval queries
    TemporalPatternDetector,    # sequence/cycle/trend detection
    TemporalVersionManager,     # snapshot creation and version comparison
    TemporalNormalizer,         # normalize timestamps across granularities
    BiTemporalFact,             # bi-temporal fact model (transaction + valid time)
    CentralityCalculator,       # degree, betweenness, closeness, PageRank, eigenvector
    CommunityDetector,          # Louvain, Leiden, Label Propagation, K-Clique
    PathFinder,                 # Dijkstra, A*, BFS, K-Shortest paths
    LinkPredictor,              # Preferential Attachment, Jaccard, Adamic-Adar
    NodeEmbedder,               # Node2Vec, DeepWalk structural embeddings
    SimilarityCalculator,       # cosine, Euclidean, Manhattan, correlation similarity
    ConnectivityAnalyzer,       # connected components, bridges, density
    ProvenanceTracker,          # source tracking and lineage management
)

What You Get

• GraphBuilder — construct graphs from entities and relationships with automatic entity merging
• TemporalGraphQuery — time-aware point-in-time snapshots, diffs, and Allen interval queries (v0.4.0)
• SimilarityCalculator — cosine, Euclidean, Manhattan, and correlation similarity scoring
• CentralityCalculator — PageRank, degree, betweenness, closeness, eigenvector centrality
• CommunityDetector — Louvain, Leiden, Label Propagation, K-Clique community detection
• PathFinder — Dijkstra, A*, BFS, K-Shortest path algorithms
• LinkPredictor — Preferential Attachment, Jaccard, Adamic-Adar link prediction
• NodeEmbedder — Node2Vec, DeepWalk structural embeddings

For conflict detection and advanced entity resolution, use `semantica.conflicts` and `semantica.deduplication` alongside this module.

<img src="/assets/img/diagrams/kg-structure.svg" alt="Knowledge graph entity and relation structure: Person, Organization, Location, Date nodes with typed labeled edges" style={{ width: '100%', borderRadius: '12px', margin: '0 0 24px' }} />

GraphBuilder

Constructs knowledge graphs from extracted entities and relationships:

from semantica.kg import GraphBuilder

builder = GraphBuilder(merge_entities=True)
kg = builder.build(entities=entities, relationships=relationships)

Method	Description
build(sources)	Build graph from multiple data sources
build_single_source(data)	Build graph from a single data source
merge_entities()	Deduplicate and merge entities during construction

Temporal Knowledge Graphs (v0.4.0)

Use TemporalGraphQuery to attach valid_from/valid_until windows and query time-aware graphs:

from semantica.kg import GraphBuilder, TemporalGraphQuery, TemporalVersionManager
from datetime import datetime

# Build a time-aware graph
builder = GraphBuilder()
kg = builder.build(sources=[
    {
        "entities": [
            {"id": "alice",     "type": "Person"},
            {"id": "acme_corp", "type": "Organization"},
        ],
        "relationships": [
            {
                "source": "alice", "target": "acme_corp", "type": "ceo_of",
                "valid_from":  "2020-01-01",
                "valid_until": "2023-06-01",
            }
        ]
    }
])

# Point-in-time snapshot
query         = TemporalGraphQuery(kg)
snapshot_2021 = query.at_time("2021-06-15")
snapshot_2023 = query.at_time("2023-01-01")

# Diff between two snapshots
diff = query.diff("2020-01-01", "2023-01-01")
print(f"New nodes since 2020: {len(diff.get('added_nodes', []))}")

# Versioned snapshots
versioner = TemporalVersionManager()
versioner.create_snapshot(kg, version_label="2024-Q1")

Supports all 13 Allen interval algebra relations (before, after, meets, overlaps, during, starts, finishes, equals, and their inverses). OWL-Time export available.

Similarity Scoring

SimilarityCalculator computes cosine, Euclidean, Manhattan, and correlation similarity between node embeddings:

from semantica.kg import SimilarityCalculator, NodeEmbedder

# First compute structural embeddings
embedder   = NodeEmbedder(method="node2vec", embedding_dimension=128)
embeddings = embedder.compute_embeddings(kg, ["Person", "Organization"], ["RELATED_TO"])

# Then compare nodes by embedding similarity
calc  = SimilarityCalculator()
score = calc.cosine_similarity(embeddings["Apple Inc."], embeddings["Google"])
print(f"Apple–Google structural similarity: {score:.3f}")

# Find structurally similar nodes
similar = embedder.find_similar_nodes(kg, "Apple Inc.", top_k=5)
for node in similar:
    print(f"{node['id']}: {node['score']:.3f}")

Graph Analytics

Centrality Analysis

from semantica.kg import CentralityCalculator

calculator = CentralityCalculator()

centrality    = calculator.calculate_degree_centrality(graph)
pagerank      = calculator.calculate_pagerank(graph, damping_factor=0.85)
betweenness   = calculator.calculate_betweenness_centrality(graph)
closeness     = calculator.calculate_closeness_centrality(graph)
eigenvector   = calculator.calculate_eigenvector_centrality(graph)
all_metrics   = calculator.calculate_all_centrality(graph)

top_nodes = calculator.get_top_nodes(centrality, top_k=10)

Method	Algorithm
calculate_degree_centrality()	Degree-based importance
calculate_betweenness_centrality()	Bridge-based importance (bottleneck nodes)
calculate_closeness_centrality()	Distance-based importance
calculate_eigenvector_centrality()	Influence-based importance
calculate_pagerank()	Link-based importance (PageRank)
calculate_all_centrality()	All measures at once

Community Detection

from semantica.kg import CommunityDetector

detector = CommunityDetector()

# Louvain (default — fast, high quality)
communities = detector.detect_communities(graph, algorithm="louvain")

# Leiden (higher quality, slower)
leiden_communities = detector.detect_communities_leiden(graph, resolution=1.2)

metrics = detector.calculate_community_metrics(graph, communities)

Algorithms: Louvain, Leiden, Label Propagation, K-Clique Communities.

Path Finding

from semantica.kg import PathFinder

finder = PathFinder()

path   = finder.dijkstra_shortest_path(graph, "node_a", "node_b")
paths  = finder.all_shortest_paths(graph, "source", "target")
k_paths = finder.find_k_shortest_paths(graph, "source", "target", k=3)

Algorithms: Dijkstra, A*, BFS, All Shortest Paths, K-Shortest Paths.

Link Prediction

from semantica.kg import LinkPredictor

predictor = LinkPredictor(method="preferential_attachment")
links = predictor.predict_links(graph, top_k=20)
score = predictor.score_link(graph, "node_a", "node_b")

Algorithms: Preferential Attachment, Common Neighbors, Jaccard, Adamic-Adar, Resource Allocation.

Node Embeddings

from semantica.kg import NodeEmbedder

embedder = NodeEmbedder(method="node2vec", embedding_dimension=128)
embeddings   = embedder.compute_embeddings(graph_store, ["Entity"], ["RELATED_TO"])
similar_nodes = embedder.find_similar_nodes(graph_store, "entity_123", top_k=10)

Algorithms: Node2Vec, DeepWalk, Word2Vec.

Algorithm Summary

Category	Algorithms	Use Cases
Node Embeddings	Node2Vec, DeepWalk, Word2Vec	Structural similarity, node representation
Similarity	Cosine, Euclidean, Manhattan, Correlation	Node matching, recommendation
Path Finding	Dijkstra, A*, BFS, K-Shortest	Route planning, network analysis
Link Prediction	Preferential Attachment, Jaccard, Adamic-Adar	Network completion
Centrality	Degree, Betweenness, Closeness, PageRank	Influence analysis
Community Detection	Louvain, Leiden, Label Propagation	Social clustering
Connectivity	Components, Bridges, Density	Network robustness

Configuration

kg:
  resolution:
    threshold: 0.9
    strategy: semantic

  temporal:
    enabled: true
    default_validity: infinite

Persist graphs in Neo4j, FalkorDB, or Apache AGE. Source of entities and relationships fed to GraphBuilder. Visualize knowledge graphs interactively. Conflict detection and resolution.

Cookbooks

• Building Knowledge Graphs — fundamentals of KG construction · Beginner
• Your First Knowledge Graph — entity extraction to visualization · Beginner
• Graph Analytics — centrality and community detection · Intermediate
• Advanced Graph Analytics — PageRank, Louvain, shortest path · Advanced
• Temporal Knowledge Graphs — temporal logic and graph evolution · Advanced