GraphBuilder constructs knowledge graphs from extracted entities and relationships. merge_entities defaults to False: pass True to enable entity deduplication during construction:
from semantica.kg import GraphBuilder# Pass a dict with "entities" and "relationships" keysbuilder = GraphBuilder(merge_entities=True)kg = builder.build({"entities": entities, "relationships": relationships})
Method
Returns
Description
build(sources)
dict
Build graph from a dict, list of dicts, or list of entity/relation objects
Measure node importance across five algorithms. Use calculate_all_centrality() to run them all at once.
from semantica.kg import CentralityCalculatorcalculator = CentralityCalculator()# Run all centrality measures at onceall_metrics = calculator.calculate_all_centrality(graph)# Or run individuallypagerank = calculator.calculate_pagerank(graph, damping_factor=0.85)betweenness = calculator.calculate_betweenness_centrality(graph)closeness = calculator.calculate_closeness_centrality(graph)# Get the top 10 most important nodestop_nodes = calculator.get_top_nodes(pagerank, top_k=10)
Method
Best for
calculate_degree_centrality()
Most-connected nodes
calculate_pagerank()
Link-based influence (like Google PageRank)
calculate_betweenness_centrality()
Bottleneck / bridge nodes
calculate_closeness_centrality()
Nodes closest to all others
calculate_eigenvector_centrality()
Nodes connected to other high-influence nodes
Discover clusters and communities within the graph. Louvain is the fastest; Leiden produces higher-quality partitions.
from semantica.kg import CommunityDetectordetector = CommunityDetector()# Louvain: fast, high quality (default)communities = detector.detect_communities(graph, algorithm="louvain")# Leiden: higher quality, slowercommunities = detector.detect_communities_leiden(graph, resolution=1.2)# Evaluate community qualitymetrics = detector.calculate_community_metrics(graph, communities)print(f"Modularity: {metrics['modularity']:.3f}")print(f"Communities found: {metrics['num_communities']}")
Algorithm
Strength
Louvain
Fast, good modularity: use for large graphs
Leiden
Best modularity: use when quality matters more than speed
Label Propagation
Near-linear time: use for very large graphs
K-Clique
Overlapping communities: nodes can belong to multiple groups
Find shortest paths and route alternatives between any two nodes.
from semantica.kg import PathFinderfinder = PathFinder()# Dijkstra shortest pathpath = finder.dijkstra_shortest_path(graph, "Alice", "Bob")print(" → ".join(path["path"]))# All shortest paths between two nodespaths = finder.all_shortest_paths(graph, "source", "target")# K-Shortest paths (alternative routes)k_paths = finder.find_k_shortest_paths(graph, "source", "target", k=3)
Algorithm
Use case
Dijkstra
Weighted shortest path: standard routing
A*
Heuristic-guided search: faster on large sparse graphs
BFS
Unweighted shortest path: hop count only
K-Shortest
Multiple alternative routes
Predict missing or future edges. Use to complete knowledge graphs or find implicit relationships.
from semantica.kg import LinkPredictorpredictor = LinkPredictor(method="preferential_attachment")# Predict the top 20 most likely missing edgespredicted = predictor.predict_links(graph, top_k=20)for link in predicted: print(f"{link['source']} → {link['target']} (score: {link['score']:.3f})")# Score a specific pairscore = predictor.score_link(graph, "Alice", "CompanyX")
Algorithm
Best for
Preferential Attachment
High-degree node connection prediction
Common Neighbors
Nodes with shared connections
Jaccard
Normalized common-neighbor overlap
Adamic-Adar
Weighted common neighbors (penalizes hubs)
Resource Allocation
Conservative: ignores high-degree intermediaries
Compute structural embeddings with Node2Vec, then find similar nodes or feed into downstream ML.
from semantica.kg import NodeEmbedder, SimilarityCalculator# Compute Node2Vec embeddingsembedder = NodeEmbedder(method="node2vec", embedding_dimension=128)embeddings = embedder.compute_embeddings( graph, ["Person", "Organization"], ["RELATED_TO"])# Find structurally similar nodessimilar = embedder.find_similar_nodes(graph, "Apple Inc.", top_k=5)for node_id in similar: print(node_id)# Compare two specific nodes by embedding similaritycalc = SimilarityCalculator()score = calc.cosine_similarity(embeddings["Apple Inc."], embeddings["Google"])print(f"Structural similarity: {score:.3f}")
find_similar_nodes returns List[str]: a list of node IDs, not node objects. Look up full node data via graph["nodes"].
Validates graph structure: checks required fields, duplicate IDs, dangling edges, and optionally detects cycles and orphan nodes:
from semantica.kg import GraphValidatorvalidator = GraphValidator()result = validator.validate(kg) # accepts the dict returned by GraphBuilder.build()if result.is_valid: print("Graph is valid")else: for issue in result.issues: print(f"{issue.severity.value}: {issue.message}")
Pass strict=True to treat warnings as errors. Pass a schema dict with "entity_types" and "relationship_types" keys to validate against a known type vocabulary.
