Relationship Between GraphBuilder, GraphAnalyzer, and GraphStore in Semantica

Semantica splits knowledge-graph operations into three decoupled components—GraphBuilder for constructing KnowledgeGraphs, GraphAnalyzer for read-only statistical analysis, and GraphStore for backend persistence—enabling flexible data pipelines that work with Neo4j, Stardog, or Jena without architectural changes.

The Semantica repository (semantica-agi/semantica) implements a modular architecture for knowledge-graph management. Understanding the relationship between GraphBuilder, GraphAnalyzer, and GraphStore allows developers to ingest raw data, perform in-memory analytics, and optionally persist results to graph databases using a clear separation of concerns.

GraphBuilder: Constructing KnowledgeGraphs

Located in semantica/kg/graph_builder.py, the GraphBuilder class constructs a KnowledgeGraph data structure from raw entities, relationships, and temporal information. It normalizes payloads, assigns unique identifiers, and attaches provenance metadata, remaining agnostic to subsequent analysis or storage layers.

The primary entry point is build_from_documents(), which returns a fully instantiated KnowledgeGraph:

from semantica.kg import GraphBuilder

builder = GraphBuilder()
kg = builder.build_from_documents(my_docs)

GraphAnalyzer: Computing Statistics and Insights

The GraphAnalyzer performs read-only analytics on existing KnowledgeGraph instances. As referenced in tests/visualization/reproduce_notebooks.py, this component calculates node and edge statistics, centrality measures, community detection, and temporal versioning without modifying graph structure.

Use compute_statistics() to derive metrics:

from semantica.kg import GraphAnalyzer

analyzer = GraphAnalyzer()
stats = analyzer.compute_statistics(kg)

GraphStore: Persisting to Graph Databases

Found in semantica/graph_store/graph_store.py, GraphStore abstracts persistence across Neo4j, Stardog, and Jena backends. It provides CRUD operations through a unified API, accepting configuration parameters such as backend and uri during instantiation.

Persist graphs using the save() method:

from semantica.graph_store import GraphStore

store = GraphStore(backend="neo4j", uri="bolt://localhost:7687")
store.save(kg)

Integration Workflow: Build, Analyze, Store

The three components interact through a linear pipeline that maintains strict separation of concerns:

1. Build – GraphBuilder ingests raw documents and produces an in-memory KnowledgeGraph.
2. Analyze – GraphAnalyzer processes the graph without side effects via compute_statistics().
3. Store – GraphStore optionally persists the graph to the configured backend using save().

This decoupling allows multiple analytical passes on the same graph before storage, or swapping storage technologies without modifying construction or analysis logic.

from semantica.kg import GraphBuilder, GraphAnalyzer
from semantica.graph_store import GraphStore

# Construct

builder = GraphBuilder()
kg = builder.build_from_documents(documents)

# Analyze

analyzer = GraphAnalyzer()
metrics = analyzer.compute_statistics(kg)

# Persist (optional)

store = GraphStore(backend="neo4j", uri="bolt://localhost:7687")
store.save(kg)

Summary

• GraphBuilder (semantica/kg/graph_builder.py) creates KnowledgeGraph instances via build_from_documents(), handling entity normalization and ID assignment.
• GraphAnalyzer (imported in tests/visualization/reproduce_notebooks.py) executes read-only analytics through compute_statistics(), supporting centrality and community detection without graph mutation.
• GraphStore (semantica/graph_store/graph_store.py) provides backend-agnostic persistence to Neo4j, Stardog, or Jena using the save() method.
• Components operate sequentially—construction, then analysis, then optional storage—enabling flexible, decoupled knowledge-graph pipelines.

Frequently Asked Questions

What is the primary responsibility of GraphBuilder in Semantica?

GraphBuilder, located in semantica/kg/graph_builder.py, is responsible for constructing KnowledgeGraph data structures from raw inputs. It normalizes entity payloads, assigns unique identifiers, attaches provenance metadata, and handles temporal information through methods like build_from_documents().

Does GraphAnalyzer modify the KnowledgeGraph during analysis?

No, GraphAnalyzer performs strictly read-only operations according to the source code structure. It computes statistics, centrality measures, and community detection without mutating the underlying graph, allowing safe repeated analysis of the same in-memory instance.

Which graph databases are supported by GraphStore?

GraphStore supports multiple backends including Neo4j, Stardog, and Jena, as implemented in semantica/graph_store/graph_store.py. The constructor accepts a backend parameter and connection URI, enabling seamless switching between storage technologies without code changes to other components.

Can I use GraphBuilder and GraphAnalyzer without GraphStore?

Yes, GraphBuilder and GraphAnalyzer function independently of GraphStore. You can construct a KnowledgeGraph and run analytical workflows entirely in-memory without ever invoking save(), making persistence optional for lightweight analytics or prototyping scenarios.

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