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

Class	Role
KnowledgeGraph	Core graph data structure — nodes, edges, properties, temporal validity
GraphBuilder	Construct from entities + relationships with automatic entity merging
GraphBuilderWithProvenance	Drop-in replacement that auto-tracks provenance for every node and edge
EntityResolver	Entity deduplication and merging during graph construction
TemporalGraphQuery	Point-in-time snapshots, temporal diffs, and all 13 Allen interval queries
CentralityCalculator	PageRank, degree, betweenness, closeness, eigenvector centrality
CommunityDetector	Louvain, Leiden, Label Propagation, and K-Clique community detection
PathFinder	Dijkstra, A*, BFS, and K-Shortest path algorithms
LinkPredictor	Preferential Attachment, Jaccard, Adamic-Adar link prediction
NodeEmbedder	Node2Vec, DeepWalk structural embeddings for downstream ML
SimilarityCalculator	Cosine, Euclidean, Manhattan, and correlation similarity scoring
GraphValidator	Schema and constraint validation before persistence

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